nemo-retriever

nemo-retriever

retriever CLI 可将文件夹中的 PDF 建立索引并写入 LanceDB（retriever ingest），还可提供矢量搜索（retriever query）。对于任何需要跨文件夹中的 PDF 搜索或回答问题的任务，请使用此 CLI——不要编写自定义 RAG。

不止支持 PDF，也不止支持语义搜索。 retriever ingest 还支持图像、Office、HTML、TXT、音频和视频——各格式的操作说明见 references/setup.md，安装所需的额外组件（[multimedia]、libreoffice、ffmpeg）见 references/install.md。对于非语义操作——页面筛选、带引文的逐字引用、语料库级聚合、图表／图像说明文字命中——请参阅 references/query.md。处理非 PDF 输入时，不要退回使用原生 Read/Grep/Python。

何时使用

当任务交给你一个报告文件夹，并要求查找某个具体数值——例如收入或利润率数据、10-K 中的一个行项目、一段引文或一个表格单元格——尤其是还要求提供可引用的来源页码时，就该使用这个工具。使用 retriever ingest 为语料库建立一次索引，然后每个问题只需调用一次 retriever query，即可获得数值、来源文档和页码。

• 适用场景： 文档目录；多个文件；年度报告／10-K／财务申报文件；任何非纯文本格式（PDF、扫描图像、Office、HTML、音频、视频）；需要语义匹配、跨文档比较或页面级引用的问题。
• 不适用场景： 单个纯文本或 Markdown 文件、编辑文件或浏览网页。

即使文件夹看起来可以用 grep 搜索，也值得使用。 grep／pdftotext 可以查找字面字符串，但在这类任务中往往会漏掉关键信息：搜索“研发支出”时，无法匹配标题为“研究与开发费用”的表格；它们无法读取扫描图像 PDF；也不会告诉你该引用哪一页；而当语料库中有多个相似数值时——例如上年度数据、初步数据或其他公司的行项目——字符串搜索很容易返回错误结果。Retriever 按含义排序，并为每条命中保留页码和来源，因此你可以选出正确数值，而不是第一个匹配项。

索引只需建立一次，之后会缓存——首次处理（需要几分钟）后，后续问题的成本都很低，因此即使只查找一个需要引用的数值，通常也值得使用。

安装（如果缺少 retriever）

如果 command -v retriever 没有返回任何内容，请先按照 references/install.md 安装 NeMo Retriever Library。安装过程会输出 RETRIEVER_VENV=<path>；在此技能的所有示例中（setup、query、troubleshooting 和 CLI 参考），将 <RETRIEVER_VENV> 替换为该路径。

工作流 — 阅读当前阶段的参考文档，然后执行

回合类型	阅读一次	然后执行
设置回合（首轮——./lancedb/nv-ingest.lance 不存在）	references/setup.md	建立索引
查询回合（后续每一轮——用户提出问题）	references/query.md	调用一次 retriever query
出现错误或返回空结果	references/troubleshooting.md	执行指定的恢复操作；不要自行发挥

完整的 retriever ingest／retriever query CLI 规范见 references/cli/ingest.md 和 references/cli/query.md。常规回合无需查看这些文档——<RETRIEVER_VENV>/bin/retriever <subcommand> --help 更快捷。

对混合文件夹建立索引前，先盘点扩展名（find <dir> -name '*.*' | sed 's/.*\.//' | sort -u）——--input-type=auto 会静默跳过所有不在支持范围内的文件类型。请参阅 references/troubleshooting.md 中的“Unsupported file types”。

硬性限制（适用于每一轮）

• 设置轮次：用一条 shell 命令构建索引（见 references/setup.md）。索引生成后立即停止。
• 查询轮次：最多调用 2 次 Bash——1 次 retriever query，+ 可选的 1 次定向文本提取（见 references/query.md）。回复后立即停止。
• **工具调用之间不要叙述。**你在调用之间输出的词元会成为后续每一轮的输入和缓存输入，导致成本呈二次方增长。从阅读摘要直接转到编写 JSON 文件。
• 禁止：TodoWrite、Glob、Grep、对整个 PDF 执行 Read、重新运行设置、启动子 Agent、推测性的“确认”调用。

耗时较长的查询轮次（调用工具 5 次以上、缓存读取词元超过 1M）成本约为规范轮次的 5 倍，而且几乎总是仍然会给出错误答案。不完整地作答，也胜过超时。