【AI大模型接入SDK】DeepSeek API 基础概述

🎬 个人主页 ：艾莉丝努力练剑
❄专栏传送门 ：《C语言》《数据结构与算法》《C/C++干货分享&学习过程记录》
《Linux操作系统编程详解》《笔试/面试常见算法：从基础到进阶》《Python干货分享》

⭐️为天地立心，为生民立命，为往圣继绝学，为万世开太平

🎬 艾莉丝的简介：

文章目录

[1 ~> DeepSeek API 基础概述](#1 ~> DeepSeek API 基础概述)
- [1.1 接入前置条件](#1.1 接入前置条件)
- [1.2 设计兼容性](#1.2 设计兼容性)
[2 ~> 请求协议与接口规范](#2 ~> 请求协议与接口规范)
- [2.1 通信协议](#2.1 通信协议)
- [2.2 对话补全接口端点](#2.2 对话补全接口端点)
- [2.3 请求头规范](#2.3 请求头规范)
[3 ~> 核心请求参数详解](#3 ~> 核心请求参数详解)
- [3.1 必选参数](#3.1 必选参数)
- - [3.1.1 model](#3.1.1 model)
  - [3.1.2 messages](#3.1.2 messages)
- [3.2 核心可选参数](#3.2 核心可选参数)
- - [3.2.1 max_tokens](#3.2.1 max_tokens)
  - [3.2.2 stream](#3.2.2 stream)
  - [3.2.3 temperature](#3.2.3 temperature)
  - [3.2.4 top_p](#3.2.4 top_p)
  - [3.2.5 frequency_penalty](#3.2.5 frequency_penalty)
  - [3.2.6 presence_penalty](#3.2.6 presence_penalty)
- [3.3 其他可选参数](#3.3 其他可选参数)
[4 ~> 无状态服务与上下文机制](#4 ~> 无状态服务与上下文机制)
- [4.1 无状态设计本质](#4.1 无状态设计本质)
- [4.2 上下文（Context）定义](#4.2 上下文（Context）定义)
- [4.3 会话连续性实现](#4.3 会话连续性实现)
[5 ~> 响应格式与字段解析](#5 ~> 响应格式与字段解析)
- [5.1 非流式响应完整结构](#5.1 非流式响应完整结构)
- [5.2 核心字段详解](#5.2 核心字段详解)
- - [5.2.1 基础元数据](#5.2.1 基础元数据)
  - [5.2.2 choices 数组](#5.2.2 choices 数组)
  - [5.2.3 usage 统计字段](#5.2.3 usage 统计字段)
- [5.3 响应内容提取流程](#5.3 响应内容提取流程)
[6 ~> 接入最佳实践](#6 ~> 接入最佳实践)
- [6.1 最简调用配置](#6.1 最简调用配置)
- [6.2 参数调优建议](#6.2 参数调优建议)
- [6.3 会话管理规范](#6.3 会话管理规范)
结尾

1 ~> DeepSeek API 基础概述

1.1 接入前置条件

获取有效的 DeepSeek API-Key
掌握 HTTP 协议基础与 JSON 数据格式规范

1.2 设计兼容性

采用与 OpenAI 高度兼容的 API 格式，可直接适配原有 OpenAI 生态工具与 SDK
兼容格式 base_url：https://api.deepseek.com/v1（v1 为格式兼容标识，与模型版本号无关）
原生接口 base_url：https://api.deepseek.com

2 ~> 请求协议与接口规范

2.1 通信协议

传输层：基于 HTTP 协议
请求方法：POST
内容类型：application/json

2.2 对话补全接口端点

完整请求 URL：https://api.deepseek.com/chat/completions
核心功能：根据输入的对话上下文，生成模型对话补全内容

2.3 请求头规范

必选请求头：
- Content-Type: application/json：声明请求体格式
- Authorization: Bearer <你的DeepSeek API-Key>：身份鉴权

3 ~> 核心请求参数详解

3.1 必选参数

3.1.1 model

类型：string
可选值：
- deepseek-chat：通用对话模型，非思考模式，响应速度快
- deepseek-reasoner：深度思考模式，擅长复杂推理、数学与代码问题
底层架构：两款模型均基于 DeepSeek-V3.1-Terminus 架构
版本演进：后续思考模式将整合进 deepseek-chat，无需单独调用

3.1.2 messages

类型：object 数组
长度约束：≥ 1
核心作用：携带完整对话上下文，是模型生成回复的唯一信息来源
数组元素角色分类：
- system：系统提示词，用于定义模型身份、行为边界与输出规则
- user：用户输入的提问与指令
- assistant：模型的历史回复内容
- tool：第三方工具调用的返回结果
单条消息对象结构：
- role（必填）：消息发起角色
- content（必填）：消息文本内容
- name（可选）：参与者标识，用于区分同角色下的不同主体

3.2 核心可选参数

3.2.1 max_tokens

类型：integer
功能：限制单次请求中模型生成回复的最大 token 数量
约束规则：仅限制输出 token 数，不限制输入 token 数；输入 + 输出总长度受模型上下文窗口限制
适用场景：控制回复篇幅，避免模型输出冗余内容，常规场景推荐设置为 1024~2048

3.2.2 stream

类型：boolean
默认值：false
功能：控制是否开启 SSE（Server-Sent Events）流式输出
- true：逐段返回生成内容，消息流以 data: [DONE] 标记结束
- false：模型生成完成后一次性返回完整响应

3.2.3 temperature

类型：number
取值范围：0 ~ 2
默认值：1
功能：从全局维度控制模型输出的随机性
- 值越高：输出随机性越强、想象力越丰富，适合创意类写作
- 值越低：输出越严谨、确定性越高，适合代码生成、数学解题
官方场景参考：
- 0.0：代码生成、数学运算等强确定性场景
- 1.3：创意写作、诗歌创作等强发散场景
注意：不建议与 top_p 参数同时修改

3.2.4 top_p

类型：number
取值范围：0 ~ 1
默认值：1
功能：通过核采样（Nucleus Sampling）控制输出随机性，是 temperature 的替代方案
工作原理：将候选 token 按概率降序排列，从最高概率开始累积，选取累积概率刚好超过 top_p 的最小 token 集合，再在集合内随机选择
示例：top_p = 0.8 时，仅从累积概率覆盖 80% 的高概率 token 中选择输出
注意：不建议与 temperature 参数同时修改

3.2.5 frequency_penalty

类型：number
取值范围：-2.0 ~ 2.0
默认值：0
功能：根据 token 在已有文本中的出现频率施加惩罚，正值会降低模型重复相同内容的概率

3.2.6 presence_penalty

类型：number
取值范围：-2.0 ~ 2.0
默认值：0
功能：根据 token 是否已在文本中出现过施加惩罚，正值会增加模型谈论新主题的可能性

3.3 其他可选参数

response_format：指定响应格式，支持 text 等结构化格式
stop：自定义停止词，模型遇到指定内容时立即停止生成
logprobs：是否返回输出 token 的对数概率
top_logprobs：指定返回概率最高的 token 数量
tools / tool_choice：函数调用与工具使用相关配置

4 ~> 无状态服务与上下文机制

4.1 无状态设计本质

底层基于 HTTP 无状态协议，每次请求 - 响应为独立事务，请求结束后 TCP 连接断开
服务端不存储任何会话信息，无法自动关联前后两次请求
符合 RESTful 设计规范，具备高可扩展性与水平扩展能力

4.2 上下文（Context）定义

定义：单次请求中 messages 数组包含的全部信息，即模型本次调用可见的所有内容
上下文窗口：DeepSeek V3.1 系列模型支持最大 128K 上下文长度，约合 300~500 页文档内容
截断规则：上下文超出最大长度时，会自动截断较早的历史内容

4.3 会话连续性实现

核心结论：模型本身不具备 "记忆" 能力，连续对话完全依赖客户端传入的完整上下文
实现方式：客户端必须主动维护对话历史，每次请求将完整的历史消息数组传入 messages 参数
官方网页端原理：后台服务替用户维护会话记录，每次请求自动拼接历史上下文后再调用模型接口
实验验证：独立两次请求不携带历史上下文时，模型无法关联前序对话内容；携带完整历史时可正常连续对话

5 ~> 响应格式与字段解析

5.1 非流式响应完整结构

json 复制代码

{
  "id": "8b1ca715-9270-429a-b40d-2a644f6e1d3f",
  "object": "chat.completion",
  "created": 1754880537,
  "model": "deepseek-chat",
  "system_fingerprint": "fp_8802369eaa_prod623_f8_kvcache",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "我是DeepSeek Chat，由深度求索公司开发的智能AI助手！"
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 5,
    "completion_tokens": 63,
    "total_tokens": 68,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "prompt_cache_hit_tokens": 0,
    "prompt_cache_miss_tokens": 5
  }
}

5.2 核心字段详解

5.2.1 基础元数据

id：本次对话补全的唯一标识符
object：对象类型，固定值为 chat.completion
created：创建时间，Unix 时间戳（秒级）
model：实际生成内容的模型名称
system_fingerprint：后端运行配置指纹，用于排查版本差异与环境问题

5.2.2 choices 数组

功能：存放模型生成的回复结果，常规场景为单条结果
内部字段：
- index：结果序号
- message：回复消息对象，包含 role 和 content 字段
- finish_reason：结束原因，常见值 stop（正常结束）、length（达到 max_tokens 限制）
- logprobs：token 对数概率信息，未开启功能则为 null

5.2.3 usage 统计字段

prompt_tokens：输入消息消耗的 token 数
completion_tokens：输出内容消耗的 token 数
total_tokens：本次请求总消耗 token 数
prompt_tokens_details：输入 token 明细，包含缓存命中情况

5.3 响应内容提取流程

解析完整 JSON 响应体
定位 choices 数组，遍历数组元素
从目标元素中提取 message 对象
读取 message.content 字段，即为模型回复的文本内容

6 ~> 接入最佳实践

6.1 最简调用配置

基础调用仅需传入 model、messages 两个必选参数，其余参数按需添加
测试与简单场景可关闭流式输出，便于调试与结果解析

6.2 参数调优建议

代码 / 解题场景：temperature 设置为 0.1~0.3，提升输出准确性
创意写作场景：temperature 设置为 1.0~1.3，增强内容发散性
生产环境：根据业务需求设置 max_tokens，控制响应时长与 token 成本

6.3 会话管理规范

客户端需持久化维护 messages 数组，每次新请求追加最新的 user 和 assistant 消息
长会话场景需监控上下文长度，超出限制时主动裁剪早期历史
角色设定需每次请求都携带 system 消息，确保模型行为一致性

结尾

uu们，本文的内容到这里就全部结束了，艾莉丝在这里再次感谢您的阅读！

|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ### 艾莉丝努力练剑 C/C++ & Linux 底层探索者 | 一个正在努力练剑的技术博主 *** ** * ** *** 👀 【关注】 跟随我一起深耕技术领域，见证每一次成长。 ❤️ 【点赞】 让优质内容被更多人看见，让知识传递更有力量。 ⭐ 【收藏】 把核心知识点存好，在需要时随时查、随时用。 💬 【评论】 分享你的经验或疑问，评论区一起交流避坑！ 不要忘记给博主"一键四连"哦！ "今日练剑达成！" "技术之路难免有困惑，但同行的人会让前进更有方向。" |

结语：希望对学习Linux相关内容的uu有所帮助，不要忘记给博主"一键四连"哦！

往期回顾：

【AI大模型接入SDK】Provider分析与实现

🗡博主在这里放了一只小狗，大家看完了摸摸小狗放松一下吧！🗡 ૮₍ ˶ ˊ ᴥ ˋ˶₎ა