基于C++构建DeepSeek大模型推理SDK:架构设计与工程实践
使用C++从零构建DeepSeek大模型推理SDK的全过程。内容涵盖云端鉴权机制、核心数据结构设计、基于策略模式的抽象接口层、适配器实现、单元测试体系以及CMake构建系统配置。通过面向对象设计和模块化开发,确保SDK在高性能计算场景下的稳定性与扩展性。测试环节验证了初始化、消息发送及日志记录功能,最终实现了生产级SDK的工程落地。

使用C++从零构建DeepSeek大模型推理SDK的全过程。内容涵盖云端鉴权机制、核心数据结构设计、基于策略模式的抽象接口层、适配器实现、单元测试体系以及CMake构建系统配置。通过面向对象设计和模块化开发,确保SDK在高性能计算场景下的稳定性与扩展性。测试环节验证了初始化、消息发送及日志记录功能,最终实现了生产级SDK的工程落地。

在高性能计算与大模型(LLM)应用开发的浪潮中,C++凭借其卓越的内存管理能力和运行时效率,成为了构建底层推理SDK的首选语言。本文将深入剖析如何从零开始,设计并实现一个能够调用云端大模型的C++ SDK。全过程涵盖了云端鉴权、面向对象架构设计、多态接口封装、单元测试体系构建以及CMake编译系统的配置。
大模型的调用始于服务提供商的鉴权流程。鉴权体系通常采用基于OAuth2或API Key的机制,确保服务调用的安全性与计费准确性。
访问控制台注册页面,完成账户初始化。
https://console.example.com/#/register
注册完成后进入模型广场。在众多大语言模型中,选择目标版本。模型ID(Model ID)是API调用中路由请求的关键标识符,系统后端依据此ID将请求分发至加载了特定权重的推理集群。此处记录模型ID为 /maas/deepseek-ai/DeepSeek-V3.2。
紧接着,在安全设置中生成API Key。API Key本质上是一个加密的凭证,通常包含用户标识和签名信息。在HTTP请求头中,它通常以Bearer Token的形式存在(Authorization: Bearer <API_KEY>)。该密钥必须严格保密,防止泄露导致额度被盗用。
查阅API文档是集成的核心步骤。文档定义了通信协议(HTTP/HTTPS)、请求方法(POST)、数据格式(JSON)以及服务端点(Endpoint)。
文档显示Base URL为 https://api.example.com/v1/chat/completions。这表明该服务遵循OpenAI兼容的API规范,/v1/chat/completions 是标准的对话补全路由。这也决定了后续C++代码中HTTP客户端需要支持SSL/TLS加密(即HTTPS),因此引入OpenSSL库是架构设计的必要条件。
SDK的健壮性取决于底层数据结构的设计。在 SDK/include/common.h 中,通过结构体(Struct)对业务实体进行抽象,利用C++标准模板库(STL)管理内存资源。
Message 结构体用于封装对话上下文。
_id:消息唯一标识,用于分布式追踪。_role:区分 user(用户)、assistant(模型)或 system(系统指令)。_content:实际文本载荷。_timestamp:使用 std::time_t 记录时间,便于会话排序与审计。Config 结构体定义了推理参数。
_temperature:双精度浮点数,控制采样随机性。0.7是一个平衡创造性与准确性的典型值。_maxTokens:限制输出长度,防止显存溢出或超长生成。APIConfig 继承自 Config,体现了面向对象设计的'扩展性'。它在基础配置之上增加了 _apiKey,专门用于云端推理场景。这种设计允许未来扩展本地模型配置(如本地模型路径)而不污染基础配置结构。
ModelInfo 结构体存储元数据,包括提供方(Provider)、服务端点(Endpoint)及可用性状态。布尔值 _isAvailable 是连接池健康检查的关键指标。
Session 结构体管理多轮对话的上下文。通过 std::vector<Message> 存储历史消息序列。在发送请求时,通常需要将此向量中的历史记录序列化为JSON数组,连同新问题一并发送,以维持LLM的'记忆'能力。
#pragma once
#include <string>
#include <ctime>
#include <vector>
namespace ai_chat_sdk {
// 消息结构
struct Message {
std::string _id; // 消息 id
std::string _role; // 消息角色
std::string _content; // 消息内容
std::time_t _timestamp;// 消息时间戳
// 构造函数
Message(const std::string& role, const std::string& content)
: _role(role), _content(content) {}
};
// 模型的公共配置信息
struct Config {
std::string _modelName; // 模型名称
double _temperature = 0.7; // 温度参数,用来控制模型的生成随机性,默认值为 0.7
int _maxTokens = 2048; // 最大 token 数,用来控制模型的生成长度,默认值为 2048
};
// 通过 API 方式接入云端模型
struct APIConfig : public Config {
std::string _apiKey; // api key
};
// LLM 模型信息
struct ModelInfo {
std::string _modelName; // 模型名称
std::string _modelDesc; // 模型描述信息
std::string _provider; // 模型提供方
std::string _endpoint; // 模型访问地址 base url
bool _isAvailable = false; // 模型是否可用,默认值为 false
ModelInfo(const std::string& modelName = "",
const std::string& modelDesc = "",
const std::string& provider = "",
const std::string& endpoint = "")
: _modelName(modelName), _modelDesc(modelDesc),
_provider(provider), _endpoint(endpoint) {}
};
// 会话结构
struct Session {
std::string _sessionId; // 会话 id
std::string _modelName; // 模型名称
std::vector<Message> _messages; // 会话消息列表
std::time_t _createAt; // 会话创建时间戳
std::time_t _updateAt; // 会话更新时间戳
// 构造函数
Session(const std::string& modelName = "") : _modelName(modelName) {}
};
} // end ai_chat_sdk
为了支持多种后端(如DeepSeek、ChatGPT、本地Ollama),在 SDK/include/LLMProvider.h 中定义了抽象基类 LLMProvider。这是'依赖倒置原则'的典型应用,上层业务逻辑依赖于抽象接口,而非具体实现。
LLMProvider 声明了纯虚函数(Pure Virtual Functions),强制派生类必须实现这些行为:
initModel:接收 std::map 类型的配置参数,具有极高的灵活性,无需硬编码配置项。sendMessage:同步阻塞式调用,适用于短文本生成。sendMessageStream:流式响应接口。利用 std::function 回调机制,实现Token逐个返回。这对于提升用户体验至关重要,用户无需等待完整生成即可看到首字。值得注意的是,代码中原有的 projected: 访问修饰符应修正为 protected:。这是C++中用于限制成员变量仅对派生类可见的关键字。将 _apiKey 和 _endpoint 设为受保护成员,既保证了封装性,又允许子类直接访问这些基础资源。
#include <string.h>
#include <map>
#include <vector>
#include "common.h"
#include <functional>
namespace kk {
// LLMProvider 类
class LLMProvider {
public:
// 初始化模型
virtual bool initModel(const std::map<std::string, std::string>& modelConfig) = 0;
// 检查模型是否可用
virtual bool isAvailable() const = 0;
// 获取模型名称
virtual std::string getModelName() const = 0;
// 获取模型描述
virtual std::string getModelDesc() const = 0;
// 发送消息 --- 全量返回 非流式响应
virtual std::string sendMessage(const std::vector<Message>& messages,
const std::map<std::string, std::string>& requestParam) = ;
= ;
:
_isAvailable = ;
std::string _apiKey;
std::string _endpoint;
};
}
DeepSeekProvider 类继承自 LLMProvider,具体实现了针对DeepSeek模型的业务逻辑。
在 src/DeepSeekProvider.cpp 中,initModel 函数执行了防御性编程。它首先在传入的 modelConfig 映射中查找 apiKey 和 endpoint。若关键参数缺失,通过宏 ERR 记录错误日志并返回 false,防止系统在配置无效的状态下启动。只有当所有必要参数校验通过后,_isAvailable 标志位才会被置为 true。
getModelName 与 getModelDesc 提供了模型的自描述能力。
虽然提供的代码片段中省略了 sendMessage 的具体HTTP实现(通常涉及 libcurl 或 httplib 的调用、JSON序列化与反序列化),但架构框架已经明确:接收 Message 向量,构建JSON Payload,发起HTTPS POST请求,解析响应中的 choices[0].message.content,并处理可能的网络异常。
#include "../include/DeepSeekProvider.h"
#include "../include/util/myLog.h"
namespace kk {
// 初始化模型
bool DeepSeekProvider::initModel(const std::map<std::string, std::string>& modelConfig) {
// 初始化 API key
auto it = modelConfig.find("apiKey");
if (it == modelConfig.end()) {
ERR("DeepSeekProvider initModel: apiKey not found");
return false;
}
_apiKey = it->second;
// 初始化 endpoint
it = modelConfig.find("endpoint");
if (it == modelConfig.end()) {
ERR("DeepSeekProvider initModel: endpoint not found");
return false;
}
_endpoint = it->second;
_isAvailable = true;
INFO("DeepSeekProvider initModel: success, apiKey: %s, endpoint: %s", _apiKey.c_str(), _endpoint.c_str());
return true;
}
// 检测模型是否可用
bool DeepSeekProvider::isAvailable() const {
return _isAvailable;
}
// 获取模型名称
std::string DeepSeekProvider::getModelName {
;
}
{
;
}
{
;
}
{
;
}
}
软件工程中,未经测试的代码不具备交付价值。本项目引入 Google Test (gtest) 框架进行单元测试。
在 testLLM.cpp 中,测试用例 TEST(DeepSeekProviderTest, sendMessage) 模拟了完整的调用流程。
std::make_shared 创建实例,自动管理生命周期,避免内存泄漏。std::getenv("deepseek_apikey") 从环境变量读取密钥。这是DevOps的最佳实践,严禁将敏感密钥硬编码在源码中。ASSERT_TRUE 验证对象指针有效性及初始化结果。若断言失败,测试立即终止,便于快速定位崩溃点。#include <gtest/gtest.h>
#include "../SDK/include/DeepSeekProvider.h"
#include "../SDK/include/util/myLog.h"
// 测试 DeepSeekProvider 的 initModel 方法
TEST(DeepSeekProviderTest, sendMessage) {
auto Provider = std::make_shared<kk::DeepSeekProvider>();
ASSERT_TRUE(Provider != nullptr);
std::map<std::string, std::string> modelParam;
const char* env_apikey = std::getenv("deepseek_apikey");
modelParam["apiKey"] = env_apikey ? env_apikey : "sk-xxxxxxxxxxxxxxxxxxxxxxxxxx";
modelParam["endpoint"] = "https://api.example.com";
// 实例化 DeepSeekProvider 对象
Provider->initModel(modelParam);
ASSERT_TRUE(Provider->isAvailable());
std::map<std::string, std::string> requestParam = {
{"temperature", "0.5"},
{"max_tokens", "2048"}
};
std::vector<kk::Message> messages;
messages.push_back({"user", "你是谁?"});
// 调用 sendMessage 方法
std::string response = Provider->sendMessage(messages, requestParam);
ASSERT_TRUE(!response.empty());
}
int main(int argc, char** argv) {
// 初始化 spdlog 日志库
kk::Logger::(, , spdlog::level::debug);
(, );
(, , );
testing::(&argc, argv);
();
}
测试入口 main 函数中初始化了 spdlog 日志库。kk::Logger::initLogger 设置了日志级别为 debug,确保在开发阶段能捕获所有交互细节。testing::InitGoogleTest 负责解析命令行参数,驱动测试执行。
#pragma once
#include <spdlog/spdlog.h>
namespace kk {
// 单例模式
class Logger {
public:
// 获取单例实例
static void initLogger(const std::string &loggerName, const std::string &loggerFile,
spdlog::level::level_enum logLevel = spdlog::level::info);
// 获取日志实例
static std::shared_ptr<spdlog::logger> getLogger();
private:
// 构造函数
Logger();
// 删除拷贝构造函数和赋值运算符
Logger(const Logger&) = delete;
Logger& operator=(const Logger&) = delete;
private:
static std::shared_ptr<spdlog::logger> _logger;
static std::mutex _mutex;
};
// 调试日志宏
#define DBG(format, ...) \
kk::Logger::getLogger()->debug("[{:>10s}:{:<4d}] " format, __FILE__, __LINE__, ##__VA_ARGS__)
#define TRACE(format, ...) \
kk::Logger::getLogger()->log(spdlog::level::trace, "[{:>10s}:{:<4d}] " format, __FILE__, __LINE__, ##__VA_ARGS__)
#define INFO(format, ...) \
kk::Logger::getLogger()->info("[{:>10s}:{:<4d}] " format, __FILE__, __LINE__, ##__VA_ARGS__)
#define WARN(format, ...) \
kk::Logger::getLogger()->warn( format, __FILE__, __LINE__, ##__VA_ARGS__)
}
C++项目的构建复杂性通过 CMake 进行管理。CMakeLists.txt 文件定义了编译规则与依赖关系。
项目依赖 OpenSSL 进行HTTPS通信,依赖 spdlog 进行日志记录,依赖 gtest 进行测试,依赖 jsoncpp 处理数据格式。
find_package(OpenSSL REQUIRED) 指令在系统中查找 OpenSSL 库的头文件与二进制文件。若未安装,CMake 配置阶段将直接报错阻断。
# 设置 Cmake 的最小版本为 3.10
cmake_minimum_required(VERSION 3.10)
# 设置项目名称为 testLLM
project(testLLM)
# 设置 C++ 标准为 C++17
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
# 不支持就报错
# 设置构建类型
set(CMAKE_BUILD_TYPE Debug)
# 添加可执行文件
add_executable(testLLM testKKLLM.cpp ../SDK/src/DeepSeekProvider.cpp ../SDK/src/util/myLog.cpp)
# 设置输出目录
set(EXECUTABLE_OUTPUT_PATH ${CMAKE_SOURCE_DIR})
# 添加头文件
include_directories(${CMAKE_PROJECT_INCLUDE_DIR}/ ../sdk/include)
find_package(OpenSSL REQUIRED)
include_directories(${OPENSSL_INCLUDE_DIR})
# 添加 CPPHTTPLIB_OPENSSL_SUPPORT 宏定义
target_compile_definitions(testLLM PRIVATE CPPHTTPLIB_OPENSSL_SUPPORT)
# 链接库
target_link_libraries(testLLM spdlog gtest jsoncpp fmt OpenSSL::Crypto OpenSSL::SSL)
add_executable 指令将源文件 DeepSeekProvider.cpp、myLog.cpp 和测试文件 testKKLLM.cpp 编译为可执行文件 testLLM。
target_link_libraries 将具体的第三方库链接至目标文件。特别注意 OpenSSL::Crypto 和 OpenSSL::SSL 的显式链接,这是实现安全套接层通信的基础。
项目目录结构清晰,遵循了 include (头文件) 与 src (源文件) 分离的标准布局,有利于大型项目的模块化管理。
在 build 目录下执行 cmake ..,CMake 读取上一级目录的配置,生成 Makefile。此步骤成功意味着环境依赖和路径配置均无误。
生成的构建工件包括 Makefile、CMakeCache.txt 等,实现了'外部构建'(Out-of-source build),保持源码目录整洁。
执行 make 命令触发实际编译。在初次尝试中,可能会遇到链接错误或头文件缺失,这通常表现为大量的编译器输出信息。
上图反映了典型的编译期错误。解决此类问题通常需要检查:
include_directories 正确包含。经过调试修正后,再次编译通过。运行 ./testLLM 执行测试程序。
控制台输出显示的绿色 [ PASSED ] 标志表明测试用例执行成功。日志中记录了初始化过程和测试值的输出,验证了 DeepSeekProvider 已正确加载配置,并且能够通过 HTTP 协议与云端 API 建立连接,完成了一次模拟的消息发送流程。
综上所述,构建一个生产级的C++ LLM SDK需要跨越网络协议、内存管理、设计模式与自动化测试等多个技术领域。通过严谨的架构设计与详尽的测试验证,能够确保SDK在复杂的生产环境中稳定运行。

微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
使用加密算法(如AES、TripleDES、Rabbit或RC4)加密和解密文本明文。 在线工具,加密/解密文本在线工具,online
生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online
将 Markdown(GFM)转为 HTML 片段,浏览器内 marked 解析;与 HTML 转 Markdown 互为补充。 在线工具,Markdown 转 HTML在线工具,online