开放模型的结构化输出

结构化输出功能可让模型生成始终遵循特定架构的输出。例如,可以为模型提供响应架构,以确保响应生成有效的 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 响应。

后续步骤