【AI大模型接入SDK】ChatSDK架构设计与实现-171主机测评

🎬 个人主页：艾莉丝努力练剑

❄专栏传送门：《C语言》《数据结构与算法》《C/C++干货分享&学习过程记录》《Linux操作系统编程详解》《笔试/面试常见算法：从基础到进阶》《Python干货分享》

⭐️为天地立心，为生民立命，为往圣继绝学，为万世开太平

🎬 艾莉丝的简介：

在这里插入图片描述

文章目录

1 ~> SDK 基础概念
- 1.1 SDK 定义
- 1.2 SDK 与 API 区别
- 1.3 项目业务背景
2 ~> ChatSDK 整体架构设计
- 2.1 核心设计目标
- 2.2 ChatSDK 类成员分析
- - 2.2.1 对外公开接口（Public）
  - 2.2.2 私有成员变量说明
- 2.3 common.h 公共结构体定义
3 ~> 会话管理相关接口逻辑
- 3.1 createSession 创建会话
- 3.2 getSession 查询会话
- 3.3 getSessionList 获取全部会话 ID
- 3.4 deleteSession 删除会话
4 ~> 消息发送接口逻辑
- 4.1 sendMessage 全量返回消息
- 4.2 sendMessageStream 流式增量消息
5 ~> 模型初始化与可用模型查询
- 5.1 initModels 初始化模型
- 5.2 getAvailableModels 获取可用模型列表
6 ~> 关键约束与易错点
结尾

在这里插入图片描述

1 ~> SDK 基础概念

1.1 SDK 定义

SDK（Software Development Kit，软件开发工具包）：面向开发者的功能工具集合，类比程序员的工具箱，用于快速实现特定业务能力，屏蔽底层复杂实现细节，降低开发接入成本。
SDK 标准组成：
- 库文件：已经实现业务逻辑的编译好的代码，分为静态库（.lib/.a）、动态库（.dll/.so）；开发者通过头文件获知对外暴露的类、函数接口。
- API 接口：SDK 对外暴露调用入口，规定调用参数、返回值，是 SDK 的调用契约。
- 开发文档：接口说明、配置说明、使用约束。
- 示例代码：可直接运行的 Demo，用于快速跑通业务流程。
- 调试工具：辅助定位运行时错误。

1.2 SDK 与 API 区别

特性APISDK

本质	软件之间交互调用的接口 / 一组函数	完整可部署下载的工具包集合
包含关系	API 是 SDK 的组成部分	SDK 包含 API、库、文档、示例、调试工具
使用场景	仅需要调用外部服务接口	完整开发业务应用，需要整套工具链支撑
获取方式	查阅文档即可调用，无需下载	需要下载整套工具包到本地工程

通俗类比：做菜场景

API：菜谱，告诉你食材、步骤，灶台、锅具需要自己准备。
SDK：食材包 + 菜谱 + 锅铲小锅，物料工具全部打包，开箱即可制作。

1.3 项目业务背景

项目原有三大独立模块：

模型管理模块：完成多模型接入，封装与大模型交互逻辑。

会话管理模块：管理聊天会话、会话内历史消息。

数据管理模块：会话、聊天消息持久化存储。

问题：直接对外暴露三大模块，外部使用者需要同时操作三套模块，接入成本高。
解决方案：封装ChatSDK，将模型管理、会话管理、数据管理做上层封装；外部应用仅依赖ChatSDK类即可完成全部聊天业务，不需要感知底层模块细节。

会话管理内部持有数据管理对象，会话管理与数据管理可以视作一个逻辑单元。

2 ~> ChatSDK 整体架构设计

2.1 核心设计目标

整合LLMManager模型管理器、SessionManager会话管理器，对外提供统一简洁接口。
屏蔽底层模型差异、会话存储、持久化细节。
支持多模型配置初始化、会话生命周期管理、普通全量消息返回、流式增量消息回调返回。
交付产物：头文件 + 编译库文件 + SDK 文档 + 使用示例。

2.2 ChatSDK 类成员分析

2.2.1 对外公开接口（Public）

#pragma once
#include "LLMManager.h"
#include "common.h"
#include "SessionManager.h"

#include <memory>
#include <string>
#include <ctime>
#include <vector>
#include <functional>

namespace ai_chat_sdk
{

class ChatSDK
{
public:
/**
* @brief 初始化SDK，加载多个模型配置
* @param configs 多个模型配置智能指针数组，支持API模型、Ollama本地模型
* @return true初始化成功，false失败
*/
bool initModels(const std::vector<std::shared_ptr<Config>>& configs);

/**
* @brief 创建聊天会话
* @param modelName 指定会话绑定的模型名称
* @return 生成唯一sessionId会话标识字符串
*/
std::string createSession(const std::string& modelName);

/**
* @brief 根据sessionId获取会话对象
* @param sessionId 会话唯一ID
* @return 会话智能指针；会话不存在返回空智能指针
*/
std::shared_ptr<Session> getSession(const std::string& sessionId);

/**
* @brief 获取全部会话ID列表
* @return 所有会话id字符串vector
*/
std::vector<std::string> getSessionList();

/**
* @brief 删除指定会话，同时清理内存与持久化存储数据
* @param sessionId 待删除会话ID
* @return true删除成功
*/
bool deleteSession(const std::string& sessionId);

/**
* @brief 获取当前所有可用模型元信息
* @return ModelInfo模型信息数组，用于前端模型选择UI渲染
*/
std::vector<ModelInfo> getAvailableModels();

/**
* @brief 发送消息，全量一次性返回完整模型回复
* @param sessionId 会话ID
* @param message 用户输入消息文本
* @return 模型完整响应字符串
*/
std::string sendMessage(const std::string& sessionId, const std::string& message);

/**
* @brief 发送消息，流式增量返回结果
* @param sessionId 会话ID
* @param message 用户输入消息
* @param callback 回调函数：第一个参数为增量分片文本；第二个bool标记是否是最后分片
*/
void sendMessageStream(const std::string& sessionId, const std::string& message,
std::function<void(const std::string&, bool)> callback);

private:
/// 注册全部模型提供者
void registerLLMProvider(const std::vector<std::shared_ptr<Config>>& configs);
/// 初始化全部模型提供者
void initProviders(const std::vector<std::shared_ptr<Config>> configs);
/// API云端模型初始化（GPT、Gemini等）
bool apiProviderInit(const std::string& modelName, const std::shared_ptr<ApiConfig>& apiConfig);
/// Ollama本地模型初始化
bool ollamaProviderInit(const std::string& modelName, const std::shared_ptr<OllamaConfig>& ollamaConfig);

bool _initialized = false; ///< SDK整体初始化标记
/// key:模型名称 value:模型配置智能指针，保存全部传入模型配置
std::unordered_map<std::string, std::shared_ptr<Config>> _modelConfigs;
LLMManager _llmManager; ///< 模型管理实例，负责和各个大模型provider交互
SessionManager _sessionManager; ///< 会话管理实例，管理会话生命周期与持久化
};

} // namespace ai_chat_sdk

2.2.2 私有成员变量说明

_initialized：布尔标记，记录 ChatSDK 是否初始化完成；执行业务接口前必须校验该标记。
_modelConfigs：哈希表，维护模型名到配置对象的映射，保存全部传入的模型配置，配置包含温度、max_tokens、apikey 等参数。
_llmManager：模型管理器实例，完成底层不同模型 Provider 调度。
_sessionManager：会话管理器实例，管理会话创建、销毁、查询，内部持有 DataManager 做持久化。

2.3 common.h 公共结构体定义

namespace ai_chat_sdk
{
/// 单条聊天消息结构体
struct Message
{
std::string _role; ///< 角色：user / assistant / system
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; ///< 温度，控制生成随机性，越大越随机
int _maxTokens = 2048; ///< 最大输出token数量
};

/// API云端模型配置，继承基础配置，用于OpenAI、Gemini等在线模型
struct ApiConfig : public Config
{
std::string _apiKey; ///< 接口访问密钥
};

/// Ollama本地模型配置，继承Config，本地部署模型使用
struct OllamaConfig : public Config
{
// Ollama服务地址、端口等本地特有配置字段
};

}

3 ~> 会话管理相关接口逻辑

3.1 createSession 创建会话

接收入参：模型名称modelName，绑定该会话使用哪个大模型。

内部调用SessionManager::createSession(modelName)。

会话管理器内部执行流程：

互斥锁保护多线程并发访问会话容器。

调用工具函数生成全局唯一sessionId。

实例化Session会话对象，填充 sessionId、创建时间、更新时间。

将会话存入内存哈希表。

调用DataManager将会话元数据写入持久化存储。

释放互斥锁，返回生成的 sessionId 给上层 ChatSDK。

3.2 getSession 查询会话

根据传入sessionId，从SessionManager获取会话对象智能指针。
会话不存在返回空 shared_ptr，调用方需要判空。

3.3 getSessionList 获取全部会话 ID

不返回完整会话对象，仅返回所有会话 id 字符串数组；业务层拿到 id 后，按需调用 getSession 获取会话详情。

3.4 deleteSession 删除会话

传入 sessionId；内存容器移除会话，同时通知 DataManager 删除持久化存储中该会话以及会话下全部消息记录。

4 ~> 消息发送接口逻辑

4.1 sendMessage 全量返回消息

参数：sessionId 会话 ID，用户输入 message 字符串。

内部处理流程：

通过 sessionId 从 Session 获取该会话绑定的模型名称，读取会话完整历史消息列表。

从_modelConfigs读取该模型预设配置（temperature、max_tokens）。

将用户最新消息追加进会话历史 Message 数组。

将历史消息、模型参数交给对应模型 Provider。

Provider 内部逻辑示例（DeepSeek 参考实现）：

校验模型 Provider 是否可用。
使用模型配置中 temperature、max_tokens 构造请求参数。
将 Message 数组转换为 JSON 数组格式，组装 HTTP 请求 Body。
JSON 序列化，发起 HTTP 请求调用模型接口。
获取模型完整响应，返回字符串。

ChatSDK 拿到模型回复，将 assistant 回复写入会话历史，持久化保存。

返回完整回答字符串给调用方。

4.2 sendMessageStream 流式增量消息

参数：sessionId，用户消息，回调 callback。

callback 回调签名：void(const std::string& chunk, bool isEnd)

chunk：模型返回的增量分片文本；每次回调只返回一小段内容。

isEnd：布尔标记，true 代表流式输出全部完成。

业务逻辑：

同样读取会话历史、模型配置，组装请求。

使用 http 长连接流式读取模型分片结果。

每拿到一块分片，执行外部传入 callback，将分片抛出给上层业务。

流式全部结束后，把完整 assistant 回答写入会话历史并持久化。

5 ~> 模型初始化与可用模型查询

5.1 initModels 初始化模型

入参是std::vector<std::shared_ptr<Config>>，支持传入多个不同模型配置（ApiConfig/OllamaConfig）。
ChatSDK 内部：
- 将配置存入_modelConfigs哈希表。
- 根据配置实际类型（API/ Ollama）分发调用apiProviderInit / ollamaProviderInit。
- 完成各个 LLM Provider 注册到LLMManager。
- 全部模型初始化完成后设置_initialized=true；任一关键模型初始化失败返回 false。

5.2 getAvailableModels 获取可用模型列表

返回std::vector<ModelInfo>模型元信息数组。
业务场景：前端 UI 渲染模型选择界面，展示模型名称、描述、能力标签（多轮对话、代码生成、问答等）。
当前项目已接入模型：
- deepseek‑r1:70b（本地部署）
- gemini‑2.0‑flash（云端 API）
- gpt‑4o‑mini（云端 API）
- deepseek‑chat（云端 API）
- deepseek‑r1:1.5b（Ollama 本地）

6 ~> 关键约束与易错点

线程安全：SessionManager 内部会话增删查改必须加互斥锁；多线程并发调用 ChatSDK 接口，会话容器存在竞态条件风险。

配置继承区分：ApiConfig、OllamaConfig继承基础Config；初始化需要 RTTI 识别实际配置类型，区分云端 API 模型与本地 Ollama 模型初始化逻辑。

会话‑模型绑定：每个 session 创建时绑定一个固定 modelName；同一个会话全程使用该模型，不允许中途切换模型。

持久化联动：会话增删、消息新增，内存操作完成的同时，必须同步调用 DataManager 写入持久化存储，内存和磁盘数据需要保持一致。

初始化状态校验：所有对外业务接口执行前，必须校验_initialized标记，SDK 未初始化直接调用接口直接返回错误。

流式回调注意点：callback 回调执行于网络 IO 线程；上层业务如果操作 UI，需要自行做线程切换，禁止在回调内部做阻塞耗时操作。

参数来源： temperature、max_tokens 优先取自模型初始化 Config 配置，不需要上层每次发消息重复传入。

结尾

uu们，本文的内容到这里就全部结束了，艾莉丝在这里再次感谢您的阅读！

艾莉丝努力练剑

C/C++ & Linux 底层探索者 | 一个正在努力练剑的技术博主

👀
【关注】 跟随我一起深耕技术领域，见证每一次成长。

❤️
【点赞】 让优质内容被更多人看见，让知识传递更有力量。

⭐
【收藏】 把核心知识点存好，在需要时随时查、随时用。

💬
【评论】 分享你的经验或疑问，评论区一起交流避坑！

不要忘记给博主“一键四连”哦！

“今日练剑达成！”

“技术之路难免有困惑，但同行的人会让前进更有方向。”

结语：希望对学习Linux相关内容的uu有所帮助，不要忘记给博主“一键四连”哦！

往期回顾：

【AI大模型接入SDK】session管理和数据管理结合

🗡博主在这里放了一只小狗，大家看完了摸摸小狗放松一下吧！🗡

૮₍ ˶ ˊ ᴥ ˋ˶₎ა

在这里插入图片描述

【AI大模型接入SDK】ChatSDK架构设计与实现

文章目录