waypoint-bio

Waypoint：Outpost Bio 的开放式微生物组基础模型

概述

Outpost Bio 在 Apache 2.0 许可下开源了三项成果，详见 Treloar 等人，bioRxiv 2026.05.02.722381：

成果	内容	Hugging Face
Waypoint	基于分类单元令牌的 GPT-2 风格因果语言模型，参数量为 6M–170M	outpost-bio/Waypoint-6m、-45m、-170m
Atlas	从 MGnify 抓取的 539,308 个微生物组样本（485,377 个用于预训练 / 53,931 个用于基准测试）	outpost-bio/Atlas
Compass	涵盖四项研究的八个下游任务	outpost-bio/Compass

核心理念是：微生物组样本就是一个句子。每个分类单元都是一个令牌，令牌按丰度 z 分数从高到低排序，模型通过预测下一个令牌进行训练。预训练检查点随后可提供样本级嵌入，或作为预测任务的微调骨干模型。

所有操作都由一个 CLI waypoint 驱动，包含五个子命令：prepare-dataset、embed、finetune、benchmark、pretrain。

适用场景

• 将 16S / 宏基因组分类谱编码为固定大小的向量，用于聚类、可视化或下游分类器。
• 微调 Waypoint 检查点，根据群落组成预测表型、治疗方案或连续读数。
• 使用 Compass 为自己的微生物组模型评分，使结果可与论文中的数据比较。
• 在 Atlas 或自己的语料库上预训练分类学语言模型。
• 将分析工具的输出（MetaPhlAn、Kraken2/Bracken、QIIME 2、MGnify TSV）转换为这些工具所需的输入格式。

如果标注样本少于约 1,000 个，请勿使用此工具——请参阅科学注意事项。此时，相对丰度随机森林是更好的工具，论文也有此建议。

设置

pip install waypoint-bio       # installs the `waypoint` command

Atlas、Compass 和所有 Waypoint 检查点都需要授权访问。访问请求会自动批准，但你必须在每个仓库页面点击一次，然后进行身份验证：

1. 在需要使用的每个仓库页面申请访问：Waypoint-6m、 Waypoint-45m、 Waypoint-170m、 Atlas、 Compass。

2. 在本地进行身份验证：

   hf auth login          # or: export HF_TOKEN=hf_...
   

任何子命令返回 401/403，几乎总是因为你尚未在对应的特定仓库申请访问——仅有令牌并不足够。请使用仅具备读取权限的令牌。分词器通过 trust_remote_code=True 加载；如果需要在不同运行中固定远程代码，请指定 revision。

waypoint 数据格式

除 prepare-dataset 外，所有命令都使用 waypoint 格式：.parquet / .csv / .tsv 文件，每行代表一个样本，包含两个对齐的列表列，以及任意所需的标签列。

列	类型	说明
Taxa	list[str]	完整谱系字符串，以 ; 分隔：k__Bacteria; p__Firmicutes; ...; g__Lactobacillus
Relative Abundances	list[float]	与 Taxa 长度相同，顺序一致
(任意)	标量	目标、协变量或 Split 列

建议优先使用 parquet。CSV/TSV 会将列表存储为 repr 字符串，并通过 ast.literal_eval 进行往返转换。

请提供完整谱系，而非单独的名称。 分词器会从每个谱系中提取属级片段（g__）；如果缺少属级信息，则会回退到最具体的更高分类等级。单独的名称会完全禁用这种回退机制。

工作流

1. 将数据转换为 waypoint 格式

如果已有带有谱系标签的样本 × 分类单元（或分类单元 × 样本）丰度矩阵：

waypoint prepare-dataset \
    --input abundance_matrix.tsv \
    --metadata sample_labels.csv \
    --output dataset.parquet

程序会根据第一列的列标题自动检测方向（taxonomy、lineage、taxon、otu、#otu id ⇒ 分类单元为行）；也可以使用 --orientation 覆盖。除非传入 --no_normalize，否则会将各行归一化至总和为 1；除非传入 --keep_zeros，否则会丢弃零值。

prepare-dataset 无法直接读取分析器的输出——MetaPhlAn 使用 | 分隔符，Kraken2 报告通过缩进表示层级，而 QIIME 2/SILVA 使用前缀 d__ 表示域，而非 k__（分词器会静默忽略该前缀）。请使用内置转换器处理这些格式：

python scripts/profiler_to_waypoint.py \
    --input merged_metaphlan.tsv --format metaphlan \
    --output dataset.parquet

python scripts/profiler_to_waypoint.py \
    --input reports/*.kreport --format kraken \
    --output dataset.parquet

python scripts/profiler_to_waypoint.py \
    --input feature-table.tsv --format qiime2 \
    --output dataset.parquet

关于所有输入布局、分类等级处理，以及 d__/| 易错点，请参阅 references/data-preparation.md。

2. 首先检查词汇表覆盖率

Waypoint 的词汇表在预训练时根据 Atlas 固定。词汇表中不存在的分类单元会变成 <unk>，并被 waypoint embed 静默丢弃；论文将此称为模型的主要局限。若某个样本的分类单元全部超出词汇表范围，则会产生退化的 [BOS][EOS] 嵌入。

python scripts/vocab_coverage.py --model outpost-bio/Waypoint-6m --data dataset.parquet

该命令会报告各样本的覆盖率和按丰度加权的覆盖率，并标记低于阈值的样本。如果按丰度加权的覆盖率中位数低于约 0.8，应重新检查分类标签，再信任任何下游指标。

3. 嵌入样本

waypoint embed \
    --model outpost-bio/Waypoint-6m \
    --data dataset.parquet \
    --output embeddings.parquet

输出以样本 ID 为索引，列名为 dim_0 … dim_{H-1}（6m 的 H = 256，45m 的 H = 512，170m 的 H = 768）。默认值：--pooling last_token、--batch_size 32、--max_length 512；设备会自动检测（cuda → mps → cpu）。

除非有理由更改，否则请保留 --pooling last_token：它与检查点的预训练方式以及 benchmark 和 finetune 的池化方式一致。对于无监督用途，mean 是合理的替代选项；first_token/cls_token 会返回 BOS 位置，而在因果 LM 中该位置携带的信号很少。

4. 根据标签微调

# classification
waypoint finetune \
    --model outpost-bio/Waypoint-45m \
    --data dataset.parquet \
    --output_dir outputs/ft_disease \
    --task_type classification \
    --target "Disease Status" \
    --config configs/finetune_classification.yaml

# regression, with a categorical covariate one-hot appended to the pooled embedding
waypoint finetune \
    --model outpost-bio/Waypoint-45m \
    --data dataset.parquet \
    --output_dir outputs/ft_degradation \
    --task_type regression \
    --target "Degradation Rate" \
    --covariate_column Drug \
    --config configs/finetune_regression.yaml

配置文件路径相对于内置的 waypoint_bio/configs/ 目录树解析，因此无需克隆仓库，从任意目录都可以使用 configs/...。

小型数据集值得覆盖的默认值：随附配置中的 warmup_steps: 1000（降至约 50，避免预热在提前停止之后才结束）；num_epochs: 1（提高该值——实际终止训练的是基于验证损失的提前停止）；显存有限时设置 use_lora: true（训练约 1% 的参数；保存前会将适配器合并回模型，因此检查点仍是普通的 AutoModel）。

默认按随机比例 80/10/10 划分。只要样本存在相关性，就将 split_column 设为 Split 列——例如重复测量、对同一供体进行多次采样，或技术重复；否则随机划分会造成数据泄漏，测试分数也就毫无意义。

输出保存到 --output_dir：best_model/（可由 embed/benchmark 加载）、test_metrics.json、training_log.csv + .html，以及 finetune_results.json。

5. 在 Compass 上进行基准测试

waypoint benchmark --model outpost-bio/Waypoint-6m --output_dir outputs/benchmark
waypoint benchmark --model outputs/pretrain/best_model --tasks 1 6 --output_dir outputs/smoke

每项任务都会使用新的分类头进行微调，并写入 benchmark_results.json。分类任务以宏平均 F1 评分；唯一的回归任务以 R² 评分，且限制在 [0, 1] 范围内；final_score 是各任务的非加权平均值。完整任务表、指标键和结果文件架构请参阅 references/compass-benchmark.md。

6. 预训练

waypoint pretrain \
    --model_config configs/models/gpt2-45m.yaml \
    --pretrain_config configs/pretraining.yaml \
    --output_dir outputs/pretrain_45m

下载 Atlas，根据语料库构建分类学分词器，计算每个词元的丰度均值/标准差以进行 z-score 排序，然后使用下一个词元预测和提前停止进行训练。添加 --data my_corpus.parquet，即可改用自有的 waypoint 格式语料库进行预训练；也可添加 --max_samples N 进行冒烟测试。

项目提供 9 种架构，从 gpt2-6m.yaml（8 层，隐藏维度为 256）到 gpt2-170m.yaml（24 层，隐藏维度为 768）；所有架构的每头维度均固定为 64。完整表格和所有配置项请参阅 references/cli-reference.md。

科学注意事项

这些注意事项至关重要。忽略它们，得到的数字看起来正常，却毫无意义。

• **标注样本少于约 1,000 个时，Waypoint 的表现不如基于原始丰度的随机森林。**论文中与 RF 基线的交叉点约为 10,000 个训练样本。请先拟合基线；只有当 Transformer 在你的数据上表现更好时，才采用它。
• **词表外的分类群会被丢弃，而非标记。**每个 Compass 数据集都包含一些此类分类群。请运行 scripts/vocab_coverage.py，并在报告结果时一并报告覆盖率。
• **最佳基准模型是 45M，而非 170M。**随着规模扩大，预训练损失会持续下降，但 Compass 下游得分并不会——请从 6m 或 45m 开始，仅在证明确有帮助时再扩大规模。
• 默认采用属级别分词，因此物种级别的差异会被折叠。更改 taxon_rank 需要重新预训练，而不只是重新分词。
• **组成型数据。**相对丰度总和受限于 1；一个分类群的差异会引起其他分类群表面上的变化。这会影响对任何逐分类群归因的解读。
• **批次和研究效应在微生物组数据中占主导地位。**Atlas 涵盖 MGnify 流程 v1.0–v5.0 和四种测序模式。切勿让研究或运行边界与标签边界重合。
• **不是临床或诊断工具。**模型卡对此有明确说明。

参考资料

• references/cli-reference.md — 每个子命令的标志、每个配置键，以及模型规模表。
• references/compass-benchmark.md — 八项任务、筛选条件、指标，以及 benchmark_results.json 架构。
• references/data-preparation.md — waypoint 格式、Profiler 转换、分类字符串规则。
• references/python-api.md — 如何在 Python 中使用分词器、数据集、头部和检查点。

脚本

• scripts/profiler_to_waypoint.py — 将 MetaPhlAn / Kraken2 / QIIME 2 / 通用谱系表转换为 waypoint 格式。
• scripts/vocab_coverage.py — 为 waypoint 格式文件生成分词器覆盖率报告。

上游项目

代码 github.com/Outpost-Bio/waypoint · 软件包 waypoint-bio · 论文 bioRxiv 2026.05.02.722381 · 社区 Waypoint Slack · 联系邮箱 [email protected]。

引用 Treloar, N. J., Ur-Rehman, S., Yang, J., & Outpost Bio (2026). Learning the Language of the Microbiome with Transformers. bioRxiv。各项成果的 DOI 列于 outpost.bio/citations。

Agent 操作流程

1. 检查环境。 确认工具版本、参考基因组／注释版本，以及输入格式（FASTQ、BAM、VCF、h5ad）。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。任何会影响结果的值都应询问，不要猜测。
3. 先运行小规模版本。 先在小型子集上运行流程（一个样本、一条染色体、几千个细胞）。
4. 使用以上说明和参考资料执行完整任务。
5. 验证结果。 解读结果前，检查 QC 指标、样本身份、基因组版本一致性和批次效应。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及仍有哪些不确定之处。

如果发生这种情况	请这样做
输入之间的基因组版本或标识符不匹配	停止并先统一（liftover、ID 映射），然后再继续。
这些说明中的函数、标志或端点在已安装版本中不存在	查阅已安装版本自己的文档（help()、--help、官方文档），调整后告知用户。切勿编造 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明所采用的假设。

完整性规则

• 切勿捏造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请如实说明。
• 不要对统计结果所能支持的范围之外的生物学意义作出解释；报告多重检验校正。
• 请将此处与版本相关的细节视为可能已过时：对照已安装版本的官方文档予以确认。
• 对于需要付费、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，须先征得同意。

相关技能

• scikit-bio：用于生物序列和群落生态学分析的 Python 库 scikit-bio：DNA/RNA/蛋白质序列、pair_align 比对、系统发育……
• distributed-llm-pretraining-torchtitan：使用 torchtitan 和 4D 并行（FSDP2、TP、PP、CP）进行 PyTorch 原生分布式大模型预训练。