DeepSeek API 接入指南与选型

作者:十万个为什么2026.11.17 03:45浏览量:0

简介:DeepSeek 接口兼容 OpenAI 格式,多数存量应用只需修改 base_url 与密钥即可接入。本文给出可直接运行的 Python 与 curl 示例,说明 deepseek-chat 与 deepseek-reasoner 的选择方法、Token 计费与缓存降本、流式输出及常见报错排查,帮助开发者少走弯路。

一、DeepSeek API 是什么

DeepSeek API 由深度求索提供,接口格式兼容 OpenAI API。如果你的应用已经基于 OpenAI SDK 开发,迁移时通常只需改两处配置:把 base_url 指向 https://api.deepseek.com,把 api_key 换成在 DeepSeek 开放平台创建的密钥。messages 结构、流式协议和错误码的含义都可以保留。

这种协议兼容让很多工具也能直接使用 DeepSeek。LangChain、LlamaIndex、Dify、Chatbox 等框架大多支持自定义 OpenAI 兼容的提供方,接入时不需要为 DeepSeek 单独写适配层。

二、准备环境与密钥

先安装 SDK。本文示例使用 OpenAI Python SDK 1.x 版本,Python 3.8 及以上可以正常运行:

  1. pip install "openai>=1.0"

在 DeepSeek 开放平台创建 API Key。密钥只在创建时完整显示一次,创建后应立即保存到密码管理器或其他安全位置。密钥属于敏感凭证,不要写进代码,也不要提交到代码仓库,建议通过环境变量读取:

  1. export DEEPSEEK_API_KEY='你的DeepSeek API Key'

Windows PowerShell 用户可以使用 $env:DEEPSEEK_API_KEY='你的DeepSeek API Key'。

三、最小可运行示例

1. Python 调用

  1. import os
  2. from openai import OpenAI
  3. client = OpenAI(
  4. api_key=os.environ["DEEPSEEK_API_KEY"],
  5. base_url="https://api.deepseek.com", # 兼容 OpenAI 协议
  6. )
  7. resp = client.chat.completions.create(
  8. model="deepseek-chat",
  9. messages=[
  10. {"role": "system", "content": "你是一名严谨的技术文档编辑。"},
  11. {"role": "user", "content": "用三句话解释什么是 Token。"},
  12. ],
  13. stream=False,
  14. )
  15. print(resp.choices[0].message.content)
  16. print(resp.usage) # prompt_tokens, completion_tokens, total_tokens

返回对象的 choices 是列表,取回回复内容要写 choices[0]。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. }'

如果返回 JSON,说明密钥、网络和模型名三项都正常。返回 401 通常是密钥问题,返回 404 或提示模型不存在时,应先检查模型名拼写。

四、模型怎么选

DeepSeek 常见的两个模型是 deepseek-chat 和 deepseek-reasoner。模型名以官方文档为准,上线前应再核对一次。

维度 deepseek-chat deepseek-reasoner
适用任务 问答、摘要、改写、抽取、客服 数学、代码、多步逻辑推演
响应内容 choices[0].message.content 额外返回 reasoning_content 思维链
延迟与成本 较低 较高,输出 Token 明显更多
参数支持 完整 部分采样参数受限,工具调用需查文档

实践中,分类、抽取、摘要和多轮客服等大多数请求用 deepseek-chat 就够了。只有需要多步推导的任务才值得使用推理模型。思维链也计入输出 Token,滥用推理模型是账单快速增长的常见原因。

五、Token 计费与降本

大模型 API 按 Token 计费。相比记住单价,先理解计费口径更重要:

  1. 单次费用 = 输入 Token 数 × 输入单价 + 输出 Token 数 × 输出单价

输入 Token 包括全部 messages,即 system 提示词和历史对话。输出 Token 是模型生成内容的长度。Token 数由分词器编码后统计,字符数只能粗略估算。做成本预算时,应以 usage 字段的实际返回值为准。

可以落地的降本手段有四项:

  1. 精简 system 提示词。 每次请求都会重复计费。把冗长的角色设定和示例压缩成结构化短句,长文档类应用收益尤其明显。
  2. 控制历史轮数。 多轮对话不要无限拼接,可以使用滑动窗口,或定期把早期对话压缩成摘要。
  3. 设置 max_tokens 上限。 避免异常情况下生成失控,也让单次成本有明确上限。
  4. 利用上下文缓存。 DeepSeek 对重复前缀提供缓存命中机制,usage 中会分别给出缓存命中与未命中的 Token 数,字段名以官方文档为准。把稳定的长前缀,如固定知识库片段和长 system 提示词,放在 messages 最前面,可以显著降低重复输入的成本。

对比不同厂商时,应使用同一批业务样本同时计算单价和效果,不要只看单一厂商的报价。

六、流式输出与 JSON 模式

流式输出

将 stream 设为 True,逐块读取 choices[0].delta.content:

  1. stream = client.chat.completions.create(
  2. model="deepseek-chat",
  3. messages=[{"role": "user", "content": "写一段接口文档说明"}],
  4. stream=True,
  5. )
  6. for chunk in stream:
  7. if not chunk.choices:
  8. continue
  9. delta = chunk.choices[0].delta.content
  10. if delta:
  11. print(delta, end="", flush=True)

流式场景要处理首字延迟和中途断流。前端应设置超时,并准备重试或续写逻辑。

JSON 模式

需要程序解析输出时,可以传入 response_format={"type": "json_object"},让模型输出合法 JSON。使用前应确认所选模型支持该参数,并在 prompt 中写清楚字段名称和结构。JSON 模式只保证语法合法,不保证字段齐全,业务侧仍要做 schema 校验。

七、常见报错排