文档
EN

指南

结构化输出

结构化输出是一项功能，它允许 API 以特定的、有组织的格式返回响应，例如 JSON 或您定义的其他架构。您收到的不是自由格式的文本，而是一致且易于解析的数据。grok.cadn.net.cn

它非常适合文档解析、实体提取或报告生成等任务，允许您使用 Pydantic 或 Zod 等工具定义架构，以强制执行数据类型、约束和结构。grok.cadn.net.cn

使用结构化输出时，可以保证 LLM 的响应与您的输入架构匹配。
结构化输出功能仅支持grok-2-1212型。


示例：发票解析

结构化输出的一个常见用例是解析原始文档。例如，发票包含供应商详细信息、金额和日期等结构化数据，但从原始文本中提取这些数据可能容易出错。结构化输出可确保提取的数据与预定义的架构匹配。grok.cadn.net.cn

假设您要从发票中提取以下数据：grok.cadn.net.cn

  • 供应商名称和地址
  • 发票编号和日期
  • 订单项（描述、数量、价格）
  • 总金额和货币

我们将使用结构化输出让 Grok 为此生成强类型 JSON。grok.cadn.net.cn

您可以使用 Pydantic 或 Zod 来定义架构。grok.cadn.net.cn

from pydantic import BaseModel, Field
from datetime import date
from enum import Enum
from typing import List

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

class LineItem(BaseModel):
    description: str = Field(description="Description of the item or service")
    quantity: int = Field(description="Number of units", ge=1)
    unit_price: float = Field(description="Price per unit", ge=0)

class Address(BaseModel):
    street: str = Field(description="Street address")
    city: str = Field(description="City")
    postal_code: str = Field(description="Postal/ZIP code")
    country: str = Field(description="Country")

class Invoice(BaseModel):
    vendor_name: str = Field(description="Name of the vendor")
    vendor_address: Address = Field(description="Vendor's address")
    invoice_number: str = Field(description="Unique invoice identifier")
    invoice_date: date = Field(description="Date the invoice was issued")
    line_items: List[LineItem] = Field(description="List of purchased items/services")
    total_amount: float = Field(description="Total amount due", ge=0)
    currency: Currency = Field(description="Currency of the invoice")

系统提示指示模型从文本中提取发票数据。由于架构是单独定义的，因此提示可以专注于任务，而无需在输出 JSON 中显式指定必填字段。grok.cadn.net.cn

textgrok.cadn.net.cn

Given a raw invoice, carefully analyze the text and extract the relevant invoice data into JSON format.

textgrok.cadn.net.cn

Vendor: Acme Corp, 123 Main St, Springfield, IL 62704
Invoice Number: INV-2025-001
Date: 2025-02-10
Items:
- Widget A, 5 units, $10.00 each
- Widget B, 2 units, $15.00 each
Total: $80.00 USD

使用 SDK 的结构化输出功能解析发票。grok.cadn.net.cn

from openai import OpenAI

from pydantic import BaseModel, Field
from datetime import date
from enum import Enum
from typing import List

# Pydantic Schemas
class Currency(str, Enum):
    USD = "USD"
    EUR = "EUR"
    GBP = "GBP"

class LineItem(BaseModel):
    description: str = Field(description="Description of the item or service")
    quantity: int = Field(description="Number of units", ge=1)
    unit_price: float = Field(description="Price per unit", ge=0)

class Address(BaseModel):
    street: str = Field(description="Street address")
    city: str = Field(description="City")
    postal_code: str = Field(description="Postal/ZIP code")
    country: str = Field(description="Country")

class Invoice(BaseModel):
    vendor_name: str = Field(description="Name of the vendor")
    vendor_address: Address = Field(description="Vendor's address")
    invoice_number: str = Field(description="Unique invoice identifier")
    invoice_date: date = Field(description="Date the invoice was issued")
    line_items: List[LineItem] = Field(description="List of purchased items/services")
    total_amount: float = Field(description="Total amount due", ge=0)
    currency: Currency = Field(description="Currency of the invoice")

# Making the request
client = OpenAI(
    api_key="<YOUR_XAI_API_KEY_HERE>",
    base_url="https://api.x.ai/v1",
)

completion = client.beta.chat.completions.parse(
    model="grok-2-1212",
    messages=[
        {"role": "system", "content": "Given a raw invoice, carefully analyze the text and extract the invoice data into JSON format."},
        {"role": "user", "content": """
            Vendor: Acme Corp, 123 Main St, Springfield, IL 62704
            Invoice Number: INV-2025-001
            Date: 2025-02-10
            Items:
            - Widget A, 5 units, $10.00 each
            - Widget B, 2 units, $15.00 each
            Total: $80.00 USD
        """}
    ],
    response_format=Invoice,
)

invoice = completion.choices[0].message.parsed
print(invoice)

输出将始终是类型安全的，并遵循输入架构。grok.cadn.net.cn

jsongrok.cadn.net.cn

{
  "vendor_name": "Acme Corp",
  "vendor_address": {
    "street": "123 Main St",
    "city": "Springfield",
    "postal_code": "62704",
    "country": "IL"
  },
  "invoice_number": "INV-2025-001",
  "invoice_date": "2025-02-10",
  "line_items": [
    {"description": "Widget A", "quantity": 5, "unit_price": 10.0},
    {"description": "Widget B", "quantity": 2, "unit_price": 15.0}
  ],
  "total_amount": 80.0,
  "currency": "USD"
}