DeepSeek API：AI 工程师完全指南（2026）

DeepSeek API 是一个兼容 OpenAI 的接口，为你提供 DeepSeek V4 模型家族的访问能力——包括其最强推理模型 V4-Pro，以及快速、极具性价比的 V4-Flash。两个模型均支持 100 万 token 上下文、可选的思维模式、工具调用和 JSON 输出。你只需在 platform.deepseek.com 注册、获取 API key、将现有 OpenAI SDK 的 base_url 指向 https://api.deepseek.com，代码即可直接运行。

我们写这篇指南是因为 DeepSeek 的定价是行业最低之一，但 V4 模型系列引入了新的模型名称、默认思维模式，以及旧名称的弃用时间线，如果不注意很容易踩坑。这是我们首次将 DeepSeek 集成到路由层时最想要的一站式参考。

3 分钟快速开始

第一步：注册账号。 访问 platform.deepseek.com 进行注册。DeepSeek 支持邮箱注册和 Google OAuth 登录。

第二步：获取 API key。 前往 API Keys，点击"创建 API Key"。复制并安全保存——Key 只会显示一次。

第三步：发起首次调用。 安装 OpenAI Python SDK：

pip install --upgrade openai

然后运行：

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_DEEPSEEK_KEY",
    base_url="https://api.deepseek.com",
)

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "什么是 DeepSeek V4？"}],
)

print(response.choices[0].message.content)

就这样。首次注册无需绑定信用卡。DeepSeek 会不定期为账户充值赠送额度——查看你的 账户余额 了解当前可用额度。

DeepSeek 模型家族：V4-Flash 与 V4-Pro

DeepSeek 目前通过 API 提供两个模型，均于 2026 年 4 月 24 日以预览版发布：

两个模型均支持思维和非思维模式。思维模式默认开启——模型会在最终回答前输出链式推理过程。

旧版模型名称（已弃用）

DeepSeek 将在 2026 年 7 月 24 日 15:59 UTC 停用两个旧模型 ID：

如果你的代码仍在使用 deepseek-chat 或 deepseek-reasoner，请立即切换到 deepseek-v4-flash。我们建议显式设置思维开关，而不是依赖隐式模式选择。

从 V3 到 V4 的变化

V4 系列是 DeepSeek 的第四代架构。与 V3.x 的主要差异：

• 统一思维模式： V4 取代了独立的 R1 推理线路——V4 的可选思维模式覆盖了 R1 的使用场景。如果你之前为推理任务路由到 deepseek-r1，现在应切换到启用思维的 deepseek-v4-pro。
• 100 万上下文窗口： V3.x 最高为 128K；V4 的 Flash 和 Pro 均支持 100 万 tokens。
• Anthropic API 兼容： V4 新增了 Anthropic 格式的端点 https://api.deepseek.com/anthropic，与现有 OpenAI 格式并存。
• FIM 补全： 两个模型在非思维模式下均支持 Fill-in-the-Middle 补全，适用于代码补全场景。

来源：DeepSeek V4 预览发布，检索于 2026-06-07。

OpenAI SDK 配置：Python、Node.js 与流式输出

DeepSeek 实现了 OpenAI ChatCompletions 规范。无需特殊 SDK——使用官方 OpenAI SDK 并修改 base_url 即可。

Python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_DEEPSEEK_KEY",
    base_url="https://api.deepseek.com",
)

# 非流式
response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "解释 CAP 定理。"}],
)
print(response.choices[0].message.content)

# 流式
stream = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "解释 CAP 定理。"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Node.js

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.DEEPSEEK_API_KEY,
    baseURL: "https://api.deepseek.com",
});

const completion = await client.chat.completions.create({
    model: "deepseek-v4-flash",
    messages: [{ role: "user", content: "解释 CAP 定理。" }],
});

console.log(completion.choices[0].message.content);

curl

curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "你好！"}],
    "stream": false
  }'

来源：DeepSeek API 文档——首次调用，检索于 2026-06-07。

思维模式：何时使用及如何配置

两个 V4 模型均支持思维模式——模型在生成最终答案前会先进行链式推理。思维模式在两个模型上默认开启。

切换思维模式

# 启用思维（默认）
response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "证明 √2 是无理数。"}],
    extra_body={"thinking": {"type": "enabled"}},
    reasoning_effort="high",
)

# 禁用思维
response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "2+2 等于多少？"}],
    extra_body={"thinking": {"type": "disabled"}},
)

推理强度

• high — 常规请求的默认值
• max — 部分 Agent 工具（Claude Code、OpenCode）自动使用；提供更深层推理，但延迟更高

访问推理内容

在思维模式下，推理链通过 reasoning_content 字段与常规 content 一起返回：

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "9.11 和 9.8 哪个更大？"}],
    reasoning_effort="high",
    extra_body={"thinking": {"type": "enabled"}},
)

reasoning = response.choices[0].message.reasoning_content  # 推理链
answer = response.choices[0].message.content               # 最终答案

多轮对话中的思维处理

当轮次之间没有工具调用时，前几轮的 reasoning_content 无需包含在后续请求中。DeepSeek API 会自动忽略。但当涉及工具调用时，reasoning_content 必须在所有后续轮次中传回——遗漏会导致 400 错误。

何时禁用思维

• 简单事实查询 — 思维只增加延迟，不提升质量
• 高吞吐对话 — 禁用思维以充分利用 V4-Flash 的并发优势
• 成本敏感场景 — 思维 token 按输出价格计费

来源：DeepSeek API 文档——思维模式，检索于 2026-06-07。

工具调用与 JSON 输出

两个 V4 模型均支持函数/工具调用和结构化 JSON 输出，兼容 OpenAI 规范。

工具调用

import json

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取指定城市的当前天气",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "城市名称"},
                },
                "required": ["city"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "北京天气怎么样？"}],
    tools=tools,
    tool_choice="auto",
)

if response.choices[0].message.tool_calls:
    call = response.choices[0].message.tool_calls[0]
    print(f"函数：{call.function.name}")
    print(f"参数：{json.loads(call.function.arguments)}")

JSON 输出

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "请以 JSON 格式回复。"},
        {"role": "user", "content": "列出 3 种编程语言及其创建年份。"},
    ],
    response_format={"type": "json_object"},
)
print(json.loads(response.choices[0].message.content))

FIM 补全（代码补全）

两个模型在非思维模式下均支持 Fill-in-the-Middle 补全：

response = client.completions.create(
    model="deepseek-v4-flash",
    prompt="def fibonacci(n):\n    ",
    suffix="    return fib",
)
print(response.choices[0].text)

来源：DeepSeek API 文档——工具调用，检索于 2026-06-07。

定价与速率限制

定价（每 100 万 tokens）

来源：DeepSeek API 文档——模型与定价，检索于 2026-06-07。价格可能变动。

缓存命中价格比缓存未命中便宜约 50 倍。这使得 DeepSeek 在复用相同系统提示或长上下文的场景下——如 RAG 管线、Agent 循环或共享代码库前缀的代码分析工具——性价比极高。

速率限制（并发）

DeepSeek 在账户级别计量并发——一个请求从发送到响应完成都占用并发。超限返回 HTTP 429。除并发限制外，没有单独的 token/分钟或请求/分钟限制。

如需更高并发，DeepSeek 提供扩容申请表，无需额外费用。

来源：DeepSeek API 文档——速率限制与隔离，检索于 2026-06-07。

计费方式

DeepSeek 采用预付费余额（充值或赠送）。赠送额度优先使用。价格可能调整——DeepSeek 建议根据实际使用量充值，并定期查看定价页面。

常见错误与修复

思维模式常见陷阱

• temperature / top_p 在思维模式下无效： 设置这些参数不会报错，但在思维启用时没有效果。
• 工具调用轮次中遗漏 reasoning_content： 如果模型执行了工具调用，后续请求必须包含 reasoning_content。遗漏会导致 400 错误。
• reasoning_effort 兼容性： low 和 medium 会被静默映射为 high；xhigh 映射为 max。不要将它们作为不同级别使用。

保活机制

当请求等待推理时，DeepSeek API 会发送周期性保活信号（非流式为空行，流式为 SSE 注释）。如果手动解析 HTTP 响应，请妥善处理这些内容。如果推理在 10 分钟内未开始，服务器将关闭连接。

来源：DeepSeek API 文档——FAQ，检索于 2026-06-07。

将 DeepSeek 与其他供应商搭配路由

如果你在构建生产应用，依赖单一供应商是有风险的。以下是我们建议的路由策略：

使用 TheRouter

如果你使用 TheRouter，可以将 DeepSeek 配置为供应商之一。TheRouter 通过已配置的供应商路由 OpenAI 兼容请求，并在实际产品路径支持时提供供应商/模型回退。这意味着你可以将 DeepSeek 设为主供应商、另一个设为备用——无需修改应用代码。

手动回退模式

如果你自行处理回退：

import openai
import time

providers = [
    {"name": "deepseek", "base_url": "https://api.deepseek.com", "model": "deepseek-v4-flash", "key": "DS_KEY"},
    {"name": "siliconflow", "base_url": "https://api.siliconflow.cn/v1", "model": "deepseek-v4-flash", "key": "SF_KEY"},
    {"name": "other", "base_url": "https://api.other-provider.com/v1", "model": "deepseek-v4-flash", "key": "OTHER_KEY"},
]

for provider in providers:
    try:
        client = openai.OpenAI(api_key=provider["key"], base_url=provider["base_url"])
        response = client.chat.completions.create(
            model=provider["model"],
            messages=[{"role": "user", "content": "你好！"}],
            timeout=30,
        )
        print(f"通过 {provider['name']} 成功")
        break
    except Exception as e:
        print(f"{provider['name']} 失败：{e}")
        time.sleep(1)

DeepSeek 模型可通过 SiliconFlow 等第三方聚合器广泛使用，为 DeepSeek 自身 API 出现区域性问题时提供地理冗余。

生产上线检查清单

在将 DeepSeek 推入生产环境前：

• 切换旧版模型名称 — 如使用 deepseek-chat 或 deepseek-reasoner，请在 2026 年 7 月 24 日前迁移到 deepseek-v4-flash
• 显式设置思维模式 — 不要依赖默认值；根据使用场景传入 {"thinking": {"type": "enabled"}} 或 {"type": "disabled"}
• 在工具调用轮次中处理 reasoning_content — 在后续请求中传回以避免 400 错误
• 监控并发量 — V4-Flash 并发限制为 2,500；V4-Pro 为 500
• 设置备用供应商 — 不要为生产流量依赖单一 API 端点
• 利用上下文前缀缓存 — DeepSeek 的磁盘缓存使重复系统提示极其便宜（V4-Flash 缓存命中 $0.0028/100 万）
• 使用 user_id 进行多租户隔离 — 为你的用户之间的内容安全、KVCache 和调度隔离传递 user_id 参数
• 设置超时 — 设定合理超时（如 60 秒）以避免长时间思维请求导致连接挂起
• 及时充值 — DeepSeek 采用预付费模式；定期检查余额并在用完前充值

常见问题

Q：DeepSeek 可以和 Claude Code 或 GitHub Copilot 一起用吗？ A：可以。DeepSeek 支持与 Claude Code、GitHub Copilot、OpenCode 等 Agent 工具直接集成。详情见 Agent 集成指南。

Q：V4-Flash 和 V4-Pro 有什么区别？ A：V4-Pro 是更强的推理模型——在复杂基准测试中得分更高，处理多步分析更出色。V4-Flash 更快、更便宜，并发量高 5 倍（2,500 vs 500）。大多数生产场景用 V4-Flash；需要深度推理或复杂工具调用链时用 V4-Pro。

Q：思维 token 额外收费吗？ A：是的。思维 token（reasoning_content 输出）按输出 token 价格计费。如果不需要深度推理，禁用思维模式可降低成本。

Q：DeepSeek API 真的兼容 OpenAI 吗？ A：是的——端点实现了 OpenAI ChatCompletions 规范。任何支持 OpenAI 格式的工具、SDK 或代码，只需修改 base_url 和 API key 即可使用 DeepSeek。DeepSeek 还支持 Anthropic 格式的端点 https://api.deepseek.com/anthropic。

Q：上下文缓存是如何工作的？ A：DeepSeek 使用基于磁盘的上下文缓存。当多个请求共享相同前缀（系统提示、共享上下文）时，仅首次请求支付完整输入价格。后续相同前缀的请求按缓存命中价格计费——V4-Flash 为 $0.0028/100 万，而缓存未命中为 $0.14/100 万。此过程自动进行，无需配置。

Q：可以在本地运行 DeepSeek 模型吗？ A：可以。V4-Flash 和 V4-Pro 的权重均在 HuggingFace 上以 MIT 许可证发布。但本地部署需要大量 GPU 资源。生产使用中，API 更简单且更具性价比。

Q：DeepSeek-R1 怎么了？ A：V4 的思维模式实际上取代了 R1 推理线路。如果你之前使用 deepseek-r1 进行复杂推理，现在应切换到启用思维的 deepseek-v4-pro。R1 仍可通过 SiliconFlow 等第三方供应商使用，但 DeepSeek 自身 API 正在聚焦 V4 线路。

---

最后更新：2026 年 6 月 7 日。定价和模型可用性来源于 DeepSeek API 文档。所有价格可能变动——预算前请在 platform.deepseek.com 核实当前费率。