实用指南：一文搞懂 DeepSeek API：兼容 OpenAI 接口的智能对话模型调用指南

关键词：AI接口、DeepSeek、OpenAI兼容、API调用、Python
适用读者：AI 应用开发者、后端工程师 /接口开发人员、AI 研究者 / 技术爱好者

---

随着国内外大模型生态的快速发展，DeepSeek 作为一款高性能、开放接口的 AI 模型，正在被越来越多开发者采用。令人惊喜的是，它的 API 接口完全兼容 OpenAI 标准 —— 也就是说，如果你已经使用过 openai SDK，那么几乎可以 零修改迁移到 DeepSeek。

本文将带你从零开始，快速完成：

1. DeepSeek API 环境配置
2. 使用 OpenAI SDK 调用 DeepSeek 模型
3. 深入理解三种 role 的设计理念
4. 非流式（stream=False）与流式输出调用示例
5. 模型模式与兼容性详解

---

一、DeepSeek API 简介

DeepSeek 提供了一组 完全兼容 OpenAI 的 RESTful 接口，支持：

• 对话模型（Chat Completions）
• 流式输出（Streaming）
• 思考/非思考模式切换
• 与 OpenAI SDK 无缝兼容

你可以直接使用 pip install openai 安装官方 SDK，无需额外包。

---

二、基础参数配置

参数	值	说明
base_url	https://api.deepseek.com	DeepSeek API 基础地址
api_key	你的 API 密钥	可在 DeepSeek 官网申请
model	deepseek-chat / deepseek-reasoner	对应不同模型模式
stream	True 或 False	是否开启流式输出

你也可以使用 https://api.deepseek.com/v1 作为 base_url（为兼容 OpenAI 而设）。
注意：此处 v1 与模型版本无关，仅是接口路径。

---

三、模型选择说明

模型名称	对应版本	模式说明
deepseek-chat	DeepSeek-V3.2-Exp	非思考模式（快速、轻量）
deepseek-reasoner	DeepSeek-V3.2-Exp	思考模式（推理更深入，适合复杂任务）

通俗理解：

• deepseek-chat 类似于 ChatGPT 的普通聊天模式；
• deepseek-reasoner 则更像是带推理链的「思考版」，在逻辑类、技术类问题上更强。

---

四、环境准备

首先，确保你的 Python 环境可用。建议 Python 版本 ≥ 3.8，pip 版本 ≥ 23.0。

pip install --upgrade pip
pip install openai

设置 API Key：

方法一：环境变量方式（推荐）

# Linux / macOS
export DEEPSEEK_API_KEY="你的_API_密钥"
# Windows PowerShell
setx DEEPSEEK_API_KEY "你的_API_密钥"

方法二：直接在代码中写入（简单测试用）

api_key = "你的_API_密钥"

---

五、为什么需要两个 role？

在调用 DeepSeek 或 OpenAI 接口时，我们通常会写出这样的结构：

messages=[
{"role": "system", "content": "请用中文回答问题"},
{"role": "user", "content": user_query},
]

很多开发者第一次看到会疑惑：为什么要有两条？是不是重复？其实不是。

这是 OpenAI Chat API 的核心设计理念——对话消息（messages）是由多种角色（role）构成的，模型会根据每个角色的语义上下文来生成回答。

---

三种角色的定义

角色（role）	含义	示例
system	系统指令。控制模型的整体行为、风格、语言。	“你是一位专业的中文助手。”
user	用户输入。即用户真正的问题或需求。	“请帮我解释什么是量子计算。”
assistant	模型回答。由模型生成，不需要你写入。	“量子计算是一种基于量子力学的计算方式……”

---

工作机制示意图

用户程序 → 发送消息：├─ role: system → 指定模型行为（中文回答、语气风格等）├─ role: user   → 提出问题或指令↓
模型接收并生成：└─ role: assistant → 返回回答内容

简而言之：

• system = 设定 AI 的人格和回答规则
• user = 输入你的问题
• assistant = 模型生成的答案

---

与 OpenAI 的兼容性

OpenAI 的 ChatGPT API 也是使用完全相同的消息结构：

{
"model": "gpt-3.5-turbo",
"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "What is quantum computing?"}
]
}

DeepSeek 保留了这一格式设计，因此你可以直接用同样的 SDK 调用，只需改动：

• base_url → https://api.deepseek.com
• model → deepseek-chat 或 deepseek-reasoner

---

六、Python 调用示例

以下为非流式调用的完整示例：

import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ.get("DEEPSEEK_API_KEY"),
base_url="https://api.deepseek.com"
)
user_query = "请用简单的语言解释一下什么是量子计算？"
response = client.chat.completions.create(
model="deepseek-chat",
messages=[
{"role": "system", "content": "请用中文回答问题"},
{"role": "user", "content": user_query},
],
stream=False
)
print(response.choices[0].message.content)

输出：

量子计算是一种利用量子力学原理进行计算的方式，它使用量子比特进行并行运算，因此在某些任务上比传统计算机更快。

---

如果你希望模型像 ChatGPT 那样边生成边输出，可启用流式模式：
以下为流式调用的完整示例：

response_stream = client.chat.completions.create(
model="deepseek-chat",
messages=[
{"role": "system", "content": "请用中文回答"},
{"role": "user", "content": "介绍一下人工智能的发展历史"},
],
stream=True
)
for chunk in response_stream:
if hasattr(chunk.choices[0].delta, "content"):
print(chunk.choices[0].delta.content, end="", flush=True)

输出效果：

人工智能的发展可以追溯到20世纪50年代……（逐字输出）

---

七、API 设计理念：与 OpenAI 完全兼容

DeepSeek 在接口层面与 OpenAI 保持一致，这意味着你可以：

直接替换：

base_url="https://api.deepseek.com"
model="deepseek-chat"

继续使用相同的 SDK 调用方式：

client = OpenAI(api_key=xxx, base_url=xxx)
client.chat.completions.create(...)

无需更改原有项目的逻辑、提示词结构、消息格式。
这对已经使用过 OpenAI 或 ChatGPT 的开发者来说，迁移成本几乎为零。

---

八、常见问题（FAQ）

问题	解决方法
报 SSL 错误（SSLError）	使用国内镜像 pip install openai -i https://pypi.tuna.tsinghua.edu.cn/simple
未设置 API Key	确认环境变量或代码中传入正确密钥
返回 401 Unauthorized	API Key 不正确或未激活
响应乱码	确保终端编码为 UTF-8 或 Python 文件使用 # -*- coding: utf-8 -*-

---

九、总结

功能	DeepSeek	OpenAI
API 接口格式	✅ 完全兼容	✅
SDK 调用方式	✅ 一致	✅
模型类型	Chat / Reasoner	GPT 系列
成本	较低	较高
国内访问速度	快速	偶有延迟

---

DeepSeek 通过与 OpenAI API 的完全兼容设计，让开发者能够无缝迁移已有项目，快速接入国产高性能大模型生态。
如果你希望更快、更稳、更省地使用 AI 能力，DeepSeek 是一个值得尝试的选择。