DeepSeek API接口调用教程｜附配置文件

在大模型应用开发中，API 接口调用是最常见、也最灵活的接入方式。相比直接使用网页端对话，API 可以让开发者把大模型能力集成到自己的业务系统、自动化脚本、知识库问答、客服机器人、内容生成工具、数据分析平台等场景中。

DeepSeek 作为近年来关注度较高的大模型服务之一，提供了较为友好的 API 调用方式。对于已经熟悉 OpenAI API 的开发者来说，DeepSeek API 的接入成本相对较低，因为它在调用结构上与 OpenAI Chat Completions 风格较为接近，很多 SDK 或封装方式可以快速适配。

本文将从零开始介绍 DeepSeek API 的调用流程，包括 API Key 获取、接口地址配置、curl 调用、Python 调用、Node.js 调用、配置文件写法、环境变量管理、常见参数说明以及调用中的常见问题。阅读完本文后，你可以快速完成 DeepSeek API 的基础接入，并在项目中进行稳定调用。

一、准备工作

在正式调用 DeepSeek API 之前，你需要准备以下内容：

1. DeepSeek 账号；
2. 可用的 API Key；
3. 一个可以发送 HTTP 请求的环境；
4. 基础编程环境，例如 Python、Node.js 或其他语言；
5. 了解基本的 JSON 数据格式。

如果你只是想测试接口是否能正常调用，使用 curl 即可。如果你要集成到项目中，建议使用 Python、Node.js、Java、Go 等语言进行封装调用。

二、获取 DeepSeek API Key

调用 DeepSeek API 通常需要使用 API Key 进行身份认证。API Key 相当于你的接口访问凭证，请务必妥善保管，不要直接写死在公开代码仓库中。

一般获取方式如下：

1. 登录 DeepSeek 开发者平台或控制台；
2. 进入 API Keys 管理页面；
3. 创建新的 API Key；
4. 复制并保存生成的 Key；
5. 在项目中通过环境变量或配置文件读取该 Key。

需要注意的是，API Key 通常只会在创建时完整显示一次。如果忘记保存，建议删除旧 Key 后重新创建。

三、DeepSeek API 基础接口说明

DeepSeek API 的聊天补全接口通常采用如下结构：

POST https://api.deepseek.com/chat/completions

请求头中需要携带认证信息：

Authorization: Bearer YOUR_DEEPSEEK_API_KEY
Content-Type: application/json

请求体通常为 JSON 格式，核心字段包括：

{
  "model": "deepseek-chat",
  "messages": [
    {
      "role": "system",
      "content": "你是一个专业的中文写作助手。"
    },
    {
      "role": "user",
      "content": "请帮我写一段产品介绍。"
    }
  ],
  "temperature": 0.7,
  "max_tokens": 1000
}

其中：

• model：指定调用的模型；
• messages：对话消息数组；
• role：消息角色，常见有 system、user、assistant；
• content：消息内容；
• temperature：控制输出随机性；
• max_tokens：限制最大输出长度。

四、使用 curl 调用 DeepSeek API

如果你想快速测试 DeepSeek API 是否可以正常访问，可以使用 curl 命令。

1. Linux / macOS 示例

curl https://api.deepseek.com/chat/completions \
  -H "Authorization: Bearer YOUR_DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [
      {
        "role": "system",
        "content": "你是一个专业的中文助手。"
      },
      {
        "role": "user",
        "content": "请用三句话介绍 DeepSeek API 的用途。"
      }
    ],
    "temperature": 0.7,
    "max_tokens": 500
  }'

2. Windows PowerShell 示例

$headers = @{
  "Authorization" = "Bearer YOUR_DEEPSEEK_API_KEY"
  "Content-Type" = "application/json"
}

$body = @{
  model = "deepseek-chat"
  messages = @(
    @{
      role = "system"
      content = "你是一个专业的中文助手。"
    },
    @{
      role = "user"
      content = "请用三句话介绍 DeepSeek API 的用途。"
    }
  )
  temperature = 0.7
  max_tokens = 500
} | ConvertTo-Json -Depth 10

Invoke-RestMethod `
  -Uri "https://api.deepseek.com/chat/completions" `
  -Method Post `
  -Headers $headers `
  -Body $body

如果调用成功，你会得到一个 JSON 响应。通常可以在返回结果中的 choices[0].message.content 字段中看到模型生成的内容。

五、Python 调用 DeepSeek API

Python 是调用大模型 API 最常用的语言之一。下面介绍两种方式：使用 requests 直接调用，以及使用 OpenAI 风格 SDK 调用。

六、方式一：使用 requests 调用

首先安装依赖：

pip install requests

然后创建一个 Python 文件，例如 deepseek_demo.py：

import requests
import json

API_KEY = "YOUR_DEEPSEEK_API_KEY"
API_URL = "https://api.deepseek.com/chat/completions"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "model": "deepseek-chat",
    "messages": [
        {
            "role": "system",
            "content": "你是一个专业的中文写作助手。"
        },
        {
            "role": "user",
            "content": "请写一段关于人工智能在教育领域应用的介绍。"
        }
    ],
    "temperature": 0.7,
    "max_tokens": 800
}

response = requests.post(API_URL, headers=headers, data=json.dumps(payload))

if response.status_code == 200:
    result = response.json()
    content = result["choices"][0]["message"]["content"]
    print(content)
else:
    print("请求失败")
    print("状态码：", response.status_code)
    print("响应内容：", response.text)

运行：

python deepseek_demo.py

这种写法直观、简单，适合初学者理解 API 调用过程。但在正式项目中，不建议把 API Key 直接写在代码里。

七、使用环境变量保护 API Key

为了避免 API Key 泄露，推荐使用环境变量。

1. Linux / macOS 设置环境变量

export DEEPSEEK_API_KEY="你的API_KEY"

如果希望长期生效，可以写入 ~/.bashrc、~/.zshrc 等配置文件。

2. Windows PowerShell 设置环境变量

$env:DEEPSEEK_API_KEY="你的API_KEY"

3. Python 读取环境变量

import os
import requests

API_KEY = os.getenv("DEEPSEEK_API_KEY")
API_URL = "https://api.deepseek.com/chat/completions"

if not API_KEY:
    raise ValueError("请先设置 DEEPSEEK_API_KEY 环境变量")

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "model": "deepseek-chat",
    "messages": [
        {"role": "system", "content": "你是一个专业的中文助手。"},
        {"role": "user", "content": "请解释什么是 API 接口调用。"}
    ]
}

response = requests.post(API_URL, headers=headers, json=payload)
print(response.json()["choices"][0]["message"]["content"])

使用环境变量可以有效降低密钥泄露风险，尤其适合团队协作和线上部署。

八、附：DeepSeek API 配置文件示例

在实际项目中，通常会把模型名称、接口地址、温度参数、最大输出长度等内容统一放到配置文件中。这样做的好处是：后期修改模型或参数时，不需要改动业务代码。

下面提供几种常见配置文件格式。

九、YAML 配置文件示例

创建 config.yaml：

deepseek:
  api_key_env: "DEEPSEEK_API_KEY"
  base_url: "https://api.deepseek.com"
  chat_endpoint: "/chat/completions"
  model: "deepseek-chat"
  temperature: 0.7
  max_tokens: 1000
  timeout: 60
  system_prompt: "你是一个专业、严谨、友好的中文助手。"

Python 读取 YAML 配置：

pip install pyyaml requests

import os
import yaml
import requests

def load_config(path="config.yaml"):
    with open(path, "r", encoding="utf-8") as f:
        return yaml.safe_load(f)

config = load_config()
ds_config = config["deepseek"]

api_key = os.getenv(ds_config["api_key_env"])
if not api_key:
    raise RuntimeError("未检测到 DeepSeek API Key，请检查环境变量配置。")

url = ds_config["base_url"] + ds_config["chat_endpoint"]

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

payload = {
    "model": ds_config["model"],
    "messages": [
        {
            "role": "system",
            "content": ds_config["system_prompt"]
        },
        {
            "role": "user",
            "content": "请帮我总结一下使用配置文件管理 API 参数的好处。"
        }
    ],
    "temperature": ds_config["temperature"],
    "max_tokens": ds_config["max_tokens"]
}

response = requests.post(
    url,
    headers=headers,
    json=payload,
    timeout=ds_config["timeout"]
)

response.raise_for_status()
result = response.json()
print(result["choices"][0]["message"]["content"])

十、JSON 配置文件示例

如果你的项目更偏向前后端工程化，也可以使用 JSON 配置文件。

创建 deepseek.config.json：

{
  "deepseek": {
    "apiKeyEnv": "DEEPSEEK_API_KEY",
    "baseURL": "https://api.deepseek.com",
    "chatEndpoint": "/chat/completions",
    "model": "deepseek-chat",
    "temperature": 0.7,
    "maxTokens": 1000,
    "timeout": 60000,
    "systemPrompt": "你是一个专业、可靠的中文助手。"
  }
}

这种配置方式在 Node.js 项目中非常常见。

十一、Node.js 调用 DeepSeek API

下面以 Node.js 为例，使用原生 fetch 进行调用。Node.js 18 及以上版本默认支持 fetch。

1. 初始化项目

mkdir deepseek-node-demo
cd deepseek-node-demo
npm init -y

2. 创建配置文件

创建 deepseek.config.json：

{
  "deepseek": {
    "apiKeyEnv": "DEEPSEEK_API_KEY",
    "baseURL": "https://api.deepseek.com",
    "chatEndpoint": "/chat/completions",
    "model": "deepseek-chat",
    "temperature": 0.7,
    "maxTokens": 1000,
    "systemPrompt": "你是一个专业的中文技术助手。"
  }
}

3. 编写调用代码

创建 index.js：

const config = require("./deepseek.config.json");

async function callDeepSeek(prompt) {
  const ds = config.deepseek;
  const apiKey = process.env[ds.apiKeyEnv];

  if (!apiKey) {
    throw new Error(`请先设置环境变量：${ds.apiKeyEnv}`);
  }

  const url = `${ds.baseURL}${ds.chatEndpoint}`;

  const response = await fetch(url, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: ds.model,
      messages: [
        {
          role: "system",
          content: ds.systemPrompt
        },
        {
          role: "user",
          content: prompt
        }
      ],
      temperature: ds.temperature,
      max_tokens: ds.maxTokens
    })
  });

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`请求失败：${response.status} ${errorText}`);
  }

  const result = await response.json();
  return result.choices[0].message.content;
}

callDeepSeek("请说明 DeepSeek API 适合哪些应用场景。")
  .then(console.log)
  .catch(console.error);

运行：

node index.js

在运行前，请确保已经设置好环境变量：

export DEEPSEEK_API_KEY="你的API_KEY"

Windows PowerShell：

$env:DEEPSEEK_API_KEY="你的API_KEY"

十二、使用 OpenAI SDK 风格调用

由于 DeepSeek API 在接口形式上较接近 OpenAI 风格，部分项目也可以通过 OpenAI SDK 设置 base_url 的方式调用。

以 Python 为例：

pip install openai

示例代码：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DEEPSEEK_API_KEY"),
    base_url="https://api.deepseek.com"
)

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[
        {
            "role": "system",
            "content": "你是一个专业的中文助手。"
        },
        {
            "role": "user",
            "content": "请介绍一下 API 网关在大模型应用中的作用。"
        }
    ],
    temperature=0.7,
    max_tokens=1000
)

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

这种方式的好处是，如果你的项目原来已经使用 OpenAI SDK，那么迁移成本会比较低，只需要调整 api_key、base_url 和 model 等配置即可。

十三、常用参数说明

1. model

model 用于指定调用的模型。例如：

"model": "deepseek-chat"

不同模型适合不同任务。有的模型更适合通用对话，有的模型更适合推理、代码、数学或复杂分析。实际使用时应根据官方文档和业务需求选择。

2. messages

messages 是对话上下文数组，按照时间顺序排列。

常见角色包括：

[
  {
    "role": "system",
    "content": "你是一个专业助手。"
  },
  {
    "role": "user",
    "content": "用户的问题"
  },
  {
    "role": "assistant",
    "content": "助手之前的回答"
  }
]

其中，system 通常用于设定模型角色、输出风格和约束条件；user 表示用户输入；assistant 表示模型历史回复。

3. temperature

temperature 用于控制输出随机性。

• 数值越低，回答越稳定、确定；
• 数值越高，回答越发散、创意更强。

常见建议：

严谨问答、代码生成、数据分析：0.1 - 0.4
内容创作、营销文案、头脑风暴：0.7 - 1.0
普通聊天、综合任务：0.5 - 0.8

4. max_tokens

max_tokens 用于限制模型最大输出长度。需要注意的是，过小可能导致回答被截断，过大则可能增加调用成本和响应时间。

5. stream

如果接口支持流式输出，可以通过设置：

"stream": true

流式输出适合聊天机器人、网页端实时显示、命令行逐字打印等场景。非流式调用需要等待完整响应后一次性返回，而流式调用可以边生成边返回，用户体验更好。

十四、流式输出示例

在聊天应用中，流式输出非常常见。下面给出一个 Python 示例。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DEEPSEEK_API_KEY"),
    base_url="https://api.deepseek.com"
)

stream = client.chat.completions.create(
    model="deepseek-chat",
    messages=[
        {"role": "system", "content": "你是一个简洁的中文助手。"},
        {"role": "user", "content": "请分点介绍大模型 API 的优势。"}
    ],
    stream=True
)

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

流式输出的核心是不断读取服务端返回的数据块，并将增量内容拼接展示。

十五、错误处理与重试机制

在正式项目中，API 调用不应只写简单请求，还需要考虑错误处理。

常见错误包括：

1. API Key 无效；
2. 请求参数格式错误；
3. 模型名称填写错误；
4. 网络连接超时；
5. 请求频率过高；
6. 账户余额不足；
7. 服务端临时异常。

建议在代码中加入以下机制：

• 请求超时设置；
• HTTP 状态码判断；
• 异常捕获；
• 日志记录；
• 失败重试；
• 限流控制；
• 敏感信息脱敏。

Python 简单重试示例：

import time
import requests

def request_with_retry(url, headers, payload, retries=3, timeout=60):
    for attempt in range(retries):
        try:
            response = requests.post(
                url,
                headers=headers,
                json=payload,
                timeout=timeout
            )

            if response.status_code == 200:
                return response.json()

            print(f"第 {attempt + 1} 次请求失败，状态码：{response.status_code}")
            print(response.text)

        except requests.exceptions.RequestException as e:
            print(f"第 {attempt + 1} 次请求异常：{e}")

        time.sleep(2 ** attempt)

    raise RuntimeError("多次请求失败，请检查网络、参数或 API Key。")

这里使用了简单的指数退避策略，即每次失败后等待时间逐渐增加，避免在服务异常时频繁请求。

十六、封装一个 DeepSeek 客户端类

为了让代码更清晰，可以将调用逻辑封装成一个客户端类。

import os
import requests

class DeepSeekClient:
    def __init__(
        self,
        api_key=None,
        base_url="https://api.deepseek.com",
        model="deepseek-chat",
        timeout=60
    ):
        self.api_key = api_key or os.getenv("DEEPSEEK_API_KEY")
        self.base_url = base_url.rstrip("/")
        self.model = model
        self.timeout = timeout

        if not self.api_key:
            raise ValueError("缺少 DeepSeek API Key")

    def chat(self, prompt, system_prompt="你是一个专业的中文助手。", temperature=0.7, max_tokens=1000):
        url = f"{self.base_url}/chat/completions"

        headers = {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }

        payload = {
            "model": self.model,
            "messages": [
                {
                    "role": "system",
                    "content": system_prompt
                },
                {
                    "role": "user",
                    "content": prompt
                }
            ],
            "temperature": temperature,
            "max_tokens": max_tokens
        }

        response = requests.post(
            url,
            headers=headers,
            json=payload,
            timeout=self.timeout
        )

        response.raise_for_status()
        result = response.json()
        return result["choices"][0]["message"]["content"]


if __name__ == "__main__":
    client = DeepSeekClient()
    answer = client.chat("请解释 RAG 检索增强生成的基本原理。")
    print(answer)

封装之后，业务层只需要调用 client.chat()，不用关心请求头、URL 拼接和 JSON 解析等细节。

十七、在业务项目中的推荐目录结构

如果你准备把 DeepSeek API 集成到正式项目中，可以采用如下目录结构：

my-ai-project/
├── config/
│   └── config.yaml
├── src/
│   ├── clients/
│   │   └── deepseek_client.py
│   ├── services/
│   │   └── chat_service.py
│   └── main.py
├── .env
├── .gitignore
├── requirements.txt
└── README.md

其中：

• config.yaml：存放模型参数和接口配置；
• deepseek_client.py：封装 API 调用；
• chat_service.py：封装业务逻辑；
• .env：存放环境变量；
• .gitignore：防止敏感文件提交；
• requirements.txt：记录 Python 依赖。

.gitignore 示例：

.env
__pycache__/
*.pyc
.DS_Store

十八、使用 .env 文件管理密钥

在本地开发中，可以使用 .env 文件保存环境变量。

安装：

pip install python-dotenv

创建 .env：

DEEPSEEK_API_KEY=你的API_KEY

Python 加载：

import os
from dotenv import load_dotenv

load_dotenv()

api_key = os.getenv("DEEPSEEK_API_KEY")
print(api_key)

注意：.env 文件不应该提交到 Git 仓库中，应加入 .gitignore。

十九、安全使用建议

调用 DeepSeek API 时，安全性非常重要。建议遵守以下原则：

1. 不要把 API Key 写死在代码中
   使用环境变量、密钥管理服务或配置中心。

2. 不要把 API Key 上传到 GitHub、Gitee 等公开仓库
   一旦泄露，应立即删除并重新生成。

3. 后端代理调用，不建议前端直接暴露 Key
   如果在浏览器端直接调用 API，API Key 很容易被用户看到。

4. 设置合理的访问控制
   对自己的业务接口增加鉴权、限流和日志。

5. 定期轮换密钥
   对重要生产系统，建议定期更换 API Key。

6. 记录调用日志但避免记录敏感内容
   日志中不要保存用户隐私、密钥或敏感业务数据。

二十、常见问题排查

1. 返回 401 Unauthorized

通常表示认证失败。请检查：

• API Key 是否正确；
• 请求头是否写成 Authorization: Bearer xxx；
• Key 是否被删除或失效；
• 是否有多余空格或换行。

2. 返回 400 Bad Request

通常表示请求参数有问题。请检查：

• JSON 格式是否正确；
• model 是否填写正确；
• messages 是否是数组；
• 每条消息是否包含 role 和 content。

3. 返回超时

可能原因包括：

• 网络不稳定；
• 输出内容过长；
• 服务端响应较慢；
• timeout 设置过短。

可以适当增加 timeout，或开启流式输出改善体验。

4. 输出内容不符合预期

可以尝试：

• 优化 system prompt；
• 降低或提高 temperature；
• 给出更明确的任务要求；
• 提供示例；
• 限定输出格式。

例如：

请严格按照以下 JSON 格式输出，不要添加额外解释：
{
  "title": "",
  "summary": "",
  "keywords": []
}

5. 回答被截断

通常是 max_tokens 设置太小。可以适当增大该参数，或者要求模型分段输出。

二十一、一个完整的配置化调用示例

下面给出一个相对完整的 Python 示例，包含 .env、config.yaml 和客户端封装。

1. .env

DEEPSEEK_API_KEY=你的API_KEY

2. config.yaml

deepseek:
  api_key_env: "DEEPSEEK_API_KEY"
  base_url: "https://api.deepseek.com"
  endpoint: "/chat/completions"
  model: "deepseek-chat"
  temperature: 0.6
  max_tokens: 1200
  timeout: 60
  system_prompt: "你是一个专业的技术文档写作助手，回答要求准确、清晰、有条理。"

3. main.py

import os
import yaml
import requests
from dotenv import load_dotenv

load_dotenv()

def load_config(path="config.yaml"):
    with open(path, "r", encoding="utf-8") as f:
        return yaml.safe_load(f)

class DeepSeekClient:
    def __init__(self, config):
        self.config = config["deepseek"]
        self.api_key = os.getenv(self.config["api_key_env"])

        if not self.api_key:
            raise RuntimeError("未找到 API Key，请检查 .env 或环境变量配置。")

        self.url = self.config["base_url"].rstrip("/") + self.config["endpoint"]

    def chat(self, user_prompt):
        headers = {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }

        payload = {
            "model": self.config["model"],
            "messages": [
                {
                    "role": "system",
                    "content": self.config["system_prompt"]
                },
                {
                    "role": "user",
                    "content": user_prompt
                }
            ],
            "temperature": self.config["temperature"],
            "max_tokens": self.config["max_tokens"]
        }

        response = requests.post(
            self.url,
            headers=headers,
            json=payload,
            timeout=self.config["timeout"]
        )

        if response.status_code != 200:
            raise RuntimeError(f"请求失败：{response.status_code}，{response.text}")

        result = response.json()
        return result["choices"][0]["message"]["content"]

if __name__ == "__main__":
    config = load_config()
    client = DeepSeekClient(config)

    question = "请写一段关于 DeepSeek API 配置化调用优势的说明。"
    answer = client.chat(question)

    print(answer)

安装依赖：

pip install requests pyyaml python-dotenv

运行：

python main.py

二十二、总结

DeepSeek API 的调用流程并不复杂，核心步骤可以概括为：

1. 获取 API Key；
2. 设置请求地址；
3. 构造请求头；
4. 组织 messages 参数；
5. 发送 POST 请求；
6. 解析返回结果；
7. 在项目中通过配置文件统一管理参数。

对于个人测试，可以直接使用 curl 或简单 Python 脚本；对于正式项目，建议采用环境变量、配置文件、客户端封装、错误重试、日志监控等工程化方式。这样不仅可以提升代码可维护性，也能减少密钥泄露、参数混乱和调用不稳定等问题。

如果你的项目原本已经使用 OpenAI 风格 SDK，还可以通过设置 base_url 的方式快速适配 DeepSeek API。无论是构建聊天机器人、智能客服、内容生成工具，还是开发知识库问答和自动化办公应用，DeepSeek API 都可以作为一个灵活的大模型能力入口。

在实际开发中，建议始终关注官方文档，确认最新的接口地址、模型名称、参数说明和计费规则。API 接入只是第一步，真正决定应用效果的，往往还包括 Prompt 设计、上下文管理、数据安全、调用成本控制和业务流程设计。只要做好这些基础工作，就可以更稳定、更高效地把 DeepSeek 的大模型能力集成到自己的产品和系统中。