《C++ 项目：手写大模型接入 SDK》云端 API 调用基础与 Apifox 调试实战

🔥小叶-duck：个人主页

❄️个人专栏：《Data-Structure-Learning》《C++入门到进阶&自我学习过程记录》

《Linux系统从入门到实践》《Linux网络从入门到实践》

《Qt 方寸极境》《MySQL》

✨未择之路，不须回头
已择之路，纵是荆棘遍野，亦作花海遨游

前言

[一、两种大模型接入方案：云端 API 接入 vs 本地部署](#一、两种大模型接入方案：云端 API 接入 vs 本地部署)

[1.1 云端 API 接入](#1.1 云端 API 接入)

[1.2 本地部署](#1.2 本地部署)

[二、API 接入云端大模型](#二、API 接入云端大模型)

[2.1 大模型 API 平台在哪里？](#2.1 大模型 API 平台在哪里？)

[2.2 API Key 获取与安全规范](#2.2 API Key 获取与安全规范)

[2.2.1 什么是 API Key](#2.2.1 什么是 API Key)

[2.2.2 DeepSeek 创建 API Key 步骤](#2.2.2 DeepSeek 创建 API Key 步骤)

[2.3 API 基础调用信息（接口地址与模型名称）](#2.3 API 基础调用信息（接口地址与模型名称）)

[2.4 接口文档：Chat Completions 对话补全接口](#2.4 接口文档：Chat Completions 对话补全接口)

[2.4.1 接口定位](#2.4.1 接口定位)

[2.5 请求报文结构详解（curl 示例）](#2.5 请求报文结构详解（curl 示例）)

[2.5.1 messages 数组：role 角色介绍](#2.5.1 messages 数组：role 角色介绍)

[三、Apifox 工具介绍](#三、Apifox 工具介绍)

[3.1 使用 Apifox 调试 DeepSeek 大模型 API](#3.1 使用 Apifox 调试 DeepSeek 大模型 API)

[3.1.1 新建 HTTP 接口](#3.1.1 新建 HTTP 接口)

[3.1.2 配置请求头 Headers](#3.1.2 配置请求头 Headers)

[3.1.3 新建测试环境，配置环境变量](#3.1.3 新建测试环境，配置环境变量)

[3.1.4 切换到调试页面，发送请求](#3.1.4 切换到调试页面，发送请求)

[3.1.5 查看流式响应结果](#3.1.5 查看流式响应结果)

小结

结束语

前言

在正式动手用 C++ 编写 SDK 代码之前，我们不能直接上手封装网络请求，需要先搞懂大模型服务背后的通信逻辑。我们最终写出来的 SDK，本质上就是对大模型开放的 HTTP 接口做一层 C++ 封装，所有对话、流式输出能力，都依赖后端标准的 Completion 对话接口。

本章我们会先区分云端 API 接入和本地部署两种主流接入思路，以 DeepSeek 平台为例，完整梳理 API Key 的获取、接口报文格式、请求规范。同时借助 Apifox 工具完成接口调试，直观看到普通请求和流式返回的数据差异。

先在接口层面跑通整个调用链路，看懂请求体、响应结构、messages 数组的含义，理解流式输出是怎样分片返回内容的。只有把 HTTP 接口这一层吃透，后续再使用 cpp-httplib、JsonCpp 去封装 C++ SDK 时，才清楚每一段代码的意义，知道我们要封装什么、解析什么，避免写代码时只照搬模板而不懂底层原理。

一、两种大模型接入方案：云端 API 接入 vs 本地部署

大语言模型主流接入方案分为云端 API 调用 与本地私有化部署，我们分别介绍两种方案的特点，对比二者适用场景。

1.1 云端 API 接入

厂商把大模型部署在自己的云服务器上，对外提供 HTTP 接口。普通用户可以直接访问网页使用，开发人员则通过调用官方 API，在自己的程序里对接大模型能力。

优势：

开箱即用，上手门槛低，不需要准备高性能显卡，不用关心模型部署与运维。
模型版本由厂商持续迭代更新，始终可以使用最新、能力更强的模型。
按量计费，前期投入低，成本相对可控。
模型经过充分优化，整体能力上限更高。

劣势：

数据安全隐患：用户对话数据会发送到厂商云端服务器，企业敏感业务数据不适合这种方式。
持续产生调用费用，业务量大时长期成本会持续累积。
存在网络延迟，依赖网络环境；断网情况下无法使用。

1.2 本地部署

借助 Ollama 这类第三方工具，将大模型权重下载到自己的服务器 / 本地主机，模型完全运行在我们自己的硬件环境中。

优势：

数据不出本机，具备高数据安全性，敏感业务场景更友好。
一次性硬件投入，调用模型不再按 token 持续扣费。
消除跨公网的网络延迟，内网环境响应更快，断网也可以运行。
模型完全可控：可自由选择模型版本、修改模型参数、做微调。

劣势：

需要高性能硬件，GPU 等设备带来较高的一次性硬件成本。
受本地硬件性能限制，同模型下推理速度、上下文上限弱于云端。
有一定技术门槛，需要自己负责环境、模型维护与运维工作。
模型每次更新需要手动下载新版本，不会自动升级。

方案选型小结：

如果是普通应用开发、快速验证产品原型、非敏感业务，优先选择云端 API 接入，开发简单，省去大量运维工作。

如果业务涉及企业内部机密、隐私数据，或者需要离线使用、对延迟要求极高，则适合本地私有化部署。

二、API 接入云端大模型

训练大模型需要极高的算力与资金成本，普通开发者很难自行完成训练与部署。厂商将大模型部署在云端服务器，对外提供基于 HTTP 协议开放 API。开发者不需要关心模型底层训练、推理硬件，直接发送 HTTP 请求就可以接入大模型能力，快速开发业务应用。

下面我们以 DeepSeek 为例，完整讲解 API 接入的全流程。

2.1 大模型 API 平台在哪里？

DeepSeek 官网地址：https://www.deepseek.com

网页端是给普通用户直接对话使用；而我们开发程序调用模型，需要进入API 开放平台。

提示：官网页面会持续迭代更新，API 开放平台入口位置可能发生变化。

厂商会在 API 平台维护云端大模型服务，模型运行在厂商的远端服务器上，我们本地程序通过网络，向这个远端服务发送 HTTP 请求完成对话交互。

2.2 API Key 获取与安全规范

2.2.1 什么是 API Key

API Key 是一串加密字符串 ，相当于访问大模型服务的密钥，承担 4 个核心作用：

身份验证：校验调用方是否为授权用户，只有携带合法 API Key 才能访问接口。
权限授权：区分不同账号的访问能力，部分高级模型需要对应权限。
调用监控与限流：统计请求量，设置调用频率上限，防止密钥被盗后恶意刷量。
计费统计：根据 Token 消耗自动扣费，用于账单结算。

可以类比银行卡：银行卡本身是凭证，银行通过卡片验证身份、区分卡片权限、监控流水、收取手续费，API Key 的作用与之类似。

2.2.2 DeepSeek 创建 API Key 步骤

进入 DeepSeek 开放平台，找到侧边栏 API keys 选项。
点击【创建 API key】，自定义密钥名称，生成密钥。
重要安全提醒：
- API Key 仅创建瞬间可以完整复制，关闭弹窗之后网页会做掩码加密，无法再次查看完整密钥。
- 严禁泄露 API Key，不要直接写在客户端代码、前端网页中。一旦泄露，其他人可以盗用你的密钥调用接口，产生费用。平台检测到密钥公开泄露，会自动禁用该密钥保护账户。
- 单个账号最多支持 200 个 API Key，可按需创建、删除管理。

2.3 API 基础调用信息（接口地址与模型名称）

DeepSeek 的 API 兼容 OpenAI 的请求格式，因此可以直接复用很多 OpenAI 生态的 SDK 与工具。

基础服务地址 base_url：https://api.deepseek.com ，也可以追加 /v1 写成https://api.deepseek.com/v1，v1只是为了保持和 OpenAI 兼容，和模型版本没有关联。
常用模型名称：
- deepseek-flash：轻量高速模型（旧名称如 deepseek-v4-flash 依然可调用，底层自动路由到新版模型）
- deepseek-v4-pro：高性能版本模型

说明： 后续模型名称会迭代升级，但HTTP 调用报文格式不会改动，我们开发的 SDK 只需要修改传入的模型名字符串，不需要改动核心业务代码。

2.4 接口文档：Chat Completions 对话补全接口

2.4.1 接口定位

bash 复制代码

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

DeepSeek 的对话补全主入口 ：根据输入的上下文，让模型补全对话内容。

协议与 OpenAI v1/chat/completions 兼容，SDK 改 base_url 即可直连。

同组接口分工：

方法	路径	用途
POST	`/chat/completions`	Chat Completions API，根据输入上下文补全对话内容
POST	`/responses`	Responses API，以 OpenAI Responses API 格式创建模型响应
POST	`/beta/completions`	FIM (Fill In the Middle) 补全 API（Beta），需设置 `base_url="https://api.deepseek.com/beta"` 使用
GET	`/models`	列出当前可用模型，提供各模型元数据：展示名称、上下文窗口、输出上限、支持的输入 / 输出模态、推理强度（effort）档位等
GET	`/user/balance`	查询账号余额

2.5 请求报文结构详解（curl 示例）

bash 复制代码

curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -d '{
    "model": "deepseek-flash",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ],
    "thinking": {"type": "enabled"},
    "reasoning_effort": "high",
    "stream": false
  }'

请求头：
- Content-Type: application/json：请求体是 JSON 格式。
- Authorization: Bearer ${DEEPSEEK_API_KEY}：身份认证，把我们生成的 API Key 放到这里。
请求体核心字段：
- model：指定本次调用使用的模型名称。
- messages：对话上下文数组，保存多轮对话历史，是整个请求最核心的部分。
- thinking：DeepSeek V4 系列新增字段，思考模式总开关，开启后模型会做深度推理。
- reasoning_effort：控制思考强度，可选low / high / max，默认high。
- stream：流式输出开关。
  - false：等模型全部生成完毕一次性返回完整结果；
  - true：SSE 流式分片返回，一边生成一边推送内容，就是我们常见的打字机效果。

2.5.1 messages 数组：role 角色介绍

messages 数组里面每一条消息，都包含role角色和content内容。

role 用来标记单条消息的身份 ，大模型依靠角色区分这条消息是谁发出的，以此理解完整对话上下文，生成符合逻辑的应答 。

主流 API 消息数组里，常用有 4 种角色：

user：代表用户输入的消息，也就是客户端传给大模型的用户提问内容。

cpp 复制代码

{
    "role": "user",
    "content": "你好，我想了解一下健康饮食的基本原则。"
}

assistant：代表大模型自身生成、返回的应答内容，也就是模型上一轮输出的回复。

cpp 复制代码

{
    "role": "assistant",
    "content": "健康饮食的基本原则包括均衡摄入各种营养素、控制热量摄入、多吃蔬菜水果、减少高糖高盐高脂肪食物等。"
}

system：用于设定 AI 助手的身份、行为规则、能力边界。在对话最开始传入，用来给大模型下达全局指令，后续对话中大模型会按照这个设定来回答用户问题。

cpp 复制代码

{
    "role": "system",
    "content": "你是一位专业的营养师，专注于健康饮食领域。"
}

tool ：用于工具调用（也叫函数调用）场景。当大模型判断需要调用外部工具获取数据，等外部工具执行完成后，tool角色消息就会把工具返回的结果交给大模型，让模型结合这个结果整理最终回复给用户。

cpp 复制代码

{
    "role": "tool",
    "tool_call_id": "call_123456",
    "content": "查询结果：每日推荐蔬菜摄入量为300~500g"
}

补充说明： 所有消息会统一放到messages数组里，按先后顺序排列，顺序代表对话时序，大模型读取整个数组，才能看懂多轮对话的上下文。
接入思路总结：

整个云端 API 接入本质：构造符合规范的 JSON 请求报文，通过 HTTP POST 发送给厂商提供的服务地址，携带 API Key 完成身份校验，服务端执行推理后返回 JSON 格式的模型应答。

三、Apifox 工具介绍

Apifox 是一站式 API 设计、开发、测试的协作平台 ，整合了接口调试（类似 Postman）、接口文档、Mock 模拟、压力测试等能力。

在我们项目里，它最核心的作用就是快速调试 HTTP 接口 ，不用写一行代码，直接构造 HTTP 请求 ，发送给大模型服务，查看请求与返回结果 ，提前验证 API 是否可用。

**简单理解：**在动手写 C++ 代码对接大模型之前，先用 Apifox 把接口调通，确认请求体、鉴权、返回数据格式没问题，后续写 SDK 的时候就能少踩很多坑。

3.1 使用 Apifox 调试 DeepSeek 大模型 API

我们以 DeepSeek 的deepseek-chat对话模型接口为例，演示完整调试流程。

接口基础地址 (Base url)：https://api.deepseek.com

请求端点：/v1/chat/completions，请求方法：POST

3.1.1 新建 HTTP 接口

首先在 Apifox 项目中新建 HTTP 接口，请求方法选择 POST。

前置 URL 我们后续在环境里统一配置，这里接口路径只填写 /chat/completions（路径不需要写前面域名）
请求体 Body 类型选择 JSON，对应大模型接口要求的 json 传参格式

请求体 JSON 模板：

bash 复制代码

{
    "model": "deepseek-flash",
    "stream": true,
    "thinking": {
        "type": "disabled"
    },
    "messages": [
        {
            "role": "user",
            "content": "你好，请简单介绍自己"
        }
    ]
}

参数说明：

model：指定要调用的模型名称
stream：true 代表开启流式响应，分块返回内容；false 为一次性返回全部结果
thinking：控制思考输出，这里关闭思考内容
messages：对话消息数组，就是上一节学习的 role 消息结构

3.1.2 配置请求头 Headers

切换到 Headers 标签页，添加两个核心请求头：

Content-Type: application/json：告诉服务端，本次请求的数据是 JSON 格式
Authorization: Bearer {``{DEEPSEEK_APIKEY}}：身份鉴权头，Bearer 后面跟随我们的密钥。

重要： API Key 属于敏感凭证，绝对不建议直接明文写在请求头里 ，一旦分享接口文档、截图就会造成密钥泄露。所以我们采用 Apifox 环境变量 {``{DEEPSEEK_APIKEY}} 来引用密钥。

3.1.3 新建测试环境，配置环境变量

点击右上角菜单，打开【环境管理】，新建一个测试环境：

前置 URL ：填写 DeepSeek 服务域名 https://api.deepseek.com，接口路径会和这个域名自动拼接成完整请求地址
添加环境变量 ：变量名 DEEPSEEK_APIKEY，本地值填入你在 DeepSeek 平台申请的密钥；Apifox 支持把变量标记为保密，不会明文展示密钥。
保存环境配置

配置完成后，Headers 里的 {``{DEEPSEEK_APIKEY}} 就会自动替换成我们填入的密钥，完整请求头自动拼接为 Bearer sk-xxxx。

3.1.4 切换到调试页面，发送请求

切换标签到【调试】，确认右上角选中我们刚刚创建好的测试环境，核对 Body 里的 JSON 消息，点击紫色【发送】按钮，向 DeepSeek 服务发起 HTTP 请求。

3.1.5 查看流式响应结果

服务端返回状态码 200 代表请求成功。因为我们设置了 stream:true，返回结果不是一个完整 JSON，而是持续不断推送多条独立的 JSON 块（chunk） ，每一条就是chat.completion.chunk。

每一条 JSON 中的**choices[0].delta.content** 就是本次新增输出的文本片段
大模型一边生成文字，一边分片下发，和网页聊天框打字的效果完全一致
当 finish_reason 有值的时候，代表本轮对话生成结束

小结

通过 Apifox 调试，我们摸清了 DeepSeek 对话接口完整调用逻辑：

本质是一次POST 的 HTTP 请求，JSON 承载对话消息数组
Authorization 鉴权头是访问接口的通行证，必须妥善保管
stream 参数控制是否流式返回，流式返回会收到大量独立的 chunk 数据包

后续我们手写 C++ SDK，核心目标就是用代码模拟这套 HTTP 请求逻辑，并且解析、拼接流式返回的每一段 delta 内容。

结束语

到这里，我们就完成了大模型云端 API 调用的前置学习。我们对比了云端 API 接入与本地部署两种方案，了解了 API Key 的作用与安全注意事项，拆解了 Chat Completions 对话接口的报文结构，并且通过 Apifox 工具真实调试了接口，亲眼观察了流式响应的返回效果。

这一章的核心目标，不是直接写出 C++ 代码，而是先建立对大模型 HTTP 接口的认知：明白一次对话请求由哪些字段组成、messages 数组如何维护多轮上下文、流式输出的数据分片是什么样的。

这些接口层面的知识，就是我们后续手写 C++ SDK 的依据。等进入正式编码阶段，我们要做的，就是用 cpp‑httplib 组装这里学的 HTTP 请求，用 JsonCpp 组装、解析 JSON 报文，把这一套调试通的接口逻辑，封装成好用的 C++ 接口。