Saída estruturada para modelos abertos

Com as saídas estruturadas, um modelo pode gerar resultados que sempre seguem um esquema específico. Por exemplo, um modelo pode receber um esquema de resposta para garantir que a resposta produza um JSON válido. Todos os modelos abertos disponíveis no Modelo como serviço (MaaS) da Vertex AI oferecem suporte a saídas estruturadas.

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

Usar respostas estruturadas

O caso de uso a seguir define um esquema de resposta que garante que a saída do modelo seja um objeto JSON com as seguintes propriedades: nome, data e participantes. O código Python usa o SDK da OpenAI e 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 obedecer ao seguinte esquema JSON:

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

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

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

exemplo detalhado

O código a seguir é um exemplo de 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 obedecer ao esquema do objeto Pydantic especificado no snippet anterior. Neste exemplo, o modelo pode gerar o seguinte formulário de UI:

Form
  Input
    Name
    Email
    Age

Uma resposta pode ser semelhante a esta:

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

Receber respostas de objetos JSON

É possível restringir o modelo para gerar apenas objetos JSON sintaticamente válidos definindo o campo response_format como { "type": "json_object" }. Isso geralmente é chamado de modo JSON. O modo JSON é útil ao gerar JSON para uso com chamadas de função ou outras tarefas downstream que exigem entrada JSON.

Quando o modo JSON está ativado, o modelo só gera strings que podem ser analisadas em objetos JSON válidos. Embora esse modo garanta que a saída seja um JSON sintaticamente correto, ele não impõe nenhum esquema específico. Para garantir que o modelo gere JSON de acordo com um esquema específico, inclua instruções no comando, como mostrado no exemplo a seguir.

Os exemplos a seguir mostram como ativar o modo JSON e instruir o modelo a retornar um objeto JSON com uma estrutura específica:

Python

Antes de testar esse exemplo, siga as instruções de configuração para Python no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Python.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Antes de executar esta amostra, defina a variável de ambiente OPENAI_BASE_URL. Para mais informações, consulte 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 você quer usar, por exemplo, meta/llama3-405b-instruct-maas.

REST

Depois de configurou seu ambiente use REST para testar uma solicitação de texto. O exemplo a seguir envia uma solicitação ao publisher endpoint do modelo.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID pelo ID do projeto no Google Cloud.
  • LOCATION: uma região compatível com modelos abertos.
  • MODEL: o nome do modelo que você 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 da solicitação:

{
  "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 a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo: 

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

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$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

Você receberá uma resposta JSON semelhante a seguinte.

A seguir