nemotron-retrieval-recipesSkill nemotron-retrieval-recipes

名称	nemotron-retrieval-recipes
版本	“0.2.0”
作者	“NVIDIA Nemotron Team noreply@nvidia.com”
开源协议	Apache-2.0 tags: - nemotron - retrieval - fine-tuning - embeddings - reranking metadata:
作者	“NVIDIA Nemotron Team noreply@nvidia.com” tags: - nemotron - retrieval - fine-tuning - embeddings - reranking tools: - Read - Bash - Search
描述	当规划、调试、调优、评估、导出或部署公共Nemotron embed/rerank检索配方时使用。

Nemotron检索配方

调用：$nemotron-retrieval-recipes。

用途

使用这个技能来处理公共的Nemotron嵌入和重排检索配方，无论是对应的源检出（checkout）还是安装包。优先使用当前的检出而不是内存，因为配方CLI、配置、容器和输出路径都在不断变化。每个配方家族仅在配方目录和相应的CLI文件存在后才可用。

这是一个公共产品技能，不是仅限贡献者的指南。它相对于静态文档的价值在于使代理能够将用户的检索失败导向正确的配方家族，将文档与当前检出进行核对，避免意外的长时间运行，保护密钥，并提供具体的预览/执行/运行报告命令。

仅将它用于与公共Nemotron embed 或 rerank 配方流程相关的任务。如果请求是无关的检索理论、通用向量数据库选择、通用基准建议或非配方的Docker/Slurm/NIM故障排除，则用一个简短的范围注释停止，并且不要在该轮中检查配方文件。

安全须知

使用Bash进行仓库范围的检查、帮助、空跑（dry-run）和经用户批准的执行命令。除非用户明确要求，否则不要运行API、GPU、Docker、Slurm、NIM或其他长时间运行的工作。在任一家族的Stage 0 SDG之前，确认用户的数据治理策略允许将语料内容发送到配置的推理端点；否则使用经批准的私有或气隙路径。切勿运行大规模的环境转储或暴露密钥值的命令。优先使用点列表覆盖（dotlist overrides）和配置审查，而不是编辑配方默认值。

来源优先级

按此顺序解决冲突：

1. 当前检出中的配方、CLI、配置和源文件。
2. 本技能内捆绑的参考。
3. 用户提供的文档或保存的片段。
4. 内存。

对于可运行的命令，以当前检出为权威。如果所需的配方目录、CLI命令、配置或环境配置文件缺失，则报告阻碍，而不是猜测。

先决条件

• 仓库环境：uv sync --all-extras 或检出文档中记录的最小相关extra。
• Stage 0 SDG：NVIDIA_API_KEY；切勿要求用户粘贴密钥值。
• 第1-3阶段GPU工作：CUDA/NVIDIA驱动可用且VRAM充足。
• 第4阶段导出：使用TensorRT时需要NeMo导出部署容器。默认的Nemotron 3 Embed配置文件有意跳过导出。
• 第5阶段部署：Docker。默认的Nemotron 3 Embed可以使用检入的vLLM路径并使用backend=vllm，或者兼容的NEMOTRON3_EMBED_NIM_IMAGE并使用backend=nim；Llama Embed和重排部署可能需要NGC访问和NGC_API_KEY。
• 远程执行：根目录env.toml配置文件用于--run或--batch；当远程调度、日志或GPU放置重要时，加载references/remote.md。

说明

1. 识别配方家族。
   • 当涉及嵌入、embed、双编码器、向量搜索、第一级检索、Recall@k低、缺少相关文档、NIM嵌入或nemotron embed时，使用references/embed.md。
   • 当涉及重排、reranker、交叉编码器、第二级检索、召回率尚可但顶部排序差、nDCG低但Recall良好或nemotron rerank时，使用references/rerank.md。
   • 仅当用户同时询问两个家族或询问应选择哪个家族时，才同时使用两个参考。
2. 对于embed，在撰写阶段命令之前选择一个模型配置文件。
   • 当请求的模型不明确时，运行uv run nemotron embed info。
   • 使用-c default用于nvidia/Nemotron-3-Embed-1B-BF16。
   • 使用-c llama用于nvidia/llama-nemotron-embed-1b-v2及其导出路径。
   • 在每个阶段都携带选定的配置文件和artifact_root；切勿混合两个配置文件中的工件。
3. 根据检索失败模式选择要调优的模型族。
   • 当相关文档不存在于候选集中时，倾向于嵌入微调。
   • 当相关文档被检索到但在顶部附近排序不佳时，倾向于重排器微调。
   • 对于生产检索堆栈，请记住这些是互补的：先嵌入，然后对候选进行重排。
4. 识别意图：规划运行、执行阶段、调试失败、调整超参数、解释指标、导出/部署模型、检查配置或提出点列表覆盖建议。
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 ...有效；不确定时通过空跑验证。
   • 在已准备好的检出中，uv run --no-sync ... --help 或 uv run --no-sync ... -d 可以避免在只读检查期间意外同步依赖。
3. 检查请求阶段的前置条件：
   • 仓库环境：uv sync --all-extras或仓库文档中记录的最小相关extra。
   • Stage 0 SDG：NVIDIA_API_KEY。
   • 第1-3阶段GPU工作：CUDA/NVIDIA驱动可用且VRAM充足。
   • 第4阶段导出：使用TensorRT时需要NeMo导出部署容器。默认的Nemotron 3 Embed会跳过此阶段。
   • 第5阶段部署：Docker以及所选后端的镜像和工件契约；默认的Nemotron 3可以使用检入的vLLM镜像而无需NIM凭据。在要求NGC凭据之前，加载家族参考。
   • 远程执行：根目录env.toml配置文件用于--run或--batch；当远程调度、日志或GPU放置重要时，加载references/remote.md。
4. 使用点列表覆盖而不是编辑默认值，除非用户要求可重用的配置更改。保持所选配置文件、工件根目录、序列长度、前缀、池化/归一化、提示模板和硬负例数量在各个阶段保持一致。
5. 除非用户明确要求运行API、GPU、Docker、Slurm、NIM或长时间运行的工作，否则避免启动这些操作。先提供或运行空跑、配置审查和小规模试点。
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>。default用于重排。默认的run目标停在eval；export和deploy是选择性加入的。
8. 评估质量时，在推荐部署之前，在固定留出评估集上比较基线模型。不要用独立的公共基准评估代替配方自身的第3阶段评估。
9. 对于长时间运行的SDG、预处理、微调或评估工作，以会话安全的方式启动进程，并以人类规模的间隔轮询：小规模试验约60秒，较大的运行约120-300秒。
10. 对于失败，定位失败阶段，然后检查阶段配置、预期输入、输出目录以及相应的CLI包装器或run_uv.py。

参考

• references/embed.md：嵌入配方的阶段、命令、默认值、输出路径和操作模式。
• references/rerank.md：重排配方的阶段、命令、默认值、输出路径和操作模式。
• references/evaluation.md：指标解释、比较卫生和部署就绪检查。
• references/remote.md：远程执行配置文件、批处理/运行模式、GPU范围、日志和轮询。

示例

用户问：“召回率尚可，但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。对简短回答省略无关字段。

提供具体的命令和文件路径。说明假设、预期输入、预期输出以及证明下一步行动就绪的最便宜的验证步骤。对于长时间运行的阶段，将预览命令和执行命令分开，以便用户可以仔细选择。

报告空跑或实际运行时，请包含简洁的运行报告：命令、模式、配置、点列表覆盖、输入路径、输出路径、验证信号或指标文件，以及下一个最便宜的检查。在可用时包含检出提交（commit）。