结构化输出

结构化输出（Structured Output）使模型返回严格符合指定格式的 JSON，而非自由发挥的文本。这在需要将模型输出直接用于程序处理时（如字段提取、配置生成、表单填充）尤为有用。

使用场景

普通对话中，模型可能以自由文本形式回答。程序难以稳定地从此类文本中提取结构化信息。结构化输出可强制模型返回规范 JSON，便于程序解析与使用。

方式一：JSON 模式（json_object）

最简单的方式，通过 response_format 要求模型返回合法 JSON：

{
  "model": "gpt-5.4-mini",
  "messages": [
    {"role": "system", "content": "你是一个信息提取助手，只返回 JSON。"},
    {"role": "user", "content": "张三今年28岁，是一名工程师。请提取姓名、年龄、职业。"}
  ],
  "response_format": {
    "type": "json_object"
  }
}

模型将返回合法的 JSON 对象：

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "{\"name\": \"张三\", \"age\": 28, \"occupation\": \"工程师\"}"
      },
      "finish_reason": "stop"
    }
  ]
}

json_object 模式仅保证返回合法 JSON，但不保证字段名与结构完全符合预期。建议在 system 提示中明确要求字段。如需严格约束结构，应使用下文的 JSON Schema 模式。

方式二：JSON Schema 模式（推荐）

使用 json_schema 精确定义所需结构，模型将严格遵守：

{
  "model": "gpt-5.4-mini",
  "messages": [
    {"role": "user", "content": "张三今年28岁，是一名工程师。"}
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "person_info",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "name": {"type": "string", "description": "姓名"},
          "age": {"type": "integer", "description": "年龄"},
          "occupation": {"type": "string", "description": "职业"}
        },
        "required": ["name", "age", "occupation"],
        "additionalProperties": false
      }
    }
  }
}

strict: true：启用严格模式，输出保证符合 schema。
required：必填字段。
additionalProperties: false：禁止出现 schema 之外的字段。

返回的 content 将严格符合该 schema 的 JSON 字符串。

完整 Python 示例

将 API_KEY 中的 sk-your-api-key 整段替换为实际密钥；需要使用其他模型时，修改 MODEL。示例会绕过系统代理环境变量，直接请求 Moxus AI。

import json
import httpx
from openai import OpenAI

# 必须替换整个字符串为实际密钥；不要保留“你的密钥”等中文占位文字。
API_KEY = "sk-your-api-key"
# 按模型广场展示的完整名称替换；当前示例使用 gpt-5.4-mini。
MODEL = "gpt-5.4-mini"

client = OpenAI(
    api_key=API_KEY,
    base_url="https://moxus.cloud/v1",
    # 直接连接 Moxus AI，不读取系统或终端代理环境变量。
    http_client=httpx.Client(trust_env=False, timeout=60.0),
)

resp = client.chat.completions.create(
    model=MODEL,
    messages=[
        {"role": "user", "content": "张三今年28岁，是一名工程师。"}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person_info",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                    "occupation": {"type": "string"},
                },
                "required": ["name", "age", "occupation"],
                "additionalProperties": False,
            },
        },
    },
)

data = json.loads(resp.choices[0].message.content)
print(data["name"], data["age"], data["occupation"])

完整 Node.js 示例

将 API_KEY 中的 sk-your-api-key 整段替换为实际密钥；需要使用其他模型时，修改 MODEL。模型返回的是 JSON 字符串，示例使用 JSON.parse 将其转换为可在代码中读取的对象。

import OpenAI from "openai";

// 替换整个字符串为实际密钥；不要保留“你的密钥”等中文占位文字。
const API_KEY = "sk-your-api-key";
// 按模型广场展示的完整名称替换；当前示例使用 gpt-5.4-mini。
const MODEL = "gpt-5.4-mini";

const client = new OpenAI({
  apiKey: API_KEY,
  baseURL: "https://moxus.cloud/v1",
});

const response = await client.chat.completions.create({
  model: MODEL,
  messages: [
    { role: "user", content: "张三今年28岁，是一名工程师。" },
  ],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "person_info",
      strict: true,
      schema: {
        type: "object",
        properties: {
          name: { type: "string" },
          age: { type: "integer" },
          occupation: { type: "string" },
        },
        required: ["name", "age", "occupation"],
        additionalProperties: false,
      },
    },
  },
});

const content = response.choices[0].message.content;
if (!content) {
  throw new Error("模型没有返回 JSON 内容");
}

const data = JSON.parse(content);
console.log(data.name, data.age, data.occupation);

复杂结构示例

Schema 支持嵌套对象、数组与枚举：

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "order",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "order_id": {"type": "string"},
          "status": {
            "type": "string",
            "enum": ["pending", "paid", "shipped", "done"]
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {"type": "string"},
                "quantity": {"type": "integer"},
                "price": {"type": "number"}
              },
              "required": ["name", "quantity", "price"],
              "additionalProperties": false
            }
          }
        },
        "required": ["order_id", "status", "items"],
        "additionalProperties": false
      }
    }
  }
}

建议

优先使用 JSON Schema 模式。需要程序稳定解析时，strict 模式最可靠。
为每个字段添加 description，帮助模型理解字段含义，提高准确率。
仍需进行容错。解析前应使用 try/except 包裹，防止极端情况下的格式异常。
并非所有模型均支持 json_schema 严格模式。若模型不支持，可退回 json_object 模式并结合 system 提示约束。