背景介绍：DeepSeek R1 与 V3 是两种不同定位的模型
红烁AI 培训，红烁 AI 中转站为您整理：DeepSeek 在 2024 至 2025 年间相继发布了 DeepSeek-V3 和 DeepSeek-R1 两款旗舰模型。两者虽然共用同一套 API 基础设施，底层能力定位却截然不同：
- DeepSeek-V3：通用对话与代码生成模型，采用混合专家架构（MoE），强调高吞吐、低延迟，适合需要快速响应的生产场景。
- DeepSeek-R1：推理增强型模型，内置”思维链”（Chain-of-Thought）推理过程，擅长数学、逻辑推导和复杂问题分析，响应中会包含独立的推理内容块。
正因为定位不同，两者在 API 请求格式上存在若干关键差异。如果直接将调用 V3 的代码套用到 R1，轻则得不到预期输出，重则触发参数错误。理解这些区别是稳定集成的第一步。
核心区别一：模型标识符（model 字段）
最直接的区别是请求体中 model 字段的取值。DeepSeek 官方 API 目前支持以下标识符：
- DeepSeek-V3：
deepseek-chat - DeepSeek-R1：
deepseek-reasoner
这两个标识符不可混用。deepseek-chat 路由到 V3 的推理后端，deepseek-reasoner 路由到 R1 的推理后端。请求示例对比如下：
// DeepSeek-V3 请求
{
"model": "deepseek-chat",
"messages": [...]
}
// DeepSeek-R1 请求
{
"model": "deepseek-reasoner",
"messages": [...]
}核心区别二：系统提示词（system prompt）的支持差异
DeepSeek-V3 完整支持 system 角色消息，可以通过系统提示词灵活定义模型的角色、输出风格和约束条件，这与主流 LLM API 的用法一致。
DeepSeek-R1 对系统提示词的支持存在限制。官方文档明确指出，R1 模型不推荐使用 system 消息，原因是 R1 的推理过程是在模型内部自主展开的，外部的角色设定可能干扰推理链的完整性，导致输出质量下降。建议将原本放在 system 中的指令直接合并到第一条 user 消息里。
// V3 推荐写法
{
"model": "deepseek-chat",
"messages": [
{"role": "system", "content": "你是一位专业的数据分析师。"},
{"role": "user", "content": "分析以下销售数据的趋势……"}
]
}
// R1 推荐写法（将指令并入 user 消息）
{
"model": "deepseek-reasoner",
"messages": [
{"role": "user", "content": "你是一位专业的数据分析师。请分析以下销售数据的趋势……"}
]
}核心区别三：响应结构中的推理内容字段
这是 R1 与 V3 在 API 层面最显著的结构差异。调用 DeepSeek-R1 时，响应体中每条 choices 的 message 对象会额外包含一个 reasoning_content 字段，存放模型的完整推理过程；最终答案则仍然在 content 字段中。
// DeepSeek-R1 响应结构示例
{
"choices": [
{
"message": {
"role": "assistant",
"reasoning_content": "首先分析题目条件……（推理过程）",
"content": "最终答案是 42。"
}
}
]
}DeepSeek-V3 的响应中不包含 reasoning_content 字段，message 对象只有标准的 role 和 content。如果你的解析代码直接读取 reasoning_content 而不做空值判断，在 V3 响应上会抛出字段不存在的错误。
核心区别四：温度参数（temperature）的推荐范围
两个模型对 temperature 参数的敏感度不同：
- DeepSeek-V3：
temperature可在 0 到 2 之间自由调整，常规对话建议设置在 0.7 至 1.0 之间。 - DeepSeek-R1：官方建议将
temperature设置为 1（默认值），不建议修改。R1 的推理过程依赖确定性较强的采样策略，过高的温度会破坏推理链的连贯性，过低则可能导致推理路径过于单一。
同样，top_p 参数在 R1 上也建议保持默认值 1，避免与推理机制产生冲突。
核心区别五：多轮对话中的上下文拼接规则
在多轮对话场景下，R1 有一条额外规则需要注意：上一轮 assistant 消息中的 reasoning_content 不应被拼接回下一轮请求的 messages 数组中。只需将 content 部分作为历史消息传入即可。
// 多轮对话时，R1 的 messages 拼接方式
{
"model": "deepseek-reasoner",
"messages": [
{"role": "user", "content": "第一轮问题"},
{"role": "assistant", "content": "第一轮答案"}, // 只传 content，不传 reasoning_content
{"role": "user", "content": "第二轮问题"}
]
}将 reasoning_content 误传回上下文不仅会增加 token 消耗，还可能导致模型行为异常。
实际应用：如何在代码中兼容两个模型
如果你的应用需要同时支持 V3 和 R1，建议封装一个统一的调用函数，在内部处理差异：
import openai
client = openai.OpenAI(
api_key="YOUR_DEEPSEEK_API_KEY",
base_url="https://api.deepseek.com"
)
def call_deepseek(prompt, model="deepseek-chat", system=None):
messages = []
if model == "deepseek-chat" and system:
messages.append({"role": "system", "content": system})
messages.append({"role": "user", "content": prompt})
else:
# R1 模式：将 system 指令合并到 user 消息
full_prompt = f"{system}\n\n{prompt}" if system else prompt
messages.append({"role": "user", "content": full_prompt})
params = {"model": model, "messages": messages}
if model == "deepseek-reasoner":
params["temperature"] = 1 # R1 固定温度
response = client.chat.completions.create(**params)
choice = response.choices[0].message
result = {"content": choice.content}
if hasattr(choice, "reasoning_content") and choice.reasoning_content:
result["reasoning"] = choice.reasoning_content
return result常见问题 FAQ
Q1：调用 R1 时传入 system 消息会报错吗？
不会直接报错，API 会正常返回响应，但官方不推荐这样做。实测中，system 消息可能被模型忽略或导致推理质量下降，建议遵循官方指引将指令并入 user 消息。
Q2：R1 的 reasoning_content 会计入 token 费用吗？
会。reasoning_content 中的 token 会计入输出 token 用量，在高频调用场景下需要注意成本控制。如果不需要展示推理过程，可以在业务层直接丢弃该字段，但无法在 API 层面关闭它的生成。
Q3：V3 和 R1 的 API base_url 一样吗？
是的，两者共用同一个端点 https://api.deepseek.com，通过 model 字段区分路由，无需配置不同的 base_url。
Q4：能用 OpenAI SDK 调用 DeepSeek API 吗？
可以。DeepSeek API 兼容 OpenAI 的接口规范，只需将 base_url 替换为 DeepSeek 的端点，并使用 DeepSeek 的 API Key 即可。注意 reasoning_content 是 DeepSeek 的扩展字段，需要通过 response.choices[0].message.reasoning_content 访问，标准 OpenAI SDK 的类型定义中不包含该字段，访问时可能需要做动态属性处理。
Q5：什么场景下选 R1，什么场景下选 V3？
需要快速响应、高并发的对话、代码补全、内容生成场景优先选 V3；涉及数学证明、逻辑推理、复杂分析、需要展示推导过程的场景选 R1。两者可以在同一应用中按需混用。
总结
DeepSeek R1 与 V3 的 API 请求格式区别集中在五个维度：模型标识符（deepseek-reasoner vs deepseek-chat）、系统提示词的处理方式、响应中独有的 reasoning_content 字段、temperature 参数的推荐设置，以及多轮对话的上下文拼接规则。掌握这些差异，可以避免绝大多数集成问题，也能让你根据业务场景做出更合理的模型选型决策。
想了解更多AI工具和技巧？欢迎访问红烁AI 培训，红烁 AI 中转站，获取最新AI资讯和实用教程。