python

安装依赖：pip install openai>=1.30.0

from openai import OpenAI

client = OpenAI( api_key="sk-你的密钥", # 在 platform.deepseek.com 的 API Keys 页创建 base_url="https://api.deepseek.com", # 注意：填到域名即可，SDK 会自己拼 /chat/completions )

---------- 场景一：普通对话 ----------

resp = client.chat.completions.create( model="deepseek-chat", messages=[ {"role": "system", "content": "你是一位严谨的中文技术编辑，回答不超过三句话。"}, {"role": "user", "content": "用三句话解释什么是 MoE 稀疏激活。"}, ], temperature=1.0, # DeepSeek 官方建议对话场景用 1.0，不要照搬 OpenAI 习惯的 0.7 stream=False, ) print(resp.choices[0].message.content) print("本次消耗 token：", resp.usage.total_tokens)

想要结构化输出，就打开 JSON 模式。这里有个坑我踩过：prompt 文本里必须显式出现 "json" 这个单词，否则接口会直接报错返回，哪怕你已经把 `response_format` 设好了。

---------- 场景二：JSON 结构化抽取 ----------

resp = client.chat.completions.create( model="deepseek-chat", messages=[ {"role": "system", "content": "你是合同信息抽取器，只输出 json，不要任何解释文字。"}, {"role": "user", "content": "从这句话提取甲方、乙方和金额：甲方北京甲科技有限公司与乙方上海乙数据服务有限公司签订合同，金额为人民币 28 万元。"}, ], response_format={"type": "json_object"}, # 注意：prompt 里必须有 "json" 关键词 ) print(resp.choices[0].message.content)

预期输出类似：{"甲方": "北京甲科技有限公司", "乙方": "上海乙数据服务有限公司", "金额": "280000"}

推理模型则多了一个字段：

---------- 场景三：推理模型，思维链单独返回 ----------

resp = client.chat.completions.create( model="deepseek-reasoner", messages=[{"role": "user", "content": "一个水池有两个进水管……（略）"}], )

reasoning_content 是思维链，最终答案在 content 里

print(resp.choices[0].message.reasoning_content) print(resp.choices[0].message.content)

计费提醒：`reasoning_content` 也是要算输出 token 的。 有些模型思考几千 token 才给一行答案，成本会明显高于 chat。生产环境里我给 R1 的输出上限做了硬约束，避免它"想太久"。

上线后才会遇到的四个坑

接入代码半小时就能跑通，真正烧时间的是下面这些。

第一个是上下文缓存。 deepseek官网api开放平台的缓存是自动的，你不用做任何配置，但它的命中条件是"前缀完全一致"。也就是说，如果你把变化的内容放在 prompt 开头，缓存永远命中不了。我改的做法是把 system prompt、few-shot 示例、长文档正文全部前置，把用户的那句短问题挪到最后。改完之后缓存命中率从 5% 涨到 70% 以上，输入成本直接砍掉一大半。

第二个是超时与重试。 高峰期偶尔会遇到长响应被中断。别用默认的无限等待，给单个请求设 60 秒超时，然后做指数退避重试（1s、2s、4s）。我们线上统计过，两次重试基本能覆盖 99% 的偶发失败。

第三个是限流。 官方没有给一个固定的 QPS 数字，它是动态调整的。我们的做法是客户端加一个令牌桶，把并发压在 20 以内，超过就排队。硬顶着打，只会收获一堆 429。

第四个，也是最容易被忽略的：别把 R1 当成万金油。 我早期为了省事，把线上所有任务都路由到 R1，结果简单分类任务的 P99 延迟从 1.8 秒飙到 15 秒，账单翻了三倍。后来写了个路由规则——按任务复杂度分流，简单任务走 chat，命中关键词（数学、证明、多步推理）才走 reasoner——成本立刻回落到合理区间。路由层才是真正决定你 API 账单的东西，模型本身反而次要。

我的学习路径建议与资源

如果你是从零开始，我建议按这个顺序走，别一上来就啃论文：

1. **第一天**：注册开放平台账号，跑通上面的三段示例代码，把 token 计费逻辑搞清楚。
2. **第二天**：拿你自己业务里一个真实任务，做 A/B 对比——同一个 prompt 分别打给 chat 和 reasoner，记录质量、延迟、成本三个指标。
3. **第三天**：加上缓存前缀设计和重试逻辑，把 demo 变成能上线的服务。
4. **之后**：如果确实需要私有化，再去读技术报告研究 V3 的 MoE 架构和 R1 的强化学习训练流程。

想深入原理的话，两份一手材料必看：DeepSeek-V3 技术报告（arXiv:2412.19437，2024 年 12 月发布）详细讲了它的多头潜在注意力和 MoE 负载均衡策略；DeepSeek-R1 论文（arXiv:2501.12948，2025 年 1 月）则把纯强化学习激发推理能力的路径讲得很透。读完之后再回头看 API 的行为，很多"为什么它这么设计"的问题就通了。

总结：关键要点速览

• **接口兼容是真的**：OpenAI SDK 换 base_url 就能用，迁移成本极低，但多模态输入目前不支持。
• **模型分工要明确**：deepseek-chat 干结构化活儿，deepseek-reasoner 干推理活儿，别混用。
• **缓存前缀决定成本**：把固定内容前置、变量后置，输入费用能省一半以上。
• **错峰时段值得利用**：凌晨批处理任务可享 50%–75% 折扣，适合离线场景。
• **路由层比模型选择更重要**：按任务复杂度分流，是控制延迟和账单的关键手段。

接下来半年我比较关注两件事：一个是开放平台什么时候补上视觉能力，另一个是缓存策略会不会开放手动管理接口。如果这两块补齐，它在 Agent 场景里的竞争力会再上一个台阶。

相关推荐

📖 阅读相关专题

• [DeepSeek-R1 推理模型实测：思维链到底值不值这个价](https://www.vergex.cn/ai/deepseek-r1)
• [大模型推理成本优化：从缓存到路由的完整方法](https://www.vergex.cn/ai/llm-inference-cost)

🛠 查看工具推荐

• 想找更多国产大模型 API 和开发工具？来 [VergeX AI 工具导航](https://nav.vergex.cn) 的大模型专区逛逛，接口文档、定价对比、开源权重下载入口都整理好了。

🔔 订阅更新

• 我们每周会更新一期大模型 API 实测报告，包含价格变动和性能横评。订阅 VergeX 邮件列表或关注公众号「VergeX技术雷达」，有新模型上线第一时间收到提醒。