goombalab/hnet · 上手攻略

  • 仓库：goombalab/hnet
  • 链接：https://github.com/goombalab/hnet
  • 分类：engineering（研究代码 / 序列模型架构）
  • 作者：spark
  • 更新：2026-10-30

是什么

goombalab/hnet 是 H-Net 的官方实现代码仓库。H-Net 的全名是 Dynamic Chunking for End-to-End Hierarchical Sequence Modeling，论文发在 arXiv:2507.07955（v1 提交于 2025-07-10，v2 于 2025-07-15），作者是 Sukjun Hwang、Brandon Wang、Albert Gu。

一句话概括它做的事：让模型自己学怎么切分输入序列，从而干掉 tokenizer。

传统 LLM 的流水线是"tokenize → LM → detokenize"，tokenizer 是一个独立训练好的静态组件，训练和推理时都得跑它，而且它的切分规则是启发式写死的。H-Net 用一个动态分块（dynamic chunking）机制替代它——切分策略由网络自己学出来，和模型其余部分联合训练。再把这个机制放进一个显式的分层网络（hierarchical network）里，就得到了 H-Net：一个直接从原始字节端到端学出来的单一模型。

论文 abstract 里最硬的几条结论（verbatim 摘译）：

  • "When compute- and data- matched, an H-Net with one stage of hierarchy operating at the byte level outperforms a strong Transformer language model operating over BPE tokens."
  • "Iterating the hierarchy to multiple stages further increases its performance by modeling multiple levels of abstraction, demonstrating significantly better scaling with data and matching the token-based Transformer of twice its size."
  • "H-Nets pretrained on English show significantly increased character-level robustness, and qualitatively learn meaningful data-dependent chunking strategies without any heuristics or explicit supervision."
  • "the H-Net's improvement over tokenized pipelines is further increased in languages and modalities with weaker tokenization heuristics, such as Chinese and code, or DNA sequences (nearly 4x improvement in data efficiency over baselines)"

代码结构（README 原样）：

hnet/
├── models/
│   ├── config_hnet.py   # H-Net 的 config
│   ├── hnet.py          # h-net 作为一个 (B, L, D) -> (B, L, D) 序列模型
│   └── mixer_seq.py     # 把 h-net 包成语言模型的 wrapper
└── modules/
    ├── dc.py            # 动态分块机制的建模代码
    └── isotropic.py     # 各向同性（非分层）组件的代码
generate.py              # 推理 / 生成脚本
configs/                 # 各模型 config

代码主体在 hnet/ 目录，用 PyTorch 实现，MIT 许可。

解决什么问题

核心问题：tokenizer 是端到端基础模型的障碍。

近年的语言模型进步主要来自"从专用模型转向通用模型"，但像 tokenization 这样的预处理步骤，依然挡在"真正的端到端基础模型"前面。tokenizer 有几个固有问题：

  1. 切分规则是启发式的，不随内容和上下文变化——同一段文字在不同语境下被切成完全不同的 token
  2. 它是独立训练的，和 LM 目标不联合，tokenization 的损失不在端到端优化里
  3. 词表有限，遇到没见过的字形、罕见符号、非自然语言序列（DNA、代码）时，退化行为明显

H-Net 的做法是让切分变成网络内部的一个可学习操作。论文里说得很形象：推理时 H-Net "decides individually for each token how much compute to use when processing it"，可以给不同 token 分配不同算力；这个过程和 speculative decoding（Leviathan et al., 2023）有天然的类比——都是在"低熵、易预测的片段"上省算力。Goomba Lab 的官方博客把这句话说得更直白：H-Net 的结构"把某种近似 speculative decoding 的过程直接烘焙进模型里"。

收益最大的场景是 tokenizer 启发式较弱的地方：中文、代码、DNA 序列。论文报告中文和代码上相对 token 化流水线的改进更大，DNA 序列上数据效率提升接近 4 倍。

代价（明说，见下文"坑"）：动态分块需要训练和推理时持续计算，不是预处理一次性成本。

快速安装

要求：PyTorch >= 2.5.1。

git clone https://github.com/goombalab/hnet
cd hnet
pip install -e .

强烈建议从最新源码编译 mamba_ssm（README 用词是 "We strongly recommend building mamba_ssm package from the latest source"）：

git clone https://github.com/state-spaces/mamba
cd mamba
pip install .

这条建议值得重视：H-Net 的动态分块和线性注意力部分建立在 Mamba 系列算子的之上，mamba_ssm 的编译对 CUDA 版本敏感，PyPI 上的预编译 wheel 常常对不上你的环境，从源码编译是最稳的路子。

预训练模型在 Hugging Face 的 cartesia-ai 组织下：

模型名 说明
hnet_1stage_L 单层分级的 Large
hnet_2stage_L 两层分级的 Large
hnet_1stage_XL 单层分级的 XL
hnet_2stage_XL 两层分级的 XL

训练数据是 FineWeb-Edu 的 100B-Token 子集。README 明确："Large and XL are compute-matched to GPT-3 Large and XL, respectively."（Large/XL 分别与 GPT-3 Large/XL 做了算力对齐）

另有中文和代码权重：

模型名 训练数据
hnet_2stage_XL_chinese FineWeb-Edu Chinese V2.1 的 46B-Token 子集
hnet_2stage_XL_code Pile Github 的 46B-Token 子集

各模型的具体 config 在仓库 configs/ 目录，更多细节在论文里。

核心用法

一、文本生成

仓库提供 generate.py 用于推理：

python generate.py --model-path [MODEL_CKPT] --config-path [CONFIG]

# 具体例子
python generate.py \
  --model-path hnet_2stage_XL.pt \
  --config-path configs/hnet_2stage_XL.json \
  --max-tokens 1024 \
  --temperature 1.0 \
  --top-p 1.0

--model-path 和 --config-path 必须配对——模型权重和对应的 config 是一一对应的（configs/hnet_2stage_XL.json 对应 hnet_2stage_XL）。

二、当序列模型用

hnet/models/hnet.py 里的 h-net 是一个 (B, L, D) -> (B, L, D) 的序列模型，不是语言模型。要拿它做语言模型（自回归生成、训练），得用 hnet/models/mixer_seq.py 这个 wrapper 包一层。

这个设计是值得注意的：h-net 本身是与具体模态无关的序列算子，输入输出都是 (batch, length, dim)。用 mixer_seq.py 包出来的语言模型版本是"最外层模态"的特化——论文里说 "H-Net generates raw bytes (or whatever the outermost modality is) autoregressively with a modified procedure to handle its hierarchical structure"，也就是说字节级是当前用法，但接别的模态在架构上是开放的。

三、动态分块的核心实现

hnet/modules/dc.py 是整个仓库的核心——动态分块的建模代码。想读懂或改这个机制，这是必看文件。hnet/modules/isotropic.py 是各向同性（非分层）组件。

作者的博客 goombalab.github.io/blog/2025/hnet-future 里有一篇专门讲 H-Net 后续方向的文章，里面有一条直白的判断："H-Nets will be useful for audio and video, but may require more research."（H-Net 在音频和视频上会很有用，但可能还需要更多研究）—— 这句话同时说明了作者对多模态方向的判断和当前状态。

四、引用

@article{hnet,
 title={Dynamic Chunking for End-to-End Hierarchical Sequence Modeling},
 author={Hwang, Sukjun and Wang, Brandon and Gu, Albert},
 journal={arXiv preprint arXiv:2507.07955},
 year={2025}
}

典型适用场景

  • 研究端到端 / tokenizer-free 序列建模：这是本项目的正主。它给出的是一套能跑起来的完整实现 + 预训练权重，可以直接在你的数据上接着训
  • 中文 / 代码 / DNA 等非自然语言序列：论文报告这几类上相对 token 化基线的改进最大，DNA 数据效率提升近 4 倍
  • 字符级鲁棒性研究：论文强调英文预训练后"significantly increased character-level robustness"，对拼写噪声、拼写错误纠正、字符级任务有价值
  • 研究数据高效训练：多层分级带来"significantly better scaling with data"，在做小数据 / 冷启动时有参考价值
  • 想复现或验证"模型真能学到有意义的分块策略"：论文声称 H-Net "qualitatively learn meaningful data-dependent chunking strategies without any heuristics or explicit supervision"，这是可以直接可视化验证的
  • 不是：想要一个能马上拿来用的生产级 LLM。H-Net 目前是研究代码，没有 vLLM / SGLang 之类的推理框架集成，没有量化，没有生产部署方案

坑与注意

  1. 动态分块有持续计算开销。这是这个架构最本质的代价：BPE 只在预处理时切一次，动态分块在训练和推理全程都要算。已有第三方分析指出这个开销"对资源受限或要求实时响应的系统可能是阻碍"——代价在短上下文、边缘设备上尤其明显。
  2. 单个研究团队的成果，尚无独立复现。arXiv 2025-07-10 公开，至 2026-10 仍未见大规模独立复现；也未走正式同行评审通道（仓库 README 只引用 arXiv preprint）。论文的"匹配两倍大小 token-based Transformer"这类强结论，引用时应标注版本与状态。
  3. 代码是研究代码，不是工程库。仓库 README 极其简短——没有 API 文档、没有训练脚本说明、没有示例 notebook。训练流程需要自己读论文和 configs/ 里的 config 拼出来。
  4. mamba_ssm 编译是最常见的卡点。README 特意强调要从最新源码编译，但没给 CUDA / PyTorch 兼容矩阵。编译失败时的排查成本不低。
  5. PyTorch 版本下限 2.5.1。老环境需要升级。
  6. 模型和 config 必须严格配对。--model-path 与 --config-path 错配时行为难以预期。
  7. 仓库最近一次提交是 2025-11-20，距今已约 11 个月，活跃度明显低于前两个项目。这是一个"论文已出、权重已放、代码基本停更"的状态——fork 后自己维护的成本要算进去。
  8. 显存需求没有明确文档。XL 模型 + 字节级输入，序列长度上去之后显存占用可能相当可观，README 未给参考值，建议从小一点的 hnet_1stage_L 起步。
  9. 多模态方向作者自己说"may require more research"。别把"字节级"之外的能力当成现成能力。
  10. 训练数据子集的口径：英文用 FineWeb-Edu 的 100B-Token 子集，中文和代码用 46B-Token 子集。中文/代码权重的训练量只有英文的一半不到，比较时不要当成同等条件。

与同类对比

方案 切分方式 是否端到端 状态
H-Net 网络内学出来的动态分块 是，字节级 arXiv 预印本，单团队，无独立复现，代码活跃度低
标准 Transformer + BPE 静态启发式 tokenizer 否 工业标准，生态最完整
SentencePiece / Unigram 等 统计学习但推理时固定 否 成熟，广泛使用
Byte-level BPE（如 GPT-2/3 系列） 字节兜底，无合并规则 部分 事实上已是"字节级"，但切分仍非学出来的
MoE / SSM（Mamba 等） 不涉及切分 否（针对序列建模效率） 与 H-Net 正交——H-Net 的底座就建在 SSM 之上
Character-level / RWKV 类 固定字符或固定粒度 部分 字符级鲁棒但长上下文效率差

H-Net 的定位很独特：它不是"更好的 tokenizer"，而是把 tokenizer 这个概念取消掉，让切分和建模在同一个目标函数下联合优化。相对标准 Transformer，它的理论优势在于：数据效率更高、字符级鲁棒性更强、在 tokenizer 启发式弱的地方优势更大；相对其他研究路线，它的风险是整个生态为零——没有推理框架支持、没有微调工具链、没有社区实践。

一句话推荐结论

如果你在做端到端建模、tokenizer-free、或中文/代码/DNA 这类非自然语言序列的研究，这是目前唯一一套完整可跑、还附带了公开预训练权重（100B token 英文 + 46B token 中文/代码）的 H-Net 实现，值得直接拿来复现或续训；但如果你只是想找个能上生产的 LLM，别在这里浪费时间——它是一份论文复现代码，不是产品。

⚠️ 核验说明：本文基于 2026-10-30 抓取的仓库 README、arXiv:2507.07955 摘要页（v1 2025-07-10 / v2 2025-07-15）、Goomba Lab 博客 goombalab.github.io/blog/2025/hnet-future（经 web_search 摘要），以及第三方分析（Medium，Joe El Khoury）。所有 abstract 结论均为 verbatim 摘译并附引号。ARD/hnet 的目录结构、mamba_ssm 编译建议、PyTorch >= 2.5.1、四个英文权重名与中文/代码权重名、100B/46B token 训练口径、"compute-matched to GPT-3 Large and XL"、generate.py 参数均取自 README 原文。第三方分析中关于"计算开销对资源受限场景是阻碍"与"尚无独立复现"两点来自 web_search 摘要（Medium 文章），非一手论文或官方声明，转述时已标注来源。仓库最近提交日期 2025-11-20 来自仓库卡片元数据（采集于 2026-10-30）。本文未能确认：具体显存需求、训练脚本用法、CUDA/PyTorch 兼容矩阵、H-Net 是否已被任何主流推理框架集成。