DeepSeek API 开发与排错

配置、调用、处理响应、排查错误,是 API 接入的四个环节。本页按这个顺序展开,帮助你将一次可运行的请求逐步接入现有程序。

完成首次接入

  1. 平台登录:先在 使用 API 平台 注册账号,再登录控制台操作。
  2. 管理密钥:先在控制台创建 API Key,并留意完整密钥通常只展示一次。请立即保存到安全位置;如果怀疑泄露,应撤销并重新生成。
  3. 请求配置:按官方文档填写 base_url,并采用 /v1 路径。模型按任务从 deepseek-chat 与 deepseek-reasoning 中选择。
  4. 从简单调用开始:单句话请求通过、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 调用帮助

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,可开启对象响应模式,在系统提示中约定字段与嵌套结构并展示样例。收到结果后检查结构,必要时重试一次或进行后处理修补。

接口怎样实现逐字显示?

启用流式请求后,服务端发送增量事件,客户端将它们组合成完整回答。这种方式可用于对话界面的逐字显示,批量任务不必开启。