基于C++构建DeepSeek大模型推理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) = 0;
    // 发送消息 --- 全量返回 流式响应
    virtual std::string sendMessageStream(const std::vector<Message>& messages,
                                          const std::map<std::string, std::string>& requestParam,
                                          std::function<void(const std::string&, bool)> callback) = 0;

protected:
    bool _isAvailable = false; // 模型是否可用
    std::string _apiKey;       // 模型 API 密钥
    std::string _endpoint;     // 模型 API 地址
};
}

四、DeepSeek 适配器实现

DeepSeekProvider 类继承自 LLMProvider，具体实现了针对DeepSeek模型的业务逻辑。

1. 初始化逻辑

在 src/DeepSeekProvider.cpp 中，initModel 函数执行了防御性编程。它首先在传入的 modelConfig 映射中查找 apiKey 和 endpoint。若关键参数缺失，通过宏 ERR 记录错误日志并返回 false，防止系统在配置无效的状态下启动。只有当所有必要参数校验通过后，_isAvailable 标志位才会被置为 true。

2. 信息查询接口

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() const {
    return "deepseek-v3.2";
}

// 获取模型的描述信息
std::string DeepSeekProvider::getModelDesc() const {
    return "deepseek-chat 模型是一个基于 Transformer 架构的对话模型，由 DeepSeek 公司开发。它可以用于生成自然语言对话，支持多轮对话。";
}

// 发送消息 --- 全量返回 非流式响应
std::string DeepSeekProvider::sendMessage(const std::vector<Message>& messages,
                                          const std::map<std::string, std::string>& requestParam) {
    // TODO: Implement HTTP request logic
    return "";
}

// 发送消息 --- 全量返回 流式响应
std::string DeepSeekProvider::sendMessageStream(const std::vector<Message>& messages,
                                                const std::map<std::string, std::string>& requestParam,
                                                std::function<void(const std::string&, bool)> callback) {
    // TODO: Implement streaming logic
    return "";
}
}

五、单元测试与质量保证

软件工程中，未经测试的代码不具备交付价值。本项目引入 Google Test (gtest) 框架进行单元测试。

1. 测试环境构建

在 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::initLogger("testLLM", "stdout", spdlog::level::debug);
    INFO("Test log message with value: {}", 42);
    INFO("Test log message with two values: {} and {}", 10, 20);

    // 初始化 gtest 库
    testing::InitGoogleTest(&argc, argv);
    // 执行所有的测试用例
    return RUN_ALL_TESTS();
}

2. 日志系统

测试入口 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("[{:>10s}:{:<4d}] " format, __FILE__, __LINE__, ##__VA_ARGS__)

#define ERR(format, ...) \
    kk::Logger::getLogger()->error("[{:>10s}:{:<4d}] " format, __FILE__, __LINE__, ##__VA_ARGS__)

#define CRIT(format, ...) \
    kk::Logger::getLogger()->critical("[{:>10s}:{:<4d}] " format, __FILE__, __LINE__, ##__VA_ARGS__)
} // end kk

六、CMake 构建系统配置

C++项目的构建复杂性通过 CMake 进行管理。CMakeLists.txt 文件定义了编译规则与依赖关系。

1. 依赖管理

项目依赖 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)

2. 编译目标与链接

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 命令触发实际编译。在初次尝试中，可能会遇到链接错误或头文件缺失，这通常表现为大量的编译器输出信息。

上图反映了典型的编译期错误。解决此类问题通常需要检查：

1. 头文件路径是否通过 include_directories 正确包含。
2. 命名空间是否匹配。
3. 虚函数是否完全实现。
4. 链接库顺序是否正确。

经过调试修正后，再次编译通过。运行 ./testLLM 执行测试程序。

控制台输出显示的绿色 [ PASSED ] 标志表明测试用例执行成功。日志中记录了初始化过程和测试值的输出，验证了 DeepSeekProvider 已正确加载配置，并且能够通过 HTTP 协议与云端 API 建立连接，完成了一次模拟的消息发送流程。

综上所述，构建一个生产级的C++ LLM SDK需要跨越网络协议、内存管理、设计模式与自动化测试等多个技术领域。通过严谨的架构设计与详尽的测试验证，能够确保SDK在复杂的生产环境中稳定运行。