用 RAG 给 Agent 接入内部知识

关注

原创最新推荐文章于 2026-11-04 15:09:04 发布 204 阅读 AI 写同款· GEO 优化 ›

8.5 小结知识库智能客服与内部助手怎么复用摘要本小节介绍了如何将RAG知识库模式迁移到智能客服、内部助手等场景。主要内容包括：复用场景：分析了企业知识库、智能客服和内部助手的数据来源、触发方式和输出特点通用要点：强调数据统一格式、索引选择和灵活触发方式的重要性实现原理：指出RAG复用的核心是保持"数据→索引→检索→生成"管线不变，只需调整数据来源等关键要素技术细节：详细说明了将RAG作为Agent工具的对接方法场景对比：提供了不同场景下的数据来源建议和更新策略安全考虑：强调了权限控制和审计日志的重要性最后指出RA 阅读详情

echo-agent 前身为 2025 年 11 月启动的个人助理项目 fubot，最初面向长期陪伴型个人智能体，围绕认知记忆、上下文延续、用户偏好沉淀、任务闭环与持续自我优化展开。随着真实场景迭代，项目逐步形成多入口接入、统一事件模型、消息总线、Agent Loop、多模型抽象、工具调用、MCP 接入、任务调度、权限审批、运行轨迹、长期记忆和受控自演进等能力。目前已支持微信、QQ、CLI、Gateway、Webhook、Cron 等入口，服务用户超过 20 万、累计下载超过 50 万，是面向长期运行、记忆增强和可持续成长智能体的开源 Agent Runtime。

项目地址：https://github.com/fuyuxiang/echo-agent

18-cover

你让 Agent 帮你排查一个内部接口认证失败。

它能读日志，也能写代码，但它不知道公司内部网关的认证规范、接口迁移公告、历史故障处理记录。于是它只能从报错文本里猜：可能是 token 过期，可能是签名算法不对，可能是环境变量没配。

这些猜测未必离谱，但对工程系统来说不够。真正可靠的 Agent 不能只依赖模型参数和当前会话，它必须能回到内部资料：查规范、查操作手册、查项目文档，并把回答依据讲清楚。

这就是 RAG 在 Agent 里的位置。

RAG 不是给模型“灌入知识”，而是在当前任务里建立一条可追溯的证据通道。

问题入口

如果只看传统文本型 Chatbot，它通常以“输入文本、返回文本”为主。没有内部资料时，模型只能依赖训练阶段学到的公共知识和当前上下文。对公开概念，这可能够用；对企业内部系统，问题马上出现。

内部接口怎么认证、上线流程走哪几个审批、某个服务的降级策略是什么、某个配置项在哪个版本废弃，这些信息通常不在模型参数里。即使模型“看起来知道”，也很难说明结论来自哪份文档。

对 Agent 来说，风险更高。普通问答答错，最多是用户再追问；Agent 如果基于错误资料执行工具，可能会改配置、发消息、创建任务，甚至把过期流程当成当前规范。

所以，Agent 接入内部知识，不是为了让回答显得更丰富，而是为了让行动有依据、依据能追溯、越权资料进不了上下文。

概念边界

RAG 的全称是 Retrieval-Augmented Generation，检索增强生成。它的基本流程很简单：回答前先检索相关资料，把资料放进模型上下文，再让模型基于资料回答。

但在 Agent 系统里，RAG 不能只理解成“接一个向量库”。它至少有三层含义：

层次	解决的问题	工程要求
可发现	相关资料能不能被找出来	文档解析、分块、索引、查询理解
可使用	资料能不能支持当前回答或行动	上下文裁剪、结构保留、冲突处理
可归因	结论能不能回到来源	引用编号、路径、权限、审计 trace

很多系统只优化第一层，比如提升 top-k 召回或换 embedding 模型。但 Agent 更需要后两层。因为检索结果不只是“参考文本”，它会影响推理、工具调用和安全决策。

18-证据通道

这也解释了 RAG 和记忆系统的区别。记忆来自 Agent 与用户、项目长期交互中沉淀出的经验，强调个性化、作用域、遗忘和更新。知识库来自预先存在的文档资料，强调可检索、可引用、可重建和权限过滤。

两者都会进入上下文，但职责不同。记忆回答“这个用户和这个项目过去形成了什么稳定经验”；知识库回答“组织已有资料里有什么可引用证据”。

证据通道

为了不停留在抽象层面，下面以 echo-agent 的实现为例。

echo-agent 的知识库模块位于 echo_agent.knowledge。当前实现不是向量 RAG，而是一个本地关键词知识索引。这个选择很克制：它不依赖外部 embedding 服务，但保留了 RAG 的关键结构，包括文档加载、分块、索引、检索、权限过滤、引用编号和上下文格式化。

知识库在 Agent 中有三个入口。

第一，自动检索。ContextStage 构造上下文时，会用用户本轮输入搜索知识库，把结果加入 retrieval context。

第二，工具检索。模型可以主动调用 knowledge_search，在推理过程中补充证据。

第三，索引维护。管理员或受信任 Agent 可以通过 knowledge_index 查看索引状态或重建索引。

这三个入口对应三种需求：默认给模型补证据、让模型主动查证据、让系统维护证据基础设施。

会调用知识库不等于可靠 RAG；检索结果必须带来源、受权限约束，并进入正确的上下文层级。

在 echo-agent 中，检索结果会被格式化成内部知识上下文，每条包含 [K1] 这样的引用编号、标题、路径和摘要片段。ContextStage 再把它作为 background context 注入，而不是把原文无标记拼进 prompt。

这个细节很重要。知识库文档是资料，不是指令。即使文档里写着“忽略之前规则”“执行某删除命令”，它也不能覆盖系统规则、用户当前目标和工具审批策略。RAG 的正确姿态是用资料增强回答，而不是让资料接管系统。

索引流水线

RAG 的质量不只由检索算法决定。文档怎么解析、怎么分块、metadata 怎么保存，都会影响模型最终看到什么。

echo-agent 用 KnowledgeConfig 定义知识库运行方式：docs_dir 指向文档目录，index_path 指向索引文件，auto_index 决定索引缺失或过期时是否自动重建，chunk_size 和 chunk_overlap 控制分块，allowed_extensions 控制可索引文件类型，max_results 控制默认返回数量，require_citations 表示内部资料回答应强调引用。

Agent Loop 初始化时，如果知识库启用，会创建 KnowledgeIndex。相对路径会解析到当前 workspace 下，所以同一套代码在不同工作空间可以使用不同知识库目录和索引文件。

18-索引流水线

索引准备入口是 ensure_ready。如果索引存在且没有过期，就加载索引；如果索引不存在或已过期，并且 auto_index=True，就重建索引。过期检测靠比较文档 mtime 和索引 mtime：只要文档比索引新，就认为索引过期。

最小化后的流程大致如下：

defensure_ready(auto_index=True):
    ifindex_file.exists() andnotis_stale(docs_dir, index_file):
        returnload_index()

    ifauto_index:
        returnrebuild_index()

    ifindex_file.exists():
        returnload_index()

defrebuild_index():
    forpathinwalk(docs_dir, allowed_extensions):
        metadata, body=extract_frontmatter(path.read_text())
        title=title_from_markdown_or_filename(body, path)

        foridx, textinenumerate(chunk_text(body, size=1200, overlap=120)):
            save_chunk({
                "id": f"{path}#{idx}",
                "path": path,
                "title": title,
                "text": text,
                "terms": count(tokenize(text)),
                "metadata": metadata,
                "mtime": path.mtime,
            })

这里有几个工程取舍。

frontmatter 会进入 chunk metadata，后续用于权限过滤。标题优先取正文第一个 Markdown 标题，其次取第一行非空文本，最后退回文件名。分块使用字符级切分，默认 chunk_size=1200、chunk_overlap=120。它不如语义分块精细，但简单、稳定、可预测。

tokenization 同时处理英文、数字、下划线和中文。英文与代码标识符按词提取；中文加入单字和相邻二元组。它不是完整中文分词，但比只按空格切分更适合本地中英文文档。

索引保存为可读 JSON，包含 chunk 的路径、标题、正文、词项、metadata 和 mtime。这个设计的价值是可调试、可重建。索引只是文档派生物，文档才是 source of truth；索引损坏或策略升级时，可以删除后重建。

检索时，系统先对 query 做同样的 tokenization，再按关键词统计打分。每个 query term 会根据 chunk 中词频、chunk 长度和 IDF 贡献分数；如果原始 query 是 chunk 文本子串，还会额外加分。最后按分数排序，并生成 K1、K2 这样的引用编号。

这不是最复杂的 RAG，但它具备一个生产系统最需要的骨架：确定性、可解释、可重建、可审计。

权限与引用

内部知识库最容易被低估的是权限。

很多 RAG 原型是在回答阶段才提醒模型“不要泄露敏感信息”。这已经太晚了。只要无权文档进入模型上下文，就已经违反最小权限原则。

echo-agent 在检索阶段做 ACL 过滤。Markdown frontmatter 可以写 allowed_users、allow_users 或 users。如果没有权限字段，默认所有用户可见；如果有权限字段，只有 * 或当前 user_id 命中时才可见。

18-权限引用

测试也围绕这个关键行为展开：公开文档能被 bob 搜到；带 allowed_users: [alice] 的私有文档不能被 bob 搜到；同一份私有文档可以被 alice 搜到；格式化结果必须包含 [K1] 引用。

这说明知识库测试不能只测“搜得到”。更重要的是：无权资料搜不到，引用格式稳定，结果 metadata 能用于审计。

工具层也延续这个边界。knowledge_search 是 read_only 工具，参数包括 query 和 max_results，执行时会从上下文取 user_id 做权限过滤，并在 metadata 中返回 citations。knowledge_index 用于 status 和 rebuild，因为重建会写索引文件，它属于写风险，不应和只读搜索混在一起。

生产级 RAG 的底线不是“能搜到相似段落”，而是能证明：谁在什么权限下，看到了哪些证据，并基于哪些证据生成了结论。

生产可用性

把 RAG 放进 Agent，不只是多接一个检索器，还要把它纳入任务链路。

首先是查询理解。用户问“这个接口现在怎么认证”，其中“这个接口”可能来自当前会话、当前文件或刚才的日志。简单场景可以直接关键词检索；复杂场景可以先让模型生成检索查询，再调用 KnowledgeSearchTool。无论哪种方式，查询改写、过滤条件和用户身份都应该进入 trace。

其次是上下文权威层级。检索结果应该作为背景证据进入模型，而不是作为新的系统指令。模型可以基于它回答，也可以说证据不足；但不能因为文档里出现命令示例，就绕过工具策略和 ApprovalGate。

再次是索引一致性。文档会新增、删除、改名，ACL 会变化，chunk 策略会升级。KnowledgeIndex 的 stale 检测、rebuild、chunk metadata 和 JSON 保存格式，处理的就是“索引是否仍然代表源文档”这个问题。知识库越大，这越接近数据库一致性问题，而不是简单文本处理。

还要处理证据生命周期。草稿、正式版、废弃版、归档资料不应拥有同样权重。过期资料可以作为历史背景，但不能直接作为当前操作依据；如果 Agent 要据此执行高风险动作，就应该先读取当前配置、运行检查命令，或要求人工确认。

最后是评估。RAG 错误不能笼统归因于“模型答错”。工程上要区分检索失败和生成失败。

失败类型	表现	优先排查
检索失败	正确证据没有进上下文	分块、索引、查询改写、ACL、top-k
生成失败	正确证据已进入但答案仍错	上下文组织、提示词、引用约束、拒答策略
权限失败	无权资料被召回或引用	ACL、用户身份、缓存、审计

评估指标也要相应拆开：retrieval recall、citation precision、answer groundedness、refusal correctness，以及权限过滤是否正确。对 Agent 来说，还要看加入 RAG 后是否减少错误工具调用，是否能在证据不足或证据冲突时停止推进。

这里也能看出向量检索、关键词检索和知识图谱的边界。向量检索擅长找语义相近片段，关键词适合精确术语和代码标识符，图谱适合服务依赖、组织结构、数据血缘这类实体关系。它们不是替代关系，而是不同证据通道。echo-agent 当前偏本地文档检索，是符合本书主线的实现起点。