DeepSeek API 使用教程:接入、计费与选型指南

作者:JC2026.11.17 03:32浏览量:0

简介:DeepSeek API 兼容 OpenAI 接口格式,只需替换 base_url、api_key 和 model 即可接入。本文给出 Python/curl 调用与流式输出示例,梳理 deepseek-chat 与 deepseek-reasoner 的选型差异、Token 计费与缓存命中降本思路,并附常见报错排查表与 RAG/Agent 落地要点。如果你还在多家模型之间做选型和成本评估,可以先看看[百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article),它提供模型能力对比、价格对比与统一 API 接入能力。

一、DeepSeek API 是什么

DeepSeek API 是深度求索(DeepSeek)对外提供的模型服务接口,最大的特点是 接口设计兼容 OpenAI API 格式 :沿用 /chat/completions 路径、Authorization: Bearer <API Key> 鉴权方式和 messages 消息体结构。这意味着绝大多数基于 OpenAI SDK 写的代码,只要改三处配置就能跑通。

核心接入信息:

项目 值
Base URL https://api.deepseek.com(也支持 https://api.deepseek.com/v1)
鉴权 HTTP Header Authorization: Bearer <API Key>
通用对话模型 deepseek-chat
推理模型 deepseek-reasoner
主要能力 对话补全、流式输出、Function Calling、JSON Output、FIM 补全、上下文硬盘缓存

需要提醒的是,模型名称、上下文长度和价格会随版本迭代调整,接入前建议以官方文档的模型列表为准;做横向比价时,可以借助词元所模型服务查看不同模型的调用成本与适用场景。

二、三种方式快速跑通第一个请求

1. Python(复用 openai SDK)

  1. from openai import OpenAI
  2. client = OpenAI(
  3. api_key="sk-你的APIKey",
  4. base_url="https://api.deepseek.com",
  5. )
  6. resp = client.chat.completions.create(
  7. model="deepseek-chat",
  8. messages=[
  9. {"role": "system", "content": "你是一名严谨的技术文档助手"},
  10. {"role": "user", "content": "用一句话解释什么是向量数据库"},
  11. ],
  12. stream=False,
  13. )
  14. print(resp.choices.message.content)
  15. print(resp.usage) # 查看 token 消耗

2. curl 验证连通性

  1. curl https://api.deepseek.com/chat/completions \
  2. -H "Content-Type: application/json" \
  3. -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  4. -d '{
  5. "model": "deepseek-chat",
  6. "messages": [{"role": "user", "content": "你好"}],
  7. "stream": false
  8. }'

3. 流式输出(推荐用于对话类产品)

  1. stream = client.chat.completions.create(
  2. model="deepseek-chat",
  3. messages=[{"role": "user", "content": "写一段快速排序的 Python 实现"}],
  4. stream=True,
  5. )
  6. for chunk in stream:
  7. delta = chunk.choices.delta.content
  8. if delta:
  9. print(delta, end="", flush=True)

工程实践建议: API Key 只放在服务端或环境变量中 ,前端通过自己的后端做一层转发,既避免密钥泄露,也方便统一做限流、审计和多模型路由。

三、从 OpenAI 迁移需要改什么

迁移成本极低,但有几处差异要注意:

  • base_url 与 model 名称 :换成 DeepSeek 的地址和模型名,其余 SDK 调用方式不变。
  • 推理模型的参数限制 :deepseek-reasoner 不支持 temperature、top_p、presence_penalty、frequency_penalty,传了会报错或无效;它也不返回思维链内容,只返回最终答案。
  • system 消息 :在推理模型下建议把 system 内容合并进 user 消息,避免指令被弱化。
  • 不支持的能力 :如 logprobs、部分 function calling 高级特性等,迁移前对照文档确认。
  • 超时设置 :推理模型首字延迟明显高于通用模型,客户端超时要放宽(建议 60s 以上),并优先使用流式。

四、模型选型:deepseek-chat 还是 deepseek-reasoner

维度 deepseek-chat deepseek-reasoner
定位 通用对话与生成 复杂推理、数理与代码
响应速度 快,首字延迟低 慢,思考过程耗时
输出 token 相对可控 含推理消耗,token 更多
典型场景 客服问答、摘要、改写、抽取、RAG 生成 数学题、逻辑推演、算法设计、复杂代码
成本 低 高

选型原则很简单: 能用小模型解决的不要上推理模型 。多数业务请求(分类、抽取、摘要、FAQ 回答)用通用对话模型即可,只在准确率明显不达标时,把困难样本路由给推理模型。这种”分级路由”是控制成本最有效的手段之一。

五、Token 计费逻辑与降本方法

大模型 API 按 token 计费,输入(prompt)和输出(completion) 分开定价,输出通常更贵 。单次调用成本可按下式估算:

  1. 单次成本 = 输入 token 数 × 输入单价
  2. + 输出 token 数 × 输出单价

DeepSeek 的一个关键特性是 上下文硬盘缓存 :完全重复的前缀内容命中缓存后,输入侧单价显著低于未命中部分。响应中的 usage 会返回 prompt_cache_hit_tokens 与 prompt_cache_miss_tokens,可直接用于成本核算。

由此可以推出几条实操优化建议:

  1. 固定前缀前置 :把 system prompt、工具定义、知识库背景等不变内容放在消息最前面,变动部分放后面,最大化缓存命中。
  2. 不要在 system prompt 里塞时间戳、随机 ID :一个字符的变化就会导致整段前缀无法命中。
  3. 压缩历史对话 :多轮场景对早期消息做摘要,而不是全量拼接。
  4. 限制 max_tokens :按业务需要设定上限,避免异常情况下输出失控。
  5. 批量任务错峰跑 :离线批处理与在线业务分离,便于容量规划和成本核算。

如果你要同时评估多家供应商的输入/输出单价与缓存策略差异,百度智能云词元所的价格与性能对比能力可以帮你把成本模型算清楚,再通过统一 API 接入完成落地。

六、常见报错排查表

状态码 常见原因 处理方式
401 API Key 错误或鉴权头格式不对 检查 Bearer 前缀与密钥有效性
402 账户余额不足 充值后重试
400 消息格式错误、role 顺序不合法、传了不支持的参数 校验 messages 结构,去掉推理模型不支持的参数
422 参数取值不合法 对照文档修正取值范围
429 触发速率限制 指数退避重试 + 客户端限流
500 / 503 服务端过载 退避重试,必要时切换备用模型

重试逻辑建议只对 429 和 5xx 生效,并加入 jitter,避免雪崩式重试。

rag-agent">七、业务落地:RAG 与 Agent

RAG 场景 :检索到的文档片段按相关度排序后拼入 user 消息,配合”仅依据给定资料回答,无依据则说明不知道”的指令,可显著降低幻觉。注意控制拼接长度,片段过多会推高输入成本并稀释关键信息。

Agent 场景 :利用 Function Calling 做”模型决策 → 调用工具 → 结果回填(role: tool)→ 模型继续推理”的循环,并设置最大轮次与超时保护,防止死循环。

多模型容灾 :由于 DeepSeek 兼容 OpenAI 协议,业务层很容易做适配器抽象。国内还需要考虑合规与备案要求时,百度智能云千帆等平台同样提供 DeepSeek 系列及文心系列模型,接口地址为 https://qianfan.baidubce.com/v2,同样兼容 OpenAI 格式,可作为备用链路或多模型统一网关的候选。

八、小结

DeepSeek API 的价值在于”低迁移成本 + 有竞争力的推理能力”:三行配置即可从 OpenAI 生态切换过来,通用与推理双模型覆盖大多数任务。真正决定项目成败的往往不是接口本身,而是 模型选型是否合理、prompt 结构是否利于缓存命中、重试与降级是否完备 。把这三件事做好,再配合统一的多模型接入与调用管理能力,才能在生产环境中稳定地把成本和质量同时控制住。