DeepSeek API 入门指南：V4 快速上手实践

如果您已经配置了OpenAI或Anthropic客户端，DeepSeek API的入门路径足够短，可以在咖啡冷却之前完成：更改基本URL，粘贴API密钥，选择模型ID，发送请求。这是好消息。本指南的其余部分涵盖了快速入门页面通常略过的问题——选择两个V4级别中的哪一个，如何实际切换思维模式，为什么API是无状态的，尽管网页聊天不是，以及如何避免意外账单来估算工作负载成本。

我在生产环境中运行DeepSeek V4-Flash和V4-Pro，与Claude和GPT-5一起，因此以下每项推荐都是基于截至2026年4月的实际使用情况。到那时，您将拥有一个工作的Python调用，一个正确的成本估算，以及针对旧模型ID的迁移计划。

本指南中您将构建的内容

三个具体成果：一个工作请求 POST /chat/completions 在Python中对 deepseek-v4-flash的请求，第二个调用使能了思考模式 deepseek-v4-pro以及一个包含缓存命中、缓存未命中和输出令牌的成本估算。所有内容都使用官方OpenAI SDK——DeepSeek的聊天界面与OpenAI的兼容，因此您不需要DeepSeek特定的客户端库。

在步骤之前进行简要的说明。当前一代产品于2026年4月24日发布，以MIT许可证提供两个开放重量的MoE模型： DeepSeek V4（1.6T总参数量 / 49B活跃参数，前沿级别）和 deepseek-v4-pro Python 3.9+及 deepseek-v4-flash (284B / 13B活跃，成本效益级别)。两者共享相同的功能集，100万个令牌的上下文窗口，以及最多384,000个输出令牌。思维模式是两个级别上的请求参数，而不是单独的模型ID。

Prerequisites

• pip pip 可用，或如果你偏好JavaScript，则使用Node.js 18+。
• 深寻平台账户和一个API密钥。如果您还没有，请参阅我们关于如何获取的配套文章。 get a DeepSeek API key 首先的。
• 在计费控制台中大约有1美元的信用额度。现实中的Flash级测试成本极低；在看到第6步的成本计算之前，请将Pro级实验保持简短。
• 熟悉环境变量。请勿在可能提交的文件中硬编码密钥。

第1步：安装OpenAI SDK

由于深寻支持与OpenAI兼容的线缆格式，一旦您将其重定向，任何OpenAI客户端都可以使用。使用pip安装官方SDK：

pip install openai

Node.js用户可以运行 npm install openai 取而代之。深寻还提供了一个与Anthropic兼容的表面，位于相同的基URL，因此如果您的代码库已经使用Anthropic SDK，那么Anthropic SDK是一个即插即用的替代方案。请参阅我们关于的笔记。 DeepSeek OpenAI SDK compatibility 进行参数到参数的映射。

第2步：安全存储您的API密钥

将密钥导出到你的shell中，使其存在于源树之外：

export DEEPSEEK_API_KEY="sk-..."

在Windows PowerShell中，使用 $env:DEEPSEEK_API_KEY = "sk-..."。对于长期设置，将其放入一个 .env 文件中，该文件位于 .gitignore。如果密钥泄露，请立即从计费控制台中更换它——我们关于的撰写中有更多细节。 DeepSeek API authentication.

第3步：发出您的第一个请求

标准聊天端点是 POST /chat/completions，通过 base_url="https://api.deepseek.com"这里是一个发送非思考请求到V4-Flash的最小Python脚本：

import os
from openai import OpenAI

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

resp = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "You are a terse assistant."},
        {"role": "user", "content": "Summarise MoE architecture in two sentences."},
    ],
    temperature=1.3,
    max_tokens=400,
    extra_body={"thinking": {"type": "disabled"}},  # V4 enables thinking by default; disable for the simplest first call
)

print(resp.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":"Hello"}],
    "temperature": 1.3,
    "thinking": {"type": "disabled"}
  }'

选择合适的温度

DeepSeek发布了针对特定任务的指导， temperature，与之匹配可以为您节省大量的提示调整：

• 0.0 ——代码生成和数学。
• 1.0 ——数据分析和数据清洗。
• 1.3 ——通用对话和翻译。
• 1.5 ——创意写作和诗歌。

您可以使用 top_p 作为替代品或补充，并且 max_tokens 限制输出长度——尤其是在JSON模式下，截断会产生无效输出。

第4步：在V4-Pro上启用思考模式

思考模式默认启用。使用 extra_body={"thinking": {"type": "disabled"}} 进行非思考请求。使用 reasoning_effort="high" or reasoning_effort="max" 在V4模型上进行思考模式请求。当启用思考模式时，API返回 reasoning_content alongside the final content.

resp = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Plan a zero-downtime Postgres 14-to-16 upgrade."}],
    reasoning_effort="high",
    extra_body={"thinking": {"type": "enabled"}},
)

print("Reasoning:", resp.choices[0].message.reasoning_content)
print("Answer:", resp.choices[0].message.content)

为了 reasoning_effort="max"，请确保您的运行时允许一个 max_model_len 至少包含393,216个token（384K）的推理轨迹不会被截断。对于对延迟敏感或高量级的聊天，使用非思考模式；当任务需要真实规划、多步骤推理或代理工具调用时，使用思考模式。

第5步：了解要发送的模型ID

V4重新设计了模型选择器。以下是当前状态，包括在迁移窗口期间仍被接受的旧ID：

如果您有一个围绕旧版 ID 构建的集成，迁移只需一行代码 model= swap — base_url 不会改变。在退休截止日期之前进行更改，以避免请求失败。关于架构转变的深入背景，请参阅我们的 DeepSeek V4 explainer.

第6步：正确计算工作负载成本

V4-Flash和V4-Pro各有三个token桶：缓存命中输入、缓存未命中输入和输出。省略任何一个——特别是每次调用中的未缓存用户消息——会产生一个过于乐观的估计，即现实不会遵守。

V4-Flash费率（每1M个token，截至2026年4月）

V4-Pro费率（每1M个token，截至2026年4月）

实例分析：1,000,000次V4-Flash调用

假设一个2,000个token的缓存系统提示，每次调用200个未缓存用户消息token，以及一个300个token的响应：

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

The same workload on deepseek-v4-pro 通过 2026-05-31 的 75% 促销价格为 $7.25 + $87.00 + $261.00 = $355.25 （列表费率：$29 + $348 + $1,044 = $1,421.00）——促销期间大约是Flash的3倍，在列表中大约是12倍。当前沿基准提升足以证明支出合理（代理编码、深度推理）时选择Pro，对于聊天、总结和标准工具调用则坚持使用Flash。请注意，高峰时段折扣不再有效——DeepSeek已于2025年9月5日结束它们。请检查实时 DeepSeek API pricing 在将数字纳入商业案例之前，请先查看页面 DeepSeek pricing calculator 用于任意工作负载。

第7步：处理无状态性

API是无状态的——您必须在每个请求中重新发送会话历史。这与网页聊天和移动应用形成对比，它们会为您维护会话历史。多轮模式看起来是这样的：

history = [{"role": "system", "content": "You are a terse assistant."}]

def turn(user_text):
    history.append({"role": "user", "content": user_text})
    resp = client.chat.completions.create(
        model="deepseek-v4-flash",
        messages=history,
    )
    reply = resp.choices[0].message.content
    history.append({"role": "assistant", "content": reply})
    return reply

由于DeepSeek将缓存命中计费为未命中率的几分之一，重复的稳定前缀——一个长的系统提示，一个检索前缀，一个工具模式——在后续调用中变得便宜。我们的指南是 DeepSeek context caching 覆盖了前缀规则。

第8步：在需要时添加JSON模式、工具和流

三个功能覆盖了除简单聊天之外的大多数生产需求：

• JSON mode. Set response_format={"type": "json_object"}。它旨在返回有效的JSON，但不保证。在提示中包含“json”一词以及一个小示例模式，设置 max_tokens 足够高以避免截断，并优雅地处理偶尔的空内容。
• 工具调用。 使用与OpenAI兼容的格式声明工具；在思维和非思维模式下都受支持。对于路由到搜索、计算器或内部API非常有用。
• Streaming. Pass stream=True 获取服务器发送的事件块。当启用思维时，推理内容流与最终答案一起流——如果您向最终用户展示，请将它们渲染到单独的UI面板中。

两个值得了解的Beta功能： FIM（中间填充）补全 用于代码用例（仅非思考模式 — 传递 extra_body={"thinking": {"type": "disabled"}} 不要传递 reasoning_effort），以及 聊天前缀补全 用于续写风格的提示。

验证是否成功

首次成功通话后的快速检查清单：

1. 响应状态为200且 choices[0].message.content 内容非空。
2. The usage 域报告令牌计数，您可以与计费控制台进行核对。
3. 为了 thinking-mode calls, reasoning_content 也会填充，除了 content.
4. 您可以在第6步中针对 usage 的数字重现成本计算。

Common errors and fixes

Next steps

您现在拥有一个工作集成的系统、一个正确的成本模型以及一个迁移计划。从现在开始，有两个方向值得您投入时间：通过我们的示例强化开发者的用户体验（流式处理、工具调用、JSON模式）。 DeepSeek API code examples，或使用该工具将工作负载推入代理和RAG工作负载中。 DeepSeek RAG tutorial。如果您想了解完整的开发者资源全景，该 DeepSeek tutorials 中心拥有其余的序列。

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.