Generare un output JSON strutturato con Phi Silica

Le risposte di testo in linguaggio naturale generate dal modello Phi Silica possono essere vincolate a json validi conformi a uno schema JSON definito dall'utente. Ciò è utile per estrarre dati strutturati dal linguaggio naturale, popolare i campi del modulo o passare risultati a un'API.

Prerequisiti

Per informazioni sui requisiti hardware dell'API di intelligenza artificiale Windows e su come configurare il dispositivo per compilare correttamente le app usando le API di intelligenza artificiale Windows, vedere Introduzione alla creazione di un'app con API di intelligenza artificiale Windows.

Specificare i namespace richiesti

L'API di output JSON strutturato è inclusa nello spazio dei nomi Microsoft.Windows.AI.Text.Experimental del canale sperimentale di SDK per app di Windows, che estende l'API Microsoft.Windows.AI.Text nel canale stabile. Aggiungi entrambi i namespace al file in modo da avere accesso alla classe LanguageModel principale e al wrapper sperimentale LanguageModelExperimental utilizzato per la generazione strutturata.

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

#include "winrt/Microsoft.Windows.AI.Text.h"
#include "winrt/Microsoft.Windows.AI.Text.Experimental.h"
using namespace Microsoft::Windows::AI;
using namespace Microsoft::Windows::AI::Text;
using namespace Microsoft::Windows::AI::Text::Experimental;

Generare una risposta JSON strutturata

L'esempio seguente invia un prompt in linguaggio naturale al modello Phi Silica sul dispositivo, vincolando l'output a uno schema JSON che descrive una persona con un nome e un'età.

1. Verificare che il modello linguistico sia disponibile chiamando GetReadyState e aspettando che EnsureReadyAsync venga restituito correttamente. Potrebbe essere necessario scaricare o inizializzare il modello sul dispositivo la prima volta che viene usato.

2. Creare un oggetto LanguageModel, quindi racchiuderlo in un'istanza LanguageModelExperimental. La classe LanguageModel stabile non espone ancora l'output strutturato, quindi è necessario il wrapper sperimentale.

3. Definire lo schema JSON come stringa JSON non elaborata (non come oggetto deserializzato). Questo schema è ciò che l'API usa per vincolare e convalidare l'output del modello.

4. Chiamare GenerateStructuredJsonResponseAsync con il prompt, la stringa dello schema e un oggetto opzioni.

5. Controllare result.Status prima di utilizzare l'output. Lo stato Complete indica che il codice JSON restituito è stato convalidato rispetto allo schema. Uno stato di ResponseInvalidJson indica che il modello ha prodotto testo non conforme (result.Text è ancora disponibile, ma potrebbe non corrispondere).

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}");
}

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

auto languageModel = LanguageModel::CreateAsync().get();
auto experimentalModel = LanguageModelExperimental(languageModel);

const winrt::hstring prompt = L"Give me information about a 30-year-old software engineer named Alice.";

const winrt::hstring jsonSchema = LR"(
{
    "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.
LanguageModelOptionsExperimental options;

auto result = experimentalModel.GenerateStructuredJsonResponseAsync(
    prompt, jsonSchema, options).get();

if (result.Status() == LanguageModelResponseStatus::Complete)
{
    std::cout << result.Text().c_str() << std::endl;
}
else
{
    std::cout << "Generation failed with status: "
              << static_cast<int32_t>(result.Status()) << std::endl;
}

La risposta generata da questo esempio è:

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

Funzionalità dello schema JSON supportate

L'API supporta un subset della specifica dello schema JSON . Se lo schema usa solo le funzionalità elencate di seguito, l'output generato sarà conforme. Le funzionalità non elencate di seguito ( ad esempio $ref, oneOfanyOf, patternProperties, o additionalProperties) non sono attualmente supportate.

Considerazioni importanti

• Filigrana nelle risposte di testo generali: se si genera JSON con GenerateResponseAsync anziché l'API di output strutturata descritta in questo articolo, assicurarsi che la logica di analisi possa gestire la filigrana invisibile. Vedi Watermarking nelle API di testo di Windows AI.

• Nessun contesto di conversazione: a differenza di GenerateResponseAsync, questo metodo non accetta languageModelContext. Ogni chiamata è autonoma: non è possibile portare la cronologia precedente della conversazione in una richiesta di output strutturata.

• Convalida dello schema: il jsonSchema parametro deve essere una stringa JSON non vuota e valida che rappresenta un oggetto JSON. Il metodo genera un'eccezione ArgumentException se la stringa è vuota, non è json valido o non è un oggetto JSON, ad esempio passando una matrice JSON come [1, 2, 3]. Il passaggio di un oggetto JSON valido che usa parole chiave dello schema non supportate non genera un'eccezione, ma può produrre output imprevisto.

• Prestazioni: l'output strutturato usa una strategia iterativa di decodifica vincolata, quindi prevedere una latenza superiore rispetto a una chiamata GenerateResponseAsync equivalente. Il metodo restituisce un IAsyncOperationWithProgress, in modo da poter segnalare all'utente i progressi token per token durante la generazione.

• Creazione di report di stato di avanzamento: come altri metodi di generazione, GenerateStructuredJsonResponseAsync restituisce un IAsyncOperationWithProgressoggetto, in modo da poter monitorare lo stato di avanzamento dei token per token durante la generazione.

• Gestione degli errori: il jsonSchema parametro deve essere una stringa JSON non vuota e valida che rappresenta un oggetto JSON. Il metodo genera ArgumentException un'eccezione se lo schema è vuoto, non è valido JSON o non è un oggetto JSON, ad esempio passando una matrice JSON come [1, 2, 3] verrà generata. Eseguire il wrapping delle chiamate in un try/catch per gestire gli schemi non validi normalmente.

Informazioni di riferimento sulle API