> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monostate.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 日志记录与调试
> 监控训练并调试问题
# 日志记录与调试
监控训练进度并诊断问题。
## 日志选项
### Weights & Biases
```bash theme={null}
aitraining llm --train \
--model google/gemma-3-270m \
--data-path ./data \
--project-name my-model \
--log wandb
```
功能：
* 实时损失曲线
* 硬件指标
* 超参数跟踪
* 模型工件
### TensorBoard
```bash theme={null}
aitraining llm --train \
--model google/gemma-3-270m \
--data-path ./data \
--project-name my-model \
--log tensorboard
```
在浏览器中查看：
```bash theme={null}
tensorboard --logdir my-model/runs
```
### W\&B 可视化器（LEET）
内置终端可视化器，在您的终端中显示实时指标。
使用 `--log wandb` 时，W\&B 可视化器**默认启用**。使用 `--no-wandb-visualizer` 禁用它。
```bash theme={null}
# 使用 wandb 时默认启用可视化器
aitraining llm --train \
--model google/gemma-3-270m \
--data-path ./data \
--project-name my-model \
--log wandb
# 禁用终端可视化器
aitraining llm --train \
--model google/gemma-3-270m \
--data-path ./data \
--project-name my-model \
--log wandb \
--no-wandb-visualizer
```
## 日志步骤
控制日志频率：
```bash theme={null}
aitraining llm --train \
--model google/gemma-3-270m \
--data-path ./data \
--project-name my-model \
--logging-steps 10 # 每 10 步记录一次
```
## 详细输出
### 捕获完整日志
```bash theme={null}
aitraining llm --train ... 2>&1 | tee training.log
```
## 环境变量
这些环境变量影响日志记录和调试行为：
| 变量 | 描述 |
| ---------------------- | ----------------------------- |
| `AUTOTRAIN_TUI_MODE=1` | 在 TUI 模式下运行时抑制日志（自动设置） |
| `PAUSE_ON_FAILURE=0` | 失败时不暂停（默认：1，启用） |
| `WANDB_API_KEY` | Weights & Biases API 密钥用于日志记录 |
### 噪声抑制
这些会自动设置以减少日志噪声：
| 变量 | 值 | 效果 |
| ------------------------ | ------- | -------------------- |
| `TF_CPP_MIN_LOG_LEVEL` | `3` | 抑制 TensorFlow 警告 |
| `TOKENIZERS_PARALLELISM` | `false` | 禁用标记器并行警告 |
| `BITSANDBYTES_NOWELCOME` | `1` | 抑制 bitsandbytes 欢迎消息 |
## 常见问题
### 内存不足（OOM）
症状：
* "CUDA out of memory" 错误
* 训练突然崩溃
解决方案：
```bash theme={null}
# 减小批次大小
aitraining llm --train --batch-size 1 ...
# 启用梯度检查点（默认开启）
# 如果禁用，重新启用：
# --disable-gradient-checkpointing false
# 使用梯度累积
aitraining llm --train \
--batch-size 1 \
--gradient-accumulation 8 \
...
# 启用自动批次大小查找
aitraining llm --train --auto-find-batch-size ...
# 使用量化
aitraining llm --train --quantization int4 ...
```
### 训练缓慢
检查：
1. **GPU 利用率**：
```bash theme={null}
nvidia-smi -l 1 # 监控 GPU 使用情况
```
2. **启用优化**：
```bash theme={null}
aitraining llm --train \
--use-flash-attention-2 \
--packing \
--mixed-precision bf16 \
...
```
3. **数据加载瓶颈**：
* 确保数据在快速存储（SSD）上
* 预处理数据以减少标记化开销
* 如果可能，使用较小的序列长度
### NaN 损失
症状：
* 损失变为 NaN
* 训练发散
解决方案：
```bash theme={null}
# 降低学习率
aitraining llm --train --lr 1e-6 ...
# 添加梯度裁剪
aitraining llm --train --max-grad-norm 0.5 ...
# 使用 fp32 而不是 fp16/bf16
aitraining llm --train --mixed-precision no ...
```
### 数据问题
症状：
* 意外行为
* 模型质量差
调试步骤：
```python theme={null}
# 检查数据格式
import json
with open("data.jsonl") as f:
for i, line in enumerate(f):
try:
data = json.loads(line)
print(f"Line {i}: {list(data.keys())}")
except:
print(f"Line {i}: INVALID JSON")
if i >= 5:
break
```
```bash theme={null}
# 预览数据处理
aitraining llm --train \
--max-samples 10 \
--epochs 1 \
...
```
## 检查点
### 保存策略
```bash theme={null}
aitraining llm --train \
--save-strategy steps \
--save-steps 500 \
--save-total-limit 3 \
...
```
### 恢复训练
如果训练崩溃，从检查点恢复：
```bash theme={null}
aitraining llm --train \
--model ./my-model/checkpoint-500 \
--data-path ./data \
...
```
## 监控工具
### GPU 监控
```bash theme={null}
# 实时 GPU 统计
watch -n 1 nvidia-smi
# GPU 内存使用随时间变化
nvidia-smi --query-gpu=memory.used --format=csv -l 5
```
### 系统资源
```bash theme={null}
# CPU 和内存
htop
# 磁盘 I/O
iostat -x 1
```
## 调试清单
1. **检查日志** - 查找错误消息
2. **验证数据** - 确保格式正确
3. **检查 GPU** - 内存和利用率
4. **尝试更小** - 减小批次/模型大小
5. **隔离问题** - 最小化复现
## 下一步
运行多个实验
自动化工作流