Generieren einer strukturierten JSON-Ausgabe mit Phi-Silika

Von Bedeutung

Verfügbar in der neuesten experimentellen Kanalversion des Windows App SDK (siehe Microsoft.Windows.AI.Text.Experimental-Namespace ).

Der Windows App SDK experimentelle Kanal umfasst APIs und Features in frühen Entwicklungsphasen. Alle APIs im experimentellen Kanal werden fortlaufend überarbeitet. Sie können Breaking Changes aufweisen und jederzeit aus nachfolgenden Releases entfernt werden. Experimentelle Features werden nicht für die Verwendung in Produktionsumgebungen und Apps unterstützt, die sie verwenden, können nicht im Microsoft Store veröffentlicht werden.

Die vom Phi-Silika-Modell generierten Textantworten in natürlicher Sprache können auf gültige JSON-Daten beschränkt werden, die einem von Ihnen definierten JSON-Schema entsprechen. Dies ist nützlich, um strukturierte Daten aus natürlicher Sprache zu extrahieren, Formularfelder aufzufüllen oder Ergebnisse an eine API zu übergeben.

Hinweis

Phi-Silika-Features sind in China nicht verfügbar.

Voraussetzungen

Informationen zu den Hardwareanforderungen der Windows AI-API und zum Konfigurieren Ihres Geräts zum erfolgreichen Erstellen von Apps mithilfe der Windows AI-APIs finden Sie unter "Erste Schritte beim Erstellen einer App mit Windows AI-APIs".

Angeben der erforderlichen Namespaces

Die strukturierte JSON-Ausgabe-API wird im Microsoft.Windows.AI.Text.Experimental-Namespace des experimentellen Windows App SDK-Kanals ausgeliefert, der die Microsoft.Windows.AI.Text-API im stabilen Kanal erweitert. Fügen Sie ihrer Datei beide Namespaces hinzu, damit Sie Zugriff auf die Kernklasse LanguageModel und den experimentellen LanguageModelExperimental-Wrapper haben, der für die strukturierte Generierung verwendet wird:

using Microsoft.Windows.AI;
using Microsoft.Windows.AI.Text;
using Microsoft.Windows.AI.Text.Experimental;

Generieren einer strukturierten JSON-Antwort

Im folgenden Beispiel wird eine Eingabeaufforderung in natürlicher Sprache an das On-Device-Phi-Silikadikatmodell gesendet, wobei die Ausgabe auf ein JSON-Schema beschränkt wird, das eine Person mit einem Namen und Alter beschreibt.

  1. Stellen Sie sicher, dass das Sprachmodell verfügbar ist, indem Sie GetReadyState aufrufen und darauf warten, dass EnsureReadyAsync erfolgreich zurückgegeben wird. Möglicherweise muss das Modell auf dem Gerät heruntergeladen oder initialisiert werden, wenn es zum ersten Mal verwendet wird.

  2. Erstellen Sie ein LanguageModel-Objekt , und umschließen Sie es dann in einer LanguageModelExperimental-Instanz . Die stabile LanguageModel-Klasse macht noch keine strukturierte Ausgabe verfügbar, daher ist der experimentelle Wrapper erforderlich.

  3. Definieren Sie Ihr JSON-Schema als unformatierte JSON-Zeichenfolge (kein deserialisiertes Objekt). Dieses Schema verwendet die API, um die Ausgabe des Modells einzuschränken und zu überprüfen.

  4. Rufen Sie GenerateStructuredJsonResponseAsync mit Ihrer Eingabeaufforderung, der Schemazeichenfolge und einem Optionsobjekt auf.

  5. Überprüfen Sie result.Status, bevor Sie die Ausgabe nutzen. Ein Status "Abgeschlossen " bedeutet, dass der zurückgegebene JSON-Code anhand Ihres Schemas überprüft wurde. Ein Status von ResponseInvalidJson bedeutet, dass das Modell Text erzeugt hat, der nicht konform ist (result.Text ist noch verfügbar, aber möglicherweise nicht übereinstimmen).

if (LanguageModel.GetReadyState() == AIFeatureReadyState.NotReady)
{
    await LanguageModel.EnsureReadyAsync();
}

using LanguageModel languageModel = await LanguageModel.CreateAsync();
using LanguageModelExperimental experimentalModel = new LanguageModelExperimental(languageModel);

string prompt = "Give me information about a 30-year-old software engineer named Alice.";

string jsonSchema = @"
{
    ""type"": ""object"",
    ""properties"": {
        ""name"": { ""type"": ""string"" },
        ""age"": { ""type"": ""integer"" },
        ""occupation"": { ""type"": ""string"" }
    },
    ""required"": [""name"", ""age"", ""occupation""]
}";

// Use options to tune Temperature, TopP, TopK, or attach a LoRA adapter.
var options = new LanguageModelOptionsExperimental();

var result = await experimentalModel.GenerateStructuredJsonResponseAsync(
    prompt, jsonSchema, options);

if (result.Status == LanguageModelResponseStatus.Complete)
{
    Console.WriteLine(result.Text);
}
else
{
    Console.WriteLine($"Generation failed with status: {result.Status}");
}

Die von diesem Beispiel generierte Antwort lautet:

{
    "name": "Alice",
    "age": 30,
    "occupation": "software engineer"
}

Unterstützte JSON-Schema-Funktionen

Die API unterstützt eine Teilmenge der JSON-Schemaspezifikation . Wenn Ihr Schema nur die unten aufgeführten Features verwendet, entspricht die generierte Ausgabe diesem. Funktionen, die hier nicht aufgeführt sind (z.B. $ref, oneOf, anyOf, patternProperties oder additionalProperties), werden derzeit nicht unterstützt.

Keyword Beschreibung Beispiel
type Beschränkt einen Wert auf einen bestimmten JSON-Typ. Unterstützte Typen: string, , integer, numberboolean, object, , array. null "type": "string"
properties Definiert die erwarteten Schlüssel und deren Typen für ein object. Die Schachtelung wird unterstützt – jede Eigenschaft kann selbst ein object mit seinem eigenen properties sein. "properties": { "name": { "type": "string" } }
required Stellt sicher, dass die angegebenen Eigenschaften in der generierten Ausgabe vorhanden sind. "required": ["name", "age"]
enum Schränkt einen Wert auf einen vordefinierten Satz von Optionen ein. "enum": ["red", "green", "blue"]
items Definiert den Typ oder das Schema für Elemente in einem array. "items": { "type": "integer" }

Wichtige Überlegungen

  • Wasserzeichen in allgemeinen Textantworten: Wenn Sie JSON mit GenerateResponseAsync anstelle der in diesem Artikel beschriebenen strukturierten Ausgabe-API generieren, stellen Sie sicher, dass Ihre Analyselogik das unsichtbare Wasserzeichen verarbeiten kann. Siehe Watermarking in Windows-KI-Text-APIs.

  • Kein Unterhaltungskontext: Im Gegensatz zu GenerateResponseAsync akzeptiert diese Methode kein LanguageModelContext. Jeder Anruf ist eigenständig – Sie können keinen früheren Unterhaltungsverlauf in eine strukturierte Ausgabeanforderung übertragen.

  • Schemaüberprüfung: Der jsonSchema Parameter muss eine nicht leere, gültige JSON-Zeichenfolge sein, die ein JSON-Objekt darstellt. Die Methode löst ArgumentException aus, wenn die Zeichenfolge leer ist, kein gültiges JSON ist oder kein JSON-Objekt ist (z. B. wenn ein JSON-Array wie [1, 2, 3] übergeben wird). Das Übergeben eines gültigen JSON-Objekts, das nicht unterstützte Schemastichwörter verwendet, löst nicht aus, kann jedoch zu unerwarteten Ausgaben führen.

  • Leistung: Bei der strukturierten Ausgabe wird eine iterative, eingeschränkte Decodierungsstrategie verwendet. Daher ist mit einer höheren Latenz zu rechnen als bei einem gleichwertigen GenerateResponseAsync-Aufruf. Die Methode gibt einen IAsyncOperationWithProgress zurück, damit Sie den Fortschritt tokenweise dem Benutzer berichten können.

  • Fortschrittsbericht: Wie bei anderen Erzeugungsmethoden gibt GenerateStructuredJsonResponseAsync einen IAsyncOperationWithProgress zurück, sodass Sie den Fortschritt Token für Token während der Generierung überwachen können.

  • Fehlerbehandlung: Der jsonSchema Parameter muss eine nicht leere, gültige JSON-Zeichenfolge sein, die ein JSON-Objekt darstellt. Die Methode löst ArgumentException aus, wenn das Schema leer ist, kein gültiges JSON oder kein JSON-Objekt (zum Beispiel wird das Übergeben eines JSON-Arrays wie [1, 2, 3] einen Fehler auslösen). Umschließen Sie Aufrufe in einem „try/catch”, um mit ungültigen Schemas ordnungsgemäß umzugehen.

API-Referenz

Klasse / Methode Beschreibung
LanguageModelExperimental Umschließt eine LanguageModel-Instanz und macht experimentelle Features verfügbar, einschließlich strukturierter JSON-Ausgabe und Laden des LoRA-Adapters.
GenerateStructuredJsonResponseAsync(String, String, LanguageModelOptionsExperimental) Generiert eine eingeschränkte Sprachmodellantwort, die dem bereitgestellten JSON-Schema entspricht.
LanguageModelOptionsExperimental Optionen für experimentelle Erzeugungsmethoden, einschließlich Temperature, TopP, TopK, ContentFilterOptions und LowRankAdapter.