Output strutturato per i modelli aperti

Gli output strutturati consentono a un modello di generare output che rispetta sempre uno schema specifico. Ad esempio, a un modello può essere fornito uno schema di risposta per assicurarsi che la risposta produca un JSON valido. Tutti i modelli aperti disponibili su Vertex AI Model as a Service (MaaS) supportano output strutturati.

Per maggiori informazioni concettuali sulla funzionalità di output strutturato, consulta la pagina Introduzione all'output strutturato.

Utilizzare 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 l'SDK OpenAI e gli oggetti 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] }

Se 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 appartenere anche alla 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à è 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 è attivata, 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 impone uno schema specifico. Per assicurarti che il modello restituisca un output JSON che segue uno schema specifico, devi includere le istruzioni nel prompt, come mostrato nell'esempio seguente.

Gli esempi riportati di seguito mostrano come attivare 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 di Python nella guida rapida di Vertex AI per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Vertex AI Python.

Per eseguire l'autenticazione in Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, 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 ulteriori informazioni, vedi 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

Dopo aver configurato l'ambiente, puoi utilizzare REST per testare un prompt di testo. Il seguente esempio invia una richiesta all'endpoint del modello del publisher.

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

  • PROJECT_ID: l'ID del tuo progetto Google Cloud.
  • LOCATION: una regione che supporta modelli aperti.
  • 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, ed esegui questo comando: 

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, ed esegui questo comando: 

$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