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

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

---

🎬 艾莉丝的简介：

---

---

---

ChatSDK 知识体系

一、ChatSDK 基础概述

• 定位：C++17 实现的大模型接入静态库，封装 HTTP 请求、会话管理、持久化底层逻辑
• 支持模型：云端（DeepSeek、GPT-4o、Gemini）、本地（Ollama DeepSeek R1）
• 核心能力：多轮对话、流式 / 非流式响应、会话全生命周期管理、SQLite 数据持久化
• 依赖栈：OpenSSL、fmt、jsoncpp、spdlog、gflags、sqlite3

二、SDK 部署流程

• 源码获取：Git 克隆官方仓库
• 构建生成：CMake 生成 Makefile + Make 编译生成静态库
• 系统安装：头文件与静态库安装至系统标准目录

三、核心类层次体系

• 顶层入口类：ChatSDK（统一对外接口）
• 管理层
  • LLMManager：模型实例管理
  • SessionManager：会话生命周期管理
  • DataManager：SQLite 持久化数据管理
• 配置层
  • 基类：Config
  • 派生：ApiConfig（云端模型）、OllamaConfig（本地模型）
• 数据实体：Session、ModelInfo、Message
• 提供者层（多态实现）
  • 基类：LLMProvider
  • 派生：DeepSeekProvider、ChatGPTProvider、GeminiProvider、OllamaDeepSeekProvider

四、核心 API 能力集

• 模型初始化：initModels
• 会话管理：createSession、getSession、getSessionList、deleteSession
• 消息交互：sendMessage（同步非流式）、sendMessageStream（异步流式）
• 元信息查询：getAvailableModels

五、项目集成规范

• 头文件引入路径
• CMake 链接配置规则
• 日志库前置初始化要求

六、常见踩坑与排错

• 日志未初始化导致段错误
• 头文件大小写不一致
• 系统依赖库缺失
• API Key 环境变量未配置
• CMake 源文件名不匹配

---

1 ~> ChatSDK 基础概述

1.1 产品定位

ChatSDK 是基于 C++ 语言封装的大模型接入开发库，屏蔽了不同厂商 API 的协议差异、HTTP 通信细节、会话上下文维护与数据持久化逻辑，为上层应用提供统一的调用接口。

1.2 支持模型清单

• 云端 API 模型：deepseek-chat、gpt-4o-mini、gemini-2.0-flash
• 本地部署模型：通过 Ollama 接入 deepseek-r1:1.5b

1.3 核心特性

• 多轮对话：自动维护会话上下文，无需开发者手动拼接历史消息
• 双模式响应：支持一次性完整返回、流式逐块回调两种响应模式
• 会话管理：支持会话创建、查询、删除全生命周期操作
• 持久化存储：基于 SQLite 实现会话与消息数据的本地落盘

---

2 ~> SDK 编译与安装流程

补充：cmake ..描述为 “编译”，属于概念错误。因为cmake是构建系统生成工具，仅负责生成 Makefile 等构建脚本；真正的编译动作由make命令执行。

2.1 源码获取

仓库地址：https://gitee.com/zhibite-edu/ai-model-access-dev.git

git clone https://gitee.com/zhibite-edu/ai-model-access-dev.git

2.2 SDK 源码目录结构

SDK 核心代码位于仓库sdk/目录下，结构如下：

sdk/
├── CMakeLists.txt    # CMake构建配置
├── include/          # 头文件目录
│   ├── chat_sdk.h    # 核心入口头文件
│   ├── common.h      # 公共数据结构定义
│   ├── ILLMProvider.h  # 模型提供者抽象接口
│   ├── LLMManager.h    # 模型管理器
│   ├── SessionManager.h # 会话管理器
│   ├── DataManager.h   # 数据持久化管理器
│   ├── DeepSeekProvider.h
│   ├── ChatGPTProvider.h
│   ├── GeminiProvider.h
│   ├── OllamaDeepSeekProvider.h
│   └── util/my_logger.h # 日志工具
├── src/              # 核心源文件
└── util/             # 工具类源文件

2.3 标准编译安装步骤

# 1. 进入sdk源码根目录
cd sdk

# 2. 创建独立构建目录并进入
mkdir build && cd build

# 3. 生成Makefile构建脚本（非编译）
cmake ..

# 4. 执行编译，生成静态库 libai_chat_sdk.a
make

# 5. 安装至系统目录（需root权限）
sudo make install

2.4 安装路径说明

• 静态库安装路径：/usr/local/lib/libai_chat_sdk.a
• 头文件安装路径：/usr/local/include/ai_chat_sdk/

2.5 CMake 安装规则原理

SDK 的 CMakeLists.txt 通过install指令指定安装行为：

• 静态库目标安装至系统lib目录
• include/下所有.h文件安装至系统include/ai_chat_sdk目录，保证头文件路径统一

---

3 ~> 核心类体系与 API 规范

3.1 类设计关系

• 组合关系：ChatSDK 类内部组合了 LLMManager、SessionManager、Config 三类对象，对外提供统一门面
• 继承关系：采用策略模式实现多厂商模型适配，不同厂商 Provider 继承自 LLMProvider 抽象基类
• 数据实体：Session、ModelInfo、Message 为纯数据结构，对应业务实体

3.2 ChatSDK 核心 API 详解

3.2.1 模型初始化

bool initModels(const std::vector<std::shared_ptr<Config>>& configs);

• 功能：根据传入的配置列表初始化所有模型实例
• 参数：configs 为所有模型配置的智能指针数组
• 返回值：初始化成功返回true，失败返回false

3.2.2 会话管理接口

// 创建指定模型的会话，返回唯一会话ID
std::string createSession(const std::string& modelName);

// 根据会话ID获取会话对象
std::shared_ptr<Session> getSession(const std::string& sessionId);

// 获取所有会话的ID列表
std::vector<std::string> getSessionList();

// 删除指定会话及其历史消息
bool deleteSession(const std::string& sessionId);

// 获取所有已初始化的可用模型列表
std::vector<ModelInfo> getAvailableModels();

3.2.3 消息交互接口

非流式发送（同步返回）：

std::string sendMessage(const std::string& sessionId, const std::string& message);

• 阻塞等待模型生成完整回复后一次性返回
• 返回值：模型完整响应文本

流式发送（回调返回）：

std::string sendMessageStream(
    const std::string& sessionId,
    const std::string& message,
    std::function<void(const std::string&, bool)> callback
);

• 模型每生成一段文本即触发一次回调，模拟打字效果
• callback参数：第一个参数为当前文本片段，第二个参数done标识响应是否结束
• 返回值：最终完整的响应文本

---

4 ~> 快速上手实战代码

**补充：**如果直接运行会触发Segmentation fault，核心原因是未初始化 spdlog 日志库。

4.1 前置要求

• 已完成 SDK 编译与系统安装
• 已配置环境变量deepseek_apikey存储 API 密钥
• 系统已安装所有依赖库

4.2 完整可运行示例代码

#include <iostream>
#include <string>
#include <vector>
#include <memory>
#include <ai_chat_sdk/chat_sdk.h>
#include <ai_chat_sdk/common.h>
#include <ai_chat_sdk/util/my_logger.h>

/**
 * @brief 封装流式消息发送与打印
 * @param chatSDK ChatSDK实例引用
 * @param sessionId 会话ID
 */
void sendMessageStream(ai_chat_sdk::ChatSDK& chatSDK, const std::string& sessionId)
{
    std::cout << "-----发送消息-----" << std::endl;
    std::cout << "user消息>";
    std::string message;
    std::getline(std::cin, message);
    std::cout << "-----发送消息完成-----" << std::endl;

    // 调用流式接口，lambda表达式作为回调处理返回
    chatSDK.sendMessageStream(sessionId, message, [](const std::string& response, bool done){
        std::cout << "assistant消息:" << response << std::endl;
        if(done){
            std::cout << "-----接收消息完成-----" << std::endl;
        }
    });
}

int main(int argc, char* argv[])
{
    // 【必须步骤】初始化日志库，否则直接触发段错误
    bite::Logger::init_logger("aiChatServer", "stdout", spdlog::level::info);

    // 1. 创建ChatSDK核心实例
    ai_chat_sdk::ChatSDK chatSDK;

    // 2. 配置DeepSeek模型参数
    ai_chat_sdk::ApiConfig deepseekConfig;
    deepseekConfig.api_key = std::getenv("deepseek_apikey"); // 从环境变量读取密钥
    deepseekConfig.temperature = 0.7;    // 采样温度，值越高随机性越强
    deepseekConfig.max_tokens = 2048;    // 单次响应最大token数
    deepseekConfig.model_name = "deepseek-chat";

    // 3. 组装配置数组（支持同时配置多个模型）
    std::vector<std::shared_ptr<ai_chat_sdk::Config>> configs;
    configs.push_back(std::make_shared<ai_chat_sdk::ApiConfig>(deepseekConfig));

    // 4. 初始化所有模型
    chatSDK.initModels(configs);

    // 5. 创建会话
    std::cout << "-----创建会话-----" << std::endl;
    std::string sessionId = chatSDK.createSession("deepseek-chat");
    std::cout << "创建会话成功，会话ID:" << sessionId << std::endl;

    // 6. 主交互循环
    int userOp = 1;
    while(true){
        std::cout << "-------1.send message 0.exit-------" << std::endl;
        std::cin >> userOp;
        if(userOp == 0){
            break;
        }
        getchar(); // 消化输入缓冲区残留的换行符，避免getline读空
        sendMessageStream(chatSDK, sessionId);
    }

    std::cout << "-----程序退出-----" << std::endl;
    return 0;
}

---

5 ~> 项目 CMake 构建配置

5.1 CMakeLists.txt 完整配置

cmake_minimum_required(VERSION 3.10)
project(AIChatDemo)

# 强制使用C++17标准
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 设置构建类型为Debug
set(CMAKE_BUILD_TYPE Debug)

# 添加可执行目标，源文件名必须与实际文件一致
add_executable(AIChatDemo chatDemo.cpp)

# 查找并引入OpenSSL依赖
find_package(OpenSSL REQUIRED)
include_directories(${OPENSSL_INCLUDE_DIR})

# 指定系统库搜索路径，确保能找到安装的ai_chat_sdk
link_directories(/usr/local/lib)

# 链接所有依赖库
target_link_libraries(AIChatDemo PRIVATE
    ai_chat_sdk    # ChatSDK静态库
    fmt
    jsoncpp
    OpenSSL::SSL
    OpenSSL::Crypto
    gflags
    spdlog
    sqlite3
)

5.2 编译运行命令

# 在项目根目录创建构建目录
mkdir build && cd build

# 生成构建文件
cmake ..

# 编译生成可执行文件
make

# 运行程序（需提前配置deepseek_apikey环境变量）
./AIChatDemo

5.3 常见构建错误排查

1. 源文件找不到：add_executable中指定的文件名必须与实际源文件名完全一致，大小写敏感
2. 依赖库缺失：需提前通过系统包管理器安装libssl-dev、libfmt-dev、libjsoncpp-dev、libspdlog-dev、libgflags-dev、libsqlite3-dev
3. 链接不到 SDK：确保已执行sudo make install，且link_directories路径正确

---

结尾

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

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

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

往期回顾：

【AI接入大模型SDK】Trae IDE开发环境搭建指南

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