命令总览与通用约定#

程序与语法#

BaizeGen 的所有功能都是同一个程序的子命令：

baizegen <命令> [选项]
baizegen <命令> --help        # 查看该命令的全部参数
baizegen --help               # 列出全部命令

• baizegen 是 CPU 版，baizegen-gpu 是 GPU 版，两者的命令和参数相同；GPU 相关的参数（--device gpu、--engine bwa-gpu 等）只有 GPU 版能用，CPU 版会明确拒绝而不是悄悄改用 CPU。
• 兼容写法：第一个参数以 - 开头时（例如 baizegen -I in.bam -R ref.fa -O out.vcf）等同于 baizegen haplotyper …。

命令一览#

通用约定#

线程与可重复性#

• -t N 设置线程数，一般设为机器的 CPU 线程数。
• 除 bwa 的默认批大小外（见 bwa 的批大小），所有命令的输出都与线程数、GPU 型号和数量无关。

内存#

• 默认按机器的内存自动调整：程序以物理内存和所在 cgroup 的限制（docker --memory、Kubernetes、systemd 的 MemoryMax）中较小的一个为上限，并在运行中随时读取当前的可用内存。排序数据、标记重复用的数据等，放得下时留在内存里（最快），放不下时写到磁盘（-T / -O 旁边）；两种情况的输出完全相同。因此机器空闲时 fastq2bam 会用掉大部分空闲内存，例如人类 30x WGS 在 125 GB 的机器上峰值约 106 GB。
• --max-memory SIZE（2026-11-11 发布包起提供；所有命令都接受，例如 --max-memory 64G；单位 K/M/G/T，可加 B）给本次运行设上限：上面这些预算都按"SIZE 减去程序当前已占用的内存"计算，超出的部分写到磁盘；GPU 版比对器也只在内存够时才读入下一批 reads（重复序列多的基因组，比对中间结果可达几十 GB）。输出不变，只是可能慢一些。适合几个任务共用一台机器。环境变量 BG_MEMORY_LIMIT_BYTES（字节）作用相同，两者同时给出时取较小的。
• 实测（fastq2bam，甘蔗 1.95 亿 reads，RTX 5090 D v2）：默认峰值 79 GB、6 分 16 秒；--max-memory 48G 峰值 40 GB、7 分 11 秒；--max-memory 32G 峰值 26 GB、7 分 13 秒；三者输出的 BAM 逐字节相同。
• 程序运行必需的内存不受上限约束：比对索引（人类约 5 GB，小麦约 17 GB）和比对器正在处理的一批 reads（甘蔗约 18 GB）。上限低于这些时程序照常完成，峰值内存会超过上限。GPU 版标记重复的数据（人类 30x WGS 约 15 GB，小麦 33x 约 67 GB）在 2026-11-11 及之前的发布包中也只能放在内存里；下一个发布包起，内存或上限不够时写到 -T 旁边，输出不变。

输入文件#

• BAM 和 CRAM 都可以作为输入，程序自动识别格式。CRAM 用 -R 给出的参考基因组解码（没有 -R 的命令使用 CRAM 头中 UR 指向的文件）。
• 需要随机访问的命令（haplotyper、mutect2、qcmetrics 等）要求输入按坐标排序并带索引（.bai / .csi / .crai）。
• VCF 类资源文件（已知位点、gVCF 等）建议用 bgzip 压缩并建立 tabix 索引。
• - 表示标准输入或标准输出（在命令说明中注明支持的地方）。

区间#

-L 参数在大多数命令中接受以下写法，可以重复给出：

mutect2、getpileupsummaries 的 -L 只接受 contig[:start-end] 写法；realign 的 -L 按染色体名限定。

输出文件#

• 文件名决定格式：.vcf 为文本，.vcf.gz 为 bgzip 压缩并同时写出 tabix 索引（.tbi），.bcf 为 BCF（写 .csi 索引）；.bam / .cram 同理。
• 染色体长度超过 512 Mb（2^29）时，tabix / BAI 索引无法表示，程序自动改写 .csi 索引。
• 内存大小参数接受 k / m / g 后缀，例如 -m 4g。

GPU 相关参数#

GPU 与 CPU 的输出逐字节相同。显存不足或显卡被其他进程占用时，程序会自动拆小任务或把部分 / 全部计算退回 CPU，并在 stderr 中说明；这时结果不变，但会变慢，见常见问题。

fastq2bam 的 BQSR 表、排序、标记重复、BAM 压缩和质控统计，在 GPU 版中默认也在 GPU 上进行，不需要额外参数。

退出码#

• 0：成功。
• 非 0：出错，原因写在 stderr。个别命令有特定含义的退出码，在该命令的说明中注明（例如 samcompare、gvcftyper）。
• 对于输入中个别格式错误、GATK 会中途报错退出的记录（例如 gVCF 中重复的等位基因、END 小于 POS 的记录），gvcftyper、combinegvcfs 等命令跳过该记录并在 stderr 给出警告，输出等于 GATK 在去掉这条记录后的结果，而不是中途退出。

输出的完整性#

每个命令的输出文件（包括 .bai、.crai、.tbi、.csi 索引和质控、报告等附带文件）先写成同目录下的 <输出名>.partial（fastp 输出的 .gz FASTQ 为 <名>.partial.gz），命令成功结束（退出码 0）时才改名为正式文件名。因此：

• 正式文件名的文件存在，就是完整的。批量运行时可以用"输出文件存在"判断某一步已经完成，失败后从这一步重跑。
• 命令出错时（退出码非 0），正式文件不会生成；若同名文件已存在（之前运行的结果），保持原样不被覆盖。命令自己报错退出时会删除 .partial 文件；进程被杀死（kill -9、内存不足被系统终止、断电）时会留下 .partial 文件，可以直接删除，重跑时也会被覆盖。
• 覆盖已有的输出时，新旧文件在命令结束前同时存在，需要能容纳两份的磁盘空间。
• 输出到标准输出（-）、命名管道、设备文件或符号链接时，照常直接写入，不经过 .partial。
• 设置环境变量 BG_ATOMIC_OUTPUT=0 可关闭这一行为，直接写正式文件名。
• index、bsprep 建立参考基因组索引时，部分文件由 bwa / bowtie2-build 直接写出，不经过 .partial；中断后请重新运行。

combinegvcfs --genotype-out 在分型时报错退出（退出码 2）时，已经完整写出的合并 gVCF 照常改名保留，分型的 VCF 不生成。

运行日志#

（下一个发布包起提供）每次运行任何命令，都会在日志目录下当天的文件 baizegen_YYYY-MM-DD.log 末尾追加两行：开始时一行 START，结束时一行 END。同一天的所有运行（不同用户、不同样本、同时运行的多个进程）都写在同一个文件里，用 run=主机:进程号 对应同一次运行的两行。日期按运行开始的那天算，跨过午夜的运行，END 也写在开始那天的文件里。

2026-11-12 18:51:03.120 +0800   START   run=node1:123456    tag=S001    version=0.1.0 (1b3f8173 2026-11-12) binary=/opt/baizegen/baizegen-gpu   user=lab    cwd=/data/run1  cmd=baizegen-gpu fastq2bam -R hg38.fa --rg '@RG\tID:L1\tSM:S001' -O S001.bam S001_R1.fq.gz S001_R2.fq.gz
2026-11-12 19:02:15.884 +0800   END run=node1:123456    tag=S001    status=OK   exit=0  elapsed=0:11:12.764 cpu=8123.4s peak_rss=112.6G
2026-11-12 19:40:02.010 +0800   END run=node1:124001    tag=S002    status=KILLED   exit=137    signal=SIGKILL  elapsed=0:31:40.210 cpu=20311.0s    peak_rss=250.1G error=killed by SIGKILL
2026-11-12 19:41:12.500 +0800   END run=node1:124100    tag=S003    status=FAILED   exit=1  elapsed=0:00:02.105 cpu=0.4s    peak_rss=31.0M  error=fastq2bam: fail to open file `S003_R2.fq.gz'

每行以时间（精确到毫秒，带时区）和事件开头，其后是以 Tab 分隔的 键=值 字段：

列出某一天失败的运行：

grep -P '\tEND\t' /opt/baizegen/logs/baizegen_2026-11-12.log | grep -v 'status=OK'

各样本的运行时间：

awk -F'\t' '$2 == "END" { delete v; for (i = 3; i <= NF; i++) { k = substr($i, 1, index($i, "=") - 1); v[k] = substr($i, index($i, "=") + 1) }
                    print v["tag"], v["status"], v["elapsed"], v["peak_rss"] }' /opt/baizegen/logs/baizegen_2026-11-12.log

日志目录，按以下顺序取第一个：

1. 参数 --log-dir DIR（任何命令都接受，位置不限，也可以写成 --log-dir=DIR）；
2. 环境变量 BAIZEGEN_LOG_DIR；
3. 程序所在目录下配置文件 baizegen.conf 中的 log_dir = DIR（相对路径相对于程序所在目录；# 之后为注释）。管理员可以用它让所有用户的日志写到同一个共享目录，而不必修改每条流程；
4. 程序所在目录下的 logs/（程序路径为符号链接时，指链接的目标所在目录）。

DIR 为 off 时不写日志。目录不存在时自动创建；程序自动创建的 logs/ 权限为 1777（与 /tmp 相同，所有用户都能写入、只能删除自己的文件），每天的日志文件权限为 0666，同一安装的所有用户写同一个文件。多台机器通过 NFS 共享同一个日志目录时，每行在文件锁下一次写入，不会交错。

日志目录不可写时（例如程序装在只读目录下），运行开始时在 stderr 给出一行 [log] cannot write the run log … 提示，命令照常运行，只是不记录；写日志失败永远不会导致命令失败。

说明：

• 不记录：baizegen、baizegen --help、baizegen --version 本身；以及一次运行内部再启动的 baizegen 进程（例如 haplotyper --gpus 的各分片），它们属于外层那次运行。
• 只有 START 没有 END：运行仍在进行，或者整台机器宕机、断电，或者监视进程本身被 kill -9（这时命令也随之终止）。
• 写日志的是一个很小的监视进程（与 --run-report 共用）：它启动命令、原样转发 stderr、等命令结束后写 END。因此 ps 中会看到两个 baizegen 进程，shell 中的进程号是监视进程的；发给它的 SIGTERM、SIGINT、SIGHUP、SIGQUIT、SIGUSR1、SIGUSR2 会转给命令，kill -9 它时命令也随之终止。退出码与不写日志时相同；/usr/bin/time 报告的时间和内存峰值包含命令本身。
• 用 gdb 等只跟踪一个进程的工具调试时，加 --log-dir off（或 BAIZEGEN_LOG_DIR=off），这时不启动监视进程。
• --log-dir、--log-tag 不进入输出文件（BAM 的 @PG、VCF 的命令行头），加不加输出完全相同。
• 日志文件不会自动删除或轮转，需要时可按日期删除旧文件。

运行报告（--run-report）#

任何命令都可以加 --run-report FILE（下一个发布包起提供；位置不限，也可以写成 --run-report=FILE），把这次运行的结果写成一个 JSON 文件，供批量流程汇总"哪些样本出错、为什么"：

baizegen fastq2bam -R ref.fa -O S1.bam --run-report S1.f2b.json S1_R1.fq.gz S1_R2.fq.gz

无论命令成功、出错、崩溃还是被杀死（包括内存不足被系统终止、调度系统超时发出的 SIGTERM），都会写出报告；程序的退出码（或终止它的信号）与不加这个参数时相同，stderr 照常输出。这个参数不进入输出文件（BAM 的 @PG、VCF 的命令行头），加不加输出完全相同。主要字段：

events 的类型：

批量运行后列出失败的样本：

for f in reports/*.json; do
  python3 -c 'import json,sys; d=json.load(open(sys.argv[1])); d["status"]!="succeeded" and print(sys.argv[1], d["status"], d["error"])' "$f"
done

加了 --run-report 时，程序会多一个很小的监视进程：它启动命令、转发 stderr、等命令结束后写报告。发给它的 SIGTERM、SIGINT、SIGHUP、SIGQUIT、SIGUSR1、SIGUSR2 会转给命令本身。