开发指南
AI大模型手册

AI 聊天对话

AI 对话，基于 LLM 大模型，实现智能聊天的功能。

说白了，就是和机器人聊天。高级点，就是智能问答！

AI 聊天

整个功能，涉及到 5 个表（上图可以看到 4 个）：

【配置】ai_api_key：API 密钥表
【配置】ai_model：模型表
【配置】ai_chat_role：聊天角色表
【对话】ai_chat_conversation：聊天对话表
【对话】ai_chat_message：聊天消息表

补充说明：

ai_api_key、ai_model 已经在《功能开启》讲解，就不重复赘述。

下面，我们逐个表进行介绍，这个过程中也会讲讲对应的功能。

# 1. 前置准备

你想使用哪个模型聊天，可以参考对应的文档，进行配置：

国内模型：《通义千问》、《DeepSeek》、《豆包》、《混元》、《文心一言》、《硅基流动》、《讯飞星火》、《智谱 GLM》、《月之暗面》、《MiniMax》、《百川智能》、《阶跃星辰》、《小米 MiMo》
国外模型：《OpenAI（ChatGPT）》、《Anthropic（Claude）》、《Grok》、《LLAMA》、《微软 OpenAI（ChatGPT）》、《谷歌 Gemini》

友情提示：

一般情况下，建议先使用《DeepSeek》模块，因为免费送了一些 tokens，可以先体验一下。

# 2. 聊天角色表

聊天角色表，配置机器人扮演怎么样的角色，例如说：通用 AI 助手、Python 专家、客服小姐姐等等。

# 2.1 表结构

省略 creator/create_time/updater/update_time/deleted/tenant_id 等通用字段

CREATE TABLE `ai_chat_role` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '角色编号',
  `name` varchar(128) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '角色名称',
  `avatar` varchar(256) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '头像',
  `description` varchar(256) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '角色描述',
  `status` tinyint DEFAULT NULL COMMENT '状态',
  `sort` int NOT NULL DEFAULT '0' COMMENT '角色排序',
  
  `user_id` bigint DEFAULT NULL COMMENT '用户编号',
  `public_status` bit(1) NOT NULL COMMENT '是否公开',
  `category` varchar(32) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '角色类别',
  
  `model_id` bigint DEFAULT NULL COMMENT '模型编号',

  `system_message` varchar(1024) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '角色上下文',
  
  `knowledge_ids` varchar(256) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '关联的知识库编号数组',
  `tool_ids` varchar(256) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '关联的工具编号数组',
  `mcp_client_names` varchar(256) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '引用的 MCP Client 名字列表',

  PRIMARY KEY (`id`)
) ENGINE=InnoDB AUTO_INCREMENT=13 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='AI 聊天角色表';

① user_id 字段：对应 system_users 表的 id 字段，表示哪个用户创建的角色。

public_status 字段：表示是否公开。如果是公开，那么其他用户也可以使用这个角色，一般由管理员创建。如果是私有，那么只有创建者 user_id 可以使用。

category 字段：公开角色的所属类别，例如说：助手、编程开发、娱乐等等。

② model_id 字段：表示角色绑定的默认模型，对应 ai_model 表的 id 字段。当然，也可以不绑定，此时使用 ai_model 排序 sort 最小的模型。

③ system_message 字段：表示角色上下文，或者说角色设定。例如说 “Python 专家” 对应如下

“ 我希望你能作为一名 python 专家。

我将向你提供有关我的技术问题的所有信息，而你的角色是解决我的问题。

你应该用你的计算机科学、网络基础设施和 IT 安全知识来解决我的问题。在你的回答中，使用聪明的、简单的、为各种层次的人所理解的语言会有帮助。

逐步解释你的解决方案并使用要点是很有帮助的。尽量避免过多的技术细节，但在必要时使用它们。我希望你用解决方案来回答，而不是写任何解释。

”

④ knowledge_ids 字段：关联的知识库编号数组，对应 ai_knowledge 表的 id 字段。后续使用，可见《AI 知识库》文档。

⑤ tool_ids 字段：关联的工具编号数组，对应 ai_tool 表的 id 字段。后续使用，可见《AI 工具库》文档。

⑥ mcp_client_names 字段：引用的 MCP Client 名字列表。后续使用，可见《MCP Client 客户端》文档。

# 2.2 管理后台

① 前端对应 [AI 大模型 -> 控制台 -> 聊天角色] 菜单，对应 yudao-ui-admin-vue3 项目的 @/views/ai/model/chatRole 目录，提供给管理员使用，创建公开角色。

聊天角色

它的后端 HTTP 接口，由 yudao-module-ai 模块的 model 包的 AiChatRoleController 实现。

② 前端聊天界面的【角色仓库】，对应 yudao-ui-admin-vue3 项目的 TODO 目录，提供给用户使用，创建私有角色。

角色仓库

可以点击【使用】按钮，使用对应的角色创建对话
也可以点击【公共角色】标签，按分类查看公开角色列表，也支持【使用】按钮

# 3. 聊天对话

聊天对话，一共有 2 个表，分别是 ai_chat_conversation 和 ai_chat_message。前者是对话的基本信息，后者是对话的消息列表。

# 3.1 表结构【聊天对话表】

省略 creator/create_time/updater/update_time/deleted/tenant_id 等通用字段

CREATE TABLE `ai_chat_conversation` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '对话编号',
  `title` varchar(256) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '对话标题',
  `pinned` bit(1) NOT NULL COMMENT '是否置顶',
  `pinned_time` datetime DEFAULT NULL COMMENT '置顶时间',
  
  `user_id` bigint NOT NULL COMMENT '用户编号',
  
  `role_id` bigint DEFAULT NULL COMMENT '聊天角色',

  `model_id` bigint NOT NULL COMMENT '模型编号',
  `model` varchar(32) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '模型标识',
  
  `system_message` varchar(1024) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '角色设定',
  `temperature` double NOT NULL COMMENT '温度参数',
  `max_tokens` int NOT NULL COMMENT '单条回复的最大 Token 数量',
  `max_contexts` int NOT NULL COMMENT '上下文的最大 Message 数量',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB AUTO_INCREMENT=1781604279872581716 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='AI 聊天对话表';

① user_id 字段：对应 system_users 表的 id 字段，表示哪个用户创建的对话。

② role_id 字段：表示对话使用的角色，对应 ai_chat_role 表的 id 字段。如果没有使用角色，则为空，此时是点击聊天界面的【新建对话】产生的。

③ model_id 字段：表示对话使用的模型，对应 ai_model 表的 id 字段。每个对话可以随时切换它所使用的模型。

model 字段：表示模型标识，冗余 ai_model 表的 model 字段。

修改模型

system_message、temperature、max_tokens、max_contexts 字段：就是对话的配置，上图也已经看到。

# 3.2 表结构【聊天消息表】

省略 creator/create_time/updater/update_time/deleted/tenant_id 等通用字段

CREATE TABLE `ai_chat_message` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '消息编号',

  `conversation_id` bigint NOT NULL COMMENT '对话编号',
  `user_id` bigint NOT NULL COMMENT '用户编号',
  `role_id` bigint DEFAULT NULL COMMENT '角色编号',

  `model` varchar(64) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '模型标识',
  `model_id` bigint NOT NULL COMMENT '模型编号',  

  `type` varchar(16) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '消息类型',  
  `reply_id` bigint DEFAULT NULL COMMENT '回复编号',

  `content` text CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '消息内容',
  `reasoning_content` text CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci COMMENT '推理内容',
  `use_context` bit(1) NOT NULL DEFAULT b'0' COMMENT '是否携带上下文',

  `segment_ids` varchar(2048) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '段落编号数组',
  `web_search_pages` text CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci COMMENT '联网搜索的网页内容数组',
  `attachment_urls` varchar(2048) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '附件 URL 数组',

  `request_id` varchar(64) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '本地请求 UUID',
  `input_tokens` bigint DEFAULT NULL COMMENT '实际输入 Token，未知为空',
  `output_tokens` bigint DEFAULT NULL COMMENT '实际输出 Token，未知为空',
  `total_tokens` bigint DEFAULT NULL COMMENT '实际合计 Token，未知为空',
  PRIMARY KEY (`id`) USING BTREE,
  KEY `idx_conversation_id` (`conversation_id`),
  KEY `idx_request_id` (`request_id`)
) ENGINE=InnoDB AUTO_INCREMENT=2147 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='AI 聊天消息表';

① conversation_id、user_id、role_id 字段：关联到 ai_chat_conversation 表的相关字段。

② model、model_id 字段：该消息所使用的模型。因为对话可以随时切换模型，所以消息也需要记录。

③ type 字段：消息类型，对应 Spring AI 提供的 MessageType 枚举类，目前表里有 user 用户发送、assistant 模型回复。

reply_id 字段：表示回复的消息编号。用户每次发送消息，会记录一条 user 类型的消息，然后模型回复的消息，会记录一条 assistant 类型的消息，这两条消息通过 reply_id 对应的。

④ content 字段：消息内容，对应用户发送的消息或者模型回复的消息。

reasoning_content 字段：推理内容，对应支持推理模式（thinking）的模型，模型在输出最终回答之前，先输出的思维链内容。对应《推理模式（thinking）》文档。

⑤ use_context 字段：表示是否携带上下文。如果为 true 时，表示这条消息会携带上下文，此时调用模型时，会带该会话的最后 max_contexts 组消息。

注意，它是在消息发送框的左下角的蓝色 switch 【上下文】小按钮噢！

⑥ segment_ids 字段：知识库找回的段落编号数组，对应 ai_knowledge_segment 表的 id 字段，可见《AI 知识库》文档。

⑦ web_search_pages 字段：联网搜索的网页内容数组，对应《AI 联网搜索》文档。

⑧ attachment_urls 字段：用户上传的附件 URL 数组，图片附件的处理，可见「3.4 图片附件」小节。

⑨ request_id 字段：请求编号，对应 ai_request_log 表的 request_id 字段，即这条回复的请求日志。

input_tokens、output_tokens、total_tokens 字段：这条回复的输入、输出、合计 Token 数，来自模型平台的返回，没有返回时为空。它们只记录在 assistant 模型回复的消息上，user 消息为空。对应《请求日志与 Token 用量》文档。

# 3.3 管理后台

① 前端对应 [AI 大模型 -> AI 对话] 菜单，对应 yudao-ui-admin-vue3 项目的 @/views/ai/chat/index 目录。上面已经有很多图了，就不重复截图了！

它的后端 HTTP 接口，由 yudao-module-ai 模块的 chat 包的 AiChatConversationController、AiChatMessageController 实现。

最最最关键的代码！！！大家可以重点看看！！！

AiChatMessageController 提供的 #sendChatMessageStream(...) 流式消息接口。

它的内部，调用 Spring AI 的 StreamingChatModel 来实现大模型的调用。

② 前端对应 [AI 大模型 -> 控制台 -> 聊天管理] 菜单，对应 yudao-ui-admin-vue3 项目的 @/views/ai/chat/manager 目录，提供给管理员使用，查看对话列表、消息列表。

聊天管理

# 3.4 图片附件

对话时可以上传附件。图片是否交给模型理解，取决于模型配置的 input_modalities 输入能力，见《功能开启》的「4.2 模型表」小节。

① 模型勾选了「图片」：当前消息，以及携带上下文时选入的历史消息中的图片，会通过 Spring AI UserMessage 的 Media 传给模型，不再以 Base64 文本拼接到提示词里。不过，Spring AI 客户端发送请求时仍可能把图片编码为 Base64，所以请求体不一定变小，图片的大小、数量仍受模型厂商的限制。

② 模型未勾选「图片」：图片仍按原有附件逻辑，以 Base64 文本拼接到提示词里，模型无法真正理解图片。视频、文档等其它附件，也继续按原有附件逻辑处理。

注意：模型厂商支持识图，不代表项目当前的 Spring AI 客户端能把图片传过去！

DeepSeek，以及复用 DeepSeek 客户端的豆包、混元、硅基流动、文心一言、智谱、讯飞星火、MiniMax、月之暗面、百川、阶跃星辰、小米 MiMo，使用的是 Spring AI 的 DeepSeekChatModel，它在 Spring AI 1.1.8 / 2.0.0 / 2.0.1 中仍会丢弃图片。
通义千问在 JDK17（Spring AI 1.1.8）版本中，同步、流式识图均已实测通过。JDK25（Spring AI 2.0.1）版本中，由于 Spring AI Alibaba 2.0.0-M1.1 与 Spring AI 2.0.x 不兼容，通义对话改为通过阿里云百炼的 OpenAI 兼容接口调用，图片同样通过 Media 传给模型。
其它平台，以「1. 前置准备」中对应的模型接入文档为准。

# 3.5 思考等级

模型配置了思考档位时，消息发送框的左下角会展示「思考等级：xx」按钮，用于选择本次回复的思考档位，具体可见《推理模式（thinking）》的「4. 思考等级配置」小节。

← 功能开启 AI 绘画创作→