Agent智能体+Skill插件引擎+Milvus混合检索 全套技术沉淀文档
一、文档概述
本文档沉淀整套生产级Agent智能体架构核心设计，包含：Skill/MCP插件调度引擎、LLM思考推理机制、Milvus向量库结构化存储与索引设计、语义+关键词混合检索、RRF重排算法、ES与Milvus架构选型、会话长期记忆时序管控、异常容错体系（超时/重试/轮次/人工兜底），为Agent RAG长期记忆系统提供统一落地规范。
适用场景：对话Agent、工具调用智能体、带长期记忆的AI助手、MCP插件化服务编排系统。
二、整体系统架构总览
整套系统采用分层解耦架构，彻底隔离LLM推理、工具调度、向量检索、结果输出，保证高可用、可扩展、可观测。
五层核心架构
- 接入层：会话管理、用户/会话ID绑定、SSE/WebSocket流式连接、全局超时/轮次总管控、长期记忆时序召回
- LLM意图推理层：结构化意图识别、ReAct思考+行动拆分、判断是否调用工具、匹配对应Skill/MCP能力
- Skill/MCP调度中心：本地插件+远端MCP服务统一注册、路由、主备节点切换、热插拔管理
- 工具执行引擎层：统一收敛超时、重试、错误分类、轮次限制、熔断降级、多级兜底机制
- 检索&输出层：Milvus结构化过滤+混合检索+RRF重排、LLM结果汇总、流式token输出
三、Skill插件+MCP调度引擎核心设计 - 能力分类
引擎统一管理两类工具能力，上层业务无感知差异化：
- 本地Skill插件：轻量内置工具（文本处理、计算、本地逻辑），目录化管理、支持热插拔，带独立配置文件（入参Schema、超时、重试策略）
- MCP远端服务：跨进程/跨业务API能力，通过MCP协议动态拉取工具列表、初始化握手，支持主备集群切换
- 全链路容错管控（生产核心）
（1）双维度轮次限制（防死循环）
- 全局轮次：单对话最大工具调用5轮，超限强制终止工具调用，LLM基于已有结果强行总结
- 单工具轮次：同一工具连续调用不超过2次，避免LLM重复错误调用
（2）双层超时限制（防服务卡死） - 单工具超时：本地Skill默认5s，MCP远端默认10s，支持单工具个性化配置
- 全局会话超时：单条对话整体最大180s，超时强制终止全链路
（3）错误分类&重试&主备切换
所有异常统一分为三类，差异化处理： - 可重试错误：网络超时、502/503、连接失败、限流。策略：最多3次指数退避重试，重试耗尽自动切换备用MCP/Skill节点
- 不可重试错误：参数缺失、格式错误、404、无权限。策略：不重试，直接将错误返回LLM，引导用户补全信息
- 高危异常：数据冲突、高危操作报错、系统崩溃。策略：禁止重试/切换，直接触发人工兜底
（4）多级兜底机制
- 一级兜底：缓存兜底，高频查询返回历史缓存数据并友好提示
- 二级兜底：AI软兜底，放弃工具调用，基于现有信息有限回答并说明服务异常
- 三级兜底：人工工单兜底，高危/全链路失败自动生成工单，流转人工处理
- 工具执行闭环流程
用户输入 → 上下文组装（短期对话+限时长期记忆）→ LLM意图识别 → 工具路由匹配 → 轮次计数+超时管控 → 工具执行/重试/切换 → 结果回填上下文 → 轮次判断（继续调用/结束）→ LLM汇总流式输出
四、LLM Agent思考机制（核心原理） - 核心结论
Agent所有思考内容100%由LLM生成，代码仅管控格式、流程、展示逻辑，不参与推理、不伪造思考内容。 - 工业标准ReAct思考架构
强制拆分双结构，适配所有工具调用场景：
- Thought（思考）：LLM自主推理需求分析、工具选择理由、参数判断、信息充足度复盘，纯自然语言逻辑
- Action（行动）：结构化JSON工具调用指令，由代码解析执行，格式错误直接判定推理失败
- 思考输出三种模式
- 后台私有模式（线上默认）：思考仅留存上下文，前端仅展示工具状态，用户无感知推理过程
- 透明流式模式（调试/后台）：思考、工具调用、工具结果全部SSE流式推送，全程可溯源
- 精简展示模式（折中）：后台留存完整思考，前端展示极简通俗提示
- 异常场景思考逻辑
工具超时、切换失败、轮次超限、服务异常等场景，均由LLM读取异常信息，自主生成兜底思考与回复，无硬编码固定文案。
五、Milvus向量库结构化存储&索引设计（核心沉淀） - 核心规范
所有筛选类元数据必须结构化独立存储，禁止塞入文本、向量、JSON大字段；向量仅存语义/关键词特征，文本仅存原始内容，三者完全隔离。 - 标准集合字段设计（生产最终版）
字段名
类型
索引类型
核心用途
pk_id
INT64
主键索引
全局唯一标识
content
VARCHAR
无索引
原始对话文本
dense_vec
FLOAT_VECTOR
HNSW
稠密向量，语义检索
sparse_vec
SPARSE_FLOAT_VECTOR
SPARSE_INVERTED
稀疏向量，关键词检索
user_id/session_id
VARCHAR
INVERTED倒排
用户/会话维度过滤
chat_unix_ts
INT64
INVERTED倒排
对话真实时间戳（核心时序筛选）
create_unix_ts
INT64
INVERTED倒排
数据入库时间
expire_ts
INT64
INVERTED倒排
记忆过期时间，自动清理
msg_role
VARCHAR
INVERTED倒排
区分user/assistant/tool消息
tool_name
VARCHAR
INVERTED倒排
关联工具名称，用于溯源筛选 - 时间存储硬性规范
- 所有时间统一存储UTC Unix时间戳（INT64数字），禁止字符串日期
- 存储层只做数字区间筛选，前端展示层再转换本地时区
- 区分聊天真实时间(chat_unix_ts)和入库时间(create_unix_ts)，避免离线导入数据时序错乱
- 索引核心说明
- 向量索引：HNSW（高速语义检索）+ 稀疏倒排（关键词检索）
- 元数据索引：全部使用Milvus原生INVERTED倒排索引，支持等值、区间、多条件组合过滤
- 无需ES存储元数据：Milvus原生倒排完全满足会话、时间、工具筛选需求，规避双写一致性问题
六、语义+关键词混合检索&RRF重排机制
- 检索架构选型
采用BGE-M3双向量架构（行业RAG最优方案），单文本同时生成：
- 稠密向量：捕捉整体语义、上下文含义
- 稀疏向量：捕捉关键词、专有名词、精准实体
- 标准检索链路（固定生产流程）
结构化Filter过滤（会话+用户+时间窗口）→ 稠密/稀疏向量并行召回（各Top20）→ RRF融合重排 → 输出最终Top10记忆 - RRF重排核心原理
公式：RRFscore=∑1k+rankRRF_{score} = \sum \frac{1}{k+rank}RRFscore=∑k+rank1
- 核心优势：不依赖分数归一化，只看排名，解决稠密、稀疏分数维度不一致的融合难题
- 通用参数：默认k=60（平衡语义与关键词）
- 参数调优：偏关键词k=20，偏语义k=100
- 时序增强优化
RRF仅做排名融合，业务层叠加时间衰减权重，新记忆权重更高、旧记忆自然下沉，解决时序优先级问题。
七、Milvus与ES架构选型最终规范 - 首选架构：Milvus单库闭环（Agent记忆默认）
所有向量、文本、结构化元数据全部存储在Milvus，依靠原生INVERTED倒排完成时间/会话过滤，原生hybrid_search+RRF完成混合检索。
优势：无数据双写、一致性高、链路简单、运维成本低、适配Agent长期记忆场景。 - 仅以下场景启用ES+Milvus双库
- 需要正则、通配符、前缀匹配、文本高亮、拼音检索等高级全文能力
- 需要海量元数据聚合统计、报表分析
- 存量业务已有ES体系，无法迁移
双库弊端：需手动双写、自行实现RRF融合、存在数据一致性风险、运维成本翻倍。
八、流式输出整体闭环
- 工具执行阶段：推送结构化SSE事件（工具开始/重试/切换/失败），前端展示加载态
- 全工具链路闭环（成功/兜底/超时）后，LLM统一汇总所有上下文（用户提问+工具入参+结果+异常信息）
- LLM以token粒度流式输出最终答案，保证用户体验流畅
九、核心避坑清单（生产关键） - 禁止时间存储字符串，必须使用Unix时间戳，否则无法区间筛选
- 禁止元数据塞入JSON大字段，高频筛选字段必须独立建倒排索引
- 禁止将会话/时间信息揉进文本向量化，必须结构化精准过滤
- Agent思考完全由LLM生成，禁止代码拼接伪造思考内容
- 工具调用必须做轮次+超时双重限制，杜绝死循环与服务卡死
- 常规记忆场景不上ES，优先Milvus单库架构，降低复杂度
- 混合检索必须双路召回足量候选（Top20+），保证RRF重排效果
十、整体业务最终落地范式 - 存储分层：结构化元数据（筛选）+ 原始文本（展示）+ 双向量（检索）三层隔离
- 检索流程：元数据过滤圈定范围 → 双向量并行召回 → RRF融合 → 时序加权优化
- Agent调度：LLM ReAct推理决策 → Skill/MCP统一调度 → 全链路容错兜底 → LLM汇总流式输出
- 稳定性保障：超时/重试/切换/轮次/熔断/人工兜底六级防护
十一、项目落地具体实践（可直接上线）
本章基于前文整套架构设计，输出标准化、可直接复刻上线的落地实操方案，包含环境配置、字段建库、检索参数、工具调度配置、异常兜底、上线校验全流程，规避理论化内容，全部为生产实操规范。 - 环境与基础依赖落地配置
1.1 核心组件版本规范（生产稳定版）
- Milvus：2.4.x 稳定版（支持稀疏向量、INVERTED倒排索引、Hybrid混合检索）
- 向量模型：BGE-M3（统一生成稠密+稀疏双向量，适配混合检索场景）
- LLM模型：通用对话大模型（支持ReAct格式输出、流式SSE输出）
- 部署环境：Docker/K8s容器化部署，开启服务健康检查、自动重启机制
1.2 全局基础配置（固定生产参数） - 时区统一：全局UTC时间，所有时间存储Unix时间戳（INT64）
- 会话最大轮次：单对话工具调用最大5轮
- 单工具重复调用上限：2次
- 全局会话超时：180s
- 本地Skill单工具超时：5s，MCP远端服务超时：10s
- 重试机制：可重试异常最大3次重试，指数退避策略（1s/2s/4s）
- Milvus集合创建实操（可直接执行）
2.1 建库核心规则
单独创建Agent记忆专属集合，不与业务数据混用，开启数据自动过期清理，规避数据堆积。
2.2 字段&索引创建实操代码（标准化）
Milvus 集合创建核心代码（生产最终版）
from pymilvus import CollectionSchema, FieldSchema, DataType, Collection
1. 定义字段
pk_id = FieldSchema(name="pk_id", dtype=DataType.INT64, is_primary=True, auto_id=True)
content = FieldSchema(name="content", dtype=DataType.VARCHAR, max_length=4096)
dense_vec = FieldSchema(name="dense_vec", dtype=DataType.FLOAT_VECTOR, dim=1024) # BGE-M3稠密向量维度
sparse_vec = FieldSchema(name="sparse_vec", dtype=DataType.SPARSE_FLOAT_VECTOR)
user_id = FieldSchema(name="user_id", dtype=DataType.VARCHAR, max_length=64)
session_id = FieldSchema(name="session_id", dtype=DataType.VARCHAR, max_length=64)
chat_unix_ts = FieldSchema(name="chat_unix_ts", dtype=DataType.INT64)
create_unix_ts = FieldSchema(name="create_unix_ts", dtype=DataType.INT64)
expire_ts = FieldSchema(name="expire_ts", dtype=DataType.INT64)
msg_role = FieldSchema(name="msg_role", dtype=DataType.VARCHAR, max_length=16)
tool_name = FieldSchema(name="tool_name", dtype=DataType.VARCHAR, max_length=32)
2. 构建集合结构
schema = CollectionSchema(
fields=pk_id, content, dense_vec, sparse_vec, user_id, session_id, chat_unix_ts, create_unix_ts, expire_ts, msg_role, tool_name,
description="Agent长期记忆向量集合"
)
3. 创建集合
agent_memory_col = Collection("agent_long_memory", schema=schema)
4. 创建索引（生产核心）
稠密向量HNSW索引
agent_memory_col.create_index(field_name="dense_vec", index_type="HNSW")
稀疏向量倒排索引
agent_memory_col.create_index(field_name="sparse_vec", index_type="SPARSE_INVERTED")
所有筛选字段创建INVERTED倒排索引
filter_fields = "user_id", "session_id", "chat_unix_ts", "expire_ts", "msg_role", "tool_name"
for field in filter_fields:
agent_memory_col.create_index(field_name=field, index_type="INVERTED")
5. 加载集合至内存
agent_memory_col.load()
2.3 数据入库实操规范
- 入库时机：单轮对话结束后异步入库，不阻塞对话响应
- 过期规则：默认记忆留存30天，expire_ts自动计算，Milvus自动清理过期数据
- 数据去重：基于session_id+content+chat_unix_ts做重复校验，避免重复入库
- 混合检索+RRF重排实操流程
3.1 检索前置过滤（必做）
检索优先执行结构化过滤，缩小检索范围，提升速度与精准度，过滤公式固定：
user_id = 目标用户 AND session_id = 当前会话 AND chat_unix_ts > 近30天时间戳
3.2 双向量召回参数（生产固定）
- 稠密向量召回：Top20
- 稀疏向量召回：Top20
- RRF融合参数：k=60（通用平衡场景）
- 最终输出记忆：Top10
3.3 检索后时序优化实操
RRF重排完成后，叠加时间衰减权重，计算公式：
最终得分 = RRF得分 × (1 + 0.3 × (1 - 间隔天数/30))
效果：3天内记忆权重最高，30天记忆权重趋近于基线，实现新记忆优先展示
- Skill/MCP工具调度落地实操
4.1 工具注册规范
- 本地Skill：统一放置固定插件目录，每个插件独立配置config.json（入参Schema、超时、重试次数、功能描述）
- MCP远端服务：启动时自动握手拉取工具列表，缓存至本地内存，失效自动重连
- 所有工具统一注册全局路由，支持LLM通过工具名称精准匹配
4.2 工具调用全流程实操管控
- 接收用户提问，拼接短期对话上下文+近期记忆
- LLM执行ReAct推理，输出Thought思考+Action工具调用参数
- 校验全局轮次、单工具轮次，超限直接终止工具链路
- 执行工具调用，监控超时状态，捕获异常分类处理
- 可重试异常自动指数退避重试，重试耗尽切换备用节点
- 工具结果回填上下文，判断是否继续调用或结束链路
4.3 三级兜底落地触发条件
- 一级兜底：高频查询、工具正常响应超时，优先返回缓存结果
- 二级兜底：服务临时异常、重试全部失败，LLM基于已有信息自主兜底回复
- 三级兜底：高危异常、数据错误、全链路超时，自动生成人工工单流转
- LLM思考与流式输出实操规范
5.1 ReAct输出强制规范
强制要求LLM输出固定双结构，后台严格校验格式，格式错误直接判定推理异常，触发兜底机制：
- Thought：完整自然语言推理过程（需求分析、工具选择理由、参数校验）
- Action：标准JSON结构化工具调用参数，无冗余内容
5.2 流式输出落地步骤
- 工具执行中：推送工具状态SSE事件（开始/重试/切换/失败），前端展示动态加载态
- 工具链路结束：汇总全部上下文信息（提问+入参+结果+异常日志）
- LLM逐Token流式输出最终答案，保证对话流畅性
- 上线校验与问题排查实操清单
6.1 上线必测场景
- 工具死循环测试：验证5轮轮次限制、单工具2次重复限制生效
- 超时测试：验证单工具、全局超时强制终止链路
- 异常重试测试：验证网络异常3次重试+主备切换
- 记忆检索测试：验证时序过滤、混合检索、RRF重排效果
- 兜底机制测试：验证三级兜底逐级触发
6.2 日常排查核心要点 - 记忆检索异常：优先检查时间戳存储格式、倒排索引是否创建、过滤条件是否准确
- 工具调用失败：查看异常分类日志，区分可重试/不可重试/高危异常
- 回答不准：核查双向量召回数量、RRF参数、时序权重配置
- 服务卡顿：检查超时配置、轮次限制、缓存兜底是否生效
- 生产极简落地总结
整套方案落地只需完成四步：标准化建库建索引→配置全局容错参数→接入双向量混合检索+RRF重排→开启ReAct工具调度+三级兜底，即可实现高可用、可迭代、易维护的生产级Agent长期记忆RAG系统。