使用DeepSeek与OpenAI SDK：实践指南

如果您已经有一个工作的OpenAI集成，并希望将其指向DeepSeek的V4模型，答案是真正只有两行代码。DeepSeek与OpenAI的兼容性意味着线缆格式与OpenAI的Chat Completions API足够接近，以至于在交换`base_url`和`api_key`后，官方的`openai` Python和Node SDKs可以在`https://api.deepseek.com`上工作。无需重新构建请求，无需更改响应解析器，无需新的依赖项。

难点——而且总是有——在于V4特定的参数、无状态对话模型、JSON模式的注意事项以及计划于2026年7月24日退役的旧ID。本指南将指导您了解哪些可以干净迁移，哪些需要调整，一个真实的成本示例是什么样的，以及OpenAI兼容的表面在哪里停止像OpenAI一样行为。

这里“OpenAI兼容”实际上意味着什么

DeepSeek的官方文档明确指出，DeepSeek API使用与OpenAI/Anthropic兼容的API格式，通过修改配置，您可以使用与OpenAI/Anthropic API兼容的OpenAI/Anthropic SDK或软件来访问DeepSeek API。在实践中，这意味着Chat Completions请求和响应封装—— messages 数组，该 角色/content 形状，该 choices[0].message.content 路径，该 usage 块，该 stream=true SSE 数据块——全部匹配。

您可以通过更改两个值将 SDK 指向 DeepSeek：

• base_url → https://api.deepseek.com (or https://api.deepseek.com/v1)
• api_key → 平台控制台中的您的 DeepSeek 密钥

聊天端点是 POST /chat/completions。为了实现OpenAI风格的兼容性，您也可以使用https://api.deepseek.com/v1作为base_url，但这里的v1与模型的版本无关——它是一个OpenAI SDK默认附加的路径别名。Beta功能，如Chat Prefix Completion和FIM（填空中间）位于 https://api.deepseek.com/beta.

一个值得一开始就弄清楚的区别：DeepSeek 还暴露了一个 Anthropic-compatible 同一主机名下。DeepSeek V4在https://api.deepseek.com/v1/chat/completions的OpenAI兼容端点和https://api.deepseek.com/anthropic的Anthropic兼容端点上发货。选择与您现有代码匹配的SDK；两者都击中相同的底层V4模型。

快速入门：curl 和 Python

这里是对 DeepSeek 的最小调用示例 deepseek-v4-flash，成本效益级别，使用DeepSeek的默认思考模式。（对于非思考模式，需显式传递 thinking: {"type": "disabled"} 在 JSON 主体中，或 extra_body={"thinking": {"type": "disabled"}} 在 Python 中。) 首先，curl 版本的 POST /chat/completions:

curl https://api.deepseek.com/chat/completions 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" 
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {"角色": "system", "content": "You are a concise assistant."},
      {"角色": "user", "content": "Summarise the OpenAI Chat Completions schema in one sentence."}
    ],
    "stream": false
  }'

使用官方 OpenAI Python SDK 的相同调用——请注意，该 仅 从真实OpenAI集成中进行的更改是 base_url 以及模型字符串：

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
)

resp = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"角色": "system", "content": "You are a concise assistant."},
        {"角色": "user", "content": "Hello"},
    ],
)
print(resp.choices[0].message.content)

如果您想要启用思考功能的边缘级别模型，切换模型ID并通过传递DeepSeek特定的字段 extra_body，这是OpenAI SDK如何将非OpenAI参数转发到服务器的：

resp = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"角色": "user", "content": "Plan the migration."}],
    reasoning_effort="high",
    extra_body={"thinking": {"type": "enabled"}},
)

如果您是刚开始，我们关于 how to get a DeepSeek API key 的操作指南中的步骤涵盖了控制台设置以及平台在请求成功之前所需的第一次 $2 充值。

V4 模型 ID 和旧版迁移窗口

DeepSeek的当前一代产品，于2026年4月24日发布，以两个开放重量的MoE模型的形式发货，它们具有相同的OpenAI兼容表面，但在大小和价格上有所不同：

两者都默认为100万个token的上下文窗口，并接受最多384,000个token的输出。DeepSeek表示V4-Pro有1.6T个总参数，其中49B个是活跃的，而V4-Flash有284B个总参数，其中13B个是活跃的，该架构使用混合注意力、MoE路由和后训练设计，旨在提高代理行为的同时减轻超长上下文的计算负担。完整的架构分解可在以下网址找到： DeepSeek V4 page.

如果您在旧ID上已有现有集成，以下是迁移表：

DeepSeek的发布说明对此进行了明确说明：保持base_url不变，只需更新模型为deepseek-v4-pro或deepseek-v4-flash；deepseek-chat和deepseek-reasoner将在2026年7月24日15:59 UTC之后完全退役且不可访问，目前正路由到deepseek-v4-flash的非思考/思考模式。以下是 base_url 不变。迁移是每个调用点的单行差异。

Thinking mode is a parameter, not a model

这是来自V3.x时代或OpenAI的o系列的人士面临的最大变化。在V4中，思考是任一模型的请求参数，而不是一个单独的ID。接受三种设置：

• Non-thinking: 通过 extra_body={"thinking": {"type": "disabled"}}. 每次请求最快且最便宜。（V4默认为启用思考功能。）
• Thinking (high): reasoning_effort="high" plus extra_body={"thinking": {"type": "enabled"}}.
• Thinking-max: reasoning_effort="max". 需要 max_model_len >= 393216 （384K个令牌）以避免截断。

当思考功能开启时，响应携带 reasoning_content alongside the final contentDeepSeek的文档说明，在思考模式下，推理跟踪内容通过reasoning_content参数返回，与内容处于同一级别。有两个重要的操作细节：

• 思考模式不支持温度、top_p、存在惩罚或频率惩罚参数；为了与现有软件兼容，设置这些参数不会触发错误，但也不会产生任何效果。
• 在V4上，当思考回合包含一个条目时， tool_calls 您 必须将其回传到下一个请求中 reasoning_content back into the next request 省略它将触发400错误。对于不带工具调用的纯思考转向，V4不需要这个往返；旧版本 deepseek-reasoner rejects reasoning_content on input, so strip it 仅 when targeting that legacy ID.

参数兼容性，逐行分析

For a deeper walk 通过 the request 形状，该 DeepSeek API documentation 辅助端点。 辅助端点。 and 辅助端点。 调用是独立的——服务器没有之前回合的记忆。您的客户端必须重新发送完整的

无状态陷阱

在chat.deepseek.com的网页聊天中，您的对话历史记录保存在服务器端。API不是这样。每次 POST /chat/completions 实际上，这意味着多回合循环看起来像这样： messages 请求中的数组，以维持多轮对话。这与OpenAI的行为相同，但值得指出，因为聊天机器人UI会掩盖这一点。

如果您使用了思维模式，则只需将

messages = [{"角色": "system", "content": "You are a helpful assistant."}]
while True:
    user_text = input("> ")
    messages.append({"角色": "user", "content": user_text})
    resp = client.chat.completions.create(
        model="deepseek-v4-flash",
        messages=messages,
    )
    reply = resp.choices[0].message
    messages.append({"角色": "assistant", "content": reply.content})
    print(reply.content)

If you used thinking mode, append 仅 content ——附加到下一个请求。 reasoning_content 通过OpenAI SDK实现的高级功能；它们只需要适当的注意事项。

JSON 模式，工具调用，FIM，流式传输

DeepSeek的文档将此描述为

JSON mode

Set response_format={"type": "json_object"}. DeepSeek’s docs describe this as designed 返回有效的JSON，而不是 保证。三条规则确保生产代码的安全性：

1. Include the word json 在您的提示和一个小型示例模式中。
2. Set max_tokens 足够高，以至于JSON不会被截断。
3. 处理返回空的情况。 content 返回空。

详细机制在我们的 DeepSeek API JSON mode guide.

Tool calling

OpenAI格式 tools 声明中有所覆盖。模型在助手消息上发出 tool_calls 条目，您的代码执行它们，并在下一次请求之前添加一个 {"角色": "tool", "tool_call_id": ..., "content": ...} 轮。思维和非思维模式都支持工具。

FIM completion (Beta)

在V4的非思维模式下，提供 non-thinking mode 仅，与 https://api.deepseek.com/beta 基础URL。适用于IDE风格的代码建议；如果您还需要逐步推理，则不适用。

Streaming

Set stream=true 并消费SSE块。这些增量包含 delta.content ，在思考模式下它们还额外包含 delta.reasoning_content。流模式和建议的背压技巧可以在我们的 DeepSeek API streaming reference.

一个实际成本示例：V4-Flash 与 V4-Pro

Pricing as of April 2026, per the 官方DeepSeek API文档中找到。在做出承诺之前，请在定价页面上进行验证——预览窗口的费率可能会变动。

想象一下有100万次调用，每次调用都包含一个2000个token的系统提示（第一次调用后缓存），一个200个token的用户消息（始终不缓存——缓存只匹配稳定的词前缀，不匹配新的用户输入），以及一个300个token的响应。

On deepseek-v4-flash:

• Cached input: 2,000 × 1,000,000 = 2,000,000,000 × $0.0028/M = $5.60
• Uncached input: 200 × 1,000,000 = 200,000,000 × $0.14/M = $28.00
• Output: 300 × 1,000,000 = 300,000,000 × $0.28/M = $84.00
• Total: $117.60

On deepseek-v4-pro:

• Cached input: 2,000,000,000 × $0.003625/M (promo) = $7.25 (list $29.00)
• Uncached input: 200,000,000 × $0.435/M (promo) = $87.00 (list $348.00)
• Output: 300,000,000 × $0.87/M (promo) = $261.00 (list $1,044.00)
• Total: $355.25 (V4-Pro 75% promo 通过 2026-05-31; list $1,421.00)

V4 Pro在2026年5月31日前的V4-Pro 75%促销期间，其价格大约是Flash的3倍，在正常价格列表中则是大约14倍。V3.1/V3.2时代适用的非高峰折扣于2025年9月5日结束，并且没有在V4中重新引入。对于交互式估计，它采用相同的三个桶并产生每个调用次数。重复的前缀会自动获得缓存命中价格层——前缀缓存机制在[2]中有详细说明。 DeepSeek pricing calculator 它采用相同的三个桶并为每个调用生成一个数字。重复的前缀会自动获得缓存命中价格层——前缀缓存机制在[2]中有详细说明。 DeepSeek context caching.

错误处理和速率限制

错误代码与OpenAI信封匹配，但有两条值得记住的DeepSeek特定的小问题：

• 402 Insufficient Balance 如果您的账户没有信用，将立即触发。在集成测试之前请先充值。
• 422 这是如果您发送了不受支持的字段组合时将看到的参数验证错误——例如， logprobs 在思考模式中。
• 429 and 5xx 应该使用指数退避重试错误。

将调用包裹在处理429和5xx状态码的指数退避的重试辅助器中；不要自动重试4xx错误——它们是逻辑错误，而不是暂时性故障。完整的代码表位于 DeepSeek API error codes reference.

当OpenAI兼容性不再完美匹配时

兼容性表面积很广，但并非100%。一个简短、诚实的列表，说明了它泄漏的地方：

• 无响应API。 DeepSeek实现了聊天完成功能。如果您的代码使用了OpenAI的新 client.responses.create 路径，您需要回退到 client.chat.completions.create.
• 没有助手API，没有文件API，没有嵌入。 兼容OpenAI的界面是聊天完成形状，而不是完整的OpenAI平台。
• 思维模式参数的怪癖。 Sampling controls are silently ignored; logprobs 出错。
• 样本默认值不同。 DeepSeek推荐温度=1.0，top_p=1.0；不要导入GPT-5.5或Claude的默认值。
• Anthropic SDK也适用。 如果您的堆栈已经支持Claude的消息格式，将其指向 https://api.deepseek.com/anthropic 而不是重新编写它。

对于更广泛的模式——重试、幂等性、可观察性——该 DeepSeek API best practices 页面收集我们在生产中运行的内容。如果您正在评估是否需要更换提供商， DeepSeek vs ChatGPT 将诚实地介绍权衡。

迁移清单

1. 获取一个密钥并将其至少 $2 添加到您的余额中——平台拒绝没有密钥的调用。
2. 更改 base_url to https://api.deepseek.com 并替换API密钥。
3. 将OpenAI模型字符串替换为 deepseek-v4-flash （默认）或 deepseek-v4-pro （前沿层工作）。
4. 如果您的代码中存在旧版本 deepseek-chat or deepseek-reasoner ，请在 2026年7月24日15:59 UTC之前更新。.
5. 决定是思考型还是非思考型 每个调用点；受功能标志门控 reasoning_effort="max" 限制，因为成本可能会激增。
6. 保留您的重试/退避层；DeepSeek的错误代码与OpenAI的形状足够接近，以至于现有的处理器通常无需更改即可迁移。
7. 运行一个小型评估工具包——即使是十个代表性的提示在两个级别上也能告诉您Pro的质量提升是否值得您在数据上的投入。

要了解API将做什么以及不会做什么的更全面概述，请参阅完整的 DeepSeek API docs and guides.

DeepSeek AI Guide is an independent resource and is not affiliated with DeepSeek or its parent company. Model IDs, pricing and API behaviour change; check the official DeepSeek documentation and pricing page before committing to a production decision.