Saída estruturada para modelos abertos

As saídas estruturadas permitem que um modelo gere uma saída que cumpre sempre um esquema específico. Por exemplo, pode ser fornecido a um modelo um esquema de resposta para garantir que a resposta produz um JSON válido. Todos os modelos abertos disponíveis no Vertex AI Model as a Service (MaaS) suportam resultados estruturados.

Para mais informações conceptuais sobre a capacidade de saída estruturada, consulte o artigo Introdução à saída estruturada.

Use resultados estruturados

O exemplo de utilização seguinte define um esquema de resposta que garante que a saída do modelo é um objeto JSON com as seguintes propriedades: name, date e participants. O código Python usa o SDK da OpenAI e os objetos Pydantic para gerar o esquema 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)

A saída do modelo vai seguir o seguinte esquema JSON:

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

Quando recebe o comando "A Alice e o Bob vão a uma feira de ciências na sexta-feira", o modelo pode produzir a seguinte resposta:

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

Exemplo detalhado

O código seguinte é um exemplo de um esquema recursivo. A classe UI contém uma lista de children, que também podem ser da 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)

A saída do modelo vai seguir o esquema do objeto Pydantic especificado no fragmento anterior. Neste exemplo, o modelo pode gerar o seguinte formulário de IU:

Form
  Input
    Name
    Email
    Age

Uma resposta pode ter o seguinte aspeto:

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')
    ]
)

Receba respostas de objetos JSON

Pode restringir o modelo para gerar apenas objetos JSON sintaticamente válidos definindo o campo response_format como { "type": "json_object" }. Esta opção é frequentemente denominada modo JSON. O modo JSON é útil quando gera JSON para utilização com chamadas de funções ou outras tarefas posteriores que requerem entrada JSON.

Quando o modo JSON está ativado, o modelo está restrito à geração apenas de strings que são analisadas em objetos JSON válidos. Embora este modo garanta que o resultado é um JSON sintaticamente correto, não impõe nenhum esquema específico. Para garantir que o modelo produz JSON que segue um esquema específico, tem de incluir instruções no comando, conforme mostrado no exemplo seguinte.

Os exemplos seguintes mostram como ativar o modo JSON e dar instruções ao modelo para devolver um objeto JSON com uma estrutura específica:

Python

Antes de experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do Vertex AI com bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Python Vertex AI.

Para se autenticar no Vertex AI, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

Antes de executar este exemplo, certifique-se de que define a variável de ambiente OPENAI_BASE_URL. Para mais informações, consulte o artigo Autenticação e credenciais.

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)

Substitua MODEL pelo nome do modelo que quer usar, por exemplo, meta/llama3-405b-instruct-maas.

REST

Depois de configurar o seu ambiente, pode usar a API REST para testar um comando de texto. O exemplo seguinte envia um pedido para o ponto final do modelo do publicador.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do seu projeto do Google Cloud.
  • LOCATION: Uma região que suporta modelos abertos.
  • MODEL: o nome do modelo que quer usar, por exemplo, meta/llama3-405b-instruct-maas.

Método HTTP e URL: 

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

Corpo JSON do pedido: 

{
  "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."
    }
  ]
}

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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

Deve receber uma resposta JSON semelhante à seguinte.

O que se segue?