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

艾莉丝努力练剑2026-09-28 14:38

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

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

🎬 艾莉丝的简介：

文章目录

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

1 ~> SDK 基础概念

1.1 SDK 定义

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

1.2 SDK 与 API 区别

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

通俗类比：做菜场景

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

1.3 项目业务背景

项目原有三大独立模块：

  1. 模型管理模块：完成多模型接入，封装与大模型交互逻辑。
  2. 会话管理模块：管理聊天会话、会话内历史消息。
  3. 数据管理模块：会话、聊天消息持久化存储。
  • 问题：直接对外暴露三大模块，外部使用者需要同时操作三套模块，接入成本高。
  • 解决方案：封装ChatSDK，将模型管理、会话管理、数据管理做上层封装；外部应用仅依赖ChatSDK类即可完成全部聊天业务，不需要感知底层模块细节。

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

2 ~> ChatSDK 整体架构设计

2.1 核心设计目标

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

2.2 ChatSDK 类成员分析

2.2.1 对外公开接口（Public）

cpp 复制代码 
#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 公共结构体定义

cpp 复制代码 
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 创建会话

  1. 接收入参：模型名称modelName，绑定该会话使用哪个大模型。
  2. 内部调用SessionManager::createSession(modelName)。
  3. 会话管理器内部执行流程：
    1. 互斥锁保护多线程并发访问会话容器。
    2. 调用工具函数生成全局唯一sessionId。
    3. 实例化Session会话对象，填充 sessionId、创建时间、更新时间。
    4. 将会话存入内存哈希表。
    5. 调用DataManager将会话元数据写入持久化存储。
    6. 释放互斥锁，返回生成的 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 全量返回消息

  1. 参数：sessionId 会话 ID，用户输入 message 字符串。
  2. 内部处理流程：
    1. 通过 sessionId 从 Session 获取该会话绑定的模型名称，读取会话完整历史消息列表。
    2. 从_modelConfigs读取该模型预设配置（temperature、max_tokens）。
    3. 将用户最新消息追加进会话历史 Message 数组。
    4. 将历史消息、模型参数交给对应模型 Provider。
    5. Provider 内部逻辑示例（DeepSeek 参考实现）：
      • 校验模型 Provider 是否可用。
      • 使用模型配置中 temperature、max_tokens 构造请求参数。
      • 将 Message 数组转换为 JSON 数组格式，组装 HTTP 请求 Body。
      • JSON 序列化，发起 HTTP 请求调用模型接口。
      • 获取模型完整响应，返回字符串。
    6. ChatSDK 拿到模型回复，将 assistant 回复写入会话历史，持久化保存。
    7. 返回完整回答字符串给调用方。

4.2 sendMessageStream 流式增量消息

  1. 参数：sessionId，用户消息，回调 callback。
  2. callback 回调签名：void(const std::string& chunk, bool isEnd)
    1. chunk：模型返回的增量分片文本；每次回调只返回一小段内容。
    2. isEnd：布尔标记，true 代表流式输出全部完成。
  3. 业务逻辑：
    1. 同样读取会话历史、模型配置，组装请求。
    2. 使用 http 长连接流式读取模型分片结果。
    3. 每拿到一块分片，执行外部传入 callback，将分片抛出给上层业务。
    4. 流式全部结束后，把完整 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 ~> 关键约束与易错点

  1. 线程安全：SessionManager 内部会话增删查改必须加互斥锁；多线程并发调用 ChatSDK 接口，会话容器存在竞态条件风险。
  2. 配置继承区分 ：ApiConfig、OllamaConfig继承基础Config；初始化需要 RTTI 识别实际配置类型，区分云端 API 模型与本地 Ollama 模型初始化逻辑。
  3. 会话‑模型绑定：每个 session 创建时绑定一个固定 modelName；同一个会话全程使用该模型，不允许中途切换模型。
  4. 持久化联动：会话增删、消息新增，内存操作完成的同时，必须同步调用 DataManager 写入持久化存储，内存和磁盘数据需要保持一致。
  5. 初始化状态校验 ：所有对外业务接口执行前，必须校验_initialized标记，SDK 未初始化直接调用接口直接返回错误。
  6. 流式回调注意点：callback 回调执行于网络 IO 线程；上层业务如果操作 UI，需要自行做线程切换，禁止在回调内部做阻塞耗时操作。
  7. 参数来源： temperature、max_tokens 优先取自模型初始化 Config 配置，不需要上层每次发消息重复传入。

结尾

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

|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ### 艾莉丝努力练剑 C/C++ & Linux 底层探索者 | 一个正在努力练剑的技术博主 *** ** * ** *** 👀 【关注】 跟随我一起深耕技术领域，见证每一次成长。 ❤️ 【点赞】 让优质内容被更多人看见，让知识传递更有力量。 ⭐ 【收藏】 把核心知识点存好，在需要时随时查、随时用。 💬 【评论】 分享你的经验或疑问，评论区一起交流避坑！ 不要忘记给博主"一键四连"哦！ "今日练剑达成！" "技术之路难免有困惑，但同行的人会让前进更有方向。" |

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

往期回顾：

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

🗡博主在这里放了一只小狗，大家看完了摸摸小狗放松一下吧！🗡 ૮₍ ˶ ˊ ᴥ ˋ˶₎ა

相关推荐
Data-Miner1 小时前
做表格数据分析的AI工具怎么选？先对一下这三个真实需求，再看哪些真能落地
人工智能·数据分析·excel
重生之小比特1 小时前
【C++进阶】红黑树的实现
java·开发语言·c++
纪念 2291 小时前
C++算法（一）
开发语言·c++·算法
闭包不眠1 小时前
网站支持HEIC上传要多大解码器？gzip后510KB
图像处理·人工智能·计算机视觉
Leo.yuan1 小时前
从 DataX 到 Informatica，再到国产一体化平台：2026 年企业数据集成平台怎么选
人工智能
All for pursuit.1 小时前
【二叉树-10】114.二叉树展开为链表
数据结构·c++·算法·leetcode·链表
叠层归一研究院1 小时前
区分预算与通道诱导：Ω–L叠层体系的观测赋值与定量验证
人工智能·算法
多弗朗皮卡丘1 小时前
C++string类
c++
知几蜗牛2 小时前
AI权限写进JSON就安全了吗？真正缺的是配置生效验证
人工智能
热门推荐
01Telegram APK 下载安装完整指南 — 2026年最新02国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）03GitHub 镜像站点04历年考研数学一、数学二、数学三真题试卷及答案PDF052026 爱知・名古屋亚运会怎么看？直播平台+赛程安排分享06蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接07给AI一张“业务概念地图“：本体如何从哲学走向企业智能08微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新092026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？10jev-ultrafast 深度解析：7 秒订机票的浏览器 Agent 是如何炼成的