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

随着大语言模型在内容生成、代码辅助、知识问答、智能客服、数据分析等场景中的广泛应用，越来越多开发者开始关注如何将模型能力接入自己的系统。DeepSeek 作为近年来较受关注的国产大模型服务之一，提供了相对友好的 API 调用方式，开发者可以通过 HTTP 请求快速完成对话生成、流式输出、多轮上下文管理等功能。

本文将以“从零开始接入 DeepSeek API”为目标，系统讲解接口调用流程、环境准备、配置文件编写、Python/Node.js 调用示例、流式输出、异常处理以及项目落地时的注意事项。你可以直接参考文中的配置文件和代码示例，快速完成 DeepSeek API 的集成。

一、DeepSeek API 简介

DeepSeek API 本质上是一个基于 HTTP 协议的模型服务接口。开发者通过向指定接口地址发送请求，将用户输入、系统提示词、历史对话等内容提交给模型，模型再返回对应的文本结果。

通常情况下，DeepSeek API 支持以下能力：

• 对话补全：根据用户输入生成回复；
• 多轮对话：通过传入历史消息维持上下文；
• 流式响应：模型边生成边返回，适合聊天机器人；
• 代码生成与解释：适合开发辅助、代码审查、脚本生成；
• 结构化输出：结合提示词，让模型返回 JSON、Markdown 等格式；
• 系统角色设定：通过 system prompt 控制模型语气、角色和输出规范。

在应用层面，DeepSeek API 可以用于：

• 智能客服系统；
• 企业知识库问答；
• 代码助手；
• 文案生成工具；
• 数据报表解释；
• 自动化办公助手；
• 教育答疑系统；
• AI Agent 应用开发。

二、调用前准备工作

在正式调用 DeepSeek API 之前，你需要完成以下几项准备。

1. 注册并获取 API Key

首先需要前往 DeepSeek 官方平台完成账号注册，并在控制台中创建 API Key。API Key 是你调用接口时的身份凭证，需要妥善保存。

一般情况下，API Key 的形式类似：

sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

注意：API Key 不要直接写死在前端代码中，也不要提交到 GitHub 等公开仓库。建议通过环境变量或配置文件进行管理。

2. 确认接口地址

DeepSeek API 通常使用类似如下的接口地址：

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

如果官方文档更新了接口地址，请以官方最新文档为准。

3. 了解请求格式

DeepSeek 的聊天补全接口通常采用 JSON 请求体，核心字段包括：

典型的 messages 格式如下：

[
  {
    "role": "system",
    "content": "你是一个专业的中文技术写作助手。"
  },
  {
    "role": "user",
    "content": "请介绍一下 DeepSeek API 的使用方法。"
  }
]

其中 role 常见取值包括：

• system：系统设定，用于定义模型角色、规则、输出风格；
• user：用户输入；
• assistant：模型历史回复，用于多轮对话上下文。

三、推荐项目目录结构

为了方便后期维护，建议不要把所有代码都写在一个文件里。下面是一个简单的后端调用项目结构：

deepseek-api-demo/
├── config/
│   ├── config.yaml
│   └── config.example.yaml
├── src/
│   ├── main.py
│   ├── deepseek_client.py
│   └── prompts.py
├── .env
├── .env.example
├── requirements.txt
└── README.md

如果你使用 Node.js，也可以采用类似结构：

deepseek-api-node-demo/
├── config/
│   └── config.json
├── src/
│   ├── index.js
│   └── deepseekClient.js
├── .env
├── .env.example
├── package.json
└── README.md

四、配置文件示例

下面给出几种常见配置文件写法，你可以根据项目需要选择。

1. .env 配置文件

.env 文件适合存放敏感信息，例如 API Key。

DEEPSEEK_API_KEY=sk-your-api-key-here
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-chat

对应的 .env.example 可以这样写：

DEEPSEEK_API_KEY=
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-chat

.env 文件应该加入 .gitignore，避免泄露密钥。

2. YAML 配置文件

config/config.yaml 示例：

deepseek:
  base_url: "https://api.deepseek.com"
  chat_endpoint: "/chat/completions"
  model: "deepseek-chat"
  timeout: 60
  temperature: 0.7
  max_tokens: 2048
  stream: false

prompt:
  system: "你是一个专业、严谨、擅长中文表达的AI助手。回答时请结构清晰，必要时使用Markdown格式。"

YAML 文件适合保存非敏感配置，例如模型名称、超时时间、默认提示词等。

3. JSON 配置文件

如果你更习惯使用 JSON，也可以这样配置：

{
  "deepseek": {
    "base_url": "https://api.deepseek.com",
    "chat_endpoint": "/chat/completions",
    "model": "deepseek-chat",
    "timeout": 60,
    "temperature": 0.7,
    "max_tokens": 2048,
    "stream": false
  },
  "prompt": {
    "system": "你是一个专业、严谨、擅长中文表达的AI助手。回答时请结构清晰，必要时使用Markdown格式。"
  }
}

五、使用 curl 调用 DeepSeek API

在写代码之前，可以先用 curl 测试接口是否可用。

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

如果请求成功，通常会返回类似结构：

{
  "id": "xxx",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "deepseek-chat",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "DeepSeek API 是一种面向开发者的大语言模型调用接口..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 100,
    "total_tokens": 120
  }
}

其中真正的模型回复通常位于：

choices[0].message.content

六、Python 调用示例

下面使用 Python 的 requests 库调用 DeepSeek API。

1. 安装依赖

创建 requirements.txt：

requests==2.32.3
python-dotenv==1.0.1
PyYAML==6.0.2

安装依赖：

pip install -r requirements.txt

2. 编写 DeepSeek 客户端

创建 src/deepseek_client.py：

import os
import yaml
import requests
from dotenv import load_dotenv


class DeepSeekClient:
    def __init__(self, config_path="config/config.yaml"):
        load_dotenv()

        self.api_key = os.getenv("DEEPSEEK_API_KEY")
        if not self.api_key:
            raise ValueError("请先在 .env 文件中配置 DEEPSEEK_API_KEY")

        with open(config_path, "r", encoding="utf-8") as f:
            config = yaml.safe_load(f)

        deepseek_config = config.get("deepseek", {})
        prompt_config = config.get("prompt", {})

        self.base_url = deepseek_config.get("base_url", "https://api.deepseek.com")
        self.chat_endpoint = deepseek_config.get("chat_endpoint", "/chat/completions")
        self.model = os.getenv("DEEPSEEK_MODEL", deepseek_config.get("model", "deepseek-chat"))
        self.timeout = deepseek_config.get("timeout", 60)
        self.temperature = deepseek_config.get("temperature", 0.7)
        self.max_tokens = deepseek_config.get("max_tokens", 2048)
        self.system_prompt = prompt_config.get(
            "system",
            "你是一个专业的AI助手。"
        )

    def chat(self, user_content, history=None):
        """
        普通非流式对话
        :param user_content: 用户输入
        :param history: 历史消息列表
        :return: 模型回复文本
        """
        if history is None:
            history = []

        url = self.base_url + self.chat_endpoint

        messages = [
            {
                "role": "system",
                "content": self.system_prompt
            }
        ]

        messages.extend(history)
        messages.append({
            "role": "user",
            "content": user_content
        })

        payload = {
            "model": self.model,
            "messages": messages,
            "temperature": self.temperature,
            "max_tokens": self.max_tokens,
            "stream": False
        }

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

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

        response.raise_for_status()
        data = response.json()

        return data["choices"][0]["message"]["content"]

3. 编写主程序

创建 src/main.py：

from deepseek_client import DeepSeekClient


def main():
    client = DeepSeekClient()

    question = "请用Markdown格式介绍一下RESTful API的核心特点。"

    answer = client.chat(question)

    print("模型回复：")
    print(answer)


if __name__ == "__main__":
    main()

运行：

python src/main.py

七、Python 多轮对话示例

多轮对话的关键是维护 messages 历史记录。每一轮对话结束后，需要将用户问题和模型回答都加入历史。

from deepseek_client import DeepSeekClient


def main():
    client = DeepSeekClient()
    history = []

    while True:
        user_input = input("用户：")

        if user_input.lower() in ["exit", "quit", "q"]:
            print("已退出对话。")
            break

        answer = client.chat(user_input, history=history)

        print("助手：", answer)

        history.append({
            "role": "user",
            "content": user_input
        })

        history.append({
            "role": "assistant",
            "content": answer
        })


if __name__ == "__main__":
    main()

需要注意的是，多轮对话会不断累积上下文，导致 token 消耗增加。实际项目中建议对历史消息进行裁剪，例如只保留最近 5 到 10 轮对话，或者对早期对话进行摘要压缩。

八、Python 流式输出示例

如果你在做聊天机器人、Web 客服、AI 写作助手等应用，建议使用流式输出。流式输出可以让用户更快看到模型生成内容，而不是等待完整结果返回。

下面给出一个简化版流式调用示例：

import os
import json
import requests
from dotenv import load_dotenv


load_dotenv()

API_KEY = os.getenv("DEEPSEEK_API_KEY")
BASE_URL = os.getenv("DEEPSEEK_BASE_URL", "https://api.deepseek.com")
MODEL = os.getenv("DEEPSEEK_MODEL", "deepseek-chat")


def stream_chat(prompt):
    url = f"{BASE_URL}/chat/completions"

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

    payload = {
        "model": MODEL,
        "messages": [
            {
                "role": "system",
                "content": "你是一个专业的中文技术助手。"
            },
            {
                "role": "user",
                "content": prompt
            }
        ],
        "temperature": 0.7,
        "max_tokens": 2048,
        "stream": True
    }

    with requests.post(url, headers=headers, json=payload, stream=True) as response:
        response.raise_for_status()

        for line in response.iter_lines(decode_unicode=True):
            if not line:
                continue

            if line.startswith("data: "):
                data = line[len("data: "):]

                if data == "[DONE]":
                    break

                try:
                    chunk = json.loads(data)
                    delta = chunk["choices"][0].get("delta", {})
                    content = delta.get("content")

                    if content:
                        print(content, end="", flush=True)

                except json.JSONDecodeError:
                    continue


if __name__ == "__main__":
    stream_chat("请用通俗语言解释什么是向量数据库。")

流式响应常见于 SSE，也就是 Server-Sent Events。服务端会不断返回以 data: 开头的数据片段，客户端解析每个片段即可。

九、Node.js 调用示例

如果你的项目使用 Node.js，也可以通过 fetch 或 axios 调用 DeepSeek API。

1. 初始化项目

mkdir deepseek-api-node-demo
cd deepseek-api-node-demo
npm init -y
npm install dotenv

如果你的 Node.js 版本较新，已经内置 fetch。如果版本较低，可以安装 node-fetch 或使用 axios。

2. .env 文件

DEEPSEEK_API_KEY=sk-your-api-key-here
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-chat

3. Node.js 普通调用

创建 src/index.js：

require("dotenv").config();

const API_KEY = process.env.DEEPSEEK_API_KEY;
const BASE_URL = process.env.DEEPSEEK_BASE_URL || "https://api.deepseek.com";
const MODEL = process.env.DEEPSEEK_MODEL || "deepseek-chat";

async function chat(prompt) {
  if (!API_KEY) {
    throw new Error("请先配置 DEEPSEEK_API_KEY");
  }

  const response = await fetch(`${BASE_URL}/chat/completions`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: MODEL,
      messages: [
        {
          role: "system",
          content: "你是一个专业的中文技术助手。"
        },
        {
          role: "user",
          content: prompt
        }
      ],
      temperature: 0.7,
      max_tokens: 1024,
      stream: false
    })
  });

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

  const data = await response.json();

  return data.choices[0].message.content;
}

chat("请介绍一下 API Key 鉴权的基本原理。")
  .then(answer => {
    console.log("模型回复：");
    console.log(answer);
  })
  .catch(error => {
    console.error("调用失败：", error);
  });

运行：

node src/index.js

十、常见参数说明

在调用 DeepSeek API 时，以下参数非常重要。

1. model

用于指定调用的模型，例如：

"model": "deepseek-chat"

不同模型的能力、价格和上下文长度可能不同。建议根据业务需求选择。

2. temperature

控制输出随机性。

"temperature": 0.7

一般建议：

值越低，输出越稳定；值越高，输出越发散。

3. max_tokens

控制模型最大输出长度。

"max_tokens": 2048

如果你发现回复被截断，可以适当增加该值。但需要注意，输出越长，消耗越多。

4. stream

是否开启流式输出。

"stream": true

如果是命令行工具、后台批处理、报告生成，可以使用非流式；如果是聊天窗口、网页助手、客服机器人，建议使用流式。

十一、接口异常处理

在真实项目中，不能只考虑调用成功的情况，还需要处理各种异常。

常见错误包括：

推荐的异常处理方式包括：

• 设置合理的请求超时时间；
• 对 429、500、502、503 等错误做重试；
• 记录请求 ID、状态码、错误信息；
• 不要在日志中打印完整 API Key；
• 对用户输入做长度限制；
• 对模型输出做安全过滤和格式校验。

下面是一个简单的 Python 重试示例：

import time
import requests


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

            if response.status_code in [429, 500, 502, 503, 504]:
                wait_time = 2 ** attempt
                time.sleep(wait_time)
                continue

            response.raise_for_status()
            return response

        except requests.RequestException as e:
            if attempt == retries - 1:
                raise e

            wait_time = 2 ** attempt
            time.sleep(wait_time)

十二、提示词配置建议

调用 API 时，很多人只关注代码，而忽略了提示词设计。事实上，系统提示词会直接影响输出质量。

一个较好的系统提示词应该包含：

• 模型角色；
• 回答风格；
• 输出格式；
• 限制条件；
• 业务边界；
• 遇到不确定问题时的处理方式。

例如：

你是一个企业内部知识库问答助手。
请严格根据用户提供的资料进行回答，不要编造不存在的信息。
如果资料中没有答案，请回答“根据当前资料无法确认”。
回答应简洁、准确，并使用Markdown格式。

如果用于代码助手，可以这样写：

你是一个资深后端工程师，擅长Python、Node.js和API设计。
回答问题时请优先给出可运行代码，并解释关键逻辑。
如果用户需求不完整，请先列出必要假设，再给出实现方案。

提示词也可以放在配置文件中统一管理，方便不同场景切换。

十三、生产环境接入注意事项

在生产环境中调用 DeepSeek API，不建议只写一个简单的 HTTP 请求就上线。你还需要考虑稳定性、安全性和成本控制。

1. API Key 安全

API Key 必须保存在后端，不应暴露给浏览器、小程序、移动端等客户端。前端应请求自己的业务后端，由后端再调用 DeepSeek API。

2. 请求限流

如果用户量较大，需要在业务侧做限流，例如：

• 单用户每分钟最多请求多少次；
• 单 IP 每小时最多请求多少次；
• 单账号每日 token 使用上限；
• 异常请求自动拦截。

3. 日志与审计

建议记录：

• 请求时间；
• 用户 ID；
• 模型名称；
• 消耗 token；
• 响应时间；
• 错误状态码；
• 是否命中重试。

但不要记录敏感内容，尤其是 API Key、用户隐私数据、企业机密信息等。

4. 成本控制

模型调用通常按 token 计费。降低成本的方法包括：

• 控制上下文长度；
• 对历史对话做摘要；
• 设置合理的 max_tokens；
• 避免重复请求；
• 对常见问题做缓存；
• 针对不同任务选择不同模型。

5. 输出校验

如果你要求模型返回 JSON，不要默认相信模型一定返回合法 JSON。应该在代码中进行解析校验。

例如：

import json

def parse_json_output(text):
    try:
        return json.loads(text)
    except json.JSONDecodeError:
        raise ValueError("模型返回内容不是合法 JSON")

在一些关键业务中，可以让模型输出后再经过规则校验或二次确认。

十四、一个完整的配置文件模板

下面给出一个相对完整的配置模板，适合实际项目参考。

app:
  name: "deepseek-api-demo"
  env: "development"
  log_level: "INFO"

deepseek:
  base_url: "https://api.deepseek.com"
  chat_endpoint: "/chat/completions"
  model: "deepseek-chat"
  timeout: 60
  temperature: 0.5
  max_tokens: 2048
  stream: false
  retry:
    enabled: true
    max_attempts: 3
    backoff_factor: 2

prompt:
  system: |
    你是一个专业的中文AI助手。
    请使用简洁、准确、结构清晰的语言回答问题。
    如涉及技术内容，请优先使用Markdown格式组织答案。
    如果问题信息不足，请说明需要补充哪些信息。

对应的 .env.example：

DEEPSEEK_API_KEY=
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-chat

.gitignore 建议添加：

.env
__pycache__/
*.pyc
node_modules/
.DS_Store

十五、常见问题 FAQ

1. DeepSeek API 可以直接在前端调用吗？

不建议。因为前端代码容易被查看，一旦 API Key 暴露，可能导致接口被盗刷。正确做法是前端请求你的后端服务，再由后端调用 DeepSeek API。

2. 为什么模型回复不稳定？

可能是 temperature 设置较高，也可能是提示词不够明确。可以降低 temperature，并在 system prompt 中明确输出格式和约束。

3. 为什么回复被截断？

通常是 max_tokens 设置过小，或者上下文太长导致可用输出空间不足。可以适当增加 max_tokens，并减少历史消息长度。

4. 如何让模型返回 JSON？

可以在提示词中明确要求：

请只返回合法JSON，不要输出解释文字。
JSON字段包括：title、summary、items。

同时在代码中进行 JSON 解析校验。

5. 多轮对话是否必须传全部历史？

不一定。传全部历史可以提高上下文连续性，但会增加成本。实际项目中通常只保留最近几轮，或者将早期对话压缩成摘要。

十六、总结

本文从接口概念、调用准备、配置文件、curl 测试、Python 示例、Node.js 示例、流式输出、多轮对话、异常处理和生产环境注意事项等方面，完整介绍了 DeepSeek API 的调用方法。

实际开发中，建议你遵循以下原则：

1. API Key 使用环境变量管理，不要硬编码；
2. 配置文件中管理模型、接口地址、超时时间和默认提示词；
3. 聊天类应用优先考虑流式输出；
4. 生产环境必须加入异常处理、重试、限流和日志；
5. 控制上下文长度，避免 token 成本失控；
6. 对模型输出进行必要校验，尤其是 JSON 和业务关键结果。

通过本文提供的配置文件和代码示例，你可以快速搭建一个可运行的 DeepSeek API 调用项目，并在此基础上扩展为智能客服、知识库问答、AI 写作助手或企业内部自动化工具。