如何使用 DeepSeek-V3.1 API——开发者实用教程

DeepSeek-V3.1 是 DeepSeek 最新的混合推理模型，既支持快速的“非思考”聊天模式，也支持更为审慎的“思考/推理”模式，提供长上下文（最高 128K）、结构化输出与函数调用能力，并可通过 DeepSeek 的 OpenAI 兼容 API、Anthropic 兼容端点或 CometAPI 直接访问。下面将依次介绍模型概览、基准与成本亮点、高级功能（函数调用、JSON 输出、推理模式），并给出端到端代码示例：直接调用 DeepSeek REST（curl / Node / Python）、Anthropic 客户端用法以及通过 CometAPI 调用。

什么是 DeepSeek-V3.1，本次版本有哪些新特性？

DeepSeek-V3.1 是 DeepSeek V3 系列的最新版本：高容量的混合专家大型语言模型，采用混合推理的推理设计，提供两种运行“模式”——快速的非思考聊天模式与思考/推理模式，可在更难的推理任务与代理/工具使用中暴露类 chain-of-thought 的推理轨迹。本次发布重点优化了“思考”时延、工具/代理能力，以及针对文档级工作流的长上下文处理。

关键实用要点：

• 两种运行模式：为吞吐与成本选择 deepseek-chat，在需要 chain-of-thought 轨迹或更高推理保真度时使用 deepseek-reasoner（推理模型）。
• 提升代理/工具接入处理能力与分词器/上下文改进，以支持长文档。
• 上下文长度：最高约 128K tokens（支持长文档、代码库、日志）。

基准测试突破

DeepSeek-V3.1 在真实世界的编码挑战中取得了显著进步。在 SWE-bench Verified 评测中（衡量模型修复 GitHub 问题并通过单元测试的频率），V3.1 达到 66% 的成功率，而 V3-0324 与 R1 均为 45%。在多语言版本中，V3.1 解决了 54.5% 的问题，几乎是其他版本约 30% 成功率的两倍。在 Terminal-Bench 评测中（测试模型在真实 Linux 环境中完成任务的能力），DeepSeek-V3.1 完成了 31% 的任务，而其他两个版本分别为 13% 与 6%。这些改进表明，V3.1 在执行代码与在真实世界工具环境中操作方面更可靠。

在信息检索方面，DeepSeek-V3.1 在浏览、搜索与问答中同样占优。在 BrowseComp 评测中（要求在网页中导航并提取答案），V3.1 正确回答了 30% 的问题，而 R1 为 9%。在中文版本中，DeepSeek-V3.1 达到 49% 的准确率，而 R1 为 36%。在 Hard Language Exam（HLE）中，V3.1 略微领先 R1（30% 对 25%）。在诸如 xbench-DeepSearch 这样的深度搜索任务中（需要跨来源综合信息），V3.1 得分为 71%，而 R1 为 55%。在（structured reasoning）、SimpleQA（事实问答）与 Seal0（领域特定问答）等基准上，DeepSeek-V3.1 也表现出小幅但稳定的领先。总体而言，V3.1 在信息检索与轻量级问答方面显著优于 R1。

在推理效率方面，token 使用结果展现了其有效性。在 AIME 2025（高难度数学考试）上，V3.1-Think 的准确率与 R1 相当或略有超越（88.4% 对 87.5%），但 token 使用量约少 30%。在 GPQA Diamond（多领域研究生水平考试）上，两者几乎持平（80.1% 对 81.0%），但 V3.1 使用的 token 近乎 R1 的一半。在 LiveCodeBench（评估代码推理）上，V3.1 不仅更准确（74.8% 对 73.3%），而且更简洁。这表明 V3.1-Think 能在提供详细推理的同时避免冗长。

总体来看，V3.1 相较 V3-0324 实现了显著的代际跃迁。与 R1 相比，V3.1 在几乎所有基准上获得更高准确率，并在重型推理任务上更为有效。唯一持平的基准是 GPQA，但在几乎双倍成本的情况下。

如何获取 API 密钥并设置开发账号？

步骤 1：注册与创建账号

1. 访问 DeepSeek 的开发者门户（DeepSeek docs / console）。使用邮箱或 SSO 提供商创建账号。
2. 完成门户要求的身份校验或计费设置。

步骤 2：创建 API 密钥

1. 在控制台进入 API Keys → Create Key。为密钥命名（例如 dev-local-01）。
2. 复制密钥并存储在安全的密钥管理器中（见下文生产环境最佳实践）。

提示：某些网关与第三方路由器（如 CometAPI）允许你使用单一网关密钥通过它们访问 DeepSeek 模型——对于多供应商冗余非常有用（参见 DeepSeek V3.1 API 部分）。

如何设置开发环境（Linux/macOS/Windows）？

以下是适用于 DeepSeek（OpenAI 兼容端点）、CometAPI 与 Anthropic 的 Python 和 Node.js 简单、可复用环境搭建方法。

先决条件

• Python 3.10+（推荐）、pip、virtualenv。
• Node.js 18+ 与 npm/yarn。
• curl（用于快速测试）。

Python 环境（逐步）

1. 创建项目目录：

mkdir deepseek-demo && cd deepseek-demo
python -m venv .venv
source .venv/bin/activate   # macOS / Linux

# .venv\Scripts\activate    # Windows PowerShell

2. 安装最小依赖：

pip install --upgrade pip
pip install requests
# Optional: install an OpenAI-compatible client if you prefer one:

pip install openai

3. 将 API 密钥保存到环境变量（切勿提交到仓库）：

export DEEPSEEK_KEY="sk_live_xxx"
export CometAPI_KEY="or_xxx"
export ANTHROPIC_KEY="anthropic_xxx"

（Windows PowerShell 使用 $env:DEEPSEEK_KEY = "…"）

Node 环境（逐步）

1. 初始化：

mkdir deepseek-node && cd deepseek-node
npm init -y
npm install node-fetch dotenv

2. 创建 .env 文件：

DEEPSEEK_KEY=sk_live_xxx
CometAPI_KEY=or_xxx
ANTHROPIC_KEY=anthropic_xxx

如何直接调用 DeepSeek-V3.1 —— 分步代码示例？

DeepSeek 的 API 与 OpenAI 兼容。以下是可直接复制的示例：curl、Python（requests 与 openai SDK 风格）与 Node。

步骤 1：简单 curl 示例

curl https://api.deepseek.com/v1/chat/completions \
  -H "Authorization: Bearer $DEEPSEEK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat-v3.1",
    "messages": [
      {"role":"system","content":"You are a concise engineering assistant."},
      {"role":"user","content":"Give a 5-step secure deployment checklist for a Django app."}
    ],
    "max_tokens": 400,
    "temperature": 0.0,
    "reasoning_enabled": true
  }'

说明：reasoning_enabled 切换 Think 模式（供应商标志）。具体标志名因提供商而异——请查阅模型文档。

步骤 2：Python（requests）含简单遥测

import os, requests, time, json

API_KEY = os.environ
URL = "https://api.deepseek.com/v1/chat/completions"

payload = {
  "model": "deepseek-chat-v3.1",
  "messages": [
    {"role": "system", "content": "You are a helpful coding assistant."},
    {"role": "user", "content": "Refactor this Flask function to be testable: ..."}
  ],
  "max_tokens": 600,
  "temperature": 0.1,
  "reasoning_enabled": True
}

start = time.time()
r = requests.post(URL, headers={
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}, json=payload, timeout=60)

elapsed = time.time() - start
print("Status:", r.status_code, "Elapsed:", elapsed)
data = r.json()
print(json.dumps(data, indent=2))

CometAPI：免费使用 DeepSeek V3.1

对于希望无需注册即可立即接入的开发者，CometAPI 提供了一个有吸引力的替代方案访问 DeepSeek V3.1（Model name: deepseek-v3-1-250821; deepseek-v3.1）。该网关服务通过统一 API 聚合多种 AI 模型，提供对 DeepSeek 的访问及其他优势，包括自动故障切换、使用分析与简化的跨供应商计费。

首先，在 https://www.cometapi.com/ 创建 CometAPI 账号——整个流程仅需两分钟且只需邮箱验证。登录后在 “API Key” 区域生成新密钥。https://www.cometapi.com/ 为新账号提供免费额度，并在官方 API 价格基础上享有 20% 折扣。

技术集成仅需极少代码变更。只需将 API 端点从直连 DeepSeek 的 URL 改为 CometAPI 的网关。

注意：该 API 支持流式（stream: true）、max_tokens、temperature、停止序列与函数调用等，与其他 OpenAI 兼容 API 类似。

如何使用 Anthropic SDK 调用 DeepSeek？

DeepSeek 提供 Anthropic 兼容端点，你可以通过将 SDK 指向 https://api.deepseek.com/anthropic 并将模型名设置为 deepseek-chat（或在支持处设置为 deepseek-reasoner）来复用 Anthropic SDK 或 Claude Code 工具链。

通过 Anthropic API 调用 DeepSeek 模型

安装 Anthropic SDK：pip install anthropic。配置环境：

export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic  
export ANTHROPIC_API_KEY=YOUR_DEEPSEEK_KEY

创建消息：

import anthropic
client = anthropic.Anthropic()
message = client.messages.create(
model="deepseek-chat",
max_tokens=1000,
system="You are a helpful assistant.",
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": "Hi, how are you?"
}
]
}
]
)
print(message.content)

在 Claude Code 中使用 DeepSeek

安装：npm install -g @anthropic-ai/claude-code。配置环境：

export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=${YOUR_API_KEY}
export ANTHROPIC_MODEL=deepseek-chat
export ANTHROPIC_SMALL_FAST_MODEL=deepseek-chat

进入项目目录并执行 Claude Code：

cd my-project  
claude

通过 CometAPI 在 Claude Code 中使用 DeepSeek

CometAPI 支持 Claude Code。安装后，在配置环境时，将 Base URL 替换为 https://www.cometapi.com/console/，密钥替换为 CometAPI 的 Key，即可在 Claude Code 中使用 CometAPI 的 DeepSeek 模型。

# Navigate to your project folder cd your-project-folder 

# Set environment variables (replace sk-... with your actual token) 
export ANTHROPIC_AUTH_TOKEN=sk-... 
export ANTHROPIC_BASE_URL=https://www.cometapi.com/console/ 
# Start Claude Code 

claude

注意：

• DeepSeek 会将不受支持的 Anthropic 模型名映射至 deepseek-chat。
• 该 Anthropic 兼容层支持 system、messages、temperature、流式、停止序列与 thinking 数组。

生产环境的具体最佳实践（安全、成本、可靠性）

以下是适用于 DeepSeek 或任何高并发 LLM 使用场景的生产级建议。

机密与身份

• 将 API 密钥存入机密管理器（生产环境不要使用 .env）。定期轮换密钥，并按最小权限为每个服务创建独立密钥。
• 为开发/预发/生产分别使用不同项目/账号。

限流与重试

• 在 HTTP 429/5xx 上实现带抖动的指数退避。限制重试次数（如 3 次）。
• 对可能重复的请求使用幂等键。

Python 示例——带退避的重试

import time, random, requests

def post_with_retries(url, headers, payload, attempts= inline):
    for i in range(attempts):
        r = requests.post(url, json=payload, headers=headers, timeout=60)
        if r.status_code == 200:
            return r.json()
        if r.status_code in (429, 502, 503, 504):
            backoff = (2 ** i) + random.random()
            time.sleep(backoff)
            continue
        r.raise_for_status()
    raise RuntimeError("Retries exhausted")

成本管理

• 限制 max_tokens，避免意外请求超大输出。
• 在合适场景下缓存模型响应（特别是重复提示）。DeepSeek 在计费上区分缓存命中与未命中——缓存可节省成本。
• 常规短回复使用 deepseek-chat；真正需要 CoT 的场景再使用 deepseek-reasoner（更昂贵）。

可观测性与日志

• 仅以明文记录请求元数据（提示哈希、token 计数、延迟）。避免记录完整用户数据或敏感内容。存储请求/响应 ID 以便支持与账单对账。
• 追踪每个请求的 token 使用量，并对成本设置预算与告警。

安全与幻觉控制

• 对安全关键场景（金融、法律、医疗）使用工具输出与确定性校验器。
• 对结构化输出，使用 response_format + JSON 模式，并在进行不可逆操作前验证输出。

部署模式

• 从专用工作进程发起模型调用 NB 的调用，以便控制并发与队列。
• 将重任务卸载到异步工作器（Celery、Fargate、Cloud Run jobs），并用进度指示反馈给用户。
• 对极端时延/吞吐需求，评估供应商 SLA 以及自托管或供应商加速器的可行性。

结语

DeepSeek-V3.1 是面向快速聊天与复杂代理任务的务实混合模型。其与 OpenAI 兼容的 API 形态使得迁移对许多项目而言十分直接，而对 Anthropic 与 CometAPI 的兼容层则为现有生态提供了灵活对接。基准与社区反馈显示了良好的性价比——但与任何新模型一样，在全面上线前请在你的真实工作负载上进行验证（提示词、函数调用、安全检查、延迟）。

在 CometAPI 上，你可以安全运行它，并通过 OpenAI 兼容 API 或用户友好的 playground 进行交互，无限流限制。

👉 立即在 CometAPI 部署 DeepSeek-V3.1！

为什么使用 CometAPI？

• 提供商多路复用：无需改代码即可切换供应商。
• 统一账单/指标：如果通过 CometAPI 路由多个模型，你可以拥有统一的集成面。
• 模型元数据：查看每个模型变体的上下文长度与活动参数。