nemotron-retrieval-recipes

Nemotron 检索方案

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

用途

使用此技能，在源码检出目录或已安装的软件包中处理公开的 Nemotron 嵌入与重排检索方案。优先依据当前检出目录，而非记忆，因为方案 CLI、配置、容器和输出路径都在持续变化。只有在方案目录和对应的 CLI 文件均存在时，才将该方案系列视为可用。

此技能面向公开产品，并非仅供贡献者使用。相较于静态文档，它的价值在于帮助 Agent 将用户的检索故障路由到合适的方案系列，将文档与当前检出目录中的内容核对一致，避免意外启动长时间运行的任务，妥善保护机密，并提供具体的预览、执行和运行报告命令。

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

安全说明

使用 Bash 执行仓库范围内的检查、帮助、试运行以及用户批准的执行命令。除非用户明确要求，否则不要运行 API、GPU、Docker、Slurm、NIM 或其他长时间运行的任务。在任一系列的 Stage 0 SDG 之前，确认用户的数据治理政策允许将语料内容发送到已配置的推理端点；否则使用获批的私有或气隙隔离路径。绝不运行会广泛转储环境或暴露机密值的命令。优先使用 dotlist 覆盖项并审查配置，而不是修改方案默认值。

来源优先级

遇到冲突时，按以下顺序处理：

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

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

先决条件

• 仓库环境：uv sync --all-extras，或当前检出目录文档中说明的最小相关 extra。
• Stage 0 SDG：NVIDIA_API_KEY；绝不要要求用户粘贴机密值。
• Stage 1–3 GPU 工作：需有 CUDA/NVIDIA 驱动，并具备足够的 VRAM。
• Stage 4 导出：使用 TensorRT 时需要 NeMo Export-Deploy 容器。默认的 Nemotron 3 Embed 配置会刻意跳过导出。
• Stage 5 部署：需要 Docker。默认的 Nemotron 3 Embed 可以使用仓库中已提交的 vLLM 路径，并设置 backend=vllm；也可以使用兼容的 NEMOTRON3_EMBED_NIM_IMAGE，并设置 backend=nim。Llama Embed 和 rerank 部署可能需要访问 NGC 和 NGC_API_KEY。
• 远程执行：使用 --run 或 --batch 时需要根目录的 env.toml 配置文件；涉及远程调度、日志或 GPU 分配时，加载 references/remote.md。

说明

1. 确定配方系列。
   • 对于 embedding、embed、bi-encoder、向量搜索、第一阶段检索、Recall@k 偏低、缺少相关文档、NIM embeddings 或 nemotron embed，使用 references/embed.md。
   • 对于 rerank、reranker、cross-encoder、第二阶段检索、召回率尚可但排名靠前的顺序不佳、Recall 良好但 nDCG 偏低，或 nemotron rerank，使用 references/rerank.md。
   • 仅当用户同时询问两个系列，或询问应选择哪个系列时，才同时使用两份参考文档。
2. 对于 embed，在编写各阶段命令前，先选择一个模型配置。
   • 如果请求中未明确模型，运行 uv run nemotron embed info。
   • 对于 nvidia/Nemotron-3-Embed-1B-BF16，使用 -c default。
   • 对于 nvidia/llama-nemotron-embed-1b-v2 及其导出路径，使用 -c llama。
   • 在每个阶段沿用所选配置和 artifact_root；绝不能混用两个配置的产物。
3. 根据检索失败模式选择要调优的模型系列。
   • 如果候选集中缺少相关文档，优先微调 embedding。
   • 如果已检索到相关文档，但它们在靠前位置的排序不佳，优先微调 reranker。
   • 对于生产检索栈，请记住两者互为补充：先 embed，再对候选项进行 rerank。
4. 确定意图：规划运行、执行阶段、调试故障、调优超参数、解读指标、导出／部署模型、检查配置，或提出 dotlist 覆盖项。
5. 操作前检查当前公开接口：
   • 配方文件：src/nemotron/recipes/<embed|rerank>/
   • CLI 文件：src/nemotron/cli/commands/<embed|rerank>/
   • 配置：src/nemotron/recipes/<family>/stage*/config/<profile>.yaml
   • 帮助和试运行：uv run nemotron <family> --help、uv run nemotron <family> <stage> -c <profile> -d

安全工作流

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

参考文档

• references/embed.md：embedding 配方阶段、命令、默认值、输出路径和操作模式。
• references/rerank.md：rerank 配方阶段、命令、默认值、输出路径和操作模式。
• references/evaluation.md：指标解读、比较规范和部署就绪检查。
• references/remote.md：远程执行配置、batch/run 模式、GPU 限定、日志和轮询。

示例

用户提问：“Recall 还不错，但 nDCG 很差，正确段落大约排在第 40 位。我应该调优 embed 还是 rerank？”

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

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

故障排查

定位失败的阶段，然后检查该阶段的配置、预期输入、输出目录，以及对应的 CLI 封装脚本或 run_uv.py。

限制

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

输出风格

在提供规划或调试建议时，酌情采用以下结构：Decision、Why、Required inputs、Preview command、Execution command、Avoid 和 Next step。对于简短回答，省略不相关的字段。

提供具体的命令和文件路径。说明假设、预期输入、预期输出，以及能够证明下一步已就绪的最低成本验证步骤。对于耗时较长的阶段，将预览命令与执行命令分开，让用户可以审慎选择。

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