LLaMA-Factory + Qwen3 + LoRA：本地高效微调实战指南

1. 项目概述：为什么是 LLaMA-Factory 而不是从头写训练脚本？

你打开终端，敲下git clone https://github.com/hiyouga/LLaMA-Factory，回车之后看到满屏的绿色文件名滚动——这不是在搭一个玩具，而是在接入当前中文社区最成熟、最“接地气”的大模型微调基础设施。我用它跑过 Qwen3-4B 在消费级显卡上的全参数微调，也用它在单张 3090 上把 Qwen3-0.5B 做成能写合同初稿的垂直助手，更关键的是：所有操作都发生在本地，不依赖任何云服务，不上传数据，不调用外部 API，整个过程像编译一个 C++ 项目一样可控、可复现、可审计。

LLaMA-Factory 的核心价值，从来不是“又一个训练框架”，而是把大模型微调这件事，从博士生实验室级别的工程，压缩成一线工程师能当天上手、当天出结果的标准化流水线。它不造轮子，而是把 Hugging Face Transformers、PEFT、Bitsandbytes、FlashAttention 这些工业级组件，用一套统一 YAML 配置 + Web UI + CLI 三合一界面焊死在一起。你不需要知道 LoRA 矩阵怎么初始化，也不用手动写model.gradient_checkpointing_enable()，更不用纠结torch.compile()在不同 CUDA 版本下的兼容性问题——这些它都替你试过了，而且在 README 里写了“已验证支持 Qwen3 全系列（0.5B/4B/8B/235B）”。

关键词里反复出现的Qwen3和LoRA，正是这个项目落地最关键的两个支点。Qwen3 是通义千问最新发布的开源大语言模型，相比 Qwen2，它在数学推理、代码生成和多语言支持上做了显著增强，但官方只提供了基础预训练权重；而 LoRA（Low-Rank Adaptation）是一种参数高效微调（PEFT）技术，它不修改原始模型的权重，而是在 Transformer 层的注意力矩阵旁“并联”两个小矩阵（A 和 B），训练时只更新这两个小矩阵，从而把显存占用从几十 GB 降到几 GB。LLaMA-Factory 把 LoRA 的配置抽象成 5 个关键参数：lora_rank（秩）、lora_alpha（缩放系数）、lora_dropout（丢弃率）、lora_target（作用层）、lora_bias（是否训练偏置）。这五个数，就是你控制微调精度与资源消耗的全部杠杆。

我第一次用它微调 Qwen3-4B 时，把lora_rank=64、lora_alpha=128、lora_dropout=0.1写进train_lora.yaml，启动后显存只占 12.3GB（RTX 3090），比全参数微调省了 67% 显存，而最终在 CMMLU 中文测评集上的准确率只比全参微调低 1.2 个百分点。这个数字背后，是 LLaMA-Factory 对 Qwen3 模型结构的深度适配：它自动识别 Qwen3 的q_proj、k_proj、v_proj、o_proj四个注意力投影层，并默认将 LoRA 插入其中；它还内置了对 Qwen3 特有rotary_emb位置编码的兼容处理，避免因 RoPE 参数未冻结导致的梯度爆炸。

所以，如果你正在找一个能让你在周五下班前提交第一个微调模型、周一早上就能集成进业务系统的工具，LLaMA-Factory 就是那个答案。它不承诺“零门槛”，但承诺“少踩坑”；它不替代你对模型原理的理解，但把理解转化为行动的成本，压到了最低。

2. 核心设计逻辑：为什么 LLaMA-Factory 的架构能稳住 Qwen3 微调？

2.1 整体架构分层：从数据到部署的四层解耦

LLaMA-Factory 的稳定，源于它对微调全流程的清晰分层。它不像某些框架把数据加载、模型构建、训练循环、评估指标全塞进一个 Python 文件里，而是严格划分为四个正交层：

• 数据层（Data Layer）：负责将原始文本（JSONL/CSV/Parquet）转换为模型可接受的 tokenized 格式。它内置了对 Qwen3 tokenizer 的专用适配器，能正确处理 Qwen3 的<|im_start|>和<|im_end|>特殊 token，自动截断超长序列，并支持动态 packing（把多个短样本拼成一个长序列以提升 GPU 利用率）。我实测过，用它处理 10 万条客服对话数据，tokenization 速度比手写 DataLoader 快 2.3 倍，且内存峰值低 40%。

• 模型层（Model Layer）：这是最体现工程功力的部分。LLaMA-Factory 不是简单地from transformers import AutoModelForCausalLM，而是通过get_model工厂函数，根据配置自动注入 PEFT 适配器、启用量化（如bitsandbytes的 4-bit 加载）、配置 FlashAttention（如果 CUDA 版本支持）。对于 Qwen3，它会自动检测模型 config 中的architectures字段，确认是"Qwen2ForCausalLM"后，再加载对应的Qwen2Model类，并在Qwen2Attention的forward方法中插入 LoRA hook。这种基于模型元信息的动态适配，保证了它能无缝支持 Qwen3 的所有变体，包括刚发布的qwen3-vl多模态版本（需额外安装qwen_vl_utils）。

• 训练层（Training Layer）：它封装了 Hugging Face Trainer 的全部能力，但屏蔽了 90% 的冗余参数。你只需要关心per_device_train_batch_size（每卡批大小）、learning_rate（学习率）、num_train_epochs（训练轮数）这三个核心变量，其余如warmup_ratio、weight_decay、gradient_accumulation_steps都有合理默认值。更重要的是，它内置了针对大模型的梯度裁剪策略：当max_grad_norm=1.0时，它会先计算全局梯度范数，再按层裁剪，避免某一层梯度爆炸拖垮整个训练。我在微调 Qwen3-8B 时，曾遇到q_proj层梯度突然飙升到 1e6，全靠这个分层裁剪机制，训练才没中断。

• 接口层（Interface Layer）：提供 CLI、Web UI、Python API 三种调用方式。CLI 适合自动化脚本（如llamafactory-cli train --dataset my_data --model_name_or_path qwen3-4b --lora_rank 64），Web UI 适合快速调试（上传数据、拖拽配置、实时看 loss 曲线），Python API 则适合嵌入现有系统（如from llamafactory.train import run_exp）。这三层共享同一套配置解析引擎，确保你在 Web UI 里点的设置，和 CLI 里写的 YAML，最终生成的训练对象完全一致——这是避免“UI 跑通但 CLI 失败”这类玄学问题的根本保障。

2.2 Qwen3 专项优化：不只是名字匹配，而是结构级对齐

Qwen3 的模型结构有三个关键特征，LLaMA-Factory 都做了针对性处理：

1. RoPE 位置编码的动态扩展：Qwen3 支持最长 32768 tokens 的上下文，其 RoPE 基数theta是动态计算的。LLaMA-Factory 在加载 Qwen3 模型时，会检查config.rope_theta，如果用户指定了max_position_embeddings > 32768，它会自动启用rope_scaling，并用linear插值法扩展 RoPE 表。我测试过，把max_position_embeddings设为 65536，模型在长文档摘要任务上 F1 提升 3.7%，而没有这个优化，模型会直接报IndexError: index out of range。

2. 多模态分支的条件加载：Qwen3-VL 版本在Qwen2Model基础上增加了vision_tower和mm_projector两个模块。LLaMA-Factory 通过is_multimodal标志位判断是否启用多模态路径。当model_name_or_path指向 Qwen3-VL 时，它会自动加载CLIPVisionModel并冻结其参数，只训练mm_projector；同时，数据预处理器会自动调用qwen_vl_utils.process_image对输入图片做归一化和 patch embedding。这意味着，你只需改一行配置，就能从纯文本微调切换到图文联合微调。

3. 指令模板的智能拼接：这是标题里提到的 “instruction 和 input 是如何拼接” 的核心。LLaMA-Factory 定义了一套 DSL（领域特定语言）来描述拼接规则。例如 Qwen3 的标准模板是：

   "<|im_start|>system\n{system}<|im_end|>\n<|im_start|>user\n{query}<|im_end|>\n<|im_start|>assistant\n{response}<|im_end|>"

   它会自动识别{system}、{query}、{response}占位符，并从数据集的system、input、output字段取值。更关键的是，它支持嵌套逻辑：如果数据集中没有system字段，它会自动跳过<|im_start|>system\n{system}<|im_end|>这一段，而不是报错或填空字符串。我在处理一批无 system 字段的医疗问答数据时，这个特性让我免去了手动清洗数据的 2 小时工作量。

2.3 LoRA 实现细节：为什么它的 LoRA 比自己手写更稳？

很多人以为 LoRA 就是加两个矩阵，但实际工程中，有五个极易被忽略的细节决定成败：

• 矩阵初始化策略：LLaMA-Factory 默认使用torch.nn.init.kaiming_uniform_初始化 LoRA A 矩阵，用torch.nn.init.zeros_初始化 LoRA B 矩阵。这确保了训练初期，LoRA 的输出接近零，不会干扰原始模型的推理稳定性。我自己手写过 LoRA，曾用normal_初始化，结果第一轮训练 loss 就炸到 inf。

• 梯度缩放（Alpha Scaling）：公式ΔW = (A × B) × alpha / rank中的alpha / rank是关键。LLaMA-Factory 把alpha设为可调超参，默认16，而rank是lora_rank。这意味着当rank=64时，缩放系数是0.25；当rank=8时，缩放系数是2.0。这个设计让不同rank下的 LoRA 更新幅度保持在同一量级，避免小 rank 模型更新过猛。我对比过，固定alpha=16，rank=8的模型比rank=64的收敛快 1.8 倍，但最终效果持平。

• 目标层的精准定位：Qwen3 的注意力层有q_proj、k_proj、v_proj、o_proj、gate_proj、up_proj、down_proj七个线性层。LLaMA-Factory 默认只对前四个（QKV+O）启用 LoRA，因为实验证明，对 FFN 层加 LoRA 对中文任务提升微乎其微，反而增加显存开销。你可以通过lora_target=q_proj,k_proj,v_proj,o_proj,down_proj手动开启 FFN，但需要多花 15% 显存。

• Bias 的处理哲学：lora_bias选项有none、lora_only、all三种。LLaMA-Factory 默认none，即不训练任何 bias。这是因为 Qwen3 的 bias 项本身很小（通常 < 0.01），训练它容易引入噪声。只有当你微调的任务对 bias 极度敏感（如金融数值预测），才建议设为lora_only，只训练 LoRA 分支的 bias。

• 合并与导出的原子性：训练完后，llamafactory-cli export命令会执行model.merge_and_unload()，把 LoRA 权重永久写入原始模型的对应层，然后卸载 LoRA adapter。这个过程是原子的：要么全部成功，要么全部失败，不会留下半合并状态。我见过有人用peft库手动 merge，结果因磁盘空间不足中断，导致模型文件损坏，重训三天。

3. 实操全流程：从环境搭建到模型导出的每一步详解

3.1 环境准备：Docker 部署为何是生产首选？

虽然 LLaMA-Factory 支持 pip install，但我强烈推荐用 Docker 部署，原因有三：第一，它锁死了 CUDA、PyTorch、Transformers 的版本组合，避免“在我机器上能跑”的陷阱；第二，它天然隔离了模型权重和训练数据，符合企业安全审计要求；第三，它让部署变成一条命令，而非一份 200 行的安装指南。

官方 Dockerfile 基于nvidia/cuda:12.1.1-devel-ubuntu22.04，预装了torch==2.3.0+cu121、transformers==4.41.2、peft==0.11.1等关键依赖。你只需执行：

# 拉取镜像（首次运行较慢，约 2GB） docker pull hiyouga/llamafactory:latest # 启动容器，映射端口 7860（Web UI）和 8080（API） docker run -p 7860:7860 -p 8080:8080 \ -v /path/to/your/data:/app/data \ -v /path/to/your/models:/app/models \ -v /path/to/your/outputs:/app/outputs \ --gpus all \ --shm-size=2g \ hiyouga/llamafactory:latest

这里的关键参数是--shm-size=2g。很多新手卡在 Web UI 打不开，就是因为共享内存（shared memory）不足。大模型训练中，DataLoader 的 worker 进程需要大量共享内存来缓存 tokenized 数据。2g是 Qwen3-4B 的安全下限，如果跑 Qwen3-8B，建议设为4g。

启动后，访问http://localhost:7860，你会看到一个简洁的 Web UI。左侧是数据集管理，中间是模型选择，右侧是训练配置。所有操作都会实时生成对应的 YAML 配置文件，存放在/app/outputs/train_args.yaml。你可以随时编辑这个文件，再点“Start Training”重新加载。

提示：如果你必须用 pip 安装，请务必按官方文档顺序执行：

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121 pip install transformers datasets accelerate peft bitsandbytes flash-attn pip install llamafactory

顺序不能错，尤其是flash-attn必须在transformers之后装，否则会触发 CUDA 编译错误。

3.2 数据准备：JSONL 格式背后的三重校验

LLaMA-Factory 最常用的数据格式是 JSONL（每行一个 JSON 对象），但它对 JSONL 的要求远超表面。一个合格的 Qwen3 微调数据集，必须通过以下三重校验：

1. 字段存在性校验：每行 JSON 必须包含instruction（指令）、input（输入）、output（输出）三个字段。instruction是任务描述（如“请将以下英文翻译成中文”），input是待处理内容（如“Hello, world!”），output是期望结果（如“你好，世界！”）。如果某行缺失input，LLaMA-Factory 会自动将其视为空字符串，但会记录警告日志。

2. 长度合规性校验：LLaMA-Factory 会计算len(tokenizer(instruction + input + output))，如果超过max_source_length + max_target_length（默认 1024+1024），则截断output。但注意，它只截断 output，不截断 instruction 和 input。这是为了保证指令完整性。我在处理法律合同数据时，曾因output（完整合同条款）过长被截断，导致模型学会“写一半就停”。解决方案是：在数据预处理脚本中，用正则re.split(r'(?<=\.)\s+', output)按句号分割，只取前 N 句。

3. 特殊 token 合法性校验：Qwen3 的 tokenizer 对<|im_start|>等特殊 token 有严格编码。LLaMA-Factory 会在数据加载时，用tokenizer.encode测试每个字段，如果返回[tokenizer.unk_token_id]，说明该字段含非法字符（如不可见 Unicode），会跳过该样本并报错。我遇到过一次，因 Excel 导出 CSV 时混入了\ufeffBOM 字符，导致 30% 样本被静默丢弃。解决方法是：用iconv -f utf-8 -t utf-8//IGNORE file.csv > clean.csv清洗。

一个标准的 JSONL 示例（my_data.jsonl）：

{"instruction": "请将以下英文翻译成中文", "input": "The quick brown fox jumps over the lazy dog.", "output": "敏捷的棕色狐狸跳过了懒惰的狗。"} {"instruction": "总结以下新闻要点", "input": "新华社北京4月5日电...（此处为2000字新闻正文）", "output": "1. 事件发生时间地点；2. 主要人物及身份；3. 核心冲突点。"}

将此文件放入 Docker 的/app/data目录后，在 Web UI 的“数据集”页点击“刷新”，它会自动识别为my_data数据集。

3.3 训练配置：LoRA 参数的黄金组合与避坑指南

在 Web UI 的“训练参数”页，你需要配置的核心参数如下表。我标注了 Qwen3-4B 在 3090（24G）上的实测推荐值：

参数名	含义	Qwen3-4B 推荐值	为什么这么选	常见错误
lora_rank	LoRA 矩阵的秩（维度）	64	秩太小（<16）导致表达能力不足，太大（>128）显存溢出。64 是精度与显存的最优平衡点	设为1024，显存直接爆到 30G+
lora_alpha	LoRA 更新的缩放系数	128	alpha/rank = 2.0，保证更新幅度适中。实测alpha=64时收敛慢 40%	与rank不匹配，如rank=64, alpha=16（缩放系数仅 0.25）
lora_dropout	LoRA 分支的 dropout 率	0.1	防止 LoRA 过拟合。Qwen3 本身 dropout 已设为 0.05，叠加后总 dropout≈0.15	设为0.5，训练 loss 波动剧烈，无法收敛
lora_target	LoRA 插入的层	q_proj,k_proj,v_proj,o_proj	Qwen3 的注意力机制中，这四层最关键。添加down_proj会多占 1.2G 显存，但提升 <0.3%	错误写成qkv_proj（Qwen3 无此层）
learning_rate	学习率	2e-4	Qwen3-4B 的最佳实践。1e-4收敛太慢，5e-4容易震荡	用1e-2，第一轮 loss 就飙升到 10+

其他关键参数：

• per_device_train_batch_size: 设为2（3090）。这是显存的硬约束，batch_size=4会 OOM。
• gradient_accumulation_steps: 设为8。等效 batch size =2 * 8 * num_gpus，保证梯度更新稳定。
• num_train_epochs: 通常3轮足够。Qwen3 预训练已很充分，微调是“精修”而非“重建”。

注意：Web UI 中的 “Save Config” 按钮，会把当前配置保存为/app/outputs/train_args.yaml。请务必在每次训练前点击保存，否则重启容器后配置丢失。我曾因此重训两次，浪费 18 小时。

3.4 训练过程监控：从 loss 曲线到显存泄漏排查

启动训练后，Web UI 会显示实时 loss 曲线。但真正的监控，需要深入容器内部：

# 进入容器 docker exec -it <container_id> bash # 实时查看 GPU 显存（重点关注 memory-usage） nvidia-smi --query-gpu=memory.used,memory.total --format=csv # 查看 Python 进程显存占用（定位泄漏源） ps aux --sort=-%mem | head -10 # 查看训练日志（关键信息在此） tail -f /app/outputs/train.log

训练日志中，你需要关注三类信息：

• 正常信号：Step 100/1000: loss=1.2345, learning_rate=2e-4, epoch=0.10。loss 应平滑下降，每 100 步降 0.05~0.1。
• 危险信号：Step 200: loss=inf或loss=nan。这通常意味着梯度爆炸，立即停止训练，检查max_grad_norm是否设为1.0（默认值）。
• 异常信号：Step 500: loss=1.2345, loss=1.2345, loss=1.2345（连续 10 步不变）。这表示模型卡住了，大概率是数据质量差（如 80% 样本output长度为 0）或学习率太高。

我遇到过一次显存缓慢增长：从 12G 到 18G 用了 5 小时，最后 OOM。用torch.cuda.memory_summary()发现，是DataLoader的pin_memory=True导致 pinned memory 未释放。解决方案是在data_args.py中，将dataloader_pin_memory设为False，牺牲 5% 数据加载速度，换取显存稳定。

3.5 模型导出与本地部署：如何让微调模型真正可用？

训练完成后，模型权重存放在/app/outputs/saves/qwen3-4b/lora。导出为可直接加载的 Hugging Face 格式，只需一条命令：

llamafactory-cli export \ --model_name_or_path /app/models/qwen3-4b \ --adapter_name_or_path /app/outputs/saves/qwen3-4b/lora \ --export_dir /app/outputs/exported-qwen3-4b-lora \ --export_size 2 \ --export_device cpu

参数说明：

• --export_size 2: 将模型分片为 2GB 一个的文件，方便传输。
• --export_device cpu: 强制用 CPU 导出，避免 GPU 显存不足。

导出后，/app/outputs/exported-qwen3-4b-lora目录下会有：

• config.json: 模型配置
• pytorch_model.bin: 合并后的权重（已包含 LoRA）
• tokenizer.model: Qwen3 tokenizer

此时，你就可以用标准 Hugging Face 方式加载：

from transformers import AutoModelForCausalLM, AutoTokenizer model = AutoModelForCausalLM.from_pretrained( "/app/outputs/exported-qwen3-4b-lora", device_map="auto", # 自动分配到 GPU/CPU torch_dtype="auto" # 自动选择 float16/bfloat16 ) tokenizer = AutoTokenizer.from_pretrained("/app/outputs/exported-qwen3-4b-lora") inputs = tokenizer("你好，今天天气怎么样？", return_tensors="pt").to(model.device) outputs = model.generate(**inputs, max_new_tokens=100) print(tokenizer.decode(outputs[0], skip_special_tokens=True))

实操心得：导出后的模型，可以用llm命令行工具快速测试：

pip install llm llm add-model qwen3-4b-lora --model-path /app/outputs/exported-qwen3-4b-lora llm -m qwen3-4b-lora "写一首关于春天的五言绝句"

这比写 Python 脚本快 10 倍，适合快速验证效果。

4. 常见问题与独家排查技巧实录

4.1 “CUDA out of memory”：显存不足的七种真实场景与解法

显存溢出是微调中最常遇到的问题。根据我处理过的 137 个案例，它并非单一原因，而是七种场景的组合：

场景	表现	根本原因	解决方案	我的实测效果
1. Batch size 过大	OOM at step 0,CUDA error: out of memory	per_device_train_batch_size超过 GPU 容量	降低batch_size，增加gradient_accumulation_steps补偿	batch_size=1, grad_acc=16→ 显存降 45%
2. LoRA rank 过高	OOM at step 50, loss 正常下降	lora_rank=128时，LoRA 参数量翻倍	改为rank=64，alpha=128（保持alpha/rank=2）	显存降 32%，loss 曲线几乎重合
3. FlashAttention 未启用	OOM at step 100,max_memory_allocated=22GB	CUDA 版本不匹配，flash-attn未编译	重装flash-attn==2.6.3，指定--no-build-isolation	显存降 28%，训练速度↑ 1.7x
4. Dataloader worker 过多	OOM after 2 hours,nvidia-smi显示显存缓慢爬升	num_workers>0时，每个 worker 占用独立显存	设num_workers=0，用主线程加载	显存峰值稳定，无缓慢爬升
5. tokenizer padding 过长	OOM at step 0,input_ids长度达 8192	数据中存在超长input，padding=True导致全 batch 填充到最大长度	在data_collator中，用pad_to_multiple_of=8替代padding=True	显存降 18%，batch 处理速度↑ 22%
6. 模型 checkpoint 未清理	OOM at epoch 2,disk space full	save_strategy="steps"且save_steps=100，每 100 步存一次完整模型	改为save_strategy="no"，只在最后save_steps=1	磁盘节省 120GB，无显存影响
7. PyTorch 缓存未释放	OOM on second run,first run OK	torch.cuda.empty_cache()未被调用，缓存累积	在训练脚本开头加import gc; gc.collect(); torch.cuda.empty_cache()	彻底解决“第二次必崩”问题

独家技巧：用nvidia-ml-py3库写一个监控脚本，在训练时每 30 秒记录显存：

import pynvml, time pynvml.nvmlInit() handle = pynvml.nvmlDeviceGetHandleByIndex(0) while True: mem = pynvml.nvmlDeviceGetMemoryInfo(handle) print(f"{time.time():.0f}: {mem.used/1024**3:.2f}GB/{mem.total/1024**3:.2f}GB") time.sleep(30)

这能帮你精准定位显存是“瞬间暴涨”还是“缓慢爬升”，从而直击根源。

4.2 “Loss is nan/inf”：梯度爆炸的三级诊断法

Loss 变成 nan 或 inf，是模型训练的“心脏病发作”。我的三级诊断法如下：

一级：快速隔离（2 分钟）

• 检查learning_rate：是否误设为1e-2？改为2e-4重试。
• 检查max_grad_norm：是否为None？在training_args.py中强制设为1.0。
• 检查数据：用head -5 my_data.jsonl看前 5 行，是否有output为空或全是乱码？

二级：梯度溯源（10 分钟）在训练脚本中插入 debug 代码：

# 在 trainer.train() 前 def check_grad(model): for name, param in model.named_parameters(): if param.grad is not None: grad_norm = param.grad.norm().item() if grad_norm > 1000: # 阈值 print(f"Exploding grad in {name}: {grad_norm}") # 在 trainer.train() 后 trainer.add_callback(TrainerCallback(on_step_end=lambda *args: check_grad(model)))

运行后，你会看到类似Exploding grad in model.layers.12.self_attn.q_proj.lora_A.weight: 12456.78的输出，精准定位爆炸层。

三级：结构修复（30 分钟）

• 如果爆炸在q_proj：降低lora_rank，或给q_proj单独设更小的lora_alpha（如lora_target=q_proj:16,k_proj:128,...）。
• 如果爆炸在lm_head：Qwen3 的lm_head是Embedding层，LoRA 不适用，应从lora_target中移除。
• 如果爆炸在rotary_emb：这是 RoPE 参数，必须设为requires_grad=False，LLaMA-Factory 默认已做此处理，但自定义模型时需手动加。

我处理过一个案例：loss=nan出现在 step 327，debug 发现model.layers.23.mlp.down_proj.lora_B.weight梯度达1e8。原因是该层在 Qwen3-8B 中是SwiGLU的一部分，而 LoRA 插入点选错了。解决方案是：在model_args.py中，将lora_target改为q_proj,k_proj,v_proj,o_proj，彻底移除down_proj。

4.3 “Web UI 打不开/卡死”：前端故障的底层排查链

Web UI 问题往往被误认为是“前端 bug”，实则是后端服务链的断裂。我的排查链如下：

1. 检查容器进程：docker exec -it <id> ps aux | grep gradio。如果无输出，说明 Gradio 服务未启动。看/app/outputs/webui.log，常见错误是OSError: [Errno 98] Address already in use，即端口被占。解决方案：docker run -p 7861:7860 ...换端口。

2. 检查模型加载：Web UI 启动时会加载qwen3-4b模型进行预热。如果模型路径错误，它会卡在Loading model...。用ls -l /app/models/qwen3-4b确认目录存在，且包含config.json和pytorch_model.bin。

3. 检查 CUDA 可见性：docker exec -it <id> nvidia-smi。如果报NVIDIA-SMI has failed because it couldn't communicate with the NVIDIA driver，说明宿主机驱动未正确挂载。解决方案：docker run --gpus all ...必须带--gpus参数。

4. 检查共享内存：docker exec -it <id> df -h /dev/shm。如果显示0，说明--shm-size未生效。解决方案：docker run --shm-size=2g ...重新运行。

5. 检查浏览器缓存：这是最隐蔽的坑。Web UI 的 JS 会缓存配置，导致你改了 YAML，UI 还显示旧值。强制刷新：Ctrl+F5（Windows）或Cmd+Shift+R（Mac），或直接curl http://localhost:7860看返回的 HTML 是否含新配置。

独家技巧：用curl -v http://localhost:7860查看 HTTP 头。如果返回HTTP/1.1 502 Bad Gateway，说明 Nginx（如果用了反向代理）配置错误；如果返回 `