parabricks

Parabricks

用途

使用此技能，发现适合的 NVIDIA Parabricks pbrun 命令、评估运行时准备情况，并为各个工具生成与版本相符的命令指南。

不要将此技能用于检查完整工作流、规划加速方案或连接可选 GPU 分支。对于管道级任务，请使用 genomics-workflow-acceleration。

何时使用此技能

• 哪个 pbrun 工具适合用户的数据和目标
• GPU、驱动程序、Docker、容器、存储或安装的准备情况
• 特定 Parabricks 工具的命令格式、标志和验证
• 参考文件/索引兼容性，以及 CPU 选项到 Parabricks 选项的转换
• 排查单个 Parabricks 命令或工具系列的问题
• 关于指定 pbrun 工具的仅规划或“不要运行”类问题（例如参考文件/索引兼容性、输出命名或标志有效性）。请使用此技能的参考资料回答；不要因为不会执行任何操作就跳过此技能。

前提条件

• 命令指南： 阅读参考资料或生成命令不需要 Parabricks/NGC 凭据，也不需要本地 GPU/容器运行时。
• 准备情况检查辅助工具： 需要被检查的主机上安装 Bash 和 GNU coreutils timeout（或 gtimeout）。缺少运行时组件时会报告准备情况缺口；若没有超时工具，则会在运行探测前退出。
• STAR 转换辅助工具： 需要 Python 3.7 或更高版本，仅使用标准库。不需要 GPU 或 Parabricks 安装。
• 执行： 文档中的 Docker 命令需要受支持的 Linux 主机、内存充足的 NVIDIA GPU、兼容的 NVIDIA 驱动程序、Docker、NVIDIA Container Toolkit，以及访问所选 Parabricks 镜像的权限。拉取镜像时，可能需要使用 NGC API 密钥向 nvcr.io 进行身份验证。有关特定版本的要求和检查，请参阅 runtime-environment.md。

工具范围：读取此技能的参考资料和用户提供的清单；仅写入用户要求的命令文件。使用随附的辅助工具进行转换或经授权的主机检查。文档查询使用 docs.nvidia.com；仅在获得授权的容器执行期间，才使用所选镜像仓库访问镜像。 这些说明不会授予工具权限；主机的权限策略仍适用于 shell、文件、网络以及可选的文档 MCP 访问。

输入

以用户明确提供的参数和清单为准；只有在不冲突时才使用先前上下文。转换清单前，先读取指定清单。提供命令指南时，确认检测类型、输入路径、参考文件/索引来源、输出和目标版本。只询问会影响答案的缺失信息；将尚未确定的模板值标记为占位符。必需输入是所选工具的读取/参考参数和输出参数。该工具支持时，可选输入包括区间、资源包、日志和调优参数；不要为了填充模板而凭空补充这些信息。仅涉及运行时的问题不需要样本元数据。用户提供部署路径，并不代表有权探测本地数据或硬件。

如果用户不确定该使用哪个工具，请先查看下面的工具参考索引，然后加载匹配的 references/pbrun-<tool>.md 文件。

限制

此技能用于选择和指导 Parabricks 命令。它不会安装 Parabricks、推断缺失的样本元数据、保证输出一致性、提供临床解读，也不会在缺少基准测试数据时承诺确切的运行时间。

指令

1. 确认请求所针对的版本。选项参考涵盖 v4.7.1；其他版本的示例会注明版本。软件版本与镜像标签可能不同：NVIDIA 的 4.7.1 镜像标签为 4.7.1-1。保留用户已核实的镜像选择；有关通用的启动和验证约定，请参阅 command-conventions.md。
2. 对请求分类：
   • 运行时 → runtime-environment.md
   • 工具发现 → 工具参考索引（下文）
   • 特定命令 → 对应的 references/pbrun-<tool>.md。在进行任何网页搜索或 MCP 查询之前，先阅读该文件；仅在参考资料无法确定版本相关细节时，才使用搜索或查询进行核实。
3. 将特定工具的映射与 shared-options.md 中 Tools 列包含所选命令的行合并。对于 STAR 参数数组或多泳道批次，请使用本地的 转换辅助工具；它会保留令牌，并报告未映射的语义，且不会执行工作负载。
4. 生成命令前，先收集缺失的生物学和文件系统上下文。
5. 返回所请求的命令或工件，并说明尚未解决的假设。对于仅限规划的工作，请依据参考资料和已提供的事实检查命令文本。文件系统、容器和输出检查仅适用于已获授权的执行。不要把命令准备变成就绪状态检查。

可用脚本

请在包含此文件的技能目录中运行这些脚本；路径均相对于该目录。请参阅上文的辅助工具先决条件。

脚本	用途	参数
scripts/check_parabricks_runtime.sh	检查执行主机；报告缺项，但不安装任何内容	--path DIR（可重复指定）、--format text|json、--timeout SECONDS；容器探测需要使用 --run-container-check 或 --run-parabricks-check，并搭配 --parabricks-version TAG / --parabricks-image IMAGE
scripts/translate_star_to_parabricks.py	将明确指定的 STAR 参数数组转换为已审核的命令草稿	--input FILE 或 --input -；请求和输出架构

输出格式

对于解释，请给出决策、完整命令以及尚需进行的检查。 对于文件请求，请按指定路径和架构写入文件，然后回读并根据输入清单验证工件。报告所有作业 ID、被省略的选项以及尚未解决的输出约定。不要用说明性示例替换已提供的值。运行时辅助工具的 JSON 包含 schema_version、checks 和就绪状态结果；转换器会为每个请求输出 status、draft_argv、command、notes、issues 和 untranslated。

工具参考索引

如果已知命令名称，请直接打开 references/pbrun-<command>.md。 如需选择工具和查找官方手册链接，请使用 tool-index.md。 常见路径：

请求	参考文档
DNA FASTQ 比对 / RNA STAR 转录组分析	fq2bam / rna_fq2bam
现有 BAM 的胚系变异检测 / 肿瘤-正常样本变异检测	haplotypecaller / mutectcaller
Giraffe 图比对	giraffe
STAR-Fusion 迁移	starfusion
重校准 / 应用重校准报告	bqsr / applybqsr
BAM 指标 / 多个指标系列	bammetrics / collectmultiplemetrics
GVCF 索引 / 联合基因分型	indexgvcf / genotypegvcf
Panel-of-normals 准备 / 注释	prepon / postpon
BWA 性能选项	performance

示例

运行环境就绪检查

对于 GPU、驱动程序、Docker、容器、存储或安装相关问题，请阅读 runtime-environment.md，并优先使用：

bash scripts/check_parabricks_runtime.sh --format json

对于已知的输入、输出或临时文件路径，请添加 --path <dir>。仅在用户同意后 运行容器探测。

STAR 转录组分析

python3 scripts/translate_star_to_parabricks.py --input requests.json

使用转录组分析模式准备请求。 使用草稿前，请检查 issues 和 untranslated。工具参考文档会展示 pbrun 部分；共享容器封装说明仅在 command-conventions.md 中记录一次。

故障排除

错误	原因	解决方案
存在多个可能的工具	数据类型或目标说明不充分	询问检测类型、输入、变异检测工具偏好和所需输出；使用工具参考索引
请求精确的标志	选项与版本有关	查看所选工具参考文档、NVIDIA 文档，或运行 pbrun <tool> --help
运行环境问题	GPU、Docker、驱动程序或存储	使用运行环境参考文档和诊断脚本
工具系列不匹配	检测类型或输入类型不明确	路由前确认 DNA/RNA/甲基化/长读长/泛基因组
CUDA 或内存故障	运行环境未就绪或 GPU 内存受限	调整命令标志前先评估运行环境
文档 MCP 不可用	连接、超时或服务端错误	优先使用随附的发布版参考文档；对于尚未解决的事实，回退到官方版本化手册，并标明任何仍未确定之处

防护原则

• 将命令可用性和选项视为与版本有关。
• 不要仅根据命令名称推断精确标志。
• 解释权衡时，不要混淆独立工具与完整流程。
• 不要用 DNA fq2bam 替代 RNA 工具，也不要用胚系变异检测工具替代体细胞变异检测工具。
• 不要虚构样本名称、read group、参考基因组版本、已知位点文件、 模型文件、图资源、容器标签或输出路径。
• 不要安装、升级或修改软件包。将设置命令标记为由用户运行。
• 不要声称 Parabricks 工具可在 CPU 上运行。
• 未经比较运行，不要声称生物学结果或 VCF 结果一致。
• 仅在随附的参考文档无法解决问题时，才使用可选的文档 MCP 服务。如果连接失败，请避免反复执行发现或查找；改用官方手册。切勿声称失败的查找验证了某个选项。访问文档不需要基因组数据或凭据。

主要参考资料

• Parabricks 文档 MCP 服务： https://docs.nvidia.com/clara/parabricks/_mcp/server
• Parabricks 工具索引： https://docs.nvidia.com/clara/parabricks/tool-reference
• 输出准确性和兼容的 CPU 软件版本： https://docs.nvidia.com/clara/parabricks/about-parabricks/software-overview/output-accuracy-and-compatible-cpu-software-versions
• 入门指南： https://docs.nvidia.com/clara/parabricks/get-started
• 概览： https://docs.nvidia.com/clara/parabricks/about-parabricks