RAG 的价值不在于“给模型外挂一个向量库”，而在于建立一条可维护的知识链路：资料能更新、检索结果能解释、回答质量能评估。对准备把内部文档接入智能体的团队来说，AgentScope RAG 可以作为工程入口，但上线前仍要把解析、切块、检索、权限和评估分别设计清楚。
先判断：你的场景是否真的需要 RAG
RAG（检索增强生成）适合处理模型训练数据之外、且会持续变化的知识，例如产品手册、运维文档、合同条款、客服知识库和团队规范。一次问答通常分成两段：先从知识库召回相关片段，再把问题与片段交给模型生成答案。
它尤其适合以下情况：
- 私有资料不能依赖模型的通用训练记忆；
- 文档更新频繁，不适合每次变化都重新训练模型；
- 回答需要保留文件名、章节或文档编号等溯源信息；
- 团队希望通过替换解析器、嵌入模型或向量库逐步扩容。
如果知识只有几十条固定问答，结构化查询或普通搜索可能更简单；如果任务要求模型学习稳定的表达风格，RAG 也不能完全替代微调。先区分“补充事实知识”和“改变模型行为”，能避免为一个简单问题搭建过重的系统。
AgentScope RAG 的核心链路
一套可维护的 AgentScope RAG 管线可以拆成六个环节：
文档采集 → 解析 → 切块 → 嵌入 → 向量存储 → 检索并生成在原型阶段，可以用文本解析器、按 token 切块的组件和本地向量存储快速验证。接入智能体后，再通过 RAG 中间件把知识检索能力交给 Agent。这里要关注的不是某一段演示代码，而是各环节能否独立替换：
- 解析器决定表格、标题、代码块等结构能否被保留；
- 切块器决定检索单元的语义是否完整；
- 嵌入模型决定问题与文档片段如何映射到向量空间；
- 向量库负责索引、过滤、持久化和扩展；
- 检索策略决定召回数量、过滤条件及是否需要重排；
- 生成阶段负责约束模型依据证据回答，并输出引用信息。
AgentScope 官方 RAG 模块将组件拆为 Reader、Knowledge 与向量存储 Store；知识库提供添加和检索文档的能力，也可把检索方法注册为 Agent 工具。官方文档展示了 QdrantStore 的内存、本地文件和远程服务等存储方式。实际接口会随版本演进，实施时应以项目锁定版本的官方文档与类型提示为准。
切块不是固定填一个数字
切块过小，定义、条件和结论可能被拆散；切块过大，则容易把不相关内容一起送入模型，增加上下文成本并降低检索精度。与其照抄一个“通用最佳值”，不如先按文档结构选择策略：
| 资料类型 | 建议起点 | 需要保留的信息 |
|---|---|---|
| Markdown、产品文档 | 按标题和段落切分 | 标题层级、章节路径 |
| 合同、制度文件 | 按条款切分 | 条款号、版本、发布日期 |
| 代码仓库 | 按类、函数或模块切分 | 文件路径、符号名、语言 |
| 扫描 PDF | 先做版面与 OCR 处理 | 页码、表格、图片说明 |
| 普通长文本 | 按 token 切分并少量重叠 | 文件名、段落位置 |
建议从一组真实问题出发做小规模实验：比较不同块大小、重叠量和切分方式下，正确证据能否进入前几条结果。中文、代码和表格的 token 密度不同，不能只用字符数推断上下文占用。
从本地演示走向生产环境
原型常用内存向量库，进程退出后数据就消失；生产环境至少要补齐持久化、更新和恢复机制。选择本地持久化还是远程向量服务，可以按规模和运维能力判断：
- 单机验证或小型内部工具，可先使用本地持久化，减少外部依赖；
- 多实例服务需要共享索引时，应使用可远程访问的向量数据库；
- 文档量大、更新频繁时，要设计增量写入、删除和重建索引流程；
- 需要按部门、项目或客户隔离时，应把租户标识写入元数据，并在检索端强制过滤。
文档更新不能只做“重新上传”。更稳妥的流程是为文档记录来源、版本、内容摘要和更新时间：内容未变则跳过，内容变化则先删除旧版本对应的块，再写入新版本。这样可以减少重复片段和版本冲突。
权限控制也不应依赖提示词。模型被告知“不要回答无权内容”并不等于完成授权；检索前就要根据当前用户身份过滤可见文档，模型只能接触已经通过授权检查的片段。
检索模式怎么选
把检索作为固定步骤，还是让 Agent 自主决定，取决于业务对稳定性和成本的取舍。
通用检索适合知识库问答、客服和制度查询。每轮回复开始时固定检索，流程容易审计，也便于稳定获得证据，但简单寒暄同样会触发检索，增加延迟和上下文开销。
智能体自主检索适合工具较多、问题类型复杂的任务。模型可以判断何时检索并改写查询，流程更灵活，但对模型的推理和工具调用能力要求更高，还要评估“该检索时没有检索”及重复调用的问题。
无论选择哪种模式，都应设置清晰的失败路径：没有足够证据时说明资料不足，而不是让模型用通用知识补齐；召回片段互相冲突时，优先展示版本和日期，让用户确认有效资料。
上线前要测什么
只看一两个演示问题命中，并不能说明系统已经可用。可以建立一份小型评测集，每个问题至少标注预期答案和对应证据，再持续记录以下指标：
- 召回质量：正确证据是否出现在候选结果中；
- 排序质量：正确证据是否排在足够靠前的位置；
- 忠实度：答案是否能由检索片段支持；
- 拒答质量：资料缺失时是否避免编造；
- 引用准确性：文件名、章节和版本是否对应实际证据；
- 延迟与成本：解析、嵌入、检索、重排和生成分别耗时多少。
调参时一次只改变一个变量，例如块大小、召回数量或重排方式，否则很难判断改进来自哪里。生产日志应记录问题、检索条件、命中文档 ID、得分、最终上下文和模型结果，同时对敏感字段做脱敏并设置保留周期。
一条更稳妥的落地路径
对个人开发者和小团队，可以按四个阶段推进：
- 选取少量高质量文档，完成解析、切块、入库和检索闭环；
- 用真实问题构建评测集，先验证“能否找到证据”，再接入大模型；
- 增加引用、拒答、版本管理和增量更新；
- 最后再处理多租户、远程向量库、监控与成本优化。
这条路径能把问题拆开：检索不准时先修知识管线，证据正确但回答偏离时再调整提示和生成策略。RAG 项目真正的门槛通常不是调用一个框架接口，而是持续维护资料质量、访问权限和可重复的评估体系。