Salida estructurada para modelos abiertos

Los resultados estructurados permiten que un modelo genere resultados que siempre se ajusten a un esquema específico. Por ejemplo, se puede proporcionar a un modelo un esquema de respuesta para asegurarse de que la respuesta genere un JSON válido. Todos los modelos abiertos disponibles en Vertex AI Model as a Service (MaaS) admiten salidas estructuradas.

Para obtener más información conceptual sobre la función de salida estructurada, consulta el artículo Introducción a la salida estructurada.

Usar resultados estructurados

En el siguiente caso práctico se define un esquema de respuesta que asegura que el resultado del modelo sea un objeto JSON con las siguientes propiedades: name, date y participants. El código de Python usa el SDK de OpenAI y los objetos de Pydantic para generar el 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)

La salida del modelo se ajustará al siguiente esquema JSON:

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

Si se le da la petición "Alice and Bob are going to a science fair on Friday" ("Alice y Bob van a una feria de ciencias el viernes"), el modelo podría generar la siguiente respuesta:

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

Ejemplo detallado

El siguiente código es un ejemplo de un esquema recursivo. La clase UI contiene una lista de children, que también pueden ser de la clase 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)

La salida del modelo se ajustará al esquema del objeto Pydantic especificado en el fragmento anterior. En este ejemplo, el modelo podría generar el siguiente formulario de interfaz de usuario:

Form
  Input
    Name
    Email
    Age

Una respuesta podría tener este aspecto:

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

Obtener respuestas de objetos JSON

Puedes limitar el modelo para que solo genere objetos JSON sintácticamente válidos si asignas el valor { "type": "json_object" } al campo response_format. A menudo se denomina modo JSON. El modo JSON es útil cuando se genera JSON para usarlo con llamadas a funciones u otras tareas posteriores que requieren una entrada JSON.

Cuando el modo JSON está habilitado, el modelo solo puede generar cadenas que se analicen en objetos JSON válidos. Aunque este modo asegura que el resultado sea un JSON sintácticamente correcto, no aplica ningún esquema específico. Para asegurarte de que el modelo genera JSON que sigue un esquema específico, debes incluir instrucciones en la petición, tal como se muestra en el siguiente ejemplo.

En los siguientes ejemplos se muestra cómo habilitar el modo JSON e indicar al modelo que devuelva un objeto JSON con una estructura específica:

Python

Antes de probar este ejemplo, sigue las Python instrucciones de configuración de la guía de inicio rápido de Vertex AI con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Python de Vertex AI.

Para autenticarte en Vertex AI, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.

Antes de ejecutar este ejemplo, asegúrate de definir la variable de entorno OPENAI_BASE_URL. Para obtener más información, consulta Autenticación y credenciales.

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)

Sustituye MODEL por el nombre del modelo que quieras usar, por ejemplo, meta/llama3-405b-instruct-maas.

REST

Después de configurar tu entorno, puedes usar REST para probar una petición de texto. En el siguiente ejemplo se envía una solicitud al endpoint del modelo del editor.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • PROJECT_ID: tu ID de proyecto de Google Cloud.
  • LOCATION: una región que admite modelos abiertos.
  • MODEL: el nombre del modelo que quieras usar, por ejemplo, meta/llama3-405b-instruct-maas.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud: 

{
  "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 tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente 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

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente 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

Deberías recibir una respuesta JSON similar a la siguiente.

Siguientes pasos