在聚合站上用 DeepSeek：从拿到 key 到第一次成功返回

准备：聚合站的 key 与 DeepSeek 的关系

在聚合站上，你拿到的 API key 是聚合站的 key，不是 DeepSeek 官方的 key。这个 key 可以调用站内多个模型，DeepSeek 只是其中之一。请求会先发到聚合站的网关，由它转发到对应的上游。

因此有两点需要注意：

• 认证头、base URL、错误结构都遵循聚合站的约定（通常与 OpenAI 兼容）。
• 计费按聚合站的规则走，而不是 DeepSeek 官方账单。

第一步：确认 base URL 和认证方式

聚合站一般提供 OpenAI 兼容的入口，形如：

https://<聚合站域名>/v1/chat/completions

认证方式通常是在请求头里带上：

Authorization: Bearer <你的聚合站 key>

不要把 DeepSeek 官方 key 填进来，那属于另一套体系。如果你同时持有官方 key 和聚合站 key，先在文档里确认当前调的是哪一端。

第二步：选择正确的 model 名称

聚合站的 model 名称不一定和官方完全一致。常见做法有两种：

• 直接沿用官方名称，例如 deepseek-chat（对话）和 deepseek-reasoner（推理）。
• 加前缀区分来源，例如 deepseek/deepseek-chat 或带渠道标识的写法。

不要凭记忆硬写。最稳妥的做法是：

1. 查聚合站的模型列表接口（通常是 GET /v1/models）。
2. 或者查文档里的「模型名称」表格。
3. 复制其中一字不差的字符串填进 model 字段。

名称写错的典型表现是返回 404 或明确的 “model not found”，这比返回空内容更容易排查。

第三步：写对请求体

DeepSeek 在 OpenAI 兼容层上工作，所以请求体基本就是标准的 chat completions 结构：

{
  "model": "deepseek-chat",
  "messages": [
    {"role": "system", "content": "你是一个简洁的助手。"},
    {"role": "user", "content": "用一句话解释什么是向量数据库。"}
  ],
  "temperature": 0.7,
  "max_tokens": 512,
  "stream": false
}

几个容易踩的点：

• messages 必须是数组，且每条有 role 和 content。role 用 system / user / assistant，不要自创。
• temperature、topp、maxtokens 这些常规采样参数通常直接透传。
• 如果你用的是 deepseek-reasoner 这类推理模型，部分参数（比如 temperature）可能不被接受或被忽略，具体以聚合站文档为准。
• 想边生成边看，把 stream 设为 true，但流式响应的解析方式和非流式不同，第一次调通建议先用 false。

第四步：发请求

用 curl 最简单，能排除 SDK 封装带来的干扰：

curl https://<聚合站域名>/v1/chat/completions \
  -H "Authorization: Bearer <你的聚合站 key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "你好"}]
  }'

如果这一步就报错，问题多半在认证、URL 或 model 名称，和业务逻辑无关。先用 curl 跑通，再换成 Python / Node SDK。

第五步：看懂正常响应长什么样

非流式的成功响应结构大致是：

{
  "id": "...",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "deepseek-chat",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 34,
    "total_tokens": 46
  }
}

重点关注三处：

• choices[0].message.content：真正的模型输出。
• finishreason：正常结束是 stop；如果是 length，说明被 maxtokens 截断，不是模型坏了。
• usage：令牌计数。聚合站按它计费，和官方口径可能略有差异。

第六步：识别返回异常

第一次调用后，先过一遍这些检查项，能快速区分「配置错」和「模型本身的问题」：

• HTTP 状态码：401/403 是认证，404 多为 model 或路径写错，429 是限流，5xx 是上游或网关问题。
• content 为空但 finish_reason 正常：检查是不是触发了内容过滤，或者 system 提示把输出压成了空串。
• content 里出现非预期结构：比如推理模型可能把思考过程放在单独的字段里，而不是 content，需要按文档取值。
• 响应里的 model 字段：如果显示的不是你请求的模型，说明网关做了路由或替换，值得留意。
• 流式返回：每条 data: 行是增量 chunk，最后一条通常是 data: [DONE]；如果中途断了，检查网络或网关超时。

注意事项与后续步骤

• 把 key 放在环境变量里，不要硬编码进代码或提交到仓库。
• 先用小 max_tokens 跑通，确认链路无误后再放开。
• 聚合站的计费规则（比如按官方价的倍数扣费）以站内说明为准，别拿官方账单来对。

跑通第一次之后，建议把 curl 请求翻译成团队常用的 SDK，并加上重试和超时逻辑。之后再考虑流式、多轮对话、函数调用等更复杂的用法，这样每一步出问题都容易定位。