/README.md

<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/kyegomez/OpenMythos) · [上游 README](https://github.com/kyegomez/OpenMythos/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

# OpenMythos

<p align="left">
  <a href="https://pypi.org/project/open-mythos/" target="_blank">
    <picture>
      <source srcset="https://img.shields.io/pypi/v/open-mythos?style=for-the-badge&color=3670A0" media="(prefers-color-scheme: dark)">
      <img alt="Version" src="https://img.shields.io/pypi/v/open-mythos?style=for-the-badge&color=3670A0">
    </picture>
  </a>
  <a href="https://twitter.com/kyegomezb/">
    <picture>
      <source srcset="https://img.shields.io/badge/Twitter-Follow-1DA1F2?style=for-the-badge&logo=twitter&logoColor=white" media="(prefers-color-scheme: dark)">
      <img src="https://img.shields.io/badge/Twitter-Follow-1DA1F2?style=for-the-badge&logo=twitter&logoColor=white" alt="Twitter">
    </picture>
  </a>
  <a href="https://discord.gg/3keGBK9Pvr" target="_blank">
    <picture>
      <source srcset="https://img.shields.io/badge/Discord-Join-5865F2?style=for-the-badge&logo=discord&logoColor=white" media="(prefers-color-scheme: dark)">
      <img alt="Discord" src="https://img.shields.io/badge/Discord-Join-5865F2?style=for-the-badge&logo=discord&logoColor=white">
    </picture>
  </a>
  <a href="https://pytorch.org" target="_blank">
    <picture>
      <source srcset="https://img.shields.io/badge/PyTorch-Implemented-EE4C2C?style=for-the-badge&logo=pytorch&logoColor=white" media="(prefers-color-scheme: dark)">
      <img alt="PyTorch" src="https://img.shields.io/badge/PyTorch-Implemented-EE4C2C?style=for-the-badge&logo=pytorch&logoColor=white">
    </picture>
  </a>
</p>

> **免责声明：** OpenMythos 是一项独立的、社区驱动的理论重构项目，仅基于公开可用的研究与推测。它与 Anthropic 及其任何专有系统均无关联、未获认可，也不存在任何联系。

OpenMythos 是 Claude Mythos 模型的开源理论实现。它实现了一个循环深度 Transformer（Recurrent-Depth Transformer，RDT），包含三个阶段：**Prelude**（transformer 块）、循环的 **Recurrent Block**（最多 `max_loop_iters`），以及最终的 **Coda**。注意力机制可在 MLA 与 GQA 之间切换，前馈网络采用稀疏 MoE（混合专家），包含路由专家与共享专家，非常适合探索计算自适应、深度可变的推理。


## 安装

```bash
pip install open-mythos

#uv pip install open-mythos
```

要在 `GQAttention` 中启用 Flash Attention 2（需要 CUDA 和构建工具）：

```bash
pip install open-mythos[flash]
```

## 用法

```python

import torch
from open_mythos.main import OpenMythos, MythosConfig


attn_type = "mla"  # or "gqa"

base = {
    "vocab_size": 1000,
    "dim": 256,
    "n_heads": 8,
    "max_seq_len": 128,
    "max_loop_iters": 4,
    "prelude_layers": 1,
    "coda_layers": 1,
    "n_experts": 8,
    "n_shared_experts": 1,
    "n_experts_per_tok": 2,
    "expert_dim": 64,
    "lora_rank": 8,
    "attn_type": attn_type,
}

if attn_type == "gqa":
    cfg = MythosConfig(**base, n_kv_heads=2)
else:
    cfg = MythosConfig(
        **base,
        n_kv_heads=8,
        kv_lora_rank=32,
        q_lora_rank=64,
        qk_rope_head_dim=16,
        qk_nope_head_dim=16,
        v_head_dim=16,
    )

model = OpenMythos(cfg)
total = sum(p.numel() for p in model.parameters())
print(f"\n[{attn_type.upper()}] Parameters: {total:,}")

ids = torch.randint(0, cfg.vocab_size, (2, 16))
logits = model(ids, n_loops=4)
print(f"[{attn_type.upper()}] Logits shape: {logits.shape}")

out = model.generate(ids, max_new_tokens=8, n_loops=8)
print(f"[{attn_type.upper()}] Generated shape: {out.shape}")

A = model.recurrent.injection.get_A()
rho = torch.linalg.eigvals(A).abs().max().item()
print(
    f"[{attn_type.upper()}] Spectral radius ρ(A) = {rho:.4f} (must be < 1)"
)
```



## 模型变体

预配置的规模从 1B 到 1T 参数：

```python
from open_mythos import (
    mythos_1b,
    mythos_3b,
    mythos_10b,
    mythos_50b,
    mythos_100b,
    mythos_500b,
    mythos_1t,
    OpenMythos,
)

cfg = mythos_7b()  # returns a MythosConfig
model = OpenMythos(cfg)

total = sum(p.numel() for p in model.parameters())
print(f"Parameters: {total:,}")
```

| 变体 | `dim` | 专家数 | `expert_dim` | 循环迭代次数 | 上下文 | 最大输出 |
|---|---|---|---|---|---|---|
| `mythos_1b` | 2048 | 64 | 2048 | 16 | 4k | 4k |
| `mythos_3b` | 3072 | 64 | 4096 | 16 | 4k | 4k |
| `mythos_10b` | 4096 | 128 | 5632 | 24 | 8k | 4k |
| `mythos_50b` | 6144 | 256 | 9728 | 32 | 8k | 4k |
| `mythos_100b` | 8192 | 256 | 13568 | 32 | 1M | 128k |
| `mythos_500b` | 12288 | 512 | 23040 | 48 | 1M | 128k |
| `mythos_1t` | 16384 | 512 | 34560 | 64 | 1M | 128k |

---

## 训练

3B 模型在 FineWeb-Edu 上的训练脚本位于 [`training/3b_fine_web_edu.py`](training/3b_fine_web_edu.py)。

**单 GPU：**
```bash
python training/3b_fine_web_edu.py
```

**多 GPU（自动检测 GPU 数量）：**
```bash
torchrun --nproc_per_node=$(python -c "import torch; print(torch.cuda.device_count())") training/3b_fine_web_edu.py
```

关键设计选择：

| 特性 | 详情 |
|---|---|
| 优化器 | AdamW |
| 数据集 | `HuggingFaceFW/fineweb-edu`（默认 `sample-10BT`，完整训练可切换为 `sample-100BT` 或 `default`） |
| 分词器 | 通过 `MythosTokenizer` 使用 `openai/gpt-oss-20b` |
| 并行 | 通过 `torchrun` 使用 PyTorch DDP，分片流式数据集 |
| 精度 | H100/A100 上使用 bfloat16，较旧 GPU 上使用 float16 + GradScaler |
| 调度 | 线性预热（2000 步）→ 余弦衰减 |
| 目标 | 30B tokens（约按 Chinchilla 为循环架构调整） |

---

## 文档

| 页面 | 描述 |
|---|---|
| [`docs/open_mythos.md`](docs/open_mythos.md) | `OpenMythos` 类的完整 API 参考 —— 构造函数、`forward`、`generate`、所有子模块、配置参考及用法示例 |
| [`docs/datasets.md`](docs/datasets.md) | 推荐训练数据集，并提供各模型规模的 token 预算指导 |

---

## 核心假设

Claude Mythos 被认为是一种 **循环深度 Transformer（RDT）** —— 也称为 Looped Transformer（LT）。它并非堆叠数百个独立层，而是将一部分层循环复用，在前向传播中多次运行。权重相同。循环更多。思考更深。

这不是思维链（chain-of-thought）。没有中间 token 输出。所有这些推理都在**单次前向传播中悄然完成**，在连续潜空间中发生。

---

## 架构

循环 Transformer 将其层划分为三个功能块：

```
Input
  ↓
[Prelude P]        — standard transformer layers, run once
  ↓
[Recurrent Block R] — looped T times
  ↑_______↓         (hidden state h updated each loop with input injection e)
  ↓
[Coda C]           — standard transformer layers, run once
  ↓
Output
```

循环块在每个循环步 t 的更新规则：

```
h_{t+1} = A·h_t + B·e + Transformer(h_t, e)
```

其中：
- `h_t` 是循环 t 之后的隐藏状态
- `e` 是来自 Prelude 的编码输入，在每次循环中注入
- `A` 和 `B` 是学习的注入参数
- Transformer 块照常应用注意力与 MLP

在每一步注入 `e` 可防止模型漂移 —— 它使原始输入信号在整个循环深度中保持活跃。

完整实现位于 [`open_mythos/main.py`](open_mythos/main.py)。请参阅 [`OpenMythos` 类参考](docs/open_mythos.md) 了解详细的 API 演练、配置选项与用法示例。

### 注意力实现

注意力层可通过 `cfg.attn_type` 切换：

| 选项 | 类 | 描述 |
|---|---|---|
| `"gqa"` | `GQAttention` | 分组查询注意力（Grouped Query Attention，Ainslie 等，2023）—— KV 头数少于 Q 头数（`n_kv_heads < n_heads`），将 KV-cache 内存降低 `n_heads / n_kv_heads`。当安装 `flash-attn>=2.8.3` 时使用 **Flash Attention 2**（Dao 等，2023）：原生支持 GQA（无需扩展 KV 头），I/O 绑定最优，并在未安装该包时透明回退到手动缩放点积注意力。 |
| `"mla"` | `MLAttention` | 多潜变量注意力（Multi-Latent Attention，DeepSeek-V2）—— 缓存压缩的 KV 潜变量（`kv_lora_rank`）而非完整 K/V，采用拆分 RoPE / 无 RoPE 头维度以实现位置感知压缩。 |

RoPE 在缓存之前应用于 Q 和 K，因此检索时无需对缓存值重新旋转。

---

## 这如何解释 Mythos

### 1. 系统性泛化（Systematic Generalization）

普通 Transformer 无法以训练中从未见过的方式组合知识。循环 Transformer 能通过这一考验。该能力通过**三阶段 grokking 过程**涌现：

1. 记忆（Memorization）—— 模型拟合训练分布
2. 分布内泛化（In-distribution generalization）—— 模型处理已知组合
3. 系统性泛化 —— 模型突然、陡然地处理分布外（OOD）的新颖组合

这就是为什么 Mythos 在新颖问题上给人的感觉与其他模型截然不同 —— 能力以相变方式涌现，而非逐渐显现。

### 2. 深度外推（Depth Extrapolation）

在 5 跳推理链上训练，在 10 跳上测试。普通 Transformer 失败。循环 Transformer 成功 —— 通过在推理时运行更多循环。这直接对应于 Mythos 能处理深度组合性问题（多步数学、长程规划、层层论证）而无需显式思维链（chain-of-thought）的观察。

推理时更多循环 = 更深的推理链 = 解决更难的问题。

### 3. 隐式思维链的潜态思考（Latent Thoughts as Implicit Chain-of-Thought）

每次循环迭代在功能上等价于思维链的一步，但运行于连续潜空间而非 token 空间。运行 T 次循环的循环模型隐式模拟 T 步 CoT 推理。这已有形式化证明（Saunshi et al., 2025）。

此外，连续潜态思考 —— 与离散 token 输出不同 —— 可同时编码**多种备选下一步**。这使得模型更接近于在推理空间上进行广度优先搜索，而非沿单条已确定的推理路径前进。模型在每次前向传播中实际上在探索多种可能方向，然后才收敛。

### 4. 无参数爆炸（No Parameter Explosion）

具有 k 层、运行 L 次的循环模型，可达到 kL 层非循环模型的质量，但参数量仅相当于 k 层。对于 Mythos 规模的部署，这一点至关重要：

- 内存占用不随推理深度增长
- 推理时计算量随循环次数扩展，而非模型规模
- 这使得更深推理在参数意义上近乎「免费」

---

## 稳定性问题（及其可能的解决方案）

训练循环模型 notoriously 不稳定。两种失效模式占主导：

- **残差爆炸** —— 隐藏状态 `h_t` 在循环间无界增长
- **损失尖峰** —— 注入参数中较大的谱范数导致训练突然发散

### 动力系统视角（The Dynamical Systems View）

将循环重新表述为残差流上的离散线性时不变（LTI）动力系统。忽略非线性 Transformer 贡献后，递推变为：

```
h_{t+1} = A·h_t + B·e
```

对该 LTI 系统，稳定性完全由 A 的**谱半径**决定：
- `ρ(A) < 1` → 稳定、收敛
- `ρ(A) ≥ 1` → 不稳定、发散

经验上，每一次发散的训练运行都会学到 `ρ(A) ≥ 1`。每一次收敛的运行都维持 `ρ(A) < 1`。

### 修复方案（The Fix）

约束注入参数，使稳定性**在构造上**得到保证：

1. 将 A 参数化为连续负对角矩阵
2. 使用 ZOH/Euler 方案离散化：`A_discrete = exp(Δt · A_continuous)`
3. 通过 `A := Diag(-exp(log_A))` 与可学习标量 `Δt` 强制负性
4. 这确保无论学习率或批次噪声如何，`ρ(A) < 1` 始终成立

结果：循环模型对超参数选择显著更鲁棒，即使在高学习率下也能干净训练。这就是 Parcae 架构（Prairie et al., 2026），它代表了 Anthropic 使 Mythos 可训练所采用的最可能一类解决方案。

---

## 循环模型的缩放定律（Scaling Laws for Looped Models）

Parcae 建立了循环训练的首套可预测缩放定律：

- **训练**：在固定 FLOP 预算与固定参数下，提高平均循环次数并减少 token 数量，相比在更多数据上以最少循环训练，可获得更低损失。最优循环次数与最优 token 数量均遵循**幂律**，且各规模下指数一致。
- **推理**：更多测试时循环按**可预测的饱和指数衰减**提升质量 —— 收益真实但递减。这与思维链的推理时缩放相呼应。

在 770M 参数下，循环模型达到与在相同数据上训练的 1.3B 固定深度 Transformer 相当的下游质量 —— 大致为**相同质量仅需约一半参数**。

应用于 Mythos：若按这些缩放定律训练，Mythos 的参数效率可能远比表面所见更高，其相当一部分看似的「能力」来自循环深度而非原始参数量。

---

## 循环索引嵌入假说（The Loop Index Embedding Hypothesis）

一个关键开放问题是：循环块在每次迭代中是否行为**完全相同**，还是能否在不同循环深度学习做不同的事。

若循环间没有任何位置信号，同一组权重必须同时处理早期模式匹配与后期精炼 —— 这是紧约束。在每一步与输入一同注入**类 RoPE 的循环索引嵌入**，可使同一参数在不同迭代中实现功能上不同的运算，正如 RoPE 使同一注意力头在不同序列位置表现不同。

若 Mythos 采用该技术，每次循环并非重复 —— 而是不同的计算阶段，共享权重但运行于不同的表示 regime。这将在不增加参数量的前提下大幅提升循环块的表达能力。

---

## 过度思考问题（The Overthinking Problem）

更多循环并不总是更好。超过一定深度后，过度循环会**劣化预测** —— 隐藏状态漂过解而进入噪声。这就是「过度思考」失效模式。

原始 Universal Transformer（Dehghani et al., 2018）通过**自适应计算时间（Adaptive Computation Time, ACT）**停机机制解决：每个位置一个可学习标量，动态决定何时停止循环。更难处理的位置获得更多计算；简单 token 提前停机。

Mythos 几乎肯定有某种版本。模型不能对每个输入天真地运行最大循环次数 —— 它需要可学习信号来判断答案何时收敛。ACT 机制还在特定假设下使模型**图灵完备（Turing-complete）**，这对它能求解的问题类有理论含义。

---

## 混合专家 —— 大参数量下的推测（Mixture of Experts — Suspected for Large Parameter Counts）

循环 Transformer 解释了 Mythos 推理的深度，但未解释广度。用同一组权重处理截然不同的领域 —— 代码、数学、文学、科学、法律 —— 需要**混合专家（Mixture of Experts, MoE）**。推测设计将循环块（Recurrent Block）中每个 FFN 替换为细粒度 MoE 层：每个 FFN 拆分为多个小专家（正常大小的 1/m），路由器通过可学习亲和分数为每个 token 选择 top-mK 个，少量**共享专家**无论路由如何始终激活，以吸收本应由各路由专家冗余学习的跨域共性知识 —— 语法、基础推理、通用上下文。通过训练期间动态调整路由器 logits 上的偏置项防止路由坍缩，在专家间保持负载均衡且不扭曲损失信号。

随着隐藏状态 `h_t` 在循环迭代中演化，路由器可能在每个深度选择不同专家子集，使每次循环在共享权重下计算上仍各不相同。MoE 提供广度；循环提供深度。若激活比例约为 5%，Mythos 可拥有数千亿总参数，而每个 token 仅激活一小部分 —— 真实参数量若日后披露，将是存储数字，而非计算数字。

---

## 记忆与推理的权衡

循环模型呈现出一种有趣的两分性：循环能提升推理能力，却可能损害记忆能力。递归结构针对迭代组合进行了优化——向前推进推理链——但并不会天然改善对机械事实的存储。

这与 Mythos 的一个可观察特征相对应：它对从未见过的新问题推理能力极强，但事实回忆可能不稳定。该架构在结构上偏向于组合而非记忆。

基于循环的正则化（Saunshi 等人，2025）可在训练期间用来平衡这一权衡——对推理任务施加更强的循环约束，而对检索任务则放松这些约束。

---

## 通过 LoRA 适配实现参数复用

来自 Relaxed Recursive Transformers（Bae 等人，2024）的一种互补方法：与其要求每次循环的权重完全一致，不如在每次迭代时添加一个小的**深度维度 LoRA 模块**。这既保持了权重共享的紧凑性，又允许每个循环略微调整其行为。

结果如下：
- 每次循环共享一个大型公共权重矩阵（递归基座）
- 一个小型秩为 r 的适配矩阵按迭代深度调整行为
- 总参数开销极小

这弥合了纯权重绑定（参数效率最高、表达能力较弱）与完全独立的层（表达能力最强、无参数节省）之间的差距。Mythos 很可能处于这一谱系的某个位置。

---

## 连续深度维度批处理

递归架构的一个下游后果：**连续深度维度批处理（Continuous Depth-wise Batching）**。由于所有 token 共享相同的递归块，模型可以为不同的 token 或序列在不同深度退出循环——在同一批次内快速处理简单输入、对困难输入进行更多迭代。

理论分析表明推理吞吐量可提升 2-3 倍。对于像 Mythos 这样同时服务大量用户的已部署模型，这将是可观的效率增益。

---

## 总结：Mythos 可能是什么

| 属性 | 描述 |
|---|---|
| 架构 | 递归深度 Transformer（Prelude + 循环递归块 + Coda） |
| FFN 层 | 疑似 MoE——细粒度专家 + 始终激活的共享专家 |
| 参数量 | 总量很大；每个 token 仅激活一小部分（约 5% 估计） |
| 推理机制 | 通过迭代隐状态更新实现隐式多跳——步骤之间无 token 输出 |
| 推理时扩展 | 更多循环 = 更深推理，遵循可预测的指数衰减 |
| 训练稳定性 | LTI 约束的注入参数，谱半径 < 1 |
| 循环区分 | 可能使用循环索引位置嵌入（类似 RoPE）区分每次迭代 |
| 停止 | 自适应计算时间（Adaptive Computation Time）或学习的收敛准则 |
| 注意力 | GQA（可选 Flash Attention 2）或带压缩 KV 隐状态缓存的 MLA |
| 缩放定律 | 最优训练将循环与数据同步扩展，而非单独扩展参数 |
| 推理 vs. 记忆 | 结构上偏向组合；记忆需要单独处理 |
| 部署 | 连续深度维度批处理可为每个请求分配可变计算量 |

---

## 参考文献

### Twitter / X

- Why Claude Mythos is so good — looped transformer theory (Sigrid Jin): https://x.com/realsigridjin/status/2044620031410266276
- LT implicit reasoning over parametric knowledge unlocks generalization (Yuekun Yao): https://x.com/yuekun_yao/status/2044229171627639004
- Looped transformer cyclic trajectories and input injection (rosinality): https://x.com/rosinality/status/2043953033428541853
- Parcae scaling laws for stable looped language models — thread (Hayden Prairie): https://x.com/hayden_prairie/status/2044453231913537927
- RoPE-like loop index embedding idea to differentiate functions across iterations (davidad): https://x.com/davidad/status/2044453231913537927
- On the Looped Transformers Controversy by ChrisHayduk: https://x.com/ChrisHayduk/status/2045947623572688943
- On the Looped Transformers Controversy Summary by @realsigridjin https://x.com/realsigridjin/status/2046012743778766875


### Papers

- Fine-grained expert segmentation and shared expert isolation in MoE: https://arxiv.org/abs/2401.06066
- Loop, Think, & Generalize — Implicit Reasoning in Recurrent Depth Transformers: https://arxiv.org/pdf/2604.07822
- Parcae — Scaling Laws for Stable Looped Language Models: https://arxiv.org/abs/2604.12946
- Parcae blog: https://sandyresearch.github.io/parcae/
- Universal Transformers: https://arxiv.org/pdf/1807.03819
- Reasoning with Latent Thoughts — On the Power of Looped Transformers: https://arxiv.org/abs/2502.17416
- Training Large Language Models to Reason in a Continuous Latent Space: https://arxiv.org/abs/2412.06769
- Relaxed Recursive Transformers — Effective Parameter Sharing with Layer-wise LoRA: https://arxiv.org/pdf/2410.20672
- Mixture-of-Depths Attention: https://arxiv.org/abs/2603.15619
- Hyperloop Transformers: https://arxiv.org/abs/2604.21254
- The Recurrent Transformer: Greater Effective Depth and Efficient Decoding: https://arxiv.org/abs/2604.21215
- LT2: Linear-Time Looped Transformers: https://arxiv.org/pdf/2605.20670

---

## 引用

如果在研究中使用 OpenMythos 或基于本工作构建，请引用：

```bibtex
@software{gomez2026openmythos,
  author    = {Kye Gomez},
  title     = {OpenMythos: A Theoretical Reconstruction of the Claude Mythos Architecture},
  year      = {2026},
  url       = {https://github.com/kyegomez/OpenMythos},
  note      = {Recurrent-Depth Transformer with MoE, MLA, LTI-stable injection, and ACT halting}
}
```

---

## 许可证

MIT License — Copyright (c) 2026 Kye Gomez。完整文本见 [`LICENSE`](LICENSE)。