UFO 离线帮助文档 RAG 实战：用 learner 构建 Faiss 知识索引并在线增强 Agent

UFO 离线帮助文档 RAG 实战用 learner 构建 Faiss 知识索引并在线增强 Agent【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFO本文是一份基于 UFOUFO³: Weaving the Digital Agent Galaxy开源仓库的离线检索增强生成Offline RAG实战指南。它围绕 learner/README.md 的核心流程展开如何把应用帮助文档如 PowerPoint、WeChat、Chrome 的操作手册加工成结构化 JSON 语料通过python -m learner构建 Faiss 向量索引再在在线推理阶段开启RAG_OFFLINE_DOCS让 AppAgent 检索并参考这些离线知识。读完本文你将掌握从帮助文档准备 → 文档集组织 → 索引构建 → 在线启用 → 参数调优的完整闭环并能结合源码理解底层实现原理。一、离线帮助文档 RAG 的整体链路在 UFO 中Agent尤其是 AppAgent面对的是具体桌面应用任务例如如何在 Chrome 中修改用户名这类问题。仅靠基础 LLM 的知识往往不够精准而每次都调用在线搜索又存在延迟与依赖问题。离线帮助文档 RAG 正是为此设计的把应用官方帮助文档或用户自己整理的操作指引预先向量化在推理阶段按需检索作为参考知识注入 Prompt。其完整链路可以拆解为四个环节语料准备将每一条用户请求 → 分步操作指引整理为 JSON 文档索引构建运行python -m learner用 sentence transformer 生成 embedding再用 Faiss 建立向量索引默认落在vectordb/docs/索引注册构建成功后索引路径被写入learner/records.json作为应用名 → 索引路径的映射记录在线检索AppAgent 在推理时通过 OfflineDocRetriever 按应用名匹配索引执行相似度检索并将命中文档注入 Prompt。这条链路让 UFO 可以针对每个应用维护一套专属的本地知识库不依赖外部网络也无需在每次任务中重新加载全部文档。二、Step 1准备帮助文档与元数据2.1 JSON 格式的帮助文档UFO 目前支持json格式的帮助文档源码中已预留xml格式的加载器详见后文。一个标准的帮助文档包含三个顶层字段字段类型含义applicationString该文档所属的应用名称如chromerequestString用户可能会提出的请求描述guidanceString 数组完成该请求的逐步操作指引learner/README.md 中给出的示例以 Chrome 修改用户名为例为{ application: chrome, request: How to change the username in chrome profiles?, guidance: [ Click the profile icon in the upper-right corner of the Chrome window., Click the gear icon labeled Manage Chrome Profiles in the profile menu., In the list of profiles, locate the profile whose name you want to change., Hover over the desired profile and click the three-dot menu icon on that profile card., Select Edit from the dropdown menu., In the Edit Profile dialog, click inside the name field., Delete the current name and type your new desired username., Click Save to confirm the changes., Verify that the profile name is updated in the profile list and in the top-right corner of Chrome. ] }2.2 字段如何被底层消费从源码看json_loader.py 中的JsonLoader.construct_document()会按以下逻辑将 JSON 文件转换为 langchainDocument读取request作为检索的问题page_content将guidance数组按行拼接成完整指引文本构建元数据{title: request, summary: request, text: guidance}。也就是说在线检索时真正与用户请求做语义匹配的是request字段而guidance是命中后作为解决方案注入 Prompt 的内容。因此request应尽量覆盖真实用户会提出的问法它决定了召回质量guidance要写成可直接执行的步骤序列每一条对应一个界面操作Agent 会把它当作参考方案再结合上下文做适配。2.3 其他支持的格式XML 与元数据文件虽然 README 声明当前以json为主但源码的加载器映射表_doc_loader_mapper见 indexer.py同时注册了xml与json两种格式。仓库中 learner/doc_example/ 下提供了 Microsoft XML 格式的样例ppt-copilot.xml及其元数据文件ppt-copilot.xml.meta元数据形如?xml version1.0 encodingutf-8? metadata titleWelcome to Copilot in PowerPoint/title Content-Summary valueLearn how Copilot in PowerPoint for the web can help you create compelling presentations, leveraging the power of AI. / /metadataxml_loader.py 使用UnstructuredXMLLoader提取正文文本并从同目录的.meta文件中读取title与Content-Summary作为检索元数据。这也解释了 README 中每个帮助文档与对应元数据必须放在同一目录的约束来源。三、Step 2组织帮助文档集准备好所有帮助文档后需要将它们统一放入一个文件夹。组织规则只有一条关键约束每个帮助文档与它对应的元数据文件必须放置在同一个目录下。目录结构允许存在子文件夹——utils.find_files_with_extension()见 utils.py会通过os.walk递归遍历整个文档目录因此你可以在根目录下按应用、版本或模块分子目录但同一份文档的正文与元数据不能拆散到不同层级。一个推荐的目录组织方式help_docs/ ├── chrome/ │ ├── change_username.json │ └── clear_cache.json ├── powerpoint/ │ ├── add_slide.json │ └── ... └── wechat/ └── ...四、Step 3构建离线索引4.1 一条命令完成索引构建在已克隆的 UFO 仓库根目录下执行# assume you are in the cloned UFO folder python -m learner --app app_name --docs path_of_the_docs参数说明参数作用示例--app应用名称用于匹配在线 RAG 中的离线索引器PowerPoint、WeChat--docs包含全部帮助文档的文件夹路径/path/to/help_docs--format帮助文档格式默认json可选xmljson--incremental增量更新标志与已有索引合并不加则全量重建--save_path索引保存目录默认./vectordb/docs/./vectordb/docs/其中--app名称的准确性至关重要因为在线阶段会用它来匹配离线索引器匹配机制详见第六节。--docs则替换为包含所有文档的文件夹完整路径。4.2 底层实现Faiss Sentence Transformer命令入口在 learner.py实际工作由 indexer.py 的DocumentsIndexer.create_indexer()完成核心步骤为读取./learner/records.json不存在则初始化为空字典记录各应用已构建的索引路径根据--format从映射表{xml: XMLLoader, json: JsonLoader}中选择对应的BasicDocumentLoader调用construct_document()把全部帮助文档转成 langchainDocument列表通过get_hugginface_embedding()获取 embedding 模型。从 ufo/utils/init.py 可以看到默认模型为sentence-transformers/all-mpnet-base-v2使用langchain_huggingface.HuggingFaceEmbeddings封装调用FAISS.from_documents(documents, embeddings)一次性完成向量化与索引构建若开启--incremental且records.json中已存在该应用的索引则加载旧索引并执行db.merge_from(prev_db)合并见 indexer.py将索引保存到save_path/appos.path.abspath解析为绝对路径并把app - db_file_path写入records.json。构建成功后终端会以彩色日志提示Indexer for app created successfully. Save in path.同时默认目录vectordb/docs/下会出现以应用名命名的 Faiss 索引文件夹。五、Step 4在线推理启用离线 RAG5.1 配置项索引构建完成后还需在 RAG 配置中显式开启离线检索。README 指向ufo/config/config.yaml在当前仓库中该配置已独立为 config/ufo/rag.yaml相关段落为## RAG Configuration for the offline docs RAG_OFFLINE_DOCS: True # Whether to use the offline RAG. RAG_OFFLINE_DOCS_RETRIEVED_TOPK: 1 # The topk for the offline retrieved documents两个核心参数的语义配置项类型默认值说明RAG_OFFLINE_DOCSBooleanFalse是否启用离线帮助文档检索RAG_OFFLINE_DOCS_RETRIEVED_TOPKInteger1离线检索返回的 Top-K 文档数量注意config/ufo/rag.yaml的默认值为False即离线 RAG 默认不启用属于可选增强能力documents/docs/configuration/system/rag_config.md 也明确 RAG 特性均为可选。仓库同时提供了新旧配置迁移工具 ufo/tools/convert_config.py可将旧式配置转换为新结构。5.2 Top-K 如何影响效果RAG_OFFLINE_DOCS_RETRIEVED_TOPK决定每次请求最多注入几条命中文档。调整原则帮助文档写得精简且覆盖精准时1通常足够避免无关文档稀释 Prompt文档较长或请求语义模糊时可适当增大配置文档中建议区间为 12让 Agent 有更多参考候选该值同时是延迟与质量的权衡点——每次检索的文档越多注入 Prompt 的 token 也越多。六、源码级纵深在线检索的调用链与匹配机制6.1 索引路径的注册与读取构建索引后records.json保存的是应用名 - 绝对路径的映射。在线侧ufo/config/init.py 中的get_offline_learner_indexer_config()会读取learner/records.json而 OfflineDocRetriever.get_offline_indexer_path() 遍历所有记录判断key.lower() in self.app_name.lower()——即用应用名字符串的子串匹配来确定使用哪个索引。这意味着如果你在构建时用--app PowerPoint注册索引在线推理时只要当前应用名包含powerpoint子串忽略大小写即可命中该索引。因此 README 特别强调app_name必须准确命名否则会出现构建了索引却在线匹配不上的问题。6.2 从配置到检索的完整调用链AppAgent 初始化时根据配置创建OfflineDocRetriever见 ufo/agents/agent/app_agent.py每次处理请求时调用offline_doc_retriever.retrieve(request, offline_top_k)offline_top_k即来自RAG_OFFLINE_DOCS_RETRIEVED_TOPKRetriever.retrieve() 执行indexer.similarity_search(query, top_k)命中文档通过retrieved_documents_prompt_helper()组装为 Prompt 片段与在线搜索文档一起注入见 app_agent.py。6.3 检索结果的角色定位需要注意检索到的帮助文档被设计为参考而非硬性指令。documents/docs/ufo2/core_features/knowledge_substrate/learning_from_help_document.md 明确指出由于检索结果不一定完全相关Agent 会把它作为计划生成的参考方案再根据实际界面上下文灵活适配而不是机械照搬。七、最佳实践与常见问题7.1 提高召回质量的实践细化request措辞request是相似度检索的查询文本应覆盖目标用户真实提问的措辞习惯必要时为同一操作准备多条不同问法的文档保持guidance步骤原子化每一步对应一个可独立执行的界面动作便于 Agent 直接引用按应用拆分文档集不同应用的帮助文档分开存放、分别构建索引避免检索时跨应用混淆善用增量更新文档持续更新时使用--incremental与旧索引合并避免每次全量重建。7.2 常见问题排查现象可能原因处理方式在线推理不检索离线文档RAG_OFFLINE_DOCS仍为False在 config/ufo/rag.yaml 中设为True构建的索引导航不到--app名称与在线应用名不一致确保app_name定义准确匹配采用子串包含规则忽略大小写索引文件找不到records.json缺失或路径失效确认索引保存目录默认./vectordb/docs/与learner/records.json存在检索结果不理想Top-K 过小或文档质量不高调整RAG_OFFLINE_DOCS_RETRIEVED_TOPK优化request表述7.3 相关参考文档文档集加载与索引实现的完整源码learner/learner.py、indexer.py、json_loader.py、xml_loader.pyRAG 完整配置说明documents/docs/configuration/system/rag_config.md帮助文档学习机制说明documents/docs/ufo2/core_features/knowledge_substrate/learning_from_help_document.md在线检索器实现ufo/rag/retriever.py按照上述四个步骤你就能为任意桌面应用搭建一套完全离线的帮助文档知识库让 UFO 的 Agent 在无网络依赖的情况下依然获得精准的应用操作知识支撑。【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFO创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考