DeepSeek API 完整文档

第一节

API 概览

DeepSeek API 提供与 OpenAI 完全兼容的接口格式，你可以使用任何 OpenAI SDK 直接调用，只需修改 base_url 和 api_key 即可。

Base URL 与认证

# Base URL
https://api.deepseek.com/v1

# 认证方式：在 HTTP Header 中携带 Bearer Token
Authorization: Bearer sk-your-api-key-here

# 获取 API Key: https://platform.deepseek.com/api_keys

速率限制

请求频率 (RPM)	默认 500 次/分钟（可联系官方提升）
并发连接数	默认 100 个并发请求
Token 速率 (TPM)	默认 500,000 TPM

支持模型

模型名称	API 参数值	说明
DeepSeek V3	`deepseek-chat`	旗舰对话模型，通用场景最优选择
DeepSeek R1	`deepseek-reasoner`	推理增强模型，数学/逻辑/编程场景

价格表

模型	输入 (每百万 Token)	输出 (每百万 Token)	上下文窗口
deepseek-chat (V3)	$0.27 (缓存命中 $0.07)	$1.10	160K
deepseek-reasoner (R1)	$0.55 (缓存命中 $0.14)	$2.19	128K

第二节

Chat Completions 接口

Chat Completions 是 DeepSeek API 最核心的接口，支持文本对话、代码生成、内容创作等全部对话场景。兼容 OpenAI Chat Completions API 格式。

接口端点

# POST 请求
POST https://api.deepseek.com/v1/chat/completions

# Content-Type
Content-Type: application/json

请求参数

参数名	类型	必填	默认值	说明
model	string	是	-	模型 ID：`deepseek-chat` 或 `deepseek-reasoner`
messages	array	是	-	对话消息列表，每条包含 role 和 content
temperature	float	否	1.0	采样温度，范围 0~2。越高越随机，越低越确定
top_p	float	否	1.0	核采样参数，范围 0~1。建议与 temperature 二选一调整
max_tokens	integer	否	4096	最大输出 token 数。V3 最大 8K，R1 最大 32K
stream	boolean	否	false	是否启用流式输出（SSE）
frequency_penalty	float	否	0	频率惩罚，范围 -2~2。正值降低重复内容概率
presence_penalty	float	否	0	存在惩罚，范围 -2~2。正值鼓励谈论新话题
stop	string/array	否	null	停止词，最多 16 个。遇到停止词时立即终止输出
tools	array	否	null	Function Calling 工具定义列表

响应格式

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "deepseek-chat",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！有什么可以帮助你的？"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 8,
    "total_tokens": 18
  }
}

finish_reason 常见值：stop（正常结束）、length（达到 max_tokens 限制）、content_filter（内容被过滤）、tool_calls（触发了函数调用）。

第三节

多轮对话

DeepSeek API 通过 messages 数组实现多轮对话。每次请求将完整的对话历史发送给模型，模型会根据上下文理解对话意图并给出连贯回复。

消息角色 (Role)

role	说明
system	系统提示词，用于设定对话的风格、角色、边界和规则。放在 messages 数组的第一条。
user	用户消息，即用户输入的问题或指令。
assistant	助手消息，即模型之前生成的回复。需要将历史 assistant 消息一并传入以维持对话上下文。

多轮对话示例

{
  "model": "deepseek-chat",
  "messages": [
    {"role": "system", "content": "你是一个专业的 Python 编程助手，所有回答使用中文。"},
    {"role": "user", "content": "Python 中如何读取 CSV 文件？"},
    {"role": "assistant", "content": "可以使用 csv 模块或 pandas 库。推荐使用 pandas：import pandas as pd; df = pd.read_csv('file.csv')"},
    {"role": "user", "content": "那如果文件很大怎么办？"}
  ]
}

上下文窗口管理

DeepSeek V3 支持 160K token 上下文窗口，R1 支持 128K。当对话历史过长时，需要管理上下文：

滑动窗口：只保留最近 N 轮对话，丢弃最早的消息
摘要压缩：用模型对早期对话生成摘要，替换原始消息
关键消息保留：始终保留 system prompt 和用户的核心问题，仅裁剪中间对话
Token 计数：每次请求前估算总 token 数，确保不超过上下文窗口

第四节

流式输出 (Streaming)

流式输出让模型逐个 token 返回结果，用户无需等待完整响应，可以实时看到生成内容。对于长文本生成和聊天应用，流式输出显著提升用户体验。

SSE 格式说明

DeepSeek 流式输出基于 Server-Sent Events (SSE) 协议。每个 chunk 以 data: 开头，以 \n\n 结束。每个 chunk 包含一个 JSON 对象，其中的 choices[0].delta.content 字段包含增量文本。

# SSE 数据流示例
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"你好"}}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"！"}}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Python 流式示例

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.deepseek.com/v1",
)

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[
        {"role": "user", "content": "写一首关于春天的五言绝句"}
    ],
    stream=True,
)

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

JavaScript (Node.js) 流式示例

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-api-key',
  baseURL: 'https://api.deepseek.com/v1',
});

const stream = await client.chat.completions.create({
  model: 'deepseek-chat',
  messages: [{ role: 'user', content: '写一首关于春天的五言绝句' }],
  stream: true,
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content || '';
  process.stdout.write(content);
}

如何解析 SSE 流

如果你不使用 SDK 而是直接通过 HTTP 请求获取流式数据，需要手动解析 SSE 格式：

按行读取响应体，每行以 data: 开头
遇到 data: [DONE] 表示流结束
解析 data 后的 JSON 字符串，提取 choices[0].delta.content
空行用于分隔不同的事件（chunk）

第五节

Function Calling (函数调用)

Function Calling 让模型能够智能地决定何时调用外部函数，并将用户自然语言转换为结构化的函数参数。这是构建 AI Agent 和工具调用场景的核心能力。

工具定义格式

在请求中通过 tools 参数定义可用的函数。每个函数需要 name、description 和 parameters（JSON Schema 格式）。

{
  "model": "deepseek-chat",
  "messages": [
    {"role": "user", "content": "北京今天天气怎么样？"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "获取指定城市的实时天气信息",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "城市名称，如 北京、上海、深圳"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "温度单位，默认摄氏度"
            }
          },
          "required": ["city"]
        }
      }
    }
  ]
}

Function Calling 工作流程

发送请求：将用户消息和 tools 定义一起发送给 DeepSeek API
模型决策：模型判断是否需要调用函数。如果需要，返回 finish_reason="tool_calls" 和函数调用信息
执行函数：开发者根据模型返回的函数名和参数，在自己的代码中执行相应函数
返回结果：将函数执行结果作为 tool role 消息，追加到 messages 中再次发送给模型
模型回复：模型根据函数返回结果，生成最终的自然语言回复

Python 完整示例

from openai import OpenAI
import json

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.deepseek.com/v1",
)

def get_weather(city: str, unit: str = "celsius"):
    """模拟天气查询函数"""
    return {"city": city, "temperature": 25, "condition": "晴", "unit": unit}

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "获取指定城市的实时天气信息",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "城市名称"},
                "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
            },
            "required": ["city"]
        }
    }
}]

messages = [{"role": "user", "content": "北京今天天气怎么样？"}]

# 第一步：发送请求，模型决定是否调用函数
response = client.chat.completions.create(
    model="deepseek-chat",
    messages=messages,
    tools=tools,
)

msg = response.choices[0].message

# 第二步：如果模型要求调用函数
if msg.tool_calls:
    for tool_call in msg.tool_calls:
        func_name = tool_call.function.name
        func_args = json.loads(tool_call.function.arguments)
        func_result = get_weather(**func_args)

        # 第三步：将函数结果追加到消息中
        messages.append(msg)
        messages.append({
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": json.dumps(func_result, ensure_ascii=False)
        })

    # 第四步：再次发送请求，获取最终回复
    final_response = client.chat.completions.create(
        model="deepseek-chat",
        messages=messages,
    )
    print(final_response.choices[0].message.content)

第六节

DeepSeek R1 (Reasoner) API

DeepSeek R1 是推理增强模型，在数学、编程、逻辑推理等场景中表现优异。API 调用方式与 deepseek-chat 基本一致，但有独特的思考过程输出。

R1 接口端点

# 与 Chat Completions 使用同一端点，仅 model 参数不同
POST https://api.deepseek.com/v1/chat/completions
# model 参数设为 "deepseek-reasoner"

思考过程 (reasoning_content)

R1 模型在生成最终答案前，会先进行内部推理。在流式输出中，推理过程通过 reasoning_content 字段返回，推理完成后才返回 content 字段。

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.deepseek.com/v1",
)

response = client.chat.completions.create(
    model="deepseek-reasoner",
    messages=[
        {"role": "user", "content": "一个水池有进水管和出水管，进水管 3 小时可注满，出水管 5 小时可排空。两管同时打开，几小时注满？"}
    ],
    stream=True,
)

for chunk in response:
    delta = chunk.choices[0].delta
    # 推理过程
    if hasattr(delta, 'reasoning_content') and delta.reasoning_content:
        print(f"[思考] {delta.reasoning_content}", end="")
    # 最终答案
    if delta.content:
        print(delta.content, end="", flush=True)

R1 与 Chat API 的区别

特性	deepseek-chat (V3)	deepseek-reasoner (R1)
上下文窗口	160K tokens	128K tokens
最大输出	8K tokens	32K tokens (含推理)
推理过程	不暴露	通过 reasoning_content 暴露
temperature	支持 (0~2)	不支持（固定推理策略）
Function Calling	支持	推荐使用 V3 处理工具调用
适用场景	通用对话、内容创作、翻译	数学证明、算法设计、逻辑推理

R1 最佳实践

R1 不需要复杂的 system prompt，简洁的指令即可获得最佳效果
推理过程会消耗 tokens，注意 max_tokens 设置要足够（建议 8000+）
非流式调用时，reasoning_content 会包含在完整响应中
对于简单对话，建议使用 V3 以节省成本和延迟；复杂推理任务才使用 R1

第七节

Token 计算

理解 Token 计算是控制 API 成本和管理上下文窗口的关键。DeepSeek 使用与 OpenAI 兼容的 tokenizer，你可以使用 tiktoken 库进行精确计算。

Token 估算规则

内容类型	Token 估算
英文文本	1 token ~ 4 个英文字符，或 ~ 0.75 个英文单词
中文文本	1 个中文字符 ~ 1.5~2 个 token
代码	1 token ~ 3~4 个代码字符（因缩进和符号而异）

使用 tiktoken 精确计算

# 安装 tiktoken
pip install tiktoken

# Python 示例
import tiktoken

# DeepSeek 使用 cl100k_base 编码（与 GPT-4 相同）
encoding = tiktoken.get_encoding("cl100k_base")

def count_tokens(text: str) -> int:
    return len(encoding.encode(text))

# 示例
text = "你好，DeepSeek！今天天气真不错。"
print(f"文本 token 数: {count_tokens(text)}")

上下文窗口与 max_tokens 限制

模型	上下文窗口	最大输出 token
deepseek-chat (V3)	160,000 tokens	8,192 tokens (默认 4,096)
deepseek-reasoner (R1)	128,000 tokens	32,768 tokens (含推理过程)

提示

每次请求的 total_tokens = prompt_tokens + completion_tokens。确保 prompt_tokens + max_tokens 不超过模型的上下文窗口上限。可通过 API 返回的 usage 字段查看实际消耗。

第八节

错误码与异常处理

了解 DeepSeek API 的错误码和异常处理策略，确保你的应用在生产环境中稳定可靠。

HTTP 状态码

状态码	含义	说明与处理方式
200	成功	请求正常处理
400	请求格式错误	参数格式不正确、缺少必填字段、JSON 解析失败等。检查请求体格式
401	认证失败	API Key 无效、过期或未传入。检查 Authorization Header
402	余额不足	账户余额不足以完成本次请求。前往 platform.deepseek.com 充值
429	速率限制	请求频率超过限制。降低请求频率或联系官方提升配额
500	服务器内部错误	DeepSeek 服务端临时故障。建议重试，使用指数退避策略
503	服务不可用	服务器繁忙或维护中。等待后重试，建议最长等待 60 秒

错误响应格式

{
  "error": {
    "message": "Insufficient Balance",
    "type": "insufficient_balance",
    "param": null,
    "code": "invalid_request_error"
  }
}

重试策略：指数退避

import time
import random
from openai import OpenAI, APIError, RateLimitError

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.deepseek.com/v1",
)

def chat_with_retry(messages, max_retries=5, base_delay=1):
    """带指数退避重试的 API 调用"""
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model="deepseek-chat",
                messages=messages,
            )
        except RateLimitError:
            if attempt == max_retries - 1:
                raise
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            print(f"速率限制，{delay:.1f}s 后重试...")
            time.sleep(delay)
        except APIError as e:
            if e.status_code < 500 or attempt == max_retries - 1:
                raise
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            print(f"服务器错误 {e.status_code}，{delay:.1f}s 后重试...")
            time.sleep(delay)

第九节

多语言 SDK 示例

DeepSeek API 兼容 OpenAI SDK，你可以使用任何语言的 OpenAI 客户端库。以下是各主流语言的完整示例代码。

Python (openai 包)

# 安装: pip install openai
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.deepseek.com/v1",
)

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[
        {"role": "system", "content": "你是一个有帮助的助手。"},
        {"role": "user", "content": "介绍一下 DeepSeek"},
    ],
    temperature=0.7,
    max_tokens=1024,
)

print(response.choices[0].message.content)

Node.js (openai 包)

// 安装: npm install openai
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-api-key',
  baseURL: 'https://api.deepseek.com/v1',
});

const response = await client.chat.completions.create({
  model: 'deepseek-chat',
  messages: [
    { role: 'system', content: '你是一个有帮助的助手。' },
    { role: 'user', content: '介绍一下 DeepSeek' },
  ],
  temperature: 0.7,
  max_tokens: 1024,
});

console.log(response.choices[0].message.content);

curl

curl https://api.deepseek.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key" \
  -d '{
    "model": "deepseek-chat",
    "messages": [
      {"role": "system", "content": "你是一个有帮助的助手。"},
      {"role": "user", "content": "介绍一下 DeepSeek"}
    ],
    "temperature": 0.7,
    "max_tokens": 1024
  }'

Go

// 安装: go get github.com/sashabaranov/go-openai
package main

import (
    "context"
    "fmt"
    openai "github.com/sashabaranov/go-openai"
)

func main() {
    config := openai.DefaultConfig("sk-your-api-key")
    config.BaseURL = "https://api.deepseek.com/v1"
    client := openai.NewClientWithConfig(config)

    resp, err := client.CreateChatCompletion(
        context.Background(),
        openai.ChatCompletionRequest{
            Model: "deepseek-chat",
            Messages: []openai.ChatCompletionMessage{
                {Role: "system", Content: "你是一个有帮助的助手。"},
                {Role: "user", Content: "介绍一下 DeepSeek"},
            },
            Temperature: 0.7,
            MaxTokens:   1024,
        },
    )
    if err != nil {
        panic(err)
    }
    fmt.Println(resp.Choices[0].Message.Content)
}

Java

// Maven 依赖: com.theokanning.openai-gpt3-java:service:0.18.2
import com.theokanning.openai.OpenAiService;
import com.theokanning.openai.completion.chat.*;
import java.time.Duration;
import java.util.List;

public class DeepSeekExample {
    public static void main(String[] args) {
        OpenAiService service = new OpenAiService(
            "sk-your-api-key",
            Duration.ofSeconds(60)
        );
        // 注意: 该库需要配置自定义 base URL
        // 建议使用 OkHttp 拦截器修改 base URL
        // 或使用 openai-java 库的 OpenAiApi 类

        ChatCompletionRequest request = ChatCompletionRequest.builder()
            .model("deepseek-chat")
            .messages(List.of(
                new ChatMessage("system", "你是一个有帮助的助手。"),
                new ChatMessage("user", "介绍一下 DeepSeek")
            ))
            .temperature(0.7)
            .maxTokens(1024)
            .build();

        ChatCompletionResult result = service.createChatCompletion(request);
        System.out.println(result.getChoices().get(0).getMessage().getContent());
    }
}

第十节

最佳实践

总结 DeepSeek API 使用中的关键最佳实践，帮助你在生产环境中高效、稳定、经济地使用 DeepSeek 模型。

1. System Prompt 设计

明确角色定位：告诉模型"你是谁"（如"你是一个专业的 Python 编程助手"）
设定输出格式：要求模型以特定格式输出（JSON、Markdown 表格、代码块等）
约束行为边界：明确告诉模型不能做什么（如"不要猜测不确定的信息"）
保持简洁：system prompt 过长会占用上下文窗口，建议控制在 200~500 字

2. Temperature 调优

Temperature	适用场景
0.0 ~ 0.3	代码生成、数学计算、数据提取、翻译——需要精确和一致性的场景
0.5 ~ 0.8	内容创作、头脑风暴、通用对话——平衡创造性和一致性
0.9 ~ 1.5	创意写作、故事生成、诗歌——需要高度多样性和创造性

3. 上下文窗口优化

只传入必要的对话历史，避免无效的往返消息
对长文档使用 RAG 方案，而非直接拼接全文
利用 system prompt 传递持久化指令，避免在每条 user 消息中重复
监控 usage.total_tokens，提前预警接近上下文窗口上限

4. 成本控制

合理设置 max_tokens，避免不必要的长输出浪费
利用缓存命中（Cache Hit）降低输入成本：重复的 system prompt 和历史消息可享受缓存折扣
对简单任务使用较小的 max_tokens 和低 temperature
在开发阶段使用 token 计数工具预估成本，设置预算告警
设置 API Key 的每月消费限额，避免意外超支

5. 并发请求管理

使用连接池复用 HTTP 连接，减少握手开销
实现请求队列，控制并发数不超过限制（默认 100）
对批量任务使用异步调用（Python asyncio / Node.js Promise.all）
监控 429 错误频率，动态调整并发数
为不同类型的请求设置不同的优先级队列

了解更多

DeepSeek 更多教程

继续探索 DeepSeek 的使用、部署和模型知识。

入门教程

DeepSeek 模型怎么用

零基础入门，四种使用方式全覆盖。

部署教程

DeepSeek Model 部署教程

Ollama、Docker、vLLM、K8s 部署方案。

技术架构

DeepSeek Model 完全指南

技术架构、Benchmark 性能对比、模型选型。

生态工具

DeepSeek 生态工具

30+ 款周边工具推荐与配置指南。

开发教程

DeepSeek + LangChain

LangChain 框架集成，构建 AI 应用。

开发帮助

DeepSeek API 常见问题

DeepSeek API 与 OpenAI API 兼容吗？ +

完全兼容。DeepSeek API 遵循 OpenAI Chat Completions API 格式，你可以直接使用 OpenAI 官方 SDK（Python、Node.js 等），只需将 base_url 改为 https://api.deepseek.com/v1，api_key 改为 DeepSeek 的 API Key，model 改为 deepseek-chat 或 deepseek-reasoner 即可。无需修改任何其他代码。

DeepSeek V3 和 R1 该如何选择？ +

V3 (deepseek-chat) 适用于通用对话、内容创作、翻译、代码生成等日常场景，价格更低，速度更快。R1 (deepseek-reasoner) 适用于数学证明、复杂逻辑推理、算法设计等需要深度思考的场景，会输出推理过程。对于大多数应用，优先使用 V3，仅在需要深度推理时切换到 R1。

如何获取 DeepSeek API Key？ +

访问 platform.deepseek.com，注册并登录后，在左侧导航栏点击「API Keys」，然后点击「创建 API Key」即可。创建后请立即保存密钥，页面关闭后将无法再次查看完整密钥。新注册用户通常会有免费额度，可以先试用再充值。

DeepSeek API 支持 Function Calling 吗？ +

支持。DeepSeek V3 (deepseek-chat) 完全支持 Function Calling，兼容 OpenAI 的 tools 参数格式。你可以在一次请求中定义多个函数，模型会智能判断是否需要调用以及调用哪个函数。R1 模型也可以使用 Function Calling，但建议使用 V3 以获得更好的工具调用稳定性和确定性。

遇到 429 错误（速率限制）怎么办？ +

429 错误表示请求频率超过限制。解决方案：1) 降低请求频率，使用指数退避重试策略；2) 合并多个请求，减少请求次数；3) 在代码中实现请求队列和并发控制；4) 如果业务确实需要更高频率，可联系 DeepSeek 官方申请提升配额。建议在代码中自动处理 429 错误，而非让用户感知。

DeepSeek API 的数据安全吗？数据会被用于训练吗？ +

DeepSeek 官方明确声明，通过 API 发送的数据不会被用于模型训练。API 调用采用 TLS 加密传输，建议在客户端做好 API Key 的安全管理：使用环境变量存储密钥，不要在代码中硬编码，不要将密钥提交到版本控制系统。企业用户还可联系官方获取专属部署方案。