docs/tutorial.md

Fusion-LLM 使用教程

简介

Fusion-LLM 是一个开源大语言模型项目，采用 Apache 2.0 许可证，核心理念为用户主权、纯本地训练推理。

核心特性

• SBLA 注意力：滑动分块潜注意力（Sliding Block Latent Attention）
• Thinking Dial：动态推理强度控制
• 纯本地：无需云端，完全本地训练和推理
• 用户主权：数据完全由用户控制

---

安装

环境要求

• Python 3.8+
• PyTorch 2.0+
• CUDA 11.7+ (可选，用于 GPU 加速)

安装步骤

1. 克隆仓库

git clone https://github.com/zhan1206/fusion-llm.git
cd fusion-llm

2. 安装依赖

pip install -r requirements.txt

3. 验证安装

python tests/test_tiny.py

如果看到 [PASS] 测试通过，说明安装成功！

---

快速开始

1. 最小训练测试（验证安装）

运行最小训练测试（1-2 步，快速验证训练功能）：

python train/test_train_mini.py

预期输出：

[TRAIN] 开始最小训练（1-2 步）...
[5] 训练 2 步...
   Step 1: Loss = 4.5879
   Step 2: Loss = 4.5768
   训练完成
[6] 验证损失下降...
   [PASS] Loss 下降: 4.5879 -> 4.5768
   训练有效！

[PASS] 训练测试通过

2. 小训练测试（10 步）

运行小训练测试（10 步，验证损失持续下降）：

python train/train_10steps.py

预期输出：

[TRAIN] 开始小训练（10 步）...
[5] 训练 10 步...
   Step  1: Loss = 6.9452
   Step  2: Loss = 6.8520
   ...
   Step 10: Loss = 6.3993
   训练完成
[6] 验证损失下降...
   [PASS] Loss 持续下降
   训练有效！

[PASS] 训练测试通过

3. 实际模型训练（100 步）

运行实际模型训练（100 步，生成模型权重）：

python train/train_real.py

预期输出：

[TRAIN] 开始实际模型训练（100 步）...
[6] 训练 100 步...
   Step  10: Loss = 3.5885 (Avg: 4.0321)
   ...
   Step 100: Loss = 1.7501 (Avg: 1.9562)
   训练完成
[7] 验证损失下降...
   [PASS] Loss 持续下降
   训练有效！

[8] 保存模型...
   模型保存路径: output/real_model
   模型保存成功

[PASS] 训练测试通过

训练完成后，模型权重将保存到 output/real_model/ 目录。

---

模型推理

1. 基本推理测试

运行基本推理测试：

python tests/test_inference_basic.py

2. 使用训练好的模型进行推理

import torch
from models.fusion_mini import FusionMini, FusionMiniConfig

# 加载模型
model = FusionMini.from_pretrained("output/real_model")
model.eval()

# 创建输入
input_ids = torch.tensor([[1, 2, 3, 4, 5]])

# 推理
with torch.no_grad():
    outputs = model(
        input_ids=input_ids,
        return_dict=True,
    )
    
    logits = outputs["logits"]
    print(f"Logits shape: {logits.shape}")

---

高级功能

1. Thinking Dial（动态推理强度控制）

Thinking Dial 允许动态控制模型的推理强度。

from models.thinking_dial import ThinkingDialProcessor

# 创建处理器
processor = ThinkingDialProcessor()

# 注入 think token
text = "<|think_depth_2|> 这是一个需要深入思考的问题。"
processed_text = processor.process(text)

print(processed_text)

2. SBLA 注意力

SBLA（Sliding Block Latent Attention）是 Fusion-LLM 的核心注意力机制。

from models.sbla_attention import SBLAttention

# 创建 SBLA 注意力层
attention = SBLAttention(
    hidden_size=128,
    num_heads=2,
    window_size=16,
)

# 前向传播
hidden_states = torch.randn(1, 32, 128)
output = attention(hidden_states)
print(f"Output shape: {output.shape}")

3. 动态量化（DyQuant）

DyQuant（Dynamic Quantization）提供动态混合精度量化（4/8/16-bit）。

from inference.dyquant import DyQuant

# 创建量化器
quantizer = DyQuant()

# 量化模型
quantized_model = quantizer.quantize(model, bits=8)

# 保存量化模型
quantizer.save(quantized_model, "output/quantized_model")

---

训练配置

1. 使用配置文件

创建配置文件 configs/my_config.json：

{
    "vocab_size": 1000,
    "hidden_size": 128,
    "num_hidden_layers": 2,
    "num_attention_heads": 2,
    "intermediate_size": 256,
    "max_position_embeddings": 64
}

使用配置文件训练：

python train/full_finetune.py --config configs/my_config.json

2. LoRA 微调

使用 LoRA 进行参数高效微调：

python train/lora_finetune.py \
    --model_name_or_path output/real_model \
    --lora_r 8 \
    --lora_alpha 16 \
    --train_epochs 3

---

评估与指标

1. 使用评估指标

from evaluation.metrics import EvaluationMetrics, ModelEvaluator

# 创建评估器
evaluator = ModelEvaluator()

# 评估模型
metrics = evaluator.evaluate(
    model=model,
    eval_data=eval_dataset,
    metrics=["perplexity", "loss", "accuracy"],
)

print(f"Perplexity: {metrics.perplexity:.2f}")
print(f"Loss: {metrics.loss:.4f}")
print(f"Accuracy: {metrics.accuracy:.4f}")

2. 生成模型卡片

python evaluation/model_card.py \
    --model_path output/real_model \
    --output_path output/model_card.json

---

部署

1. Ollama 部署

使用 Ollama 部署模型：

python inference/ollama_deploy_v2.py \
    --model_path output/real_model \
    --output_path output/ollama_model

2. 量化部署

使用动态量化减小模型大小：

python inference/dyquant.py \
    --model_path output/real_model \
    --bits 8 \
    --output_path output/quantized_model

---

常见问题

1. 训练时 Loss 不下降？

可能原因：

• 学习率太大或太小
• 数据量太少
• 模型太小

解决方案：

• 调整学习率（尝试 1e-4 到 5e-4）
• 增加训练数据量
• 增大模型配置（hidden_size、num_layers）

2. 推理时出现 NaN？

可能原因：

• 注意力掩码错误
• 梯度爆炸

解决方案：

• 检查注意力掩码格式
• 使用梯度裁剪（torch.nn.utils.clip_grad_norm_）

3. 训练速度太慢？

可能原因：

• SBLA 注意力计算量大
• 没有使用 GPU

解决方案：

• 使用更小的配置（hidden_size=32, num_layers=1）
• 使用 GPU 训练
• 启用混合精度训练（FP16/BF16）

---

贡献

欢迎贡献！请查看 CONTRIBUTING.md 了解详情。

---

许可证

Fusion-LLM 采用 Apache 2.0 许可证。查看 LICENSE 文件了解详情。