CONTRIBUTING.md

贡献指南

感谢你对 Fusion 项目的兴趣！这份文档将指导你如何参与贡献。

🚀 快速开始

1. Fork 和克隆

# Fork 本仓库（在 GitHub 上点击 Fork 按钮）

# 克隆你的 Fork
git clone https://github.com/YOUR_USERNAME/fusion-llm.git
cd fusion-llm

# 添加上游仓库
git remote add upstream https://github.com/zhan1206/fusion-llm.git

2. 创建开发环境

# 创建虚拟环境（推荐）
conda create -n fusion python=3.10
conda activate fusion

# 安装依赖
pip install -r requirements.txt

# 安装开发依赖
pip install -e ".[dev]"

3. 创建分支

git checkout -b feature/your-feature-name

---

🎯 如何贡献

报告 Bug

打开 Issue，并包含：

• 操作系统版本
• Python 版本
• 依赖版本（pip freeze）
• 重现步骤
• 期望行为 vs 实际行为

建议新功能

打开 Discussion 讨论你的想法。

提交代码

1. 遵循代码规范

   • 使用 Python 3.8+ 语法
   • 遵循 PEP 8 规范
   • 使用类型注解（type hints）
   • 添加文档字符串（docstrings）

2. 编写测试

   • 为所有新功能编写单元测试
   • 确保测试覆盖率 >80%
   • 运行 pytest tests/

3. 提交信息规范

   使用 Conventional Commits 格式：

   feat: 添加 DyQuant 混合精度量化工具
   ^
   |__ 类型：feat|fix|docs|style|refactor|test|chore
   

   示例：

   feat: 实现 SBLA 注意力机制的 CPU 版本
   fix: 修复 Thinking Dial 在 batch 生成时的维度错误
   docs: 更新训练指南，添加 24GB 显卡配置示例
   test: 为 bilingual_filter.py 添加单元测试
   

4. 提交 Pull Request

   • 填写 PR 模板
   • 关联相关的 Issue（Fixes #123）
   • 等待代码审查

---

🧪 测试指南

运行测试

# 运行所有测试
pytest tests/ -v

# 运行特定测试文件
pytest tests/test_sbla_attention.py -v

# 检查测试覆盖率
pytest tests/ --cov=models --cov-report=html

编写测试

测试文件位于 tests/ 目录，命名格式：test_*.py

示例：

import torch
from models.sbla_attention import SlidingBlockLatentAttention

def test_sbla_forward():
    """测试 SBLA 注意力前向传播"""
    batch_size = 2
    seq_len = 1024
    d_model = 512
    
    attn = SlidingBlockLatentAttention(
        d_model=d_model,
        n_heads=8,
        block_size=512,
    )
    
    x = torch.randn(batch_size, seq_len, d_model)
    output = attn(x)
    
    assert output.shape == (batch_size, seq_len, d_model)

---

📂 项目结构

fusion-llm/
├── models/              # 模型架构
│   ├── fusion_model.py      # 完整模型定义
│   ├── sbla_attention.py   # SBLA 注意力
│   └── thinking_dial.py    # Thinking Dial
├── train/               # 训练脚本
│   ├── lora_finetune.py    # LoRA/QLoRA
│   └── full_finetune.py    # 全参数微调
├── data_pipeline/       # 数据处理
│   └── bilingual_filter.py  # 双母语清洗
├── inference/           # 推理部署
│   └── ollama_deploy.py    # Ollama 部署
├── configs/             # 配置文件
│   └── ds_zero3.json       # DeepSpeed 配置
├── tests/               # 单元测试
├── docs/                # 文档
└── scripts/             # 工具脚本

---

🎨 代码风格

Python 规范

• 使用 Black 格式化：black models/ train/
• 使用 isort 排序导入：isort models/ train/
• 使用 Flake8 检查：flake8 models/ --max-line-length=120

文档规范

• 使用 Google 风格 docstrings：

def my_function(param1: int, param2: str) -> bool:
    """
    函数简短描述
    
    详细描述（可选）
    
    Args:
        param1: 参数1的描述
        param2: 参数2的描述
        
    Returns:
        返回值的描述
        
    Raises:
        ValueError: 参数错误时
    """
    pass

---

🐛 Debug 技巧

调试 SBLA 注意力

# 在 models/sbla_attention.py 添加调试信息
import pdb; pdb.set_trace()

# 或使用 print
print(f"Q shape: {q.shape}")
print(f"Attention weights: {attn_weights.shape}")

调试训练问题

# 使用 --debug 模式（如果支持）
python train/lora_finetune.py --debug ...

# 检查显存使用
nvidia-smi -l 1

# 使用 TensorBoard
tensorboard --logdir=runs

---

📊 性能优化建议

模型训练

• 使用 混合精度训练（--fp16 或 --bf16）
• 使用 梯度累积（--gradient_accumulation_steps 8）
• 使用 DeepSpeed ZeRO（--deepspeed configs/ds_zero3.json）

推理优化

• 使用 量化（q4_k_m 或 q8_0）
• 使用 KV 缓存（use_cache=True）
• 使用 批处理（batch_size > 1）

---

💬 社区

• 讨论区: GitHub Discussions
• Discord: （待创建）
• 微信/QQ 群: （待创建）

---

📜 行为准则

请阅读并遵守我们的 行为准则（待创建）。

---

❓ 需要帮助？

• 查看 文档
• 搜索已有 Issues
• 在 Discussions 提问

---

再次感谢你的贡献！ 🙏

让我们一起打造最强的开源大模型！ 🚀