Generare output strutturati (come JSON) utilizzando l'API Gemini


Per impostazione predefinita, Gemini API restituisce le risposte come testo non strutturato. Tuttavia, alcuni casi d'uso richiedono testo strutturato, come JSON. Ad esempio, potresti utilizzare la risposta per altre attività a valle che richiedono uno schema di dati stabilito.

Per assicurarti che l'output generato dal modello rispetti sempre uno schema specifico, puoi definire uno schema di risposta, che funge da modello per le risposte del modello. In questo modo, puoi estrarre direttamente i dati dall'output del modello con meno post-elaborazione.

Ecco alcuni esempi:

  • Assicurati che la risposta di un modello generi JSON valido e sia conforme allo schema fornito.
    Ad esempio, il modello può generare voci strutturate per le ricette che includono sempre il nome della ricetta, l'elenco degli ingredienti e i passaggi. In questo modo, potrai analizzare e visualizzare più facilmente queste informazioni nell'interfaccia utente della tua app.

  • Limita il modo in cui un modello può rispondere durante le attività di classificazione.
    Ad esempio, puoi chiedere al modello di annotare il testo con un insieme specifico di etichette (ad esempio, un insieme specifico di enum come positive e negative) anziché con le etichette prodotte dal modello (che potrebbero avere un grado di variabilità come good, positive, negative o bad).

Questa guida illustra come generare output JSON fornendo un responseSchema in una chiamata a generateContent. Si concentra sull'input di solo testo, ma Gemini può anche produrre risposte strutturate a richieste multimodali che includono immagini, video e audio come input.

Nella parte inferiore di questa pagina sono riportati altri esempi, ad esempio come generare valori enum come output. Per visualizzare altri esempi di come generare output strutturato, consulta l'elenco di schemi di esempio e risposte del modello nella documentazione di Google Cloud.

Prima di iniziare

Se non l'hai ancora fatto, completa la guida introduttiva agli SDK Vertex AI in Firebase. Assicurati di aver eseguito tutte le seguenti operazioni:

  1. Configura un progetto Firebase nuovo o esistente, ad esempio utilizzando il piano di prezzi Blaze e attivando le API richieste.

  2. Collega la tua app a Firebase, inclusa la registrazione e l'aggiunta della configurazione Firebase.

  3. Aggiungi l'SDK e inizializza il servizio Vertex AI e il modello generativo nella tua app.

Dopo aver collegato l'app a Firebase, aggiunto l'SDK e inizializzato il servizio Vertex AI e il modello generativo, puoi chiamare Gemini API.

Passaggio 1: definisci uno schema di risposta

Definisci uno schema di risposta per specificare la struttura dell'output di un modello, i nomi dei campi e il tipo di dati previsto per ogni campo.

Quando un modello genera la sua risposta, utilizza il nome e il contesto del campo del prompt. Per chiarire le tue intenzioni, ti consigliamo di utilizzare una struttura chiara, nomi di campi non ambigui e anche descrizioni, se necessario.

Considerazioni per gli schemi di risposta

Quando scrivi lo schema di risposta, tieni presente quanto segue:

  • Le dimensioni dello schema di risposta vengono conteggiate ai fini del limite di token di input.

  • La funzionalità dello schema di risposta supporta i seguenti tipi MIME di risposta:

    • application/json: output JSON come definito nello schema di risposta (utile per i requisiti di output strutturato)

    • text/x.enum: restituisce un valore enum come definito nello schema di risposta (utile per le attività di classificazione)

  • La funzionalità dello schema di risposta supporta i seguenti campi dello schema:

    enum
    items
    		 maxItems
    nullable
    		 properties
    required

    Se utilizzi un campo non supportato, il modello può comunque gestire la tua richiesta, ma ignora il campo. Tieni presente che l'elenco riportato sopra è un sottoinsieme dell'oggetto schema di OpenAPI 3.0 (consulta il riferimento allo schema di Vertex AI).

  • Per impostazione predefinita, per gli SDK Vertex AI in Firebase tutti i campi sono considerati obbligatori, a meno che non li specifichi come facoltativi in un array optionalProperties. Per questi campi facoltativi, il modello può completarli o ignorarli.

    Tieni presente che questo è opposto al comportamento predefinito per Vertex AI Gemini API.

Passaggio 2: invia un prompt con uno schema di risposta per generare JSON

Il seguente esempio mostra come generare un output JSON strutturato.

Per generare un output strutturato, devi specificare durante l'inizializzazione del modello il responseMimeType appropriato (in questo esempio application/json) nonché il responseSchema che vuoi che il modello utilizzi.

L'utilizzo di responseSchema è supportato da Gemini 1.5 Pro e Gemini 1.5 Flash.

Scopri come scegliere un modello Gemini e, facoltativamente, una posizione appropriata per il tuo caso d'uso e la tua app.

Altri esempi

Per visualizzare altri esempi di come utilizzare e generare output strutturato, consulta l'elenco di schemi di esempio e risposte del modello nella documentazione di Google Cloud.

Genera valori enum come output

L'esempio seguente mostra come utilizzare uno schema di risposta per un'attività di classificazione. Al modello viene chiesto di identificare il genere di un film in base alla sua descrizione. L'output è un valore enumerato in testo normale selezionato dal modello da un elenco di valori definiti nello schema di risposta fornito.

Per eseguire questa attività di classificazione strutturata, devi specificare durante l'inizializzazione del modello il responseMimeType appropriato (in questo esempio, text/x.enum) e il responseSchema che vuoi che il modello utilizzi.

Scopri come scegliere un modello Gemini e, facoltativamente, una posizione appropriata per il tuo caso d'uso e la tua app.

Altre opzioni per controllare la generazione di contenuti

  • Scopri di più sul design dei prompt per poter influenzare il modello in modo che generi output specifici per le tue esigenze.
  • Configura i parametri del modello per controllare il modo in cui il modello genera una risposta. Questi parametri includono token di output massimi, temperatura, topK e topP.
  • Utilizza le impostazioni di sicurezza per regolare la probabilità di ricevere risposte che potrebbero essere considerate dannose, tra cui incitamento all'odio e contenuti sessualmente espliciti.
  • Imposta le istruzioni di sistema per indirizzare il comportamento del modello. Questa funzionalità è simile a un "preambolo" che viene aggiunto prima che il modello venga esposto ad eventuali ulteriori istruzioni dell'utente finale.


Inviare un feedback sulla tua esperienza con Vertex AI in Firebase