常见问题#

GPU 被占用或显存不足#

现象：GPU 版运行得比预期慢很多（例如人类 WGS 比对从约 5 分钟变成 2 小时以上），并且占满了所有 CPU 核。

原因：启动时显卡被其他程序占用、显存不够。BaizeGen 不会因此报错退出，而是自动把部分或全部计算退回 CPU，结果不变，但会慢几十倍。stderr 中会出现以下提示：

处理：运行前用 nvidia-smi 确认卡是空闲的；同一张卡上不要同时运行多个 GPU 任务；需要时用 CUDA_VISIBLE_DEVICES 指定空闲的卡。

结果与 GATK 有极少量差异#

先确认比较的是同一个 BAM、同一个 GATK 版本和同样的参数（见复现已有的 GATK 结果和结果一致性验证）。在此前提下，仍可能出现的差异：

• CPU 指令集：GATK 使用的 PairHMM 库（Intel GKL）在 AVX-512 和 AVX2 CPU 上的浮点计算不完全相同，GATK 自己在两类 CPU 上的结果也有同样的差别（少数记录的 PL / QUAL 差几分，F1 不受影响）。BaizeGen 默认复现 GATK 在 AVX2 机器上的结果；GATK 运行在 AVX-512 机器上时加 --gatk-host-simd avx512。用 grep -c avx512f /proc/cpuinfo 查看 CPU 是否支持 AVX-512。
• glibc 版本：GATK 运行在 glibc 2.41 及以后的系统上时，个别 PL 会差 1，加 --gatk-host-glibc 2.43。
• GATK 4.0.12.0：GATK 4.0 自身两次运行之间就有少量随机差异。

同一台机器上，GPU 版与 CPU 版的输出始终逐字节相同。

比对结果随线程数变化#

不给 -K 时，bwa（以及 BaizeGen 的 bwa 引擎）的批大小是 1000 万 × 线程数，批大小影响插入片段长度的估计，因此少量 reads 的比对会随 -t 变化。在 -- 之后明确给出 -K 即可，见 bwa 的批大小。

读组写成了 -R，报参考基因组的错误#

现象：fastq2bam / align 报 -R is the reference FASTA, not the read group '@RG…'；2026-11-11 及更早的发布包报 cannot load the bwa index '@RG\tID:…'。

原因：fastq2bam / align 的 -R 是参考基因组。读组行（bwa mem 的 -R）写在 -- 之前时，被当作参考基因组。

处理：读组用 --rg '@RG\tID:…\tSM:…' 给出。也可以把 -R '@RG…' 放到 -- 之后，作为 bwa mem 的参数，两种写法结果相同。读组要用单引号括起来，并且必须有 ID，否则报 bad read group line for -R。

参考基因组相关的错误#

• 缺少 .fai / .dict：用 samtools faidx ref.fa 和 samtools dict ref.fa > ref.dict 生成。gvcftyper、mutect2 需要 .dict。
• 缺少 bwa 索引：--engine bwa / bwa-gpu 需要已有的 bwa 索引，用 baizegen index --engine bwa ref.fa 或 bwa index 生成。
• 染色体命名不一致：已知位点、区间文件等资源中的染色体名（chr1 与 1）必须与参考基因组一致。

gvcftyper 遇到旧版 gVCF 报错退出#

GATK 3 / 4.0 生成的 gVCF 使用 RAW_MQ 注释。与 GenotypeGVCFs 一样，gvcftyper 遇到只有 RAW_MQ 的记录时报错退出（退出码 2）。加 --allow-old-rms-mapping-quality-annotation-data 按 GATK 的旧规则计算 MQ。combinegvcfs --genotype-out 同理（此时合并的 gVCF 仍会完整写出）。

输出目录里有 .partial 文件#

.partial 是命令写到一半的输出：命令成功结束时改名为正式文件，进程被杀死或机器断电时留下。它不是完整结果，可以直接删除；重新运行同一命令时也会被覆盖。见输出的完整性。

输出所在的文件系统不支持 O_DIRECT#

部分网络文件系统或叠加文件系统不支持直接写盘（O_DIRECT）。fastq2bam 会自动改用普通写入，输出内容不变，无需处理。

从 NFS 读写很慢#

BaizeGen 的计算速度往往快于千兆网络的读写速度（约 110 MB/s）。把参考基因组、索引和输入数据拷到本地盘（最好是 NVMe）再运行，输出也先写到本地盘。

已知限制#

• applybqsr 暂不支持 --quantize-quals、--static-quantized-quals、--round-down-quantized、--emit-original-quals、--use-original-qualities、--global-qscore-prior。
• combinegvcfs 暂不支持 --call-genotypes；不支持 --input-is-somatic 和注释参数。
• --gatk-version 4.0.12.0 只支持二倍体。
• 甲基化 --aligner baize --local 与 Bismark 的差异超出 bowtie2 自身的差异水平，要求一致性时请用 --aligner bowtie2。
• bsalign 暂不支持 FASTA 输入、SAM / CRAM 输出和 bowtie2 的调参选项。
• V100 等未实测的显卡：第一次使用前请做 GPU 自检。

反馈时请附上#

• 完整的命令行和 stderr 日志（2> log.txt）。建议用 /usr/bin/time -v 包住命令，以便得到耗时和峰值内存。
• 发布包目录名（含日期和版本号）。
• 硬件与系统信息：nvidia-smi 的输出（显卡型号、驱动版本）、ldd --version | head -1、lscpu | head -20、free -g。
• 数据规模（样本的碱基数）和所用的参考基因组。