DeepSeek返回结构各项注解。

zeyizhang
3 阅读4分钟 
# DeepSeek V4 API 响应数据结构字段解析

本文档基于 DeepSeek V4 API（`deepseek-v4-pro` 模型）的一次实际调用返回，详细解析了 Chat Completions 响应体中的每一个字段。该响应格式兼容 OpenAI 标准，并包含 DeepSeek 的特有扩展。

---

## 一、返回示例（原始 JSON）

```json
{
    "id": "唯一id",
    "object": "chat.completion",
    "created": 1777472403,
    "model": "deepseek-v4-pro",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Hello! How can I help you today?",
                "reasoning_content": "We are starting a conversation. The user says \"Hello!\". I should respond in a helpful and friendly manner. I'll greet them back and ask how I can assist."
            },
            "logprobs": null,
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 12,
        "completion_tokens": 45,
        "total_tokens": 57,
        "prompt_tokens_details": {
            "cached_tokens": 0
        },
        "completion_tokens_details": {
            "reasoning_tokens": 35
        },
        "prompt_cache_hit_tokens": 0,
        "prompt_cache_miss_tokens": 12
    },
    "system_fingerprint": "信息脱敏"
}

二、字段详细说明

字段路径类型示例值必返回说明
idstring"8692dasdasb2c-a646-4ff71a-iiisace3-0dce58b70easda55"✅本次请求的唯一标识符，可用于日志追踪或向技术支持反馈问题。
objectstring"chat.completion"✅返回类型标识，固定为 "chat.completion"。
creatednumber1777472403✅响应生成时间的 Unix 时间戳（秒），可用 new Date(created * 1000) 转换为可读时间。
modelstring"deepseek-v4-pro"✅实际处理本次请求的模型名称，可用于计费或确认模型版本。
choicesarray[...]✅候选回复列表。通常长度为 1，若请求参数 n > 1 则可能包含多个。
choices[0].indexnumber0✅候选回复的索引，从 0 开始递增。
choices[0].messageobject{...}✅模型生成的完整消息对象。
choices[0].message.rolestring"assistant"✅消息角色，此处始终为 "assistant"，代表 AI 助手。
choices[0].message.contentstring"Hello! How can I help you today?"✅模型最终返回给用户的文本回复，可直接展示在对话界面。
choices[0].message.reasoning_contentstring / null"We are starting a conversation..."❌（按需）DeepSeek 特有：模型的思维链（推理过程）。仅当使用推理模型（如 deepseek-v4-pro）且开启相应能力时返回。可用于调试或实现“展示思考过程”功能；默认不应直接呈现给最终用户。
choices[0].logprobsnull / objectnull❌（按需）token 级别的对数概率信息。只有请求中设置 logprobs=true 时才会返回详细数据，否则为 null。
choices[0].finish_reasonstring"stop"✅模型停止生成的原因。常见取值：
• "stop" - 自然结束或命中停止词；
• "length" - 因 max_tokens 限制被截断；
• "content_filter" - 内容被安全策略过滤；
• "tool_calls" - 模型决定调用外部工具。
usageobject{...}✅本次请求的 token 使用统计，用于计费和监控。
usage.prompt_tokensnumber12✅提示词（prompt）消耗的 token 数量。
usage.completion_tokensnumber45✅补全内容消耗的 token 总数，包含 reasoning_tokens。
usage.total_tokensnumber57✅总 token 消耗量，等于 prompt_tokens + completion_tokens。
usage.prompt_tokens_detailsobject{...}✅提示 token 的细分信息。
usage.prompt_tokens_details.cached_tokensnumber0✅命中 KV Cache（上下文缓存）的提示 token 数量。命中的 token 通常以更低费率计费，0 表示本次无缓存命中。
usage.completion_tokens_detailsobject{...}✅补全 token 的细分信息。
usage.completion_tokens_details.reasoning_tokensnumber35✅属于推理内容（reasoning_content）的 token 数。该值从 completion_tokens 中拆分，可用于区分计费（某些模型推理 token 费率不同）。
usage.prompt_cache_hit_tokensnumber0✅命中 磁盘缓存（Prompt Cache） 的提示 token 数。当重复发送相同前缀（如长 system prompt）时可显著降低延迟和费用。
usage.prompt_cache_miss_tokensnumber12✅未命中磁盘缓存的提示 token 数。此例中全部 12 个 prompt token 均为未命中，所以该值等于 prompt_tokens。
system_fingerprintstring"fp_9954b31cddhha7_prod08aae20_fpe8_kvcacddadsdhe_20260221402"✅后端部署环境的唯一指纹。当 DeepSeek 的硬件、模型量化策略、基础设施等发生可能影响输出的变更时，该值会变化。可用于行为一致性排查。

注：“必返回”列中标记为 ✅ 的字段在每次正常响应中都会出现；标记为 ❌（按需）的字段仅在特定条件下返回或取决于请求参数。

三、关键使用提示

1. 获取助手回复

直接读取 choices[0].message.content 即可，这是面向用户的最终文本。

2. 显示“思考过程”（可选）

若产品需要展示模型的推理过程（如类似 DeepSeek 官网的“深度思考”功能），可读取 choices[0].message.reasoning_content，并建议在 UI 上区分于正式回复。

3. 处理截断情况

当 finish_reason 为 "length" 时，说明模型输出因 max_tokens 不足被截断。此时需要适当增加 max_tokens 参数并重新调用。

4. 利用缓存节省成本

  • 尽量保持系统提示词（system prompt）稳定，可命中 Prompt Cache（prompt_cache_hit_tokens 会用减少费用）。
  • 多轮对话时，历史消息可能命中 KV Cache（cached_tokens），也能降低 token 成本。

5. 计费与 Token 统计

  • 推理 token（reasoning_tokens）和普通输出 token（completion_tokens - reasoning_tokens）可能适用不同费率，请参考 DeepSeek 官方定价。
  • 总消耗 total_tokens 已包含所有 token 类型，可直接用于成本估算。

四、相关资源

文档生成日期：2026-04-29
基于模型：deepseek-v4-pro

avatar
文章
阅读
粉丝