Output strutturato per i modelli aperti

Gli output strutturati consentono a un modello di generare output che aderiscono sempre a uno schema specifico. Ad esempio, a un modello può essere fornito uno schema di risposta per garantire che la risposta produca JSON valido. Tutti i modelli open source disponibili sulla Gemini Enterprise Agent Platform Model as a Service (MaaS) supportano gli output strutturati.

Per ulteriori informazioni concettuali sulla funzionalità di output strutturato, consulta Introduzione all'output strutturato.

Utilizzare gli output strutturati

Il seguente caso d'uso imposta uno schema di risposta che garantisce che l'output del modello sia un oggetto JSON con le seguenti proprietà: nome, data e partecipanti. Il codice Python utilizza gli oggetti OpenAI SDK e Pydantic per generare lo schema JSON.

from pydantic import BaseModel
from openai import OpenAI

client = OpenAI()

class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]

completion = client.beta.chat.completions.parse(
    model="MODEL_NAME",
    messages=[
        {"role": "system", "content": "Extract the event information."},
        {"role": "user", "content": "Alice and Bob are going to a science fair on Friday."},
    ],
    response_format=CalendarEvent,
)

print(completion.choices[0].message.parsed)

L'output del modello rispetterà il seguente schema JSON:

{ "name": STRING, "date": STRING, "participants": [STRING] }

Quando viene fornito il prompt "Alice e Bob andranno a una fiera della scienza venerdì", il modello potrebbe produrre la seguente risposta:

{
  "name": "science fair",
  "date": "Friday",
  "participants": [
    "Alice",
    "Bob"
  ]
}

Esempio dettagliato

Il seguente codice è un esempio di schema ricorsivo. La classe UI contiene un elenco di children, che possono anche essere della classe UI.

from pydantic import BaseModel
from openai import OpenAI
from enum import Enum
from typing import List

client = OpenAI()

class UIType(str, Enum):
  div = "div"
  button = "button"
  header = "header"
  section = "section"
  field = "field"
  form = "form"

class Attribute(BaseModel):
  name: str
  value: str

class UI(BaseModel):
  type: UIType
  label: str
  children: List["UI"]
  attributes: List[Attribute]

UI.model_rebuild() # This is required to enable recursive types

class Response(BaseModel):
  ui: UI

completion = client.beta.chat.completions.parse(
  model="MODEL_NAME",
  messages=[
    {"role": "system", "content": "You are a UI generator AI. Convert the user input into a UI."},
    {"role": "user", "content": "Make a User Profile Form"}
  ],
  response_format=Response,
)

print(completion.choices[0].message.parsed)

L'output del modello rispetterà lo schema dell'oggetto Pydantic specificato nello snippet precedente. In questo esempio, il modello potrebbe generare il seguente modulo UI:

Form
  Input
    Name
    Email
    Age

Una risposta potrebbe essere simile alla seguente:

ui = UI(
    type=UIType.div,
    label='Form',
    children=[
        UI(
            type=UIType.div,
            label='Input',
            children=[],
            attributes=[
                Attribute(name='label', value='Name')
            ]
        ),
        UI(
            type=UIType.div,
            label='Input',
            children=[],
            attributes=[
                Attribute(name='label', value='Email')
            ]
        ),
        UI(
            type=UIType.div,
            label='Input',
            children=[],
            attributes=[
                Attribute(name='label', value='Age')
            ]
        )
    ],
    attributes=[
        Attribute(name='name', value='John Doe'),
        Attribute(name='email', value='john.doe@example.com'),
        Attribute(name='age', value='30')
    ]
)

Ottenere risposte di oggetti JSON

Puoi vincolare il modello a restituire solo oggetti JSON sintatticamente validi impostando il campo response_format su { "type": "json_object" }. Questa modalità viene spesso chiamata modalità JSON. La modalità JSON è utile quando si genera JSON da utilizzare con la chiamata di funzioni o altre attività downstream che richiedono input JSON.

Quando la modalità JSON è abilitata, il modello è vincolato a generare solo stringhe che vengono analizzate in oggetti JSON validi. Sebbene questa modalità garantisca che l'output sia JSON sintatticamente corretto, non applica uno schema specifico. Per assicurarti che il modello restituisca JSON che segue uno schema specifico, devi includere le istruzioni nel prompt, come mostrato nell'esempio seguente.

Gli esempi seguenti mostrano come abilitare la modalità JSON e indicare al modello di restituire un oggetto JSON con una struttura specifica:

Python

Prima di provare questo esempio, segui le istruzioni di configurazione Python nella guida rapida di Agent Platform per l'utilizzo delle librerie client.

Per eseguire l'autenticazione in Agent Platform, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

Prima di eseguire questo esempio, assicurati di impostare la variabile di ambiente OPENAI_BASE_URL. Per saperne di più, consulta Autenticazione e credenziali.

from openai import OpenAI
client = OpenAI()

response = client.chat.completions.create(
  model="MODEL",
  response_format={ "type": "json_object" },
  messages=[
    {"role": "user", "content": "List 5 rivers in South America. Your response must be a JSON object with a single key \"rivers\", which has a list of strings as its value."},
  ]
)
print(response.choices[0].message.content)

Sostituisci MODEL con il nome del modello che vuoi utilizzare, ad esempio meta/llama3-405b-instruct-maas.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud.
  • LOCATION: una regione che supporta i modelli open source.
  • MODEL: il nome del modello che vuoi utilizzare, ad esempio meta/llama3-405b-instruct-maas.

Metodo HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions

Corpo JSON della richiesta: 

{
  "model": "MODEL",
  "response_format": {
    "type": "json_object"
  },
  "messages": [
    {
      "role": "user",
      "content": "List 5 rivers in South America. Your response must be a JSON object with a single key \"rivers\", which has a list of strings as its value."
    }
  ]
}

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions"

PowerShell

Salva il corpo della richiesta in un file denominato request.json, e quindi esegui il comando seguente: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente.

Passaggi successivi