【AI大模型接入SDK】ChatServer接口设计规范

艾莉丝努力练剑2026-10-18 9:43

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

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

🎬 艾莉丝的简介：

文章目录

  • [1 ~> ChatServer 接口整体概述](#1 ~> ChatServer 接口整体概述)
    • [1.1 业务功能点](#1.1 业务功能点)
    • [1.2 API 预先约定的工程价值](#1.2 API 预先约定的工程价值)
  • [2 ~> RESTful API 接口设计规范](#2 ~> RESTful API 接口设计规范)
    • [2.1 RESTful 基础概念](#2.1 RESTful 基础概念)
      • [2.1.1 核心要素](#2.1.1 核心要素)
    • [2.2 RESTful 接口通用报文范式](#2.2 RESTful 接口通用报文范式)
      • [2.2.1 请求报文构成](#2.2.1 请求报文构成)
      • [2.2.2 响应报文通用结构](#2.2.2 响应报文通用结构)
  • [3 ~> ChatServer 全部接口契约定义](#3 ~> ChatServer 全部接口契约定义)
    • [3.1 获取会话列表](#3.1 获取会话列表)
      • [3.1.1 请求定义](#3.1.1 请求定义)
      • [3.1.2 响应体](#3.1.2 响应体)
    • [3.2 获取可用模型列表](#3.2 获取可用模型列表)
      • [3.2.1 请求定义](#3.2.1 请求定义)
      • [3.2.2 响应体](#3.2.2 响应体)
    • [3.3 创建新会话](#3.3 创建新会话)
      • [3.3.1 请求定义](#3.3.1 请求定义)
      • [3.3.2 响应体](#3.3.2 响应体)
    • [3.4 获取会话历史消息](#3.4 获取会话历史消息)
      • [3.4.1 请求定义](#3.4.1 请求定义)
      • [3.4.2 响应体](#3.4.2 响应体)
    • [3.5 发送消息‑全量返回模式](#3.5 发送消息‑全量返回模式)
      • [3.5.1 请求定义](#3.5.1 请求定义)
      • [3.5.2 响应体](#3.5.2 响应体)
    • [3.6 发送消息‑流式 SSE 异步模式](#3.6 发送消息‑流式 SSE 异步模式)
      • [3.6.1 请求定义](#3.6.1 请求定义)
      • [3.6.2 SSE 流式响应报文格式](#3.6.2 SSE 流式响应报文格式)
    • [3.7 删除会话](#3.7 删除会话)
      • [3.7.1 请求定义](#3.7.1 请求定义)
      • [3.7.2 响应体](#3.7.2 响应体)
  • [4 ~> ChatServer 接口开发总结](#4 ~> ChatServer 接口开发总结)
    • [4.1 工程约束](#4.1 工程约束)
    • [4.2 关键工程要点](#4.2 关键工程要点)
  • 结尾

1 ~> ChatServer 接口整体概述

1.1 业务功能点

ChatServer 聊天服务核心业务能力，客户端通过 HTTP 接口与服务端完成交互，实现前后端分离架构。

  • 获取会话列表
  • 获取支持的模型列表
  • 新建会话
  • 发送消息（支持全量返回、SSE 流式返回两种模式）
  • 获取会话历史消息
  • 删除会话

1.2 API 预先约定的工程价值

  • 前后端依据同一套 API 文档并行开发，避免联调阶段接口契约不匹配问题。
  • 测试人员可基于 API 文档提前编写测试用例、设计测试计划。
  • 所有角色开发、测试工作同步推进，提升整体项目迭代效率。

2 ~> RESTful API 接口设计规范

2.1 RESTful 基础概念

REST：Representational State Transfer，表现层状态转移；RESTful 为基于 REST 思想的 API 设计风格，不是网络协议，是一套接口设计标准，底层依托 HTTP 协议实现客户端‑服务器通信。

2.1.1 核心要素

  • 资源 (Resource)
    • 将业务中每一个实体、对象抽象为资源，例如会话、模型、用户。
    • 每一份资源使用唯一 URI 进行标识，URL 作为 URI 的具体实现形式。
    • 示例：/api/sessions 代表会话集合资源。
  • 表现层
    • 代表资源在网络传输中的序列化格式，支持 JSON、XML、HTML。
    • RESTful 工程实践优先选用JSON，具备轻量、程序易于解析的特性。
  • HTTP 动作（HTTP Methods），使用 HTTP 方法描述对资源的操作行为
    • GET：获取资源
    • POST：创建资源
    • PUT：更新资源
    • DELETE：删除资源
  • 无状态特性
    • 每一次 HTTP 请求完全独立；服务端不保存客户端会话上下文状态。
    • 客户端每一次请求必须携带服务端处理业务所需要的全部参数信息。
    • 若业务需要会话状态，必须额外自行实现会话存储机制。

2.2 RESTful 接口通用报文范式

2.2.1 请求报文构成

  1. HTTP 请求方法
  2. 资源 URI（请求 URL）
  3. 请求体 JSON 载荷（POST/PUT 场景）

2.2.2 响应报文通用结构

  • HTTP 状态码标识请求传输层级结果；业务结果由响应体内业务字段表达。
  • 响应体统一 JSON 格式，包含请求标识、业务错误码、错误信息、结果载体对象。
json 复制代码 
{
  "requestId": "string",    // 请求唯一ID，用于链路追踪
  "errorCode": 0,           // 业务错误码，0代表业务执行成功
  "errorMsg": "",           // 业务错误描述，成功时为空字符串
  "result": {}              // 业务返回数据载体对象
}

3 ~> ChatServer 全部接口契约定义

公共约束： 非流式接口 HTTP 返回状态码均为200 OK，业务成功失败通过 JSON 内部布尔 / 错误码字段区分；所有非流式接口请求、响应均使用 JSON 格式。

3.1 获取会话列表

3.1.1 请求定义

  • 请求方法：GET
  • 请求 URL：/api/sessions
  • 请求体：无

3.1.2 响应体

json 复制代码 
{
  "success": true,                 // bool，本次业务是否成功
  "message": "string",             // 结果描述文本
  "data": [                        // array，会话列表数组
    {
      "id": "string",              // 会话id
      "model": "string",           // 使用的模型名称
      "created_at": 1700000000,    // int64_t，会话创建时间戳
      "updated_at": 1700000100,    // int64_t，会话最后更新时间戳
      "message_count": 10,         // int，该会话对话总次数
      "first_user_message": "string"// string，第一条用户消息正文，用于会话列表预览
    }
  ]
}

3.2 获取可用模型列表

3.2.1 请求定义

  • 请求方法：GET
  • 请求 URL：/api/models
  • 请求体：无

3.2.2 响应体

json 复制代码 
{
  "success": true,          // bool，业务是否成功
  "message": "string",      // 结果描述
  "data": [                 // array，可用模型数组
    {
      "name": "string",     // 模型名称，调用时作为入参使用
      "desc": "string"      // 模型功能描述
    }
  ]
}

3.3 创建新会话

3.3.1 请求定义

  • 请求方法：POST
  • 请求 URL：/api/session
  • 请求体
json 复制代码 
{
  "model": "string" // 需要使用的模型名称，来源于/api/models接口返回name字段
}

3.3.2 响应体

json 复制代码 
{
  "success": true,        // bool，业务是否成功
  "message": "string",    // 结果描述
  "data": [
    {
      "session_id": "string", // 会话唯一ID，后续所有会话相关接口必须携带该标识
      "model": "string"       // 当前会话绑定的模型名称
    }
  ]
}

3.4 获取会话历史消息

3.4.1 请求定义

  • 请求方法：GET
  • 请求 URL：/api/session/${session_id}/history
  • 路径参数：session_id，创建会话接口返回的会话 ID
  • 请求体：无

3.4.2 响应体

json 复制代码 
{
  "success": true,         // bool，业务是否成功
  "message": "string",     // 结果描述
  "data": [                // array，消息历史数组，按时间排序
    {
      "id": "string",      // 单条消息唯一id
      "role": "string",    // 消息角色：user / assistant
      "content": "string", // 消息正文内容
      "timestamp": 1700000200 // int64_t，消息生成时间戳，秒级
    }
  ]
}

3.5 发送消息‑全量返回模式

等待大模型完整生成全部内容之后，一次性返回全部应答结果。

3.5.1 请求定义

  • 请求方法：POST
  • 请求 URL：/api/message
  • 请求体
json 复制代码 
{
  "session_id": "string",  // 目标会话ID
  "model": "string",       // 模型名称
  "message": "string"      // 用户输入提问内容
}

3.5.2 响应体

json 复制代码 
{
  "success": true,         // bool，业务是否成功
  "message": "string",     // 结果描述
  "data": [
    {
      "session_id": "string",
      "response": "string" // 大模型完整应答全部文本
    }
  ]
}

3.6 发送消息‑流式 SSE 异步模式

SSE（Server‑Sent Events）服务端推送事件，分片逐块返回模型输出文本，前端实时渲染打字机效果；HTTP 状态码 200 OK，响应 Content‑Type 为text/event‑stream。

3.6.1 请求定义

  • 请求方法：POST
  • 请求 URL：/api/message/async
  • 请求体
json 复制代码 
{
  "session_id": "string",
  "model": "string",
  "message": "string"
}

3.6.2 SSE 流式响应报文格式

Plain 复制代码 
data:模型输出片段1
data:模型输出片段2
data:模型输出片段3
data:[DONE]
  • 每一条data:代表一块增量输出文本；客户端持续拼接收到的 data 内容。
  • data:[DONE]为流结束标记，客户端收到该标记代表本次对话流式输出全部完成，关闭 SSE 连接。

3.7 删除会话

3.7.1 请求定义

  • 请求方法：DELETE
  • 请求 URL：/api/session/${session_id}
  • 路径参数：session_id，待删除会话 ID
  • 请求体：无

3.7.2 响应体

json 复制代码 
{
  "success": true,     // bool；true代表会话服务端删除成功，前端需要同步删除本地页面会话条目
  "message": "string"  // 结果描述
}

4 ~> ChatServer 接口开发总结

4.1 工程约束

  1. ChatServer 后端服务、前端页面交互逻辑，必须严格遵循本套 RESTful 接口契约实现。
  2. 前端页面调用全部接口，完成会话全生命周期管理：创建会话、发送消息、拉取历史、销毁会话。

4.2 关键工程要点

  • 接口契约先行：正式编码开发前完成 API 文档定义，支撑前后端、测试多角色并行工作。
  • 两种消息返回模式选型：
    • 全量返回：逻辑简单，适合简短问答；大模型长输出场景用户体验差，等待时间长。
    • SSE 流式输出：实时增量推送，聊天产品主流方案；客户端需要实现 SSE 事件监听、文本分片拼接逻辑。
  • RESTful 无状态：会话状态全部通过session_id参数携带，服务端不在 HTTP 上下文存储会话信息。
  • 资源路径语义化：使用 HTTP 动词表达增删改查行为，URI 代表业务资源，不使用 URL 中出现/getSession这类动词形式。

结尾

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

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

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

往期回顾：

【AI大模型接入SDK】ChatServer项目整体概述与系统架构

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

相关推荐
纪念 2291 小时前
C++算法(三)
开发语言·c++·算法
程序员-Benothing1 小时前
Linux网络排错命令：ping、traceroute、mtr、dig、nslookup
linux·运维·网络
摇滚侠1 小时前
《大模型应用开发实践：基于 Spring AI+DeepSeek 实现》第 12 章 Spring AI 开发入门 阅读笔记 2
人工智能·笔记·spring
武汉星际互动1 小时前
技术拐点已至：AI Agent给政务大厅带来什么变革？
大数据·人工智能·政务
科技研学社1 小时前
服装AI视觉质检落地实战：从人工验布到自动缺陷检测的多品牌方案对比
人工智能
QinHsiu1 小时前
4B干翻9B底座：首个Agent-Native模型NeoHorse-1，把“做事的过程”压进了参数里
人工智能
QinHsiu1 小时前
微软实锤：Agent的长记忆是毒药，清空聊天记录后性能提升58%
人工智能
xiaomuzuirenzhen1 小时前
2027秋招准备：统计学专业投商业分析、战略分析，除了SQL还要补什么？
人工智能·数据分析
知行产研1 小时前
三年三起收购，拆解卡特彼勒AI并购版图
数据库·人工智能·mysql
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02「全语录+省流版」邵艾伦 × 孙宇晨：聊风口、聊个人IP、聊年轻人如何抓住 AI 时代的机会03GitHub 镜像站点04历年考研数学一、数学二、数学三真题试卷及答案PDF05几个好用的ip纯净度检测网站06如何新建文件夹？ 电脑新建文件夹的4种方法07蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接08Telegram APK 下载安装完整指南 — 2026年最新09苹果iPA游戏软件资源下载网站10Windows 10/11 如何退出微软账户并改用本地账户登录（含找不到选项的解决方法）