AI 大模型接入 SDK —项目概述

hehelm2026-07-18 11:20

项目架构说明

一、项目概述

本项目是一个基于 C++17 的 AI 大模型接入 SDK，同时附带 HTTP 聊天服务器和单元测试模块。整体采用三层架构设计：

  • SDK 层：提供模型管理、会话管理、数据持久化等核心能力
  • 服务层：基于 HTTP 协议对外暴露 RESTful API
  • 测试层：基于 gtest 的功能验证

二、整体架构

复制代码 
┌─────────────────────────────────────────────────────────────┐
│                      测试层 (test_sdk/)                      │
│  test_LLM.cpp ──▶ SDK 所有头文件                             │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      服务层 (ChatServer/)                    │
│  main.cpp ──▶ ChatServer.h ──▶ ChatSDK.h (SDK)              │
│       │                                                      │
│       └──▶ gflags / httplib / spdlog / jsoncpp              │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                        SDK 层 (sdk/)                         │
│                                                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │ ChatGPT  │  │DeepSeek  │  │ Gemini   │  │ Ollama   │    │
│  │ Provider │  │ Provider │  │ Provider │  │ Provider │    │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘    │
│       │             │             │             │           │
│       └─────────────┴──────┬──────┴─────────────┘           │
│                            ▼                                │
│                    ┌──────────────┐                         │
│                    │ LLMProvider  │  (抽象接口)              │
│                    └──────┬───────┘                         │
│                           │                                 │
│                           ▼                                 │
│                    ┌──────────────┐                         │
│                    │  LLMManager  │  (模型管理)             │
│                    └──────┬───────┘                         │
│                           │                                 │
│                           ▼                                 │
│                    ┌──────────────┐                         │
│                    │   ChatSDK    │  (SDK 入口)             │
│                    └──────┬───────┘                         │
│                           │                                 │
│              ┌────────────┴────────────┐                    │
│              ▼                         ▼                    │
│    ┌─────────────────┐      ┌─────────────────┐            │
│    │ SessionManager  │──▶   │  DataManager    │            │
│    └─────────────────┘      └─────────────────┘            │
│                                                              │
│  ┌────────────────────────────────────────────────────┐    │
│  │ common.h / myLog.h  (基础工具，被全模块依赖)        │    │
│  └────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

三、模块详解与文件关系

3.1 SDK 层 (sdk/)

SDK 层是项目的核心，对外提供统一的模型调用接口，对内管理多个 LLM 提供者、会话和持久化数据。

3.1.1 基础数据结构 (common.h)

文件 ：include/common.h

定义了项目中的核心数据结构，被 SDK 内几乎所有模块引用：

结构体 说明 被引用方
Message 单条聊天消息（角色、内容、时间戳） LLMProvider、SessionManager、DataManager、所有 Provider 实现
Config 模型配置基类（模型名、温度、最大 token） ChatSDK、ApiConfig、OllamaConfig
ApiConfig 云端 API 模型配置（继承 Config，增加 API Key） ChatSDK、main.cpp
OllamaConfig Ollama 本地模型配置（继承 Config，增加端点信息） ChatSDK、main.cpp
ModelInfo 模型元信息（名称、描述、可用性） LLMManager、ChatServer
Session 会话信息（ID、模型名、消息列表、时间戳） SessionManager、DataManager、ChatServer
3.1.2 LLM 提供者抽象层

文件 ：include/LLMProvider.h

定义了所有模型提供者的统一接口（策略模式中的 Strategy 接口），包含：

  • 模型初始化与可用性检测
  • 全量消息发送
  • 流式消息发送（回调方式）

实现类：

实现文件 头文件 模型 API 端点
src/ChatGPTProvider.cpp include/ChatGPTProvider.h gpt-4o-mini https://api.openai.com
src/DeepSeekProvider.cpp include/DeepSeekProvider.h deepseek-chat https://api.deepseek.com
src/GeminiProvider.cpp include/GeminiProvider.h gemini-2.0-flash https://generativelanguage.googleapis.com
src/OllamaLLMProvider.cpp include/OllamaLLMProvider.h Ollama 本地模型 用户自定义

依赖关系：

复制代码 
ChatGPTProvider.h      DeepSeekProvider.h      GeminiProvider.h      OllamaLLMProvider.h
        │                      │                      │                      │
        └──────────────────────┴──────────┬───────────┴──────────────────────┘
                                          │
                                          ▼
                                include/LLMProvider.h
                                          │
                                          ▼
                                include/common.h
3.1.3 模型管理器 (LLMManager)

文件 ：include/LLMManager.h / src/LLMManager.cpp

职责：

  • 注册 LLMProvider 实例（registerProvider）
  • 初始化指定模型（initModel）
  • 路由消息到对应 Provider（sendMessage / sendMessageStream）
  • 维护模型可用性状态

依赖关系：

复制代码 
LLMManager.h ──▶ LLMProvider.h ──▶ common.h
       │
       ▼
LLMManager.cpp ──▶ LLMManager.h + myLog.h + common.h

内部持有 std::map<std::string, std::unique_ptr<LLMProvider>>，以模型名称为键管理多个提供者。

3.1.4 会话管理器 (SessionManager)

文件 ：include/SessionManager.h / src/SessionManager.cpp

职责：

  • 创建、获取、删除会话
  • 管理会话消息历史
  • 线程安全的会话操作（使用 std::mutex）
  • 持久化会话数据（委托 DataManager）

依赖关系：

复制代码 
SessionManager.h ──▶ common.h + DataManager.h
         │
         ▼
DataManager.h ──▶ common.h + sqlite3.h
3.1.5 数据管理器 (DataManager)

文件 ：include/DataManager.h / src/DataManager.cpp

职责：

  • 封装 SQLite3 数据库操作
  • 提供 Session 和 Message 的增删改查
  • 线程安全的数据库访问（使用 std::mutex）

依赖关系 ：直接依赖 common.h 和 sqlite3.h。

3.1.6 SDK 入口 (ChatSDK)

文件 ：include/ChatSDK.h / src/ChatSDK.cpp

职责：

  • 对外暴露的统一 SDK 接口
  • 注册并初始化所有模型提供者
  • 管理会话生命周期
  • 封装消息发送逻辑（全量/流式）

内部组合关系：

复制代码 
ChatSDK
 ├── LLMManager      (模型管理)
 ├── SessionManager  (会话管理，内含 DataManager)
 └── Config 映射     (模型配置缓存)

依赖关系：

复制代码 
ChatSDK.cpp ──▶ ChatSDK.h
         │
         ├──▶ DeepSeekProvider.h
         ├──▶ ChatGPTProvider.h
         ├──▶ GeminiProvider.h
         └──▶ OllamaLLMProvider.h
3.1.7 日志工具 (myLog)

文件 ：include/util/myLog.h / src/util/myLog.cpp

职责：

  • 基于 spdlog 的单例日志封装
  • 提供 TRACE / DBG / INFO / WARN / ERR / CRIT 宏
  • 所有 SDK 模块均依赖此日志工具

依赖关系 ：被 ChatSDK、LLMManager、所有 Provider 实现、DataManager、SessionManager 引用。

3.1.8 SDK 层完整依赖图
复制代码 
                      ┌─────────────┐
                      │  myLog.h    │
                      └──────┬──────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
        ▼                    ▼                    ▼
  ┌──────────┐       ┌──────────┐       ┌──────────────┐
  │ common.h │◀──────│LLMProvider│◀──────│ ChatSDK.h    │
  └────┬─────┘       └────┬─────┘       └──────┬───────┘
       │                  │                    │
       │        ┌─────────┴─────────┐         │
       │        │                   │         │
       │        ▼                   ▼         │
       │   ┌──────────┐      ┌──────────┐    │
       │   │DeepSeek  │      │ChatGPT   │    │
       │   │Provider  │      │Provider  │    │
       │   └──────────┘      └──────────┘    │
       │   ┌──────────┐      ┌──────────┐    │
       │   │ Gemini   │      │ Ollama   │    │
       │   │Provider  │      │Provider  │    │
       │   └──────────┘      └──────────┘    │
       │                                     │
       ▼                                     ▼
  ┌──────────────┐                    ┌──────────────┐
  │DataManager.h │◀───────────────────│SessionManager│
  └──────────────┘                    └──────────────┘
                                             │
                                             │ (组合)
                                             ▼
                                       ┌──────────┐
                                       │ ChatSDK  │
                                       └──────────┘

3.2 服务层 (ChatServer/)

服务层基于 cpp-httplib 构建 HTTP 服务器，将 SDK 能力以 RESTful API 形式暴露。

3.2.1 HTTP 服务器 (ChatServer)

文件 ：ChatServer.h / ChatServer.cpp

职责：

  • 初始化 ChatSDK 并配置模型
  • 注册 HTTP 路由（7 个接口）
  • 处理全量/流式消息请求
  • 托管静态前端页面

内部依赖：

复制代码 
ChatServer.cpp ──▶ ChatServer.h
         │
         ├──▶ httplib.h  (HTTP 服务器库)
         ├──▶ ChatSDK.h  (SDK 入口)
         └──▶ jsoncpp    (请求/响应 JSON 处理)
3.2.2 程序入口 (main.cpp)

文件 ：main.cpp

职责：

  • 使用 gflags 解析命令行参数和配置文件
  • 从环境变量读取 API 密钥
  • 参数验证与日志初始化
  • 创建并启动 ChatServer

依赖关系：

复制代码 
main.cpp ──▶ ChatServer.h ──▶ ChatSDK.h (SDK)
     │
     ├──▶ gflags/gflags.h   (参数解析)
     ├──▶ spdlog            (日志级别设置)
     └──▶ ai_chat_sdk/util/myLog.h
3.2.3 前端页面 (www/)

文件 ：build/www/index.html、script.js、styles.css

职责：提供聊天交互的 Web UI，通过 HTTP API 与服务器通信。

注意：ChatServer 中通过硬编码路径挂载静态资源。

3.3 测试层 (test_sdk/)

文件 ：test_LLM.cpp / CMakeLists.txt

职责：

  • 使用 gtest 框架对 SDK 各模块进行单元测试
  • 包含各 Provider 的独立测试（目前被 #if 0 注释）
  • 包含 ChatSDK 的集成测试

依赖关系：

复制代码 
test_LLM.cpp ──▶ 所有 SDK 头文件 + gtest/gtest.h

四、跨层依赖关系

4.1 层间依赖方向

复制代码 
test_sdk/  ──▶  sdk/  ◀────  ChatServer/
   (测试)        (核心)       (服务)
  • SDK 层不依赖上层，可被独立编译为静态库
  • 服务层依赖 SDK 层提供的头文件和静态库
  • 测试层依赖 SDK 层的头文件和实现

4.2 第三方库依赖

第三方库 使用模块 用途
cpp-httplib 所有 Provider、ChatServer HTTP 客户端/服务器
jsoncpp 所有 Provider、ChatServer、test_sdk JSON 序列化/反序列化
spdlog 全项目（通过 myLog） 日志输出
sqlite3 DataManager、SessionManager 数据持久化
OpenSSL 全项目（编译宏 CPPHTTPLIB_OPENSSL_SUPPORT） HTTPS 支持
gflags ChatServer/main.cpp 命令行参数解析
gtest test_sdk 单元测试

4.3 文件引用路径关系

头文件搜索路径：

复制代码 
SDK 层编译：
  -I sdk/include
  -I /usr/local/include (系统安装路径)

ChatServer 编译：
  -I ../sdk/include
  -I ../sdk/util/include
  -L /usr/local/lib

test_sdk 编译：
  -I ../sdk/include

静态库链接：

复制代码 
ChatServer ──link──▶ ai_chat_sdk.a (SDK 静态库)

五、核心设计模式

模式 应用场景 涉及文件
策略模式 不同模型提供者实现统一的 LLMProvider 接口 LLMProvider.h + 四个 Provider 实现
单例模式 全局唯一的日志实例 myLog.h
工厂模式 ChatSDK 根据配置创建对应的 Provider 实例 ChatSDK.cpp
组合模式 ChatSDK 组合 LLMManager 和 SessionManager ChatSDK.h

六、数据流向总结

6.1 消息发送（全量模式）

复制代码 
用户调用
   │
   ▼
ChatSDK::sendMessage(sessionId, message)
   │
   ├──▶ SessionManager::addMessage()      (保存用户消息)
   ├──▶ SessionManager::getHistoryMessages() (获取历史)
   │
   ▼
LLMManager::sendMessage(modelName, messages, params)
   │
   ▼
[ChatGPT|DeepSeek|Gemini|Ollama]Provider::sendMessage()
   │
   ▼
HTTP POST ──▶ 模型 API 服务端
   │
   ▼
JSON 响应解析
   │
   ▼
返回 assistant 回复
   │
   ▼
SessionManager::addMessage()             (保存回复)
SessionManager::updateSessionTimestamp() (更新时间)

6.2 消息发送（流式模式）

复制代码 
用户调用
   │
   ▼
ChatSDK::sendMessageStream(sessionId, message, callback)
   │
   ├──▶ SessionManager::addMessage()      (保存用户消息)
   ├──▶ SessionManager::getHistoryMessages() (获取历史)
   │
   ▼
LLMManager::sendMessageStream(modelName, messages, params, callback)
   │
   ▼
Provider::sendMessageStream() ──▶ HTTP POST (stream=true)
   │
   ▼
逐块接收响应 ──▶ 回调 callback(chunk, isLast)
   │
   ▼
流结束，聚合完整回复
   │
   ▼
SessionManager::addMessage()             (保存完整回复)

七、文件索引

SDK 层头文件

文件路径 职责
sdk/include/common.h 公共数据结构定义
sdk/include/LLMProvider.h LLM 提供者抽象接口
sdk/include/ChatGPTProvider.h ChatGPT 模型接口声明
sdk/include/DeepSeekProvider.h DeepSeek 模型接口声明
sdk/include/GeminiProvider.h Gemini 模型接口声明
sdk/include/OllamaLLMProvider.h Ollama 模型接口声明
sdk/include/LLMManager.h 模型管理器
sdk/include/ChatSDK.h SDK 主入口
sdk/include/SessionManager.h 会话管理器
sdk/include/DataManager.h 数据持久化管理器
sdk/include/util/myLog.h 日志工具

SDK 层源文件

文件路径 职责
sdk/src/ChatGPTProvider.cpp ChatGPT API 调用实现
sdk/src/DeepSeekProvider.cpp DeepSeek API 调用实现
sdk/src/GeminiProvider.cpp Gemini API 调用实现
sdk/src/OllamaLLMProvider.cpp Ollama API 调用实现
sdk/src/LLMManager.cpp 模型注册与路由实现
sdk/src/ChatSDK.cpp SDK 初始化与消息发送实现
sdk/src/SessionManager.cpp 会话生命周期管理实现
sdk/src/DataManager.cpp SQLite 数据库操作实现
sdk/src/util/myLog.cpp 日志初始化实现

服务层文件

文件路径 职责
ChatServer/ChatServer.h HTTP 服务器类定义
ChatServer/ChatServer.cpp HTTP 路由与请求处理
ChatServer/main.cpp 程序入口与配置解析
ChatServer/build/www/index.html 前端页面
ChatServer/build/www/script.js 前端交互逻辑
ChatServer/build/www/styles.css 前端样式

测试层文件

文件路径 职责
test_sdk/test_LLM.cpp 单元测试用例
test_sdk/test_SQLite3/test_sqlite3.cpp SQLite 基础测试

构建文件

文件路径 职责
sdk/CMakeLists.txt SDK 静态库编译配置
ChatServer/CMakeLists.txt ChatServer 可执行文件编译配置
test_sdk/CMakeLists.txt 测试程序编译配置
相关推荐
mounter6251 小时前
跨越鸿沟：从内核驱动开发到超大规模云端生产环境的思考
linux·驱动开发·linux kernel·kernel
国科安芯1 小时前
抗辐射微控制器在卫星电源管理分系统中的控制架构与可靠性研究——基于AS32S601型MCU的星载能源系统智能化管理技术分析
网络·单片机·嵌入式硬件·安全·架构·系统架构·能源
Database_Cool_1 小时前
阿里云 Lindorm vs Elasticsearch 检索存储一体对比：多模数据库一站式方案首选
数据库·阿里云
大郭鹏宇2 小时前
下篇：LangChain Agent 智能体从入门到实战（二）—— 记忆管理、中间件与最佳实践
网络·数据库·人工智能
Fnetlink12 小时前
Fnet 云网安 260717
网络·安全·网络安全
kdxiaojie2 小时前
Linux 驱动研究 —— V4L2 （3）
linux·运维·笔记·学习
facaixxx20242 小时前
雨云游戏服务器MCSM面板指南：低延迟BGP线路（一键开服）
运维·服务器·游戏
数行拙笔2 小时前
Redis---set类型
数据库·redis·缓存
小白学大数据2 小时前
企业内网场景下 Python 自定义 CA 证书信任链的正确配置方法
开发语言·网络·python·信任链
热门推荐
012026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片02GitHub 镜像站点03AI科技热点日报 | 2026年07月01日04幻兽帕鲁 - 服务器管理员权限与 GM 命令完全指南05AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路06国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）072026年AI技术突破与产业落地全景：从GPT-5到多模态智能体的新纪元082026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？09Codex 下载安装指南：Windows 和 macOS 官方版下载102026 年 AI 大模型 & AI 编程工具实战全总结