DeepSeek 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 中获取。请求的 token 用量由 usage 字段给出。
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"])结果需经过结构检查,遇到多余说明导致解析错误时,用重试或后处理解决。实现细节请参考 JSON 和工具调用流程。
检查请求失败原因
| 问题表现 | 通常原因 | 修复方法 |
|---|---|---|
| 接口请求超时 | 链路不稳定,或服务端响应繁忙 | 检查超时设置及重试次数,减少批量并发 |
| 401:认证未成功 | 请求头缺 Authorization,或 Key 含空白、已撤销 | 确保采用 Bearer 密钥 方式,从环境变量读取 Key 后去除空格 |
| 429:触及频率或额度 | 高并发与高频请求、余额不足 | 先核查余额及限制,再用指数退避重试 |
| 回答为空或中途截断 | max_tokens 较小、提示长度较大 | 调大 max_tokens、减少历史占用,必要时多轮拼合 |
| 输出结构不正确 | 缺失输出约束或参考示例 | 约定字段及样例,指定 JSON 响应并执行校验 |
进一步使用 API
- 模型选择问题可通过 按任务对照 DeepSeek 模型 进一步了解。
- 需要 API 工程化流程,继续进入 JSON 和工具调用流程。
- 有关不同产品调用成本的选择依据,见 DeepSeek 与其他产品比较。
接入问题答疑
如何确认 DeepSeek 的接入地址?
API 地址应从官方文档取得,客户端通常把 base_url 设为该地址的 /v1,沿用 OpenAI 兼容的通信格式。按用途选择模型名:通用任务用 deepseek-chat,推理任务可用 deepseek-reasoning。
DeepSeek 的接口密钥如何申请?
密钥由 API 开放平台控制台提供,创建后完整内容一般不会反复展示。生成后妥善保存;若可能已经泄露,应在控制台撤销并更换。
收到 401 后怎样检查密钥?
401 的常见原因包括未发送 Authorization、密钥含空白字符,或继续使用已撤销的 Key。确认请求头为 Bearer 密钥形式,且 Key 来自环境变量而非代码常量。
遇到 429 时怎样重试?
遇到 429,应先考虑调用频率以及速率、额度限制。检查余额和速率限制,使用指数退避重试,不要在循环里高并发发送相同请求。
使用 JSON 输出要做哪些配置?
要得到 JSON,可开启对象响应模式,在系统提示中约定字段与嵌套结构并展示样例。使用前验证结构,失败可通过一次重试或后续修补处理。
DeepSeek 的流式返回如何使用?
启用流式请求后,服务端发送增量事件,客户端将它们组合成完整回答。若希望对话逐字呈现,可使用流式;批量处理场景通常无需启用。