# 结构化输出（JSON 模式）

> 在 BigModel.io 上获得 JSON 输出：分组透传时使用 response_format，response_format 被丢弃时改用工具 schema，并对结果做校验。

网页版: https://bigmodel.io/zh-cn/docs/structured-output · 更新于 2026-10-18

获取机器可读 JSON 有两种方法：OpenAI 的 `response_format` 字段，或参数定义即你的 schema 的工具。哪种可用取决于 API Key 的分组。

| Key 的分组 | `response_format` | 工具 schema |
|---|---|---|
| GLM、DeepSeek（仅 Chat Completions） | 原样转发给模型，模型支持即可用 | 模型支持工具即可用 |
| Anthropic 平台分组的 `/v1/chat/completions` | **被丢弃** | 可用 |
| Chat Completions 被转换为 Responses 的分组 | **被丢弃**，`n`、`seed`、`user`、`logprobs` 也会被丢弃 | 可用 |

`response_format` 被丢弃时不会报错：请求照常成功，但模型不受约束，可能返回普通文本，或包在 Markdown 代码块里的 JSON。请始终校验输出。

### 如何判断自己的分组类型？

用你的 Key 向 `/v1/messages` 发任意请求。如果返回 404 并提示该平台只支持 `/v1/chat/completions`，说明是仅 Chat Completions 分组，`response_format` 会透传。其他结果都意味着它可能被丢弃，请使用工具 schema 方法。

## 方法一：response_format

在仅 Chat Completions 分组上，模型支持时使用 `json_schema`，否则用 `json_object`。同时在提示词中要求输出 JSON，部分模型要求这样做。

```python [Python]
import json, os
from openai import OpenAI

client = OpenAI(base_url="https://bigmodel.io/v1", api_key=os.environ["BIGMODEL_API_KEY"])

completion = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "用 JSON 对象回答，包含 name 和 year 两个字段。"},
        {"role": "user", "content": "Guido van Rossum 创造了哪门编程语言？"},
    ],
    response_format={"type": "json_object"},
)
data = json.loads(completion.choices[0].message.content)
print(data["name"], data["year"])
```

```js [Node.js]
import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://bigmodel.io/v1", apiKey: process.env.BIGMODEL_API_KEY });

const completion = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [
    { role: "system", content: "用 JSON 对象回答，包含 name 和 year 两个字段。" },
    { role: "user", content: "Guido van Rossum 创造了哪门编程语言？" },
  ],
  response_format: { type: "json_object" },
});
console.log(JSON.parse(completion.choices[0].message.content));
```

```bash [cURL]
curl https://bigmodel.io/v1/chat/completions \
  -H "Authorization: Bearer $BIGMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {"role": "system", "content": "用 JSON 对象回答，包含 name 和 year 两个字段。"},
      {"role": "user", "content": "Guido van Rossum 创造了哪门编程语言？"}
    ],
    "response_format": {"type": "json_object"}
  }'
```

各模型支持情况不同：有的支持 `json_object` 但不支持 `json_schema`，严格的 schema 约束也并非都有。请查阅所选模型厂商的文档。

## 方法二：工具 schema（所有分组可用）

`tools` 和 `tool_choice` 在所有协议转换中都会保留，所以强制调用一个工具是获得符合 schema 的 JSON 最通用的方法。

```python [Python]
import json, os
from openai import OpenAI

client = OpenAI(base_url="https://bigmodel.io/v1", api_key=os.environ["BIGMODEL_API_KEY"])

schema = {
    "type": "object",
    "properties": {"name": {"type": "string"}, "year": {"type": "integer"}},
    "required": ["name", "year"],
}
completion = client.chat.completions.create(
    model="glm-5.3",
    messages=[{"role": "user", "content": "Guido van Rossum 创造了哪门编程语言？"}],
    tools=[{"type": "function", "function": {"name": "answer", "description": "返回答案", "parameters": schema}}],
    tool_choice={"type": "function", "function": {"name": "answer"}},
)
data = json.loads(completion.choices[0].message.tool_calls[0].function.arguments)
print(data)
```

```js [Node.js]
const schema = {
  type: "object",
  properties: { name: { type: "string" }, year: { type: "integer" } },
  required: ["name", "year"],
};
const completion = await client.chat.completions.create({
  model: "glm-5.3",
  messages: [{ role: "user", content: "Guido van Rossum 创造了哪门编程语言？" }],
  tools: [{ type: "function", function: { name: "answer", description: "返回答案", parameters: schema } }],
  tool_choice: { type: "function", function: { name: "answer" } },
});
console.log(JSON.parse(completion.choices[0].message.tool_calls[0].function.arguments));
```

如果模型不接受强制指定函数，改用 `"tool_choice": "required"`，或 `"auto"` 配合明确的指令。

## 校验结果

两种方法都不能保证所有模型都返回合法数据。请解析并校验，失败时重试一次：

```python [Python]
from pydantic import BaseModel, ValidationError

class Answer(BaseModel):
    name: str
    year: int

try:
    answer = Answer.model_validate_json(raw_json)
except ValidationError as err:
    # 把 err 发回给模型要求修正 JSON，或直接重试
    raise
```

## 验证配置

运行 cURL 示例。`choices[0].message.content` 应是一个 JSON 对象，例如 `{"name": "Python", "year": 1991}`，前后没有其他文字。如果返回的是普通文本，说明 `response_format` 被丢弃或模型不支持，请改用工具 schema。

## 常见问题排查

**返回普通文本，或包在 Markdown 代码块里的 JSON。** `response_format` 在你的分组上被丢弃，或被模型忽略。改用工具 schema，或在解析前去掉代码块标记。

**供应方返回 400，指向 `response_format`。** 模型不支持你发送的格式，常见于 `json_schema`。改用 `json_object` 或工具 schema。

**JSON 被截断。** 回复达到了 `max_tokens`，`finish_reason` 为 `length`。调大 `max_tokens` 或减少输出内容。

**`seed`、`n`、`logprobs` 似乎不起作用。** 在转换协议的分组上，这些字段和 `response_format` 一起被丢弃。只有仅 Chat Completions 分组会透传，且需模型支持。

**503 `api_error`「No available accounts」。** Key 的分组不提供该模型。见[模型 ID](https://bigmodel.io/zh-cn/docs/model-ids)。

## 相关文档

- [工具调用](https://bigmodel.io/zh-cn/docs/tool-calling)：完整的工具调用流程。
- [Chat Completions API 参考](https://bigmodel.io/zh-cn/docs/api-chat-completions)。
- [错误码](https://bigmodel.io/zh-cn/docs/errors)。