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