DeepSeek API 开发与排错
配置、调用、处理响应、排查错误,是 API 接入的四个环节。本页按这个顺序展开,帮助你将一次可运行的请求逐步接入现有程序。
完成首次接入
- 平台登录:先在 使用 API 平台 注册账号,再登录控制台操作。
- 管理密钥:先在控制台创建 API Key,并留意完整密钥通常只展示一次。请立即保存到安全位置;如果怀疑泄露,应撤销并重新生成。
- 请求配置:按官方文档填写 base_url,并采用
/v1路径。模型按任务从deepseek-chat与deepseek-reasoning中选择。 - 从简单调用开始:单句话请求通过、assistant 返回正常后,再进行系统集成。
从可运行请求开始
curl
调用示例从环境变量取密钥,不要把真实密钥写入命令历史:
export DEEPSEEK_API_KEY="sk-你的密钥"
curl https://api.deepseek.com/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
-d '{
"model": "deepseek-chat",
"messages": [
{"role": "system", "content": "你是一个严谨的技术助理。"},
{"role": "user", "content": "用三句话解释什么是 API。"}
],
"stream": false
}'回答内容可从响应的 choices[0].message.content 中获取。usage 记录这次调用的 token 使用量。
Python
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["DEEPSEEK_API_KEY"],
base_url="https://api.deepseek.com",
)
response = client.chat.completions.create(
model="deepseek-chat",
messages=[
{"role": "system", "content": "你是一个严谨的技术助理。"},
{"role": "user", "content": "用三句话解释什么是 API。"},
],
temperature=0.3,
max_tokens=1024,
)
print(response.choices[0].message.content)
print(response.usage)使用兼容 Python SDK 即可运行,专用依赖并非必需。接入时将 base_url 改为 DeepSeek 地址。
JavaScript
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.DEEPSEEK_API_KEY,
baseURL: "https://api.deepseek.com",
});
const stream = await client.chat.completions.create({
model: "deepseek-reasoning",
messages: [{ role: "user", content: "解释一下什么是流式输出。" }],
stream: true,
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}响应格式与输出处理
逐段返回:使用 stream=true,将服务端推送的增量内容在前端拼接展示。对话界面可开启,批量任务则可按需关闭。
程序消费结果:请求中可使用 JSON 对象响应模式。同时在系统提示中明确字段、类型和嵌套关系:
response = client.chat.completions.create(
model="deepseek-chat",
messages=[
{"role": "system", "content": "仅输出 JSON,字段为 city、population、tags(字符串数组)。"},
{"role": "user", "content": "杭州的人口规模和标签。"},
],
response_format={"type": "json_object"},
)
import json
data = json.loads(response.choices[0].message.content)
print(data["city"], data["tags"])结果需经过结构检查,遇到多余说明导致解析错误时,用重试或后处理解决。更完整的工程流程见 API 输出验证及工具执行。
常见错误与解决步骤
| 报错现象 | 原因排查 | 处理思路 |
|---|---|---|
| 结果格式偏离要求 | 格式要求和示例不完整 | 增加字段定义、JSON 样例,并验证 JSON 模式的输出 |
| 连接未及时完成 | 网络状态不佳、服务器繁忙 | 给超时和重试设合理值,批量任务先降并发 |
| 401 认证错误 | 检查 Authorization 是否缺失、Key 空白字符及撤销状态 | 首先检查 Bearer 密钥 格式,同时使用环境变量并清理空白 |
| 429 限流或额度问题 | 调用速度、并发超限或余额不足 | 按指数退避重试,同时查看余额和限速规则 |
| 响应内容为空或截断 | 提示过长或 max_tokens 设得太小 | 精简历史并增加 max_tokens,长任务可分多次调用合并 |
从基础请求继续扩展
- 需要比较调用模型,可进入 查看模型系列对比。
- 后端流程中的输出与工具处理可阅读 API 输出验证及工具执行。
- 需要横向评估 API 成本,请阅读 三款 AI 产品选型。
API 调用帮助
base_url 应如何配置?
API 地址应从官方文档取得,客户端通常把 base_url 设为该地址的 /v1,沿用 OpenAI 兼容的通信格式。
deepseek-chat 面向通用任务,deepseek-reasoning 则偏向推理任务。
怎样创建和保存 API Key?
密钥由 API 开放平台控制台提供,创建后完整内容一般不会反复展示。应立即安全保存;疑似泄露时,在控制台撤销旧 Key 并创建新 Key。
如何处理接口身份验证失败?
401 的常见原因包括未发送 Authorization、密钥含空白字符,或继续使用已撤销的 Key。
Authorization 应采用 Bearer 加密钥的格式,密钥从环境变量读取,不写死在代码中。
如何排查 429 与调用额度?
遇到 429,应先考虑调用频率以及速率、额度限制。可采用指数退避重试,检查控制台余额和限制,并避免循环中高并发重复请求。
如何让返回内容符合 JSON 结构?
要得到 JSON,可开启对象响应模式,在系统提示中约定字段与嵌套结构并展示样例。收到结果后检查结构,必要时重试一次或进行后处理修补。
接口怎样实现逐字显示?
启用流式请求后,服务端发送增量事件,客户端将它们组合成完整回答。这种方式可用于对话界面的逐字显示,批量任务不必开启。