开放模型的结构化输出

结构化输出功能可让模型生成始终遵循特定架构的输出。例如，可以为模型提供响应架构，以确保响应生成有效的 JSON。Vertex AI 模型即服务 (MaaS) 上提供的所有开放模型均支持结构化输出。

如需详细了解结构化输出功能的概念性信息，请参阅结构化输出简介。

使用结构化输出

以下用例设置了一个回答架构，该架构可确保模型输出是一个具有以下属性的 JSON 对象：name、date 和 participants。Python 代码使用 OpenAI SDK 和 Pydantic 对象生成 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)

模型输出将遵循以下 JSON 架构：

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

如果向模型提供提示“Alice and Bob are going to a science fair on Friday”，模型可能会生成以下回答：

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

详细示例

以下代码是一个递归架构示例。UI 类包含 children 的列表，该列表也可以是 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)

模型输出将遵循上一个代码段中指定的 Pydantic 对象的架构。在此示例中，模型可以生成以下界面表单：

Form
  Input
    Name
    Email
    Age

响应可能如下所示：

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

获取 JSON 对象响应

您可以将 response_format 字段设置为 { "type": "json_object" }，以限制模型仅输出语法有效的 JSON 对象。这通常称为 JSON 模式。当生成 JSON 以用于函数调用或其他需要 JSON 输入的下游任务时，JSON 模式非常有用。

启用 JSON 模式后，模型只能生成可解析为有效 JSON 对象的字符串。虽然此模式可确保输出是语法正确的 JSON，但不会强制执行任何特定架构。为确保模型输出符合特定架构的 JSON，您必须在提示中添加说明，如以下示例所示。

以下示例展示了如何启用 JSON 模式并指示模型返回具有特定结构的 JSON 对象：

Python

在尝试此示例之前，请按照《Vertex AI 快速入门：使用客户端库》中的 Python 设置说明执行操作。 如需了解详情，请参阅 Vertex AI Python API 参考文档。

如需向 Vertex AI 进行身份验证，请设置应用默认凭证。 如需了解详情，请参阅为本地开发环境设置身份验证。

在运行此示例之前，请务必设置 OPENAI_BASE_URL 环境变量。如需了解详情，请参阅身份验证和凭据。

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)

将 MODEL 替换为您要使用的模型名称，例如 meta/llama3-405b-instruct-maas。

REST

设置您的环境后，您可以使用 REST 测试文本提示。以下示例会向发布方模型端点发送请求。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您的 Google Cloud 项目 ID。
  • LOCATION：支持开放模型的区域。
  • MODEL：您要使用的模型名称，例如 meta/llama3-405b-instruct-maas。

HTTP 方法和网址：

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

请求 JSON 正文： 

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

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

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

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

$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

您应该收到类似以下内容的 JSON 响应。

后续步骤