xAI 文档
首页/文本能力/结构化输出

结构化输出

结构化输出让 API 以特定格式返回响应，例如匹配你定义的 JSON Schema 的对象。

此功能特别适用于文档解析、实体提取和报告生成等任务。使用支持的 Schema 功能时， 响应保证匹配你的 Schema。

有两种方式从模型请求结构化输出：

  • response_format 参数 — 设置 response_format.type 为 "json_schema" 并提供你的 Schema。也接受 "json_object"（任意格式良好的 JSON）和 "text"（默认，自由文本）。
  • 工具调用 — 定义工具时，xAI 模型始终生成严格遵循工具输入 JSON Schema 的工具调用参数（strict 标志隐式始终为 true）。

可以使用 Pydantic 或 Zod 等库定义 Schema。

JSON Schema 支持

我们支持 JSON Schema 的一个实用子集。使用 Draft 2020-12 编写的 Schema 效果最佳；也接受 Draft-07 Schema。

支持的类型

  • string, number, integer, boolean, null
  • enum, const
  • array, object
  • anyOf, oneOf（行为与 anyOf 相同）
  • allOf（仅单个子 Schema）
  • $ref / $defs（仅非循环引用）

additionalProperties 默认为 false，必须显式设置为 true。

字符串格式

以下 format 值会被强制执行：

date · time · date-time · email · uuid · ipv4 · ipv6 · uri

约束限制

关键字保证上限
minimum / maximum / exclusiveMinimum / exclusiveMaximum无限制
minLength / maxLength2,048
minItems / maxItems256
minProperties / maxProperties64

示例：发票解析

结构化输出的常见用例是解析原始文档。例如，从发票中提取供应商详情、金额和日期。

第 1 步：定义 Schema

Python (Pydantic)
from datetime import date
from enum import Enum
from pydantic import BaseModel, Field

class Currency(str, Enum):
    USD = "USD"
    EUR = "EUR"
    CNY = "CNY"

class LineItem(BaseModel):
    description: str = Field(description="项目描述")
    quantity: int = Field(description="数量", ge=1)
    unit_price: float = Field(description="单价", ge=0)

class Invoice(BaseModel):
    vendor_name: str = Field(description="供应商名称")
    vendor_address: str = Field(description="供应商地址")
    invoice_number: str = Field(description="发票编号")
    invoice_date: date = Field(description="发票日期")
    line_items: list[LineItem] = Field(description="行项目")
    total_amount: float = Field(description="总金额", ge=0)
    currency: Currency = Field(description="货币")

第 2 步：使用结构化输出

Python (OpenAI)
from openai import OpenAI
from pydantic import BaseModel

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
)

response = client.responses.parse(
    model="grok-4.5",
    input=[
        {"role": "system", "content": "Extract invoice data from the provided text."},
        {"role": "user", "content": "Invoice from ACME Corp..."},
    ],
    text_format=Invoice,
)

invoice = response.output_parsed
print(invoice.vendor_name)
print(invoice.total_amount)

正则表达式支持 (pattern)

在字符串字段上使用 pattern 关键字时，我们支持 ECMAScript 正则表达式的一个实用子集。

支持：

  • 字面量和字符类（[abc], [a-z], [^abc]）
  • .（匹配任何 Unicode 码点，包括换行符）
  • 交替 |、分组 (...) 和非捕获组 (?:...)
  • 量词 *, +, ? 和重复范围 {n}, {n,}, {n,m}
  • 简写类 \d, \w, \s（及其否定 \D, \W, \S）

不支持：

  • 反向引用（\1, \k<name> 等）
  • Unicode 属性转义（\p{L}, \P{Letter}）
  • 单词边界（\b, \B）
  • 前瞻和后顾（(?=...), (?<=...) 等）