deepseek-api-guide

name	deepseek-api-guide
description	指导 Agent 在项目中调用 DeepSeek API 的完整技能。涵盖 OpenAI 格式和 Anthropic 格式的 API 调用、模型选择（deepseek-v4-pro / deepseek-v4-flash）、思考模式、Tool Calls、JSON Output、多轮对话、错误处理、上下文缓存等。适用于任何需要集成 DeepSeek 大模型能力的项目开发任务。当用户提到 DeepSeek API、deepseek-v4、调用 DeepSeek 模型、集成 DeepSeek 到项目、或者需要在代码中使用 DeepSeek 时触发此技能。

DeepSeek API 调用指南

快速开始

DeepSeek API 兼容 OpenAI 和 Anthropic 格式，使用 base_url 替换即可接入。

格式	base_url
OpenAI	https://api.deepseek.com
Anthropic	https://api.deepseek.com/anthropic

获取 API Key：https://platform.deepseek.com/

最小调用示例（OpenAI SDK）

from openai import OpenAI

client = OpenAI(api_key="<DeepSeek API Key>", base_url="https://api.deepseek.com")

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ]
)
print(response.choices[0].message.content)

最小调用示例（Anthropic SDK）

import anthropic

client = anthropic.Anthropic(api_key="<DeepSeek API Key>")

message = client.messages.create(
    model="deepseek-v4-pro",
    max_tokens=1000,
    messages=[{"role": "user", "content": [{"type": "text", "text": "Hello!"}]}]
)
print(message.content)

模型选择

场景	推荐模型	说明
通用任务、追求性价比	deepseek-v4-flash	速度快，价格低，支持思考模式
复杂推理、高质量输出	deepseek-v4-pro	性能更强，思考效率更高
旧代码兼容	deepseek-chat / deepseek-reasoner	将于 2026-07-24 弃用，分别映射到 v4-flash 的非思考/思考模式

注意：deepseek-v4-flash 默认开启思考模式。如需关闭，设置 thinking={"type": "disabled"}。

核心工作流

1. 基本对话调用

from openai import OpenAI

client = OpenAI(api_key="<DeepSeek API Key>", base_url="https://api.deepseek.com")

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ],
    stream=False  # 设为 True 开启流式输出
)
print(response.choices[0].message.content)

2. 多轮对话

API 是无状态的，每次请求必须携带完整对话历史。

messages = [{"role": "user", "content": "Hello!"}]
response = client.chat.completions.create(model="deepseek-v4-pro", messages=messages)

# 将 assistant 回复追加到上下文
messages.append(response.choices[0].message)
messages.append({"role": "user", "content": "How are you?"})

response = client.chat.completions.create(model="deepseek-v4-pro", messages=messages)

3. 思考模式（Reasoning）

模型先输出思维链，再输出最终答案。deepseek-v4-pro 和 deepseek-v4-flash 均支持。

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "9.11 and 9.8, which is greater?"}],
    reasoning_effort="high",  # "high" 或 "max"
    extra_body={"thinking": {"type": "enabled"}}
)

# 思维链内容
reasoning = response.choices[0].message.reasoning_content
# 最终答案
answer = response.choices[0].message.content

思考模式下的多轮对话：

• 无工具调用时：reasoning_content 无需回传（会被 API 忽略）
• 有工具调用时：reasoning_content 必须完整回传，否则返回 400 错误

# 正确回传方式（工具调用后）
messages.append(response.choices[0].message)
# 等价于手动拼接 content + reasoning_content + tool_calls

4. Tool Calls（函数调用）

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get weather of a location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "City name"}
                },
                "required": ["location"]
            }
        }
    }
]

messages = [{"role": "user", "content": "How's the weather in Hangzhou?"}]
response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=messages,
    tools=tools
)

message = response.choices[0].message
messages.append(message)

# 执行工具函数
tool = message.tool_calls[0]
tool_result = get_weather(**json.loads(tool.function.arguments))

# 将工具结果回传
messages.append({"role": "tool", "tool_call_id": tool.id, "content": tool_result})

# 获取最终回答
response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=messages,
    tools=tools
)
print(response.choices[0].message.content)

strict 模式（Beta）：强制模型严格遵循 JSON Schema。需要设置 base_url="https://api.deepseek.com/beta"，并在所有 tool 的 function 中设置 strict: true。

5. JSON Output

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Summarize this in JSON"}],
    response_format={"type": "json_object"}
)
result = json.loads(response.choices[0].message.content)

注意：在 prompt 中必须明确说明期望的 JSON 结构，否则模型可能输出不完整。

6. 流式输出

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

关键参数速查表

参数	类型	说明
model	string	deepseek-v4-pro / deepseek-v4-flash
messages	array	对话历史，每条包含 role 和 content
stream	boolean	是否流式输出，默认 false
temperature	float	0-2，默认 1，思考模式下不生效
max_tokens	integer	最大输出长度
response_format	object	{"type": "json_object"} 强制 JSON 输出
tools	array	Tool 定义列表
reasoning_effort	string	"high" / "max"，思考强度控制
thinking	object	{"type": "enabled"} 或 "disabled"，思考模式开关
user_id	string	业务用户隔离，正则 [a-zA-Z0-9\-_]+，最大 512 字符

错误处理

错误码	含义	处理方式
400	请求格式错误或参数错误	检查请求体和参数
401	API Key 认证失败	检查 API Key 是否有效
402	余额不足	前往平台充值
429	并发/速率达到上限	降低请求频率或申请扩容
500	服务器内部故障	稍后重试
503	服务器繁忙	稍后重试

最佳实践

1. 优先使用流式输出：API 默认非流式，使用 stream=True 提升交互体验
2. 处理保活空行：非流式请求等待时持续返回空行，流式返回 SSE : keep-alive，自行解析时需注意过滤
3. 利用上下文缓存：重复前缀（如 system prompt、长文档）会自动命中缓存，大幅降低输入成本
4. 思考模式与工具调用：当使用工具调用时，若开启思考模式，必须正确回传 reasoning_content
5. user_id 隔离：多租户场景下使用 user_id 实现内容和缓存隔离，避免用户间数据泄露
6. Beta 功能：对话前缀续写、FIM 补全、strict 模式需使用 base_url="https://api.deepseek.com/beta"

完整参考文档

本文档仅包含核心调用指南。完整的模型参数、价格详情、错误码列表、缓存机制、FAQ 等请参阅：

references/deepseek-api-reference.md

该参考文件包含：

• 完整模型参数与价格表
• Token 用量计算方法
• 限速与隔离机制（并发限制、user_id 隔离）
• 思考模式完整说明（多轮对话拼接、工具调用回传）
• 对话前缀续写和 FIM 补全示例
• JSON Output 和 Tool Calls 详细示例
• 上下文硬盘缓存机制
• Anthropic API 格式示例
• 常见问题与更新日志