README_zh.md

# TMCRA TokenGraph-LLM Stage C

TMCRA TokenGraph-LLM 是实验性的图原生自回归语言模型原型。它不是 Transformer 外壳，推理时也不调用外部 LLM。文本生成来自 token 级图编码、学习式边门控、图消息传递和动态图因果解码器。

本 Hugging Face 仓库主要托管模型资产。完整源码、训练脚本、建图脚本和文档在 GitHub：

https://github.com/reshuibuduo/TMCRA-TokenGraph-LLM

## 当前模型

- 版本线：`v0.2.0-stagec`
- 模型包：`tmcra_tokengraph_stagec_model_package_20260606.zip`
- checkpoint：`checkpoint/token_graph_dynamic_decoder_v3.pt`
- 参数量：`114,615,372`
- 结构：`dim=512`，`graph_layers=8`，`decoder_layers=10`
- embedding：untied
- 训练精度：`bf16`
- 有效训练样本：约 `1.03M`
- 训练步数：`62,000`
- SHA256：`cc23285628eaed47c20009b6be6b5eb0600ded57ac2e09519370d97158fecd33`

旧 v0.1 文件可能仍保留用于历史对比。当前推荐使用 Stage C 模型包。

## 全链路训练代码

GitHub 源码仓库已经补齐 Stage C 全链路训练路径：

- 开源语料转换为 schema2 JSONL；
- 可选 OpenAI 兼容接口或本地 Hugging Face teacher 标注；
- token-level reasoning graph dataset 构建；
- `simple_plus_causal_target` 图模式；
- Stage C 训练和 checkpoint 续训；
- 图消融和 token attribution 评测。

入口文档：

```text
docs/FULL_CHAIN_TRAINING.md
docs/FULL_CHAIN_TRAINING_ZH.md
scripts/run_stagec_full_chain_template.sh
scripts/run_stagec_sharded_training_template.sh
```

## Next-Token 生成机制

Stage C 通过图原生因果链路预测下一个 token：

```mermaid
flowchart TD
    A["Text / prompt / source segments / target text"] --> B["Tokenizer"]
    B --> C["Token Graph Builder"]
    C --> D["Token nodes"]
    C --> E["Typed candidate edges"]
    D --> G["TokenGraphEncoderV3"]
    E --> G
    G --> H["Encoded context graph states"]
    H --> I["Dynamic Token Graph Decoder"]
    I --> J["Generated token node"]
    J --> I
    I --> K["Next-token distribution"]
```

```text
schema2 text
  -> token graph nodes and typed candidate edges
  -> learned edge-gated graph propagation
  -> dynamic generated-token graph nodes
  -> prefix-edge + context-edge gated decoding
  -> vocabulary logits
```

建图程序提出 token 节点和 typed candidate edges；模型学习每条候选边的 gate，并通过 token graph 做消息传递。推理时，已经生成的 token 会作为动态 generated-token graph nodes 继续参与后续生成。decoder 同时接收来自历史 generated-token nodes 的 prefix message，以及来自 encoded graph nodes 的 context message，最后把更新后的 graph-decoder state 映射成 next-token logits。主目标仍然是 next-token prediction，但 hidden state 来源是 typed graph propagation 和 dynamic graph decoding，而不是 Transformer self-attention。

单步解码图：

```mermaid
flowchart LR
    A["Encoded context graph<br/>N nodes"] --> D["Context gate"]
    B["Generated prefix nodes<br/>window W"] --> C["Prefix gate"]
    C --> E["Generated-token node t"]
    D --> E
    E --> F["Graph decoder update"]
    F --> G["Vocabulary logits"]
    G --> H["next token"]
    H --> I["Append as graph node"]
```

## 复杂度增长机制

Transformer dense self-attention 的交互成本大致是：

```text
O(n^2 * d)
```

Stage C 用候选图边和动态图解码替代 sequence-wide all-token attention：

```text
Graph encoder:        O(L_g * (N + E) * d)
Dynamic prefix path:  O(L_d * T * W * d)
Context tunnel path:  O(L_d * T * N * d)
```

其中 `N` 是 context graph nodes，`E` 是 candidate edges，`T` 是生成长度，`W` 是有限 generated-prefix window。当前 context tunnel 仍然会扫描 encoded context nodes；准确说法不是“恒定成本生成”，而是用 sparse typed graph propagation 和 explicit context tunneling 替代 dense sequence-wide self-attention。

## 能力边界

Stage C 能生成早期英文故事续写，并且图消融显示 typed graph edges 会实质影响生成结果。它还不是生产可用 LLM。当前弱项包括精确事实问答、数值推理、稳定指令跟随、强语法、多语种生成和长程概念绑定。

当前结果是 smoke 测试，不是榜单成绩。

## 许可证

MIT。