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 测试程序编译配置
相关推荐
hz5678932 分钟前
涉密视频会议设备配置指南：终端、音视频采集与配套设施选型
服务器·网络·数据库·安全·实时音视频·信息与通信·智能硬件
广州浮点FLOATLIC37 分钟前
许可证服务器迁移后软件打不开：研发 IT 怎样定位连接问题
linux·服务器·数据库
程序员Sunday39 分钟前
MySQL 为什么使用 B+ 树索引？把范围查询、回表和覆盖索引连起来
数据库·mysql
优橙教育42 分钟前
零基础学AI应用开发要多久？3个月能到什么水平
服务器·开发语言·网络·php
BLUcoding1 小时前
接口服务公网超时排查记录：SecureRandom 阻塞问题分析与解决
java·linux·springboot·aes·securerandom
半杯咖啡半行码1 小时前
Qt开发实战：数据库、MV 模式、QProcess与串口通信全攻略
数据库·qt
AIgorithmGEEK1 小时前
[Linux]从手写报头到内核套路：序列化、反序列化与自定义协议全链路
linux·运维·服务器·网络·序列化·反序列化
Nil2081 小时前
leetcode 139单词拆分
linux·运维·服务器
Starry-sky(jing)1 小时前
BUG: unable to handle kernel paging request 完整排查：dmesg 四要素与三路定罪
linux·运维·服务器·内核·排障
mounter6251 小时前
从硬件互连到操作系统变革：CXL 技术演进与 Linux 内核工程挑战
linux·运维·服务器
热门推荐
01如何新建文件夹？ 电脑新建文件夹的4种方法02历年考研数学一、数学二、数学三真题试卷及答案PDF03国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）04GitHub 镜像站点05蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接06轻量化AI渗透武器库｜ARTEX自主攻防系统、资产梳理、漏洞挖掘、链路分析全流程智能化落地07Windows 10/11 如何退出微软账户并改用本地账户登录（含找不到选项的解决方法）08Telegram APK 下载安装完整指南 — 2026年最新09微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新10「全语录+省流版」邵艾伦 × 孙宇晨：聊风口、聊个人IP、聊年轻人如何抓住 AI 时代的机会