FAQ - 常见问题
本文档收集了在使用 LLM 项目时的常见问题和解答.
目录
安装和环境
Q: 如何设置开发环境？
使用 make init 命令即可一键设置：
这会自动创建虚拟环境、安装依赖并配置 pre-commit 钩子.
Q: 为什么项目使用 uv 而不是 pip？
uv 是用 Rust 编写的现代 Python 包管理器, 相比 pip 有以下优势：
- 速度快: 依赖解析和安装速度快 10-100 倍
- 可靠性: 更好的依赖冲突解决
- 锁文件: 提供
uv.lock确保可重现构建
了解更多：uv 官方文档
训练相关
Q: 我应该使用哪个任务？
项目提供了两个主要任务：
lm: 语言模型任务(推荐)- 用于训练生成式语言模型regression: 回归任务 - 用于简单的回归测试
示例：
# Regression task (uses synthetic data, works out of the box)
llm-train --task regression --epochs 10 --batch-size 32
# Language modeling task (requires dataset configuration)
llm-train --task lm --config-path configs/example.yaml --epochs 10
[!NOTE]
--task lm需要通过配置文件指定数据集。快速实验可使用scripts/train_simple_decoder.py。
Q: 如何启用分布式训练？
使用 torchrun 启动多 GPU 训练：
Q: 内存不足 (OOM) 怎么办？
尝试以下方法：
- 减小 batch size:
--batch-size 16 - 启用混合精度: 默认已启用 AMP
- 减小模型大小:
--model.hidden_size 512 - 使用 Gradient Checkpointing: 将在未来版本中支持
模型架构
Q: 什么是 GQA (Grouped Query Attention)？
GQA 是一种优化的注意力机制, 通过让多个 Query 头共享同一组 Key/Value 头来减少 KV Cache 的显存占用.
优势:
- 显存占用减少 40-60%
- 推理速度提升 20-30%
- 训练性能几乎无损失
配置:
详见：Tutorial
Q: 什么是 SwiGLU？
SwiGLU 是一种结合 Swish 激活和门控线性单元的激活函数, 相比标准 GELU 能提供更好的性能.
启用方式:
详见：Tutorial
Q: 如何选择使用 LayerNorm 还是 RMSNorm？
- LayerNorm: 标准选择, 稳定可靠
- RMSNorm: 更快的计算速度, 内存占用更少, 效果相当
性能优化
Q: 如何提升训练速度？
- 启用混合精度: 默认已启用
- 优化数据加载: 增加
num_workers - 使用 torch.compile: 将在未来版本中集成
- 使用多 GPU: 见分布式训练问题
Q: 推理速度慢怎么办？
- 使用 KVCache: 见 Inference Optimization Guide
- 使用 Top-k 采样: 减小搜索空间
- 批处理推理: 同时处理多个请求
- 合并 LoRA 权重: 推理前调用
merge_lora(model)
LoRA / QLoRA
Q: LoRA 和 QLoRA 有什么区别？
| 特性 | LoRA | QLoRA |
|---|---|---|
| 基础权重 | FP16/FP32 | 4-bit NF4 |
| 内存占用 | ~10% 参数 | ~5% 内存 |
| 推理开销 | 可合并, 无开销 | 需反量化 |
| 适用场景 | 有足够显存 | 显存严重受限 |
Q: 如何选择 LoRA rank？
- rank=4-8: 简单任务, 快速实验
- rank=16-32: 复杂任务, 更多容量
- alpha: 通常设为
2 * rank
开发工具
Q: 为什么使用 ty 而不是 mypy？
ty 是 Astral 出品的现代类型检查器, 与 Ruff 同系列：
- 速度快: 比 mypy 快数倍
- 更好的错误信息: 更清晰的类型错误提示
- 零配置: 开箱即用
Q: 为什么使用 prek 而不是 pre-commit？
prek 是更现代的 Git 钩子管理工具：
- 性能更好: 使用 Rust 编写
- 更简单的配置: 与项目工具链一致
- 更好的集成: 原生支持 uv, ruff, ty 等工具
Q: 如何运行代码质量检查？
其他问题
Q: 如何贡献代码？
请参考 Contributing Guide 了解详细流程.
Q: 在哪里报告 Bug？
请在 GitHub Issues 提交 bug 报告, 使用 bug report 模板.
Q: 如何获取帮助？
- 查看本 FAQ 和其他文档
- 查看 Troubleshooting Guide
- 在 GitHub Discussions 提问
- 提交 Issue(如果是 bug)
找不到答案？ 欢迎在 GitHub Discussions 提问！