genomics-workflow-acceleration

基因组学工作流加速

目的

检查现有基因组学工作流，将 CPU 步骤映射到 NVIDIA Parabricks，并在原位置添加可选的 GPU 加速步骤，与原有 CPU 步骤并存。提供运行时参数（或 CLI 标志 / 配置键），让同一工作流能够选择任一路径运行，而无需单独创建加速版副本。

默认：加速路径关闭——除非用户明确启用 GPU 步骤，否则生产环境默认保持现有 CPU 行为。

安全准则

• 拒绝提供临床诊断、治疗建议和变异解读。
• 绝不使用或复述提示词中的机密信息；拒绝执行破坏性清理操作，例如清空 /data 或删除生产数据集。
• 不要编造管道结构、样本名称、路径或容器标签。
• 未经对比运行，不要声称 VCF/BAM 输出完全一致。
• 不要声称 Parabricks 可在 CPU 上运行。

前提条件

Agent 需要可供检查的工作流路径、代码仓库或入口点。本地 Parabricks 并非检查和接入所必需；加速执行和 A/B 对比需要 GPU 访问权限（本地、HPC 或云端）。

局限性

此技能不提供集群范围的 Parabricks 安装，也不保证结果完全一致。添加 GPU 替代步骤时，不会移除原有 CPU 步骤；除非用户在对比后明确批准合并。

如需深入了解运行时诊断、安装和各工具的命令标志，请使用 parabricks 技能。

参考资料

• parabricks-runtime-readiness.md — 本地检查；HPC / 云端指南
• workflow-frameworks.md — 检测框架；原位添加模式
• parabricks-tool-map.md — CPU → Parabricks 映射（所有框架）
• nf-core-parabricks-map.md — Nextflow nf-core 模块
• workflow-layout.md — 开关命名、布局、ACCELERATION.md
• step-consolidation.md — 在 GPU 分支上合并步骤
• comparison-checklist.md — 关闭与开启开关时的验证

说明

1. 收集信息并确定范围

如果用户要求加快管道、提升性价比、缩短运行时间或降低成本、改用 GPU，或使用 Parabricks，则仅在有可供检查的工作流路径、代码仓库或相关打开文件时继续。如果没有路径或入口点，请询问工作流位置和框架；不要编造管道或步骤映射。

如果代码仓库受版本控制，请在原位编辑前建议创建 git 分支。如果用户只有一份副本且没有分支，请先说明开关设计，并在编辑前征得确认。

**仅报告触发条件：**遵循“仅报告”“检查”“不要编辑文件”或“暂时不要更改任何文件”等要求——映射步骤并提出开关方案，但不写入工作流文件。

2. 运行时就绪状态

承诺运行前，先确认 Parabricks 能否在当前环境中运行。如果用户已提供相关信息，则使用该信息；否则，仅在适当时运行安全且耗时较短的命令，例如 nvidia-smi 和 pbrun --version。记录以下状态之一：

• Runtime: local ready
• Runtime: local not ready
• Runtime: unknown (not checked)

如果本地运行时未就绪，仍需检查并映射工作流。除非用户已经说明，否则请询问 GPU 运行将在哪处进行：共享 HPC、AWS、Google Cloud、Azure、OCI / 其他云端、两者兼有，或尚未确定。根据目标环境提供高层次的运行指南。

如需详细评估运行时，请阅读 parabricks-runtime-readiness.md，或委派给 parabricks 技能。

3. 检测并清点

根据工作流路径检测框架：

框架	标记	清点内容
Nextflow	main.nf、nextflow.config、modules/、include {	流程和通道连接方式
Snakemake	Snakefile、rules/、config.yaml	规则、shell/script 块、资源
WDL	*.wdl、workflow {、task、call	任务、命令、运行时块
Python	*.py、pyproject.toml、CLI 入口点	函数和 subprocess/shell 调用

如果仓库中混合使用多个框架或情况不明确，请列出候选入口点，并在实现前询问哪个是规范入口。

4. 将步骤映射到 Parabricks

所有框架均使用 parabricks-tool-map.md。对于 Nextflow，优先使用 nf-core-parabricks-map.md 中的 nf-core Parabricks 模块。对于 Snakemake、WDL、Python 或 shell，使用 pbrun 或官方 Parabricks 容器；不要要求转换为 Nextflow。

常见映射：

现有步骤	首选 Parabricks 目标
BWA-MEM / bwa mem 加排序和重复标记	pbrun fq2bam；Nextflow：parabricks_fq2bam
BWA 之后的 GATK/Picard MarkDuplicates	通常可合并到 fq2bam 中
GATK BaseRecalibrator / ApplyBQSR	fq2bam BQSR 模式或 pbrun applybqsr；需要时，Nextflow：parabricks_applybqsr
GATK HaplotypeCaller	pbrun haplotypecaller；Nextflow：parabricks_haplotypecaller
DeepVariant	pbrun deepvariant；Nextflow：parabricks_deepvariant

推荐使用 fq2bam 时，请说明它可以整合比对、排序、重复标记，有时还包括 BQSR。对于 Nextflow parabricks_fq2bam，请说明 nf-core 的注意事项：输入必须复制到 work 目录中（可考虑使用 stageInMode 'copy'），不能以符号链接方式暂存。

如果没有可用的 Parabricks 映射，请记录这一缺口，并保留原有 CPU 步骤作为唯一执行路径。

5. 报告格式

对于仅检查/报告的请求，不要编辑文件。请返回：

• 工作流路径和检测到的框架
• 运行时就绪情况，以及已知时的目标 GPU
• 映射表：

| 步骤 ID | 当前工具 | Parabricks 目标 | 集成方式 | GPU 说明 | 结果一致性风险 |

• 建议的切换开关名称、默认值（false/关闭）和分支方案
• 合并机会（例如，在 GPU 分支中将 BWA + MarkDuplicates 合并为单个 fq2bam）
• 下一步：就地接入可选 GPU 步骤，然后对比关闭和开启切换开关时的结果

对于带有具体工作流路径的通用性能优化请求，应将 Parabricks 映射作为首要优化手段。请说明 GPU 成本/运行时间之间的权衡；不要用无关的纯 CPU 建议取代映射。

6. 就地实现可选加速步骤

除非用户明确要求创建单独副本，否则请编辑现有工作流目录树。在 CPU 步骤旁边添加 Parabricks 步骤，并通过运行时切换开关进行路由。

切换开关约定

框架	建议的切换开关	默认值
Nextflow	params.use_parabricks 或 params.accelerated	false
Snakemake	config["use_parabricks"] 或 config.yaml 键	false
WDL	工作流输入 Boolean use_parabricks	false
Python	--use-parabricks CLI 标志或 USE_PARABRICKS 环境变量	关闭

在 ACCELERATION.md 中记录切换开关名称、默认值和示例运行命令。

实现模式

框架	模式
Nextflow	添加可选的 Parabricks 进程/模块：GPU 路径使用 when: params.use_parabricks，CPU 路径使用 when: !params.use_parabricks。通过 Profile 或 -params-file accelerated.config 开启此开关。GPU 标签仅用于加速进程。
Snakemake	并行设置 CPU 与 GPU 规则；在 rule all 中根据 config["use_parabricks"] 分支。使用 --configfile config.accelerated.yaml 或 --config use_parabricks=true。
WDL	if (use_parabricks) { call Parabricks_fq2bam } else { call BwaMem ... }。GPU runtime 仅用于 Parabricks 任务。
Python	添加 --use-parabricks 标志；根据分支通过子进程调用 docker run ... pbrun 或现有 CPU 命令。

规则：

• 首次添加加速时，不要删除原有 CPU 步骤。
• 默认关闭时必须重现当前的 CPU 路径。
• 后续步骤应使用实际运行分支的输出（尽可能匹配通道/输出名称）。
• GPU 资源、容器和执行器提示仅用于加速步骤。
• 对于 Nextflow，优先使用 nf-core Parabricks 模块；将其安装在同一仓库目录树中。

ACCELERATION.md 至少应包含以下部分：开关用法、运行时目标、映射关系、 输出接线、整合机会、A/B 对比检查清单。

参见 workflow-layout.md。

7. 整合迭代

完成 A/B 对比后，检查是否可以合并相邻步骤的 GPU 分支 （例如 BWA + sort + MarkDuplicates + BQSR → 一个 fq2bam / parabricks_fq2bam）。

仅报告：建议合并并征求批准。获得批准后：仅编辑 GPU 分支（when: params.use_parabricks 或等效项），移除被取代的 GPU 子步骤，更新 ACCELERATION.md 中的 Consolidation history，并提醒用户 重新运行开关关闭与开启时的对比。

除非用户明确要求在验证后切换，否则不要从默认路径中移除 CPU 步骤。不要将变异调用合并到 fq2bam 中。

参见 step-consolidation.md。

8. 生产使用前进行对比

绝不要声称结果一致。使用相同工作流，对比开关关闭与开启时的结果——样本、参考序列和区间相同；使用不同的输出目录 （例如 results-cpu/ 与 results-gpu/）。

使用 comparison-checklist.md 检查 flagstat、 重复率、VCF 一致性、运行时间、GPU 利用率和 Parabricks 版本。在 ACCELERATION.md 的 A/B comparison 部分记录结果。

# CPU path (default)
<framework-run-command>                         # toggle off

# GPU path
<framework-run-command-with-toggle-on>          # e.g. -params-file accelerated.config

9. 可选：基准测试和对比产物

当用户要求自动化，或已有测试数据和可运行的配置时，你还可以：

• 提供脚本，使用相同输入分别运行开关关闭和开启的流程
• 记录运行时间，并在可用时记录每个步骤或整体的 CPU/GPU 利用率
• 在 ACCELERATION.md 中总结结果，或制作简单的 HTML/Markdown 对比表

如果没有测试数据集，建议创建一个小型子集运行，并在 ACCELERATION.md 中记录对比计划，而不是因等待定制脚本而停滞。

除非用户提出要求，否则不要要求每种实现都提供基准测试脚本或 HTML 报告。

故障排查

情况	操作
没有工作流路径	请用户提供仓库、目录、Snakefile、WDL、Nextflow 入口点或 Python 脚本
本地无法使用 nvidia-smi / pbrun	继续接线；询问目标环境是 HPC 还是云端
没有 Parabricks 映射	标记为缺口；仅保留 CPU 步骤
结果一致性不确定	在生产环境使用 GPU 前，运行开关关闭与开启时的对比
只有一份生产副本，且没有 git	建议创建分支；默认关闭开关；在 ACCELERATION.md 中记录回滚方法

示例

没有路径

用户：“让我的基因组学流水线更快，并将其转换为使用 GPU。”

回复：询问工作流路径和框架。不要编造工作流映射。

Nextflow 检查（仅报告）

用户：“检查 main.nf 中是否有使用 Parabricks 的机会——不要编辑文件。”

回复：将 BWA/MarkDuplicates/HaplotypeCaller 对应到 nf-core 模块，建议设置默认值为 false 的 params.use_parabricks，说明 fq2bam 整合以及符号链接/复制限制，并引用 nf-core 文档。不要修改文件。

Nextflow 原地修改

添加 params.use_parabricks = false，添加可选的 parabricks_fq2bam 和 parabricks_haplotypecaller，并使用 when: 条件保护；默认路径保留 CPU 进程；添加 accelerated.config，在 ACCELERATION.md 中记录两种运行命令。

Snakemake 原地修改

在 config.yaml 中添加 use_parabricks: false，添加并行的 pbrun fq2bam 和 pbrun haplotypecaller 规则并配置 GPU 资源，在 rule all 中添加分支，并在 ACCELERATION.md 中记录 snakemake --config use_parabricks=true。

WDL 原地修改

添加 Boolean use_parabricks = false，为 true 时切换到 Parabricks 任务，仅在 GPU 分支中使用 GPU 运行时，并在 ACCELERATION.md 中记录两种模式的输入 JSON。

Python 原地修改

添加默认值为 false 的 --use-parabricks，在容器中时将子进程切换为调用 pbrun，否则使用 CPU 命令，并在 ACCELERATION.md 中记录两种调用方式。

生产环境中的单份拷贝请求

用户：“在唯一的 main.nf 中用 Parabricks 替换 BWA——直接编辑。”

回复：添加默认关闭的可选 Parabricks 步骤，保留 CPU 路径；建议使用 Git 分支；在 ACCELERATION.md 中记录切换开关和 A/B；未经验证后的批准，不要移除 CPU 步骤。