Ragent AI 1.1.0
发布于 2026 年 8 月 11 日
Ragent AI 1.1.0 是继 1.0.x 之后的首个功能版本，围绕混合检索、摄取内核、回答溯源、Prompt 运行时管理和业务审计五个方向进行了系统性升级，同时对模型路由、对象存储和检索架构做了结构性调整。
1.1.0 不只是应用代码升级。对于已有 1.0.x 数据的部署，数据库、向量数据、对象存储布局和配置文件均存在破坏性变更，务必在切流前完成迁移验证。
版本亮点
- 混合检索：在向量检索基础上扩展 Elasticsearch 关键词检索、LightRAG 图检索和 You.com Web Search，引入 Scope / Channel / Fusion 与分阶段检索预算
- 摄取内核：统一 Parse → Chunk → Embed → Index 四阶段链路，引入 MIME / 解析档位、MinerU 富文档解析和 VLM 图像理解
- 回答溯源与推荐追问：消息持久化回答来源、引用信息和检索上下文，前端新增来源查看与推荐追问交互
- Agent Profile 与 Prompt Slot：Prompt 从静态
.st模板演进为数据库级 Agent Profile / Prompt Slot，支持管 理端维护和动态激活 - 业务变更审计：记录关键管理操作的变更前后快照、字段差异、操作者及请求上下文
- 可靠性增强：模型路由升级为 Tier 模型，修复 Pipeline 非法条件、模型 fallback / 熔断探测、会话排序和 MQ 回调等稳定性问题
新功能
1. 混合检索与多知识库路由
1.0.x 已具备向量检索、意图路由、去重与 Rerank。1.1.0 将检索链路扩展为完整的异构 Hybrid Retrieval：
- 新增 Elasticsearch 关键词检索、LightRAG 图检索和 You.com Web Search 三个检索通道
- 多通道并行执行，经统一 Fusion 阶段完成 RRF 融合与 Rerank
- 引入 Scope 层控制知识库范围、置信度与补充召回比例
- 检索预算分 recall → rerank → final 三阶段配置，启动时校验
- Intent Node 从单知识库绑定扩展为可关联多个 Collection
- 图检索配套知识图谱可视化
Web、关键词和图检索均为可选能力，按部署环境独立启用；可选远程通道故障不会阻断本地检索。
2. 回答来源、引用与推荐追问
聊天结果从「仅返回正文」扩展为可持久 化的回答上下文：
- 消息持久化回答来源
sources，支持文档级来源展示并可结合引用定位回答依据 - 保存检索上下文用于推荐问题生成，消息可携带
recommended_questions - 新增消息状态、回复关系等上下文字段
- 前端增加推荐追问与来源查看交互
用户可据此确认回答依据，并基于当前答案继续深入提问。
3. Agent Profile 与 Prompt Slot
1.1.0 将部分运行时 Prompt 从静态 .st 模板迁移至 Agent Profile / Prompt Slot 模型：
- 创建和维护 Agent Profile，按 Prompt Slot 管理不同运行阶段的提示词
- Profile 激活后作用于后续会话执行
- Prompt 占位符校验降低误配置风险，未配置的 Slot 回退至系统内置默认值
- 管理端新增 Profile 维护页面
Prompt 调整从「修改代码 / 模板文件」演进为可管理的运行时配置。
4. 摄取内核与富文档解析
知识摄取链路系统性升级，形成明确的 Parse → Chunk → Embed → Index 四阶段边界：
- 统一
IngestionSpec描述摄取规则，Parser Registry 按 MIME Type 与 Parse Profile 选择解析器 - 解析器不再对未知格式无限制兜底，不支持的组合明确失败
- PDF、Word、PPT 等富文档可接入 MinerU 解析，请求支持并发控 制
- 新增 VLM 配置与多模态图像理解，用于摄取阶段的图片文本化
- Chunk 新增
embedding_text，将向量化文本与展示正文解耦 - 摄取过程记录 Parse、Chunk、Embed、Persist 各阶段信息，便于诊断
5. 业务变更审计
新增业务变更日志，记录关键管理操作和配置变更：
- 业务类型、业务 ID、操作类型
- 变更前 / 变更后数据快照与字段差异
- 操作者、执行结果、异常信息
- 调用类方法、IP、User-Agent 等请求上下文
管理端同步增加审计查询页面。
功能优化
1. 模型路由升级为 Tier
1.0.x 的多 Provider 优先级路由演进为 Tier 模型，可按场景定义 fast、standard、deep 等档位，每个 Tier 独立配置候选模型与超时。通过 default-tier、deep-thinking-tier 等参数选择运行档位——轻量任务（如 Query Rewrite）走 Fast Tier，复杂回答走更高能力档位。启动阶段对 Tier 引用及候选模型进行校验，避免错误配置到请求阶段才暴露。
2. 检索链路的超时、融合与预算控制
新的检索配置统一管理 Channel 总体超时、各通道启停、RRF 参数、通道权重、Rerank Candidate Limit、Scope Supplement Ratio 和 Recall / Rerank / Final Budget。检索策略从若干独立开关演进为一套多阶段检索管线。
3. Query Understanding 去重优化
多问题改写过程中对重复子问题去重，减少 Intent Classification、Embedding、Retrieval、Rerank 和 Context Assembly 的重复执行。Intent Tree 为空时跳过无意义的意图分类调用。
4. 对象存储抽象升级
对象存储从具体的 S3 / RustFS 实现升级为 ObjectStorageClient 抽象，当前支持 S3 Compatible Storage（RustFS / MinIO）和 Aliyun OSS。知识库文件与资产文件分别使用全局 Bucket 配置，便于不同存储实现之间切换。
5. 远程文件刷新判断增强
远程内容刷新判断不再依赖单一机制，按服务端能力逐级使用 ETag → Last-Modified → Content SHA-256，降低无 变化时重复下载和重新摄取的概率。
缺陷修复
本节仅记录具有独立升级价值的修复主题；新功能开发中的局部 follow-up fix 已合并至对应 Feature。
1. 模型 fallback 与熔断探测稳定性
模型调用成功返回但正文为空白时不再视为成功，不会阻断后续 fallback，降低「最终返回空答案」风险。同时修复 Half-Open 状态下首包探测被中断时探测许可无法释放的问题，避免模型被长期误排除。相关问题：#101、#74。
2. Pipeline 非法配置改为 Fail Closed
修复多类 Pipeline 配置异常被静默接受的问题：多 Root 时只执行第一个、未知 Condition 默认判 true、数值转换失败误参与 gte/lte 判断。1.1.0 增加严格的结构和条件校验，避免错误配置产生「看似正常、路径错误」的执行结果。相关问题：#95、#85、#72。
3. 会话消息排序稳定性
仅按 createTime 排序时，同一时间戳下消息顺序不稳定。现使用 ID 作为二级排序依据，避免历史会话和模型上下文出现顺序漂移。相关问题：#89。
4. 多意图检索结果归属修复
多意图召回结果合并后，Chunk 可能被错误复制到多个 Intent 上，导致 Prompt Planning 误判内容来源。1.1.0 保留准确的 Intent 与召回内容对应关系。相关问题：#87。
5. RocketMQ 事务回调资源释放
事务消息发送异常或未返回 SEND_OK 时，内部 Callback 可能残留在进程级 Map 中。修复后避免长时间运行产生无界资源累积。相关问题：#91。
架构重构
1. Retrieval Engine 分层重构
检索配置和执行模型明确为 Scope → Channels → Fusion → Budget，保留 SearchChannel 等扩展点，新增检索通道时减少对主流程的侵入。
2. Ingestion Kernel 阶段化
摄取逻辑围绕 Parse、Chunk、Embed、Index / Persist 建立稳定的阶段边界，Parser、Chunker 及后续扩展能力可独立演进。
3. Prompt Runtime 数据化
运行时 Prompt 从文件模板迁移为 Agent Profile + Prompt Slot + Resolver，Prompt 管理与应用运行逻辑解耦。
4. Object Storage SPI
文件存储从面向具体 S3 实现的 Service 调整为统一对象存储 SPI，RustFS / MinIO 与 OSS 共享上层文件管理逻辑。
接口与兼容性变更
1. 消息模型新增字段
消息持久化结构新增 Thinking 内容与耗时、Sources、Recommended Questions、Retrieved Chunks、Reply-To Message、Message Status 字段。使用自定义数据库查询、DTO 映射或消息同步逻辑的部署需同步适配。
2. Intent Node 支持多 Collection
新 collection_names 字段支持一个 Intent 关联多个知识库。升级脚本将原 collection_name 转换为数组形式，旧字段暂保留用于兼容。
3. Feedback 支持取消
反馈接口增加删除 / 取消能力，前端可撤销已提交的反馈状态。
4. 扩展点兼容性
1.0.x 核心稳定扩展点（SearchChannel、IngestionNode、McpToolExecutor、ChatClient）未被移除，但 配置结构、数据库结构、向量数据布局和对象存储布局均存在破坏性变更，不可无迁移直接替换。
破坏性变更
下述为升级相关教程，或者简单一些，按照项目官网启动方式，重置项目启动即可。
1. 必须执行数据库升级脚本
仓库包含 9 个 v1.1.0 SQL 升级脚本，须严格按文件名顺序执行：
| # | 脚本 | 用途 |
|---|---|---|
| 1 | 260328_knowledge_chunk_log_duration.sql | 调整 Embed / Persist 阶段耗时字段 |
| 2 | 260408_message_thinking.sql | 消息增加 Thinking 内容与耗时 |
| 3 | 260703_knowledge_vector_collection.sql | 向量记录新增 collection_name |
| 4 | 260709_biz_change_log.sql | 新增业务变更审计表 |
| 5 | 260722_01_message_sources.sql | 消息增加 Sources |
| 6 | 260722_02_message_recommendation_context.sql | 推荐追问、检索上下文、回复关系及消息状态 |
| 7 | 260725_intent_multi_collections.sql | Intent 支持多 Collection |
| 8 | 260730_ingestion_kernel.sql | 摄取规范、MIME、embedding_text 等 |
| 9 | 260803_agent_profile.sql | Agent Profile / Prompt Slot 及内置 Prompt 数据 |
执行前完成数据库备份。
2. 旧 chunk_config 不再兼容读取
摄取内核升级脚本移除旧的 chunk_strategy 和 chunk_config 字段，存量文档退回系统默认摄取规则。
1.0.x 中使用过按文档定制的 Chunk 参数的部署，请在升级前导出这些配置，并在升级后转换到新的 ingestion_spec。
3. 向量数据须迁移或重建索引
这是 1.0.x → 1.1.0 最需要关注的数据兼容点。
PGVector：1.1.0 新增顶层 collection_name 字段，查询直接基于该字段过滤。升级脚本只增加字段并设置默认值，不会自动回填旧记录 metadata 中的 Collection 信息。已有数据须设计回填方案，或对存量知识库重建索引。
Milvus：存储模型从「每知识库独立物理 Collection」调整为「共享物理 Collection（rag_default_store）+ 标量 collection_name 隔离」。新代码的写入和查询均面向共享 Collection。
未发现将 1.0.x 旧 Milvus 物理 Collection 自动搬迁至共享 Collection 的迁移逻辑。已有 Milvus 知识库须在升级窗口规划向量迁移或重建索引，切流前完成召回验证。
4. 对象存储布局变更
1.0.x 采用「一个知识库对应一个 Bucket」，1.1.0 调整为「全局 Knowledge Base Bucket + Collection Namespace」，同时配置从 rustfs.* 迁移至 rag.storage.*。默认 Bucket：
- Knowledge Base：
ragent-sources - Asset：
ragent-assets
未发现自动搬迁旧 per-KB Bucket 文件至新布局的升级程序。已有知识库文件须在切换前验证文件定位信息与新 Bucket 布局的一致性，必要时迁移或重新摄取。
5. Prompt 自定义方式变更
部分旧 .st Prompt 模板已移除，Prompt 运行时转向 Agent Profile / Prompt Slot。曾直接修改仓库 Prompt 模板的部署：
- 升级前保存自定义内容
- 升级后迁移至对应 Agent Profile / Prompt Slot
- 检查必须保留的模板占位符
- 激活 Profile 后完成会话回归验证
6. 配置文件须重新合并
不建议直接沿用 1.0.x 的 application.yaml，以 1.1.0 默认配置为基准重新合并生产差异。主要变更：
| 1.0.x 结构 | 1.1.0 方向 | 说明 |
|---|---|---|
app.demo-mode | ragent.demo-mode | 命名空间迁移 |
app.eval.enabled | ragent.eval.enabled | 命名空间迁移 |
rustfs.* | rag.storage.* | 对象存储统一抽象 |
AI Chat model/priority | AI Chat tier | 模型路由升级 |
vector-global / intent-directed 等 | scope + channels + fusion | 混合检索配置重构 |
| 每 KB 独立 Bucket | kb-bucket + namespace | 对象存储布局变更 |
7. 会话记忆默认参数调整
默认保留历史轮数、摘要起始轮数及摘要最大字符数均有变化。对 Prompt Token 和长会话行为敏感的部署应在升级前显式固定这些参数。
部署与依赖
1. Elasticsearch（可选）
启用关键词检索时需准备 Elasticsearch 并打开 Keyword Channel；未启用不影响其他检索方式。
2. LightRAG（可选）
图检索需配置 LightRAG。当前一个 LightRAG 实例对应一个图空间，多知识库物理图隔离须结合部署架构额外设计。
3. You.com Web Search（可选）
需配置 API Key（YDC_API_KEY）。远程搜索失败时降级，不阻断本地 RAG。
4. MinerU（可选）
PDF、Word、PPT 等富文档摄取可使用 MinerU，需提前准备 API Key、网络配置和并发参数，并验证第三方服务限额。
5. VLM（可选）
图片理解 / 文本化能力需配置支持多模态输入的模型，并进行实际文件摄取验证。
6. Object Storage
配置统一使用 rag.storage，支持 S3 Compatible Storage 和 Aliyun OSS。升级现有 RustFS / MinIO 环境时需同时迁移配置和 Bucket 布局。
变更统计
以下统计按聚合主题计算，不等于 Commit 数量。
| 类别 | 数量 |
|---|---|
| 新功能 | 5 |
| 功能优化 | 5 |
| 缺陷修复 | 5 |
| 架构重构 | 4 |
| 破坏性变更 | 7 |
该范围包含约 91 个 Commits、456 个变更文件。Release Notes 已将属于同一功能的连续开发、修复和重构提交合并为独立主题。