项目架构说明

一、项目概述

本项目是一个基于 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 测试程序编译配置
# 数据库 # 服务器 # c++ # linux # 网络
Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

cover

四天蒸发近2000亿，宇树科技股价近乎“腰斩”；苹果举办库克告别派对：9月1日正式卸任CEO；Anthropic两款新Claude模型曝光 | 极客头条

avatar AI编程社区
cover

Claude Code反超GitHub Copilot登顶第一、90%程序员已用上Agent，最新AI编码调查报告来了

avatar AI编程社区
cover

如何用好 Claude Code 写后端代码

avatar AI编程社区