安装与运行环境#
发布包内容#
BaizeGen 以一个目录的形式发布（目录名形如 baizegen-YYYYMMDD-xxxxxxx，日期加代码版本号），包含以下文件：
| 文件 | 说明 |
|---|---|
baizegen |
CPU 版。全静态链接，不依赖系统的任何动态库，任何 x86-64 Linux 都能运行 |
baizegen-gpu + lib/ |
GPU 版。lib/ 中是 libcudart.so.12 和 libjemalloc.so.2，必须与可执行文件放在同一目录下（拷贝时整个目录一起拷） |
README.md |
本版本的变化、实测环境与参考耗时 |
SHA256SUMS |
各文件的校验和 |
GPU 版包含 CPU 版的全部功能：不加 --device gpu、--engine bwa-gpu 等 GPU 参数时，baizegen-gpu 的行为与 baizegen 相同。
平台要求#
GPU 版（baizegen-gpu）#
- 显卡：NVIDIA V100，以及 RTX 20 系（如 2080 Ti）、30 系、40 系、50 系及同代的数据中心卡。程序为 sm_70 / 75 / 86 / 89 / 120 编译。
- 驱动：≥ 535。不需要安装 CUDA toolkit。
- 操作系统：x86-64 Linux，glibc ≥ 2.17（
ldd --version查看）。CentOS 7 / RHEL 7 及以后、Ubuntu 16.04 及以后均可。 - 显存：人类基因组 11 GB 显存的卡即可运行全部流程。比对大基因组时，bwa 索引需要整体放入显存（例如小麦索引约 17 GB，需要 24 GB 的卡）；显存不够时这一步自动退回 CPU 比对，能跑完但慢很多。
- 内存（峰值，
-t 48，人类 30× WGS）：fastq2bam约 65–85 GB（-K 100000000），haplotyper输出 VCF 约 13–31 GB、输出 gVCF 约 22–45 GB。内存紧张时见内存受限的机器。
关于 V100 等未实测的显卡
每个发布包都在 2080 Ti、RTX 4090、RTX 5090 上验证过。其他架构（例如 V100 的 sm_70）的机器码是单独编译的，第一次使用前请按GPU 自检对比 GPU 与 CPU 的结果。
CPU 版（baizegen）#
- 任何 x86-64 Linux，包括 CentOS 7 这类老系统和 Alpine 这类 musl 系统，以及空容器（
scratch）。 - 程序在运行时自动选用 AVX-512、AVX2 或通用指令，无需选择版本。
- 结果不依赖系统的 glibc：程序自带数学库，在任何系统上的输出都相同。
安装步骤#
- 把发布包目录完整拷贝到目标机器，例如
/opt/baizegen。 -
校验文件：
bash cd /opt/baizegen sha256sum -c SHA256SUMS -
确认程序能运行：
bash ./baizegen --help # 列出全部子命令 ./baizegen-gpu --help nvidia-smi # GPU 版：确认驱动版本 ≥ 535，卡处于空闲状态 -
（可选）加入
PATH：bash export PATH=/opt/baizegen:$PATH不要把
baizegen-gpu单独拷贝到别处：它从自身所在目录的lib/加载运行库。需要放进PATH时，把整个目录加入PATH。
参考基因组准备#
各命令需要的参考基因组文件如下。建议把参考基因组及其全部索引放在同一目录、同一文件名前缀下。
| 文件 | 生成方式 | 用到它的命令 |
|---|---|---|
ref.fa |
— | 全部 |
ref.fa.fai |
samtools faidx ref.fa |
全部 |
ref.dict |
samtools dict ref.fa > ref.dict（或 Picard CreateSequenceDictionary） |
gvcftyper、mutect2 等；建议总是生成 |
bwa 索引：ref.fa.bwt .sa .pac .ann .amb |
baizegen index --engine bwa ref.fa，或已有的 bwa index 结果 |
align / fastq2bam 的 --engine bwa、--engine bwa-gpu |
ref.fa.alt |
bwakit 随 GRCh38 提供 | --postalt |
minibwa 索引：ref.fa.l2b .mbw |
首次使用时自动生成，或 baizegen index ref.fa |
align / fastq2bam 的默认引擎 minibwa |
Bismark 基因组目录：Bisulfite_Genome/ |
baizegen bsprep |
甲基化流程 |
samtools faidx ref.fa
samtools dict ref.fa > ref.dict
baizegen index --engine bwa ref.fa # 与 bwa index 生成的文件相同格式；已有 bwa 索引可直接使用
已知位点等资源文件#
部分步骤需要公共资源文件，均应为 bgzip 压缩并带 tabix 索引（.tbi）的 VCF，染色体命名与参考基因组一致：
| 资源 | 用途 | 命令与参数 |
|---|---|---|
| dbSNP、Mills and 1000G gold standard indels、1000G phase1 SNPs 等 | BQSR 的已知变异位点 | bqsr -k、fastq2bam --known-sites |
| Mills and 1000G gold standard indels 等 | indel 重比对的已知 indel | realign --known-indels、fastq2bam --known-indels |
| dbSNP | VCF 的 ID 列注释 | gvcftyper -d |
带 INFO/AF 的人群频率资源（如 gnomAD af-only） |
体细胞检测的胚系先验 | mutect2 --germline-resource |
| Panel of Normals | 体细胞检测的正常样本假阳性位点 | mutect2 --panel-of-normals |
常见双等位 SNP（带 INFO/AF） |
污染估计 | getpileupsummaries -V |
存储建议#
把参考基因组、索引和 FASTQ / BAM 拷到本地盘（最好是 NVMe）再运行。 BaizeGen 的计算速度很快，输入输出往往成为瓶颈：从千兆网的 NFS 读数据只有约 110 MB/s，一个人类 WGS 的 BAM（60–70 GB）光读一遍就要 10 分钟，比 GPU 计算本身还慢。
临时文件（排序的溢出文件等）默认写在输出文件旁边或 $TMPDIR 下，可用 -T 指定位置。
环境变量#
| 变量 | 作用 |
|---|---|
CUDA_VISIBLE_DEVICES |
限定 GPU 版可见的显卡，例如 CUDA_VISIBLE_DEVICES=0 只用第一张卡。默认使用全部可见且未被其他进程占用的卡 |
TMPDIR |
没有给 -T 时，sort / fastq2bam 溢出文件的位置之一 |
BQSR_NUMA=1 |
bqsr 在多路 CPU 服务器上把工作线程和统计表绑定到各自的 NUMA 节点（约快 15%，结果不变） |
程序启动时会自动把进程可打开的文件数提高到系统允许的上限，一般无需手动 ulimit -n。
首次使用：GPU 自检#
同一台机器上，GPU 计算的结果应与 CPU 计算的结果逐字节相同。在一张没有实测过的显卡上第一次使用时，用一小段数据对比两者：
# 比对：取 100 万对 reads
zcat sample_R1.fq.gz | head -4000000 | gzip -1 > t_R1.fq.gz
zcat sample_R2.fq.gz | head -4000000 | gzip -1 > t_R2.fq.gz
RG='@RG\tID:t\tSM:t\tPL:ILLUMINA\tLB:lib1'
baizegen-gpu fastq2bam --engine bwa-gpu -R ref.fa -t 32 -O gpu.bam --rg "$RG" t_R1.fq.gz t_R2.fq.gz -- -K 100000000 2> gpu_f2b.log
baizegen-gpu fastq2bam --engine bwa -R ref.fa -t 32 -O cpu.bam --rg "$RG" t_R1.fq.gz t_R2.fq.gz -- -K 100000000 2> cpu_f2b.log
samtools view gpu.bam | md5sum; samtools view cpu.bam | md5sum # 两个 md5 应相同
# haplotyper：用一个完整样本的 BAM，取一段 10 Mb 的区间（hs38 写 chr20:1-10000000，hs37d5 写 20:1-10000000）
baizegen-gpu haplotyper --device gpu -R ref.fa -I sample.bam -L chr20:1-10000000 -t 32 --emit-mode gvcf -O gpu.g.vcf.gz 2> gpu_hc.log
baizegen-gpu haplotyper -R ref.fa -I sample.bam -L chr20:1-10000000 -t 32 --emit-mode gvcf -O cpu.g.vcf.gz 2> cpu_hc.log
zcat gpu.g.vcf.gz | grep -v '^##' | md5sum; zcat cpu.g.vcf.gz | grep -v '^##' | md5sum # 两个 md5 应相同
- CPU 对照使用
baizegen-gpu本身（比对用--engine bwa，haplotyper 不加--device gpu）。 - 两组 md5 都相同，说明这张卡可以正常使用。
- 同时检查 GPU 版的日志：
gpu_hc.log中出现the run failed on device，或gpu_f2b.log中出现no room on the device、aligned on the host，说明有一部分或全部计算退回了 CPU。这时 md5 仍会相同，但并没有验证到 GPU，请把日志发给我们（见反馈时请附上）。