DeepSeek API 支持 JSON Output 模式，通过设置 response_format: {type: "json_object"} 强制模型输出合法 JSON 字符串，适合需要结构化数据的场景。使用时 prompt 中必须包含 json 字样，否则模型可能不知道要输出什么结构。

DeepSeek API JSON Output

什么是 JSON Output

JSON Output 模式确保模型输出合法的 JSON 字符串，解析时不会抛出 JSON.parse 异常。适用场景：

• 从文本中提取结构化数据
• 生成配置文件
• API 返回固定格式的结果

使用方法

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.deepseek.com",
  apiKey: process.env.DEEPSEEK_API_KEY,
});

const systemPrompt = `从用户提供的文字中提取信息，输出 JSON 格式。
示例输入：小明今年 25 岁，住在北京。
示例 JSON 输出：{"name": "小明", "age": 25, "city": "北京"}`;

const response = await client.chat.completions.create({
  model: "deepseek-v4-pro",
  messages: [
    { role: "system", content: systemPrompt },
    { role: "user", content: "李华，女，32 岁，目前在上海工作。" },
  ],
  response_format: { type: "json_object" }, // 开启 JSON Output
});

const data = JSON.parse(response.choices[0].message.content ?? "{}");
console.log(data);
// { name: "李华", gender: "女", age: 32, city: "上海" }

Python 版本：

import json
from openai import OpenAI

client = OpenAI(api_key="<your api key>", base_url="https://api.deepseek.com")

system_prompt = """从用户提供的文字中提取信息，以 JSON 格式输出。
示例输入：小明今年 25 岁，住在北京。
示例 JSON 输出：{"name": "小明", "age": 25, "city": "北京"}"""

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": "李华，女，32 岁，目前在上海工作。"},
    ],
    response_format={"type": "json_object"},
)

data = json.loads(response.choices[0].message.content)
print(data)

必须遵守的规则

规则	说明
prompt 必须包含 json 字样	system 或 user prompt 中至少有一个地方提到 json，否则模型不知道要输出什么结构
提供示例输出	告诉模型你期望的 JSON 结构，否则字段可能不稳定
设置合理的 max_tokens	防止 JSON 被截断，导致无法解析
处理 null/空 content	极少情况下模型可能返回空 content，需要做 fallback

常见踩坑

踩坑 1：忘记在 prompt 里写 json

// ❌ 错误：没有提到 json
const systemPrompt = "从文字中提取姓名和年龄";

// ✅ 正确：明确说明要 json 格式
const systemPrompt = "从文字中提取姓名和年龄，以 json 格式输出";

踩坑 2：JSON 被截断

// ❌ max_tokens 太小
{ max_tokens: 50 }  // JSON 还没结束就被截断

// ✅ 留够空间
{ max_tokens: 500 }

踩坑 3：没有处理空 content

// ❌ 直接 parse，空 content 会抛异常
const data = JSON.parse(response.choices[0].message.content);

// ✅ 做 fallback
const raw = response.choices[0].message.content ?? "{}";
const data = JSON.parse(raw);

JSON Output vs Tool Calls Strict 模式

	JSON Output	Tool Calls Strict 模式
约束程度	保证合法 JSON，但字段不严格	严格按 JSON Schema
schema 定义	在 prompt 中描述	在 tools.function.parameters 中定义
适用场景	灵活提取、字段不固定	需要精确结构的 Agent
复杂度	低	中

如果需要严格保证字段结构（比如必须有某字段、类型必须正确），建议用 Tool Calls Strict 模式，比 JSON Output 更可靠。

常见问题

Q: JSON Output 和直接在 prompt 里要求输出 JSON 有什么区别？

A: 没有 response_format: {type: "json_object"} 时，模型可能输出 markdown 代码块（json ... ）包裹的内容，或者加一些解释文字，导致 JSON.parse 失败。开启 JSON Output 模式后，模型保证直接返回 JSON 字符串，不会有任何包装。

Q: 可以指定具体的 JSON Schema（字段类型、必须字段）吗？

A: JSON Output 模式不支持 schema 约束，只保证合法 JSON。需要 schema 约束请用 Tool Calls Strict 模式。

Q: stream 流式输出支持 JSON Output 吗？

A: 支持，但需要等流结束后再拼接完整字符串再解析，不能在流中间解析。