nemotron-retrieval-recipes

Nemotron 检索方案

调用方式：$nemotron-retrieval-recipes。

用途

使用此技能处理源代码检出目录或已安装软件包中的公开 Nemotron 嵌入和重排检索方案。优先以当前检出内容为准，而不是依赖记忆，因为方案 CLI、配置、容器和输出路径都在积极变更。只有在方案目录和匹配的 CLI 文件均存在时，才将相应方案系列视为可用。

这是面向公众的产品技能，并非仅供贡献者使用。相较于静态文档，它的价值在于引导 Agent 将用户的检索故障归入正确的方案系列，使文档与当前检出内容保持一致，避免意外启动长时间运行的任务，保护机密信息，并提供具体的预览、执行和运行报告命令。

仅将它用于与公开 Nemotron embed 或 rerank 方案流程相关的任务。如果请求涉及无关的检索理论、通用向量数据库选择、通用基准测试建议，或非方案相关的 Docker/Slurm/NIM 故障排查，请以简短的范围说明结束本轮，不要检查方案文件。

安全说明

使用 Bash 进行仓库范围内的检查、查看帮助、试运行和用户批准的执行命令。除非用户明确要求，否则不要运行 API、GPU、Docker、Slurm、NIM 或其他长时间运行的任务。切勿运行会广泛转储环境信息或泄露机密值的命令。优先使用 dotlist 覆盖和检查配置，而不是编辑方案默认值。

来源优先级

冲突时按以下顺序处理：

1. 当前检出内容中的方案、CLI、配置和源文件。
2. 此技能中附带的参考资料。
3. 用户提供的文档或保存的片段。
4. 记忆。

对于可运行命令，以当前检出内容为准。如果缺少必需的方案目录、CLI 命令、配置或环境配置文件，应报告阻碍，而不是猜测。

先决条件

• 仓库环境：uv sync --all-extras，或当前检出内容文档中最相关的最小 extra。
• Stage 0 SDG：NVIDIA_API_KEY；切勿要求用户粘贴机密值。
• Stage 1-4 GPU 任务：需要 CUDA/NVIDIA 驱动可用且 VRAM 充足。
• Stage 4 导出：使用 TensorRT 时需要 NeMo Export-Deploy 容器。
• Stage 5 部署：Docker、NGC 访问权限和 NGC_API_KEY。
• 远程执行：使用 --run 或 --batch 时需要根目录下的 env.toml 配置；若涉及远程调度、日志或 GPU 分配，请加载 references/remote.md。

说明

1. 确定方案系列。
   • 对于嵌入、embed、bi-encoder、向量搜索、第一阶段检索、Recall@k 偏低、缺少相关文档、NIM 嵌入或 nemotron embed，请使用 references/embed.md。
   • 对于 rerank、重排器、cross-encoder、第二阶段检索、召回率可接受但顶部排序较差、Recall 良好但 nDCG 偏低，或 nemotron rerank，请使用 references/rerank.md。
   • 只有在用户询问两个系列，或询问应选择哪个系列时，才同时使用两个参考资料。
2. 根据检索故障模式确定要调优的模型。
   • 如果相关文档未出现在候选集中，优先微调嵌入模型。
   • 如果已检索到相关文档，但它们在顶部附近的排序不佳，优先微调重排器。
   • 对于生产环境中的检索技术栈，请记住这两者互为补充：先 embed，再对候选项进行 rerank。
3. 确定意图：规划运行、执行某个阶段、调试故障、调优超参数、解读指标、导出/部署模型、检查配置，或提出 dotlist 覆盖方案。
4. 行动前检查当前公开接口：
   • 方案文件：src/nemotron/recipes/<embed|rerank>/
   • CLI 文件：src/nemotron/cli/commands/<embed|rerank>/
   • 默认配置：src/nemotron/recipes/<family>/stage*/config/default.yaml
   • 帮助和试运行：uv run nemotron <family> --help、uv run nemotron <family> <stage> -c default -d

安全工作流

1. 只收集与任务相关的上下文：语料库路径、现有 SDG/训练/评估数据、目标阶段范围、输出目录、检查点路径、执行模式、GPU ID，以及所需密钥是否已配置。绝不要要求用户粘贴密钥值。
2. 先进行成本较低的检查，再执行成本较高的工作：
   • uv run nemotron <family> --help
   • uv run nemotron <family> <stage> --help
   • uv run nemotron <family> <stage> -c default -d
   • uv run nemotron <family> run -c default -d --from <stage> --to <stage>
   • run --help 可能不会显示继承的 -c 和 -d 选项，尽管 run -c default -d ... 可以正常运行；不确定时，请通过运行试运行来验证。
   • 在已准备好的检出目录中，执行 uv run --no-sync ... --help 或 uv run --no-sync ... -d，可避免只读检查期间意外同步依赖。
3. 检查请求阶段的前置条件：
   • 仓库环境：uv sync --all-extras，或使用仓库文档说明的最小相关 extra。
   • 阶段 0 SDG：NVIDIA_API_KEY。
   • 阶段 1-4 GPU 工作：CUDA/NVIDIA 驱动是否可用，以及 VRAM 是否充足。
   • 阶段 4 导出：使用 TensorRT 时需要 NeMo Export-Deploy 容器。
   • 阶段 5 部署：Docker、NGC 访问权限和 NGC_API_KEY。
   • 远程执行：--run 或 --batch 需要根目录中的 env.toml 配置文件；涉及远程调度、日志或 GPU 分配时，加载 references/remote.md。
4. 除非用户要求可复用的配置更改，否则使用点列表覆盖项，而不要编辑默认值。确保各阶段的序列长度、前缀、池化/归一化、提示词模板和困难负样本数量保持一致。
5. 除非用户明确要求运行，否则不要启动 API、GPU、Docker、Slurm、NIM 或长时间运行的作业。优先提供或执行试运行、配置审查和小规模试点。
6. 如果用户指定了 GPU ID，请为每个阶段的命令设置 CUDA_VISIBLE_DEVICES=<ids>。
7. 进行多阶段本地运行时，优先使用 uv run nemotron <family> run -c default --from <stage> --to <stage>。默认的 run 目标会在 eval 阶段停止；export 和 deploy 需显式启用。
8. 评估质量时，在建议部署前，先使用固定的留出评估集与基础模型进行比较。不要用单独的公开基准评估替代该方案自身的阶段 3 评估。
9. 对于长时间运行的 SDG、数据准备、微调或评估工作，以适合会话安全的方式启动进程，并以符合人工监控节奏的间隔轮询：小规模试点约每 60 秒一次，较大规模运行约每 120-300 秒一次。
10. 遇到故障时，加载 PITFALLS.md，确定失败阶段，然后检查该阶段的配置、预期输入、输出目录，以及对应的 CLI 包装器或 run_uv.py。

参考资料

• references/embed.md：嵌入方案的阶段、命令、默认值、输出路径和操作模式。
• references/rerank.md：重排方案的阶段、命令、默认值、输出路径和操作模式。
• references/evaluation.md：指标解读、比较规范和部署就绪情况检查。
• references/remote.md：远程执行配置文件、批处理/运行模式、GPU 作用域、日志和轮询。
• PITFALLS.md：SDG、数据准备、训练、评估、导出、部署和 CLI 设置中常见故障及恢复方法。

示例

用户问：“召回率还不错，但 nDCG 很差，正确段落排在第 40 位左右。我应该调整嵌入模型还是重排模型？”

加载 references/rerank.md 和 references/evaluation.md，说明召回率尚可但前列排序较差，表明应调整重排器，然后提供训练前的低成本预览。

uv run nemotron rerank run -c default -d --from prep --to eval

故障排查

遇到故障时，先加载 PITFALLS.md。确定失败阶段，然后检查该阶段的配置、预期输入、输出目录，以及对应的 CLI 包装器或 run_uv.py。

限制

• 捆绑的参考资料是精简快照；执行前，请根据当前检出版本核实命令、标志、默认值和输出路径。
• 此技能不提供数据集、检查点、凭据、GPU 算力、Docker 镜像或 NIM 服务。

输出风格

在提供规划或调试建议时，如有帮助，请采用以下格式：Decision、Why、Required inputs、Preview command、Execution command、Avoid 和 Next step。简短回答中可省略不相关的字段。

提供具体命令和文件路径。说明假设、预期输入、预期输出，以及能证明下一步已就绪的最低成本验证方法。对于耗时较长的阶段，请将预览命令与执行命令分开，让用户自行决定是否执行。

报告试运行或实际运行时，请附上简明的运行报告：命令、模式、配置、dotlist 覆盖项、输入路径、输出路径、验证信号或指标文件，以及下一项最低成本检查。若能获取检出版本的提交信息，也请一并提供。