# Fusion-LLM 架构设计文档

## 整体架构

```
┌─────────────────────────────────────────────┐
│         推理层 (Inference)                   │
│  Ollama | GGML/ONNX | TensorRT/OpenVINO     │
└─────────────────────────────────────────────┘
                        ↑
┌─────────────────────────────────────────────┐
│         模型层 (Models)                      │
│  FusionModel + SBLA + Thinking Dial          │
└─────────────────────────────────────────────┘
                        ↑
┌─────────────────────────────────────────────┐
│         训练层 (Training)                   │
│  LoRA | Full | DPO | GRPO | T-KD            │
└─────────────────────────────────────────────┘
                        ↑
┌─────────────────────────────────────────────┐
│         数据层 (Data Pipeline)               │
│  BilingualFilter | T-KD | Tokenizer         │
└─────────────────────────────────────────────┘
```

## 核心组件

### 1. FusionModel (models/fusion_model.py)

标准 Transformer 解码器 + 自定义注意力 + 可配置 KV 缓存。

关键特性:
- RMSNorm 归一化
- SwiGLU 激活
- RoPE 位置编码
- KV 缓存 (增量推理)
- GQA (Grouped Query Attention)

### 2. SBLA 注意力 (models/sbla_attention.py)

**Sliding Block Latent Attention** — 分块低秩近似注意力。

```
输入序列 T 个 token, 分块大小 B
  ↓
每块 [B tokens] → 块内高秩注意力 (O(B²))
  ↓
所有块合并 → 压缩至 latent_dim → 块间低秩注意力 (O(B·latent))
  ↓
output = output_std + gate · latent_expanded
```

**复杂度对比:**

| 方法 | 复杂度 | KV 缓存 | 长序列适用性 |
|------|--------|---------|-------------|
| 标准注意力 | O(n²) | 100% | 差 |
| GQA | O(n²) | ~50% | 一般 |
| **SBLA** | **O(n·B)** | **~12.5%** | **优** |

当前配置: block_size=8, latent_dim=8 (mini 模型)

### 3. Thinking Dial (models/thinking_dial.py)

推理深度控制器，通过 logits bias 调节思考深度。

```
depth=0: 无思考偏差 → 直接回答
depth=1: 简短思考 → 快速推理
depth=2: 中等思考 → 深入分析
depth=3: 深度思考 → 思维链模式
```

实现: 在 vocabulary 空间对特定 token 区间施加 depth × depth_bias 的 logits 偏移。

### 4. KV 缓存 (FusionModel.generate)

增量推理时缓存已计算的 K/V:

```python
# 增量推理流程
for step in range(max_new_tokens):
    if past_key_values:
        model_input = input_ids[:, -1:]  # 仅新 token
        outputs = model(model_input, past_key_values=past_key_values, ...)
    else:
        outputs = model(input_ids, ...)
    past_key_values = outputs.past_key_values
```

## 训练流程

### 预训练
```bash
# 完整参数微调
python train/full_finetune.py --data_path data/training_data.txt

# LoRA 微调
python train/lora_finetune.py --data_path data/training_data.txt
```

### 对齐训练
```bash
# DPO 对齐
python train/dpo_finetune.py

# GRPO Thinking Dial 训练
# 在 models/thinking_dial.py 的 GRPOTrainer
```

### 知识蒸馏
```bash
python data_pipeline/t_kd_distillation_train.py
```

## 部署方式

| 方式 | 格式 | 量化 | 适用场景 |
|------|------|------|---------|
| Ollama | ggml/gguf | 4/8-bit | 本地快速部署 |
| ONNX | .onnx | 动态 | 跨平台 |
| TensorRT | .plan | INT8 | 高性能推理 |
| OpenVINO | .blob | INT8 | Intel 硬件 |

## 文件结构

```
fusion-llm/
├── models/
│   ├── fusion_model.py      # 主模型 (Transformer 解码器)
│   ├── fusion_mini.py       # 小型变体 (4.5M params)
│   ├── sbla_attention.py    # SBLA 注意力实现
│   ├── thinking_dial.py     # Thinking Dial + GRPOTrainer
│   └── tokenizer.py         # 统一 tokenizer 接口
├── train/
│   ├── full_finetune.py     # 全参数微调
│   ├── lora_finetune.py     # LoRA 微调
│   ├── dpo_finetune.py      # DPO 对齐
│   └── model_utils.py       # 模型创建工具
├── inference/
│   ├── ollama_deploy_v2.py  # Ollama 部署
│   ├── dyquant.py           # 动态量化
│   └── dashboard.py         # 可视化推理面板
├── deployment/
│   ├── export_ggml.py       # GGML/GGUF 导出
│   ├── export_onnx.py       # ONNX 导出
│   └── export_tensorrt_openvino.py  # TensorRT/OpenVINO
├── evaluation/
│   ├── metrics.py           # 基础指标
│   ├── bertscore_moverscore.py  # 语义相似度
│   ├── bleu_rouge_meteor.py # BLEU/ROUGE/METEOR
│   ├── gsm8k_reward.py      # GSM8K 奖励函数
│   └── model_card.py        # 模型卡片生成
└── data_pipeline/
    ├── bilingual_filter.py   # 双语数据过滤
    └── t_kd_distillation.py # 知识蒸馏
```

## 已知限制

1. **无预训练权重**: 当前仅有合成数据训练的 mini 模型，无法直接用于实际任务
2. **Mini 模型能力有限**: 4.5M 参数仅能学习简单模式（加法），复杂任务需要更大模型和真实数据
3. **双母语训练**: 架构已就绪，缺真实中英双语训练数据和训练资源
4. **Thinking Dial 效果待验证**: 在简单任务上 depth=0 优于 depth=3（符合预期），复杂任务有待评估