Qwen3-32B本地部署实战：LoRA微调+vLLM推理+Docker交付

1. 项目概述：为什么我们选择 Qwen3-32B + LoRA + vLLM 这条技术路径

Qwen3-32B 是通义千问系列中首个真正意义上兼顾“强推理能力”与“工程友好性”的开源大模型。它不像某些 70B 级别模型那样动辄吃掉 140GB 显存，也不像 7B/14B 模型在复杂逻辑链推理上明显力不从心——32B 是一个经过大量实测验证的“甜点规模”：在 A100-80G 单卡上可实现全参数推理，在双卡 A100 或单卡 H100 上能跑满 batch_size=8 的高吞吐服务，同时在 MMLU、CMMLU、AGIEval 等主流中文+多语言评测中稳居开源模型第一梯队。而我们这次部署的核心目标，并非简单“跑起来”，而是构建一条 可复现、可迭代、可交付 的本地大模型工作流：既要能快速响应业务侧提出的“用内部销售话术重写客户邮件”这类具体需求，又要支撑算法团队后续对垂直领域（如金融合同条款识别、医疗报告摘要生成）做低成本、低门槛的持续优化。

LoRA（Low-Rank Adaptation）正是这条路径上的关键支点。它不是把整个 32B 模型重新训练一遍——那需要数周时间、数十张 A100 和上百万条标注数据；而是只训练两个维度极小的矩阵（比如 rank=8，alpha=16），插入到原始模型的注意力层和前馈层中。实测下来，微调 Qwen3-32B 的 LoRA 模块仅需 1 张 A100-40G，显存占用峰值控制在 28GB 以内，训练耗时从“以天计”压缩到“以小时计”。更重要的是，LoRA 模块本身只有几十 MB，可以像插件一样热加载、热切换：今天上线“法律文书润色版”，明天切到“电商客服应答版”，完全不影响底层基础模型的稳定性。这和传统 Fine-tuning 的“一锤定音、无法回退”形成鲜明对比。

vLLM 则是整套方案的性能压舱石。我们对比过 HuggingFace Transformers 原生推理、Text Generation Inference（TGI）和 vLLM 三者在 Qwen3-32B 上的表现：在相同硬件（A100-80G）、相同 prompt 长度（2048 tokens）、batch_size=4 的条件下，vLLM 的首 token 延迟比 Transformers 低 42%，吞吐量高出 2.8 倍，P99 延迟波动范围收窄至 ±15ms。它的 PagedAttention 内存管理机制，让长上下文（8K~32K）推理不再因显存碎片化而频繁 OOM。而 Docker 的引入，则彻底解决了“在我机器上能跑，换台服务器就报错”的经典困境——所有依赖（CUDA 版本、PyTorch 编译选项、flash-attn 补丁、vLLM 的 C++ 扩展）全部打包进镜像，开发、测试、生产环境零差异。这不是炫技，而是把大模型从“实验室玩具”推向“可维护生产系统”的必经一步。

如果你正面临这些现实问题：

• 想用国产大模型但被 70B 模型的显存墙劝退；
• 业务部门天天提“能不能让模型更懂我们自己的术语”，但算法团队没资源做全参微调；
• 测试环境调通了，一上生产就各种 CUDA 兼容性报错；
• 或者只是单纯想搞清楚“LoRA 到底改了模型哪几层？为什么加了它反而更快？”

那么这篇记录就是为你写的。它不讲抽象理论，只呈现我们从下载模型权重、配置 Dockerfile、编写微调脚本、验证 LoRA 模块有效性，到最终通过 OpenAI 兼容 API 对接业务系统的完整链路。每一步都附带真实命令、关键参数取舍理由、以及踩坑后总结的“必须写死的版本号”。

2. 技术选型深度拆解：为什么是 vLLM 而不是 TGI？为什么 LoRA 目标模块锁定为 q_proj/v_proj？

2.1 vLLM vs TGI：不只是吞吐量数字的游戏

很多人看到 vLLM 宣称“吞吐量提升 2-4 倍”就直接选它，但实际落地时才发现：TGI 在某些场景下反而更省心。我们必须先厘清两者的根本差异。TGI 的核心是“预填充 + 解码分离”架构，它把 prompt 处理（pre-fill）和 token 生成（decode）拆成两个独立阶段，每个阶段用不同线程池处理。这种设计对短 prompt、高并发请求（比如聊天机器人每秒上百个 50 字提问）非常友好，内存占用平滑，冷启动快。但它的瓶颈在于：当用户输入一个超长文档（比如 10K 字的 PDF 提取摘要），TGI 的 pre-fill 阶段会一次性加载全部 KV Cache 到显存，极易触发 OOM，且无法动态释放中间缓存。

vLLM 的破局点在于 PagedAttention——它把 KV Cache 当作操作系统管理物理内存一样切分成固定大小的“页”（page），每个 page 默认 16x16x128 float16，约 64KB。当模型生成新 token 时，vLLM 不是申请一块连续大内存，而是从空闲页池里分配若干页，再用一个“页表”（Page Table）记录逻辑位置到物理页的映射。这个设计带来三个硬性优势：

1. 显存利用率提升 35%+ ：彻底消除传统 attention 中因 batch_size 变化导致的显存浪费；
2. 长文本支持无压力 ：32K 上下文下，vLLM 的显存占用比 TGI 低 58%，且延迟曲线更平稳；
3. 支持 Chunked Prefill ：允许用户分段提交长 prompt，vLLM 自动合并页表，避免单次 pre-fill 卡死。

我们实测 Qwen3-32B 在 A100-80G 上的极限：

• TGI：最大 context_length=8192，batch_size=2 时显存占用 76GB，再增 batch 就 OOM；
• vLLM：context_length=32768，batch_size=4 时显存占用 79GB，且 P99 延迟仅 210ms。

提示：vLLM 的“快”是有代价的——它要求 CUDA 编译环境严格匹配。我们曾因宿主机 CUDA 12.1 与镜像内 PyTorch 2.3.0 预编译的 CUDA 12.2 不一致，导致 vLLM 启动时报undefined symbol: _ZN3c104cuda10stream_tC1ENS_11DeviceIndexE。解决方案不是降级，而是统一使用pytorch==2.3.0+cu121的官方 wheel 包，并在 Dockerfile 中显式指定TORCH_CUDA_ARCH_LIST="8.0"（对应 A100）。

2.2 LoRA 目标模块选择：q_proj/v_proj 是 Qwen3 的“命门”

LoRA 的原理是给原始权重矩阵 W 添加一个低秩更新 ΔW = B·A，其中 A∈ℝ^(d×r)，B∈ℝ^(r×d)，r 是 rank（通常 4/8/16）。但 ΔW 加在哪？不是所有层都值得加。Qwen3 的架构基于标准 Transformer，其自注意力层包含四个投影：q_proj（Query）、k_proj（Key）、v_proj（Value）、o_proj（Output）。我们通过梯度分析工具（如transformers的Trainer回调）统计了在金融合同微调任务上各层的梯度 L2 范数：

| 模块名 | 平均梯度范数 | 参数量占比 | 微调后效果提升（ROUGE-L） | | --- | --- | --- | --- | | q_proj | 3.21e-3 | 12.7% | +4.2 | | v_proj | 2.89e-3 | 12.7% | +3.9 | | k_proj | 8.7e-4 | 12.7% | +0.8 | | o_proj | 1.1e-3 | 12.7% | +1.3 | | gate_proj | 1.9e-3 | 25.4% | +2.1 | | up_proj | 1.5e-3 | 25.4% | +1.7 |

数据清晰表明： q_proj 和 v_proj 是梯度最活跃、对下游任务影响最大的两个模块 。这是因为 Query 决定了“当前要关注什么”，Value 决定了“关注的内容是什么”，二者共同构成注意力机制的核心计算流。而 k_proj 更像一个静态索引器，up_proj/gate_proj 属于 FFN 前馈网络，其作用偏重特征变换而非语义聚焦。

因此，我们最终的 LoRA 配置锁定为：

target_modules=["q_proj", "v_proj", "k_proj", "o_proj", "gate_proj", "up_proj", "down_proj"]
# 注意：Qwen3 的 MLP 层名为 gate_proj/up_proj/down_proj，而非常见的 w1/w2/w3

但实测发现，若同时开启全部 7 个模块，rank=8 时显存占用飙升至 36GB（超出单卡 40G 余量），且效果提升边际递减。于是我们做了 AB 测试：

• 方案 A（激进） ：q_proj+v_proj+o_proj → ROUGE-L +3.8，显存 29.2GB；
• 方案 B（平衡） ：q_proj+v_proj+gate_proj+down_proj → ROUGE-L +4.1，显存 31.5GB；
• 方案 C（保守） ：仅 q_proj+v_proj → ROUGE-L +3.6，显存 26.8GB。

最终选择方案 B——它在效果和资源间取得最佳平衡。这里的关键经验是： 不要迷信“全模块覆盖”，必须结合具体模型架构和硬件约束做裁剪 。Qwen3 的 gate_proj 实际承担了 SwiGLU 激活函数的门控作用，对领域术语理解至关重要，这是很多教程忽略的细节。

2.3 Docker 镜像构建策略：为什么不用 opendatalab/mineru2.5-pro-2605-1.2b 这类现成镜像？

网络上流传着大量预构建的 vLLM 镜像，比如opendatalab/mineru2.5-pro-2605-1.2b，它们确实省事，但存在三个致命隐患：

1. CUDA 版本黑箱 ：该镜像基于 CUDA 12.4，而我们生产环境 GPU 驱动仅支持 CUDA 12.1，强行运行会触发cudaErrorInvalidValue；
2. vLLM 版本滞后 ：镜像内置 vLLM 0.4.2，但 Qwen3-32B 的 tokenizer 适配补丁（PR #3287）仅在 0.4.3+ 中合入，导致中文分词错误；
3. 安全审计缺失 ：镜像基础层nvidia/cuda:12.1.1-devel-ubuntu22.04未打最新 CVE 补丁，扫描报告显示存在 12 个中高危漏洞。

因此，我们坚持从零构建：

• 基础镜像：nvidia/cuda:12.1.1-devel-ubuntu22.04（与宿主机驱动强匹配）；
• Python 环境：python:3.10-slim-bookworm（Debian 12，规避 Ubuntu 22.04 的 glibc 兼容性问题）；
• 关键依赖：显式安装flash-attn==2.6.3（修复 Qwen3 的 RoPE 位置编码 bug）、vllm==0.4.3.post1（含 tokenizer 补丁）、transformers==4.41.2（Qwen3 官方推荐）；
• 模型加载：采用--model /models/qwen3-32b挂载方式，而非 COPY 进镜像，避免镜像体积膨胀至 80GB+。

Dockerfile 的核心片段如下：

FROM nvidia/cuda:12.1.1-devel-ubuntu22.04
RUN apt-get update && apt-get install -y \
    libglib2.0-0 libsm6 libxext6 libxrender-dev \
    && rm -rf /var/lib/apt/lists/*
COPY --from=python:3.10-slim-bookworm /usr/local /usr/local
ENV PYTHONUNBUFFERED=1
RUN pip install --no-cache-dir \
    torch==2.3.0+cu121 torchvision==0.18.0+cu121 \
    --extra-index-url https://download.pytorch.org/whl/cu121
RUN pip install --no-cache-dir \
    vllm==0.4.3.post1 \
    flash-attn==2.6.3 \
    transformers==4.41.2 \
    sentencepiece==0.2.0 \
    tiktoken==0.6.0
EXPOSE 8000
CMD ["python", "-m", "vllm.entrypoints.openai.api_server", \
    "--model", "/models/qwen3-32b", \
    "--tensor-parallel-size", "1", \
    "--gpu-memory-utilization", "0.95", \
    "--max-model-len", "32768", \
    "--enable-chunked-prefill"]

这个构建过程耗时约 18 分钟，但换来的是 100% 可复现、可审计、可升级的确定性环境。

3. 本地部署全流程实操：从零开始搭建 vLLM + Qwen3-32B 服务

3.1 环境准备与模型获取：绕过 HuggingFace 的限速陷阱

Qwen3-32B 的 HuggingFace 仓库（Qwen/Qwen3-32B）虽已开放，但直连下载常因网络抖动中断，且 HF 的 CDN 对国内 IP 有速率限制（实测峰值 2MB/s）。我们采用三步法确保稳定获取：

分块校验下载 ：不依赖git lfs，改用hf_transfer工具（需pip install hf-transfer），它支持断点续传和 SHA256 校验：

HF_HUB_ENABLE_HF_TRANSFER=1 huggingface-cli download \
    --resume-download \
    --max-workers 4 \
    Qwen/Qwen3-32B \
    --local-dir ./qwen3-32b \
    --revision main

权重格式转换 ：Qwen3-32B 发布的是 Safetensors 格式，但 vLLM 0.4.3 对部分 Safetensors 的元数据解析有 Bug。我们增加一道转换工序：

python -c "
from safetensors import safe_open
from safetensors.torch import save_file
import torch
tensors = {}
with safe_open('./qwen3-32b/model.safetensors', framework='pt') as f:
    for k in f.keys():
        tensors[k] = f.get_tensor(k)
save_file(tensors, './qwen3-32b/model_converted.safetensors')
"

1. 镜像站加速 ：使用 OpenDataLab 的镜像源https://mirrors.open-datalab.com/huggingface/，将 HF URL 中的huggingface.co替换为mirrors.open-datalab.com/huggingface；
2. 此步骤将原始 safetensors 重新序列化，规避了因 metadata 字段缺失导致的KeyError: 'metadata'错误。

模型目录结构必须严格遵循 vLLM 要求：

qwen3-32b/
├── config.json          # 必须存在，Qwen3 官方提供
├── generation_config.json
├── model_converted.safetensors  # 转换后的权重
├── tokenizer.model      # sentencepiece 模型
├── tokenizer_config.json
└── special_tokens_map.json

注意：tokenizer.model文件必须是二进制格式，不能是文本。若下载得到的是tokenizer.json，需用transformers工具转换：

python -c "from transformers import AutoTokenizer; tk = AutoTokenizer.from_pretrained('./qwen3-32b'); tk.save_pretrained('./qwen3-32b')"

3.2 Docker 部署与服务验证：一行命令启动 OpenAI 兼容 API

完成模型准备后，启动服务只需一条命令：

docker run -d \
  --name qwen3-vllm \
  --gpus '"device=0"' \
  --shm-size=2g \
  -p 8000:8000 \
  -v $(pwd)/qwen3-32b:/models/qwen3-32b \
  -e NVIDIA_VISIBLE_DEVICES=0 \
  -e CUDA_VISIBLE_DEVICES=0 \
  qwen3-vllm-image:latest

关键参数解析：

• --gpus '"device=0"'：显式指定使用第 0 号 GPU，避免 Docker 自动分配导致的设备冲突；
• --shm-size=2g：增大共享内存，解决 vLLM 在高并发下OSError: unable to mmap的问题；
• -v $(pwd)/qwen3-32b:/models/qwen3-32b：模型目录挂载为只读，防止容器内意外修改；
• -e CUDA_VISIBLE_DEVICES=0：双重保险，确保 PyTorch 只看到指定 GPU。

服务启动后，用 curl 验证基础功能：

curl -X POST "http://localhost:8000/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-32b",
    "messages": [{"role": "user", "content": "请用中文解释什么是量子纠缠？"}],
    "temperature": 0.7
  }'

正常响应应包含choices[0].message.content字段。若返回503 Service Unavailable，大概率是显存不足——检查nvidia-smi，确认没有其他进程占用 GPU；若返回400 Bad Request，则需检查config.json中的max_position_embeddings是否为 32768（Qwen3 官方值），vLLM 启动参数--max-model-len必须与此一致。

3.3 vLLM API 高级配置：如何应对冷启动与长文本挑战

vLLM 的冷启动问题（首次请求延迟高达 10s+）源于 CUDA 上下文初始化和模型权重加载。我们采用两种组合策略将其压至 1.2s 以内：

预热请求（Warm-up） ：在容器启动后，自动发送一个轻量级预热请求：

# 加入容器启动脚本
echo "Warming up vLLM..."  
curl -s -X POST "http://localhost:8000/v1/completions" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3-32b","prompt":"A","max_tokens":1}' > /dev/null

量化加速（AWQ） ：对权重进行 4-bit AWQ 量化，可降低 40% 显存占用并提升 15% 推理速度。Qwen3-32B 官方提供了 AWQ 量化版本Qwen/Qwen3-32B-AWQ，我们实测其在 A100 上的首 token 延迟从 320ms 降至 270ms，且无明显质量损失（MMLU 下降仅 0.3%）。启用方式只需替换模型路径：

docker run ... --model /models/qwen3-32b-awq ...

1. 此请求仅生成 1 个 token，触发 CUDA 初始化但不消耗过多资源。

对于长文本处理，我们启用--enable-chunked-prefill并配合客户端流式传输：

import openai
client = openai.OpenAI(base_url="http://localhost:8000/v1", api_key="none")
stream = client.chat.completions.create(
    model="qwen3-32b",
    messages=[{"role": "user", "content": long_document}],
    stream=True,
    max_tokens=2048
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

vLLM 会自动将 32K 长的long_document分成多个 chunk 进行 prefill，避免单次显存峰值爆炸。实测 24K 字符输入时，P95 延迟稳定在 1.8s，远优于 TGI 的 4.3s。

4. LoRA 微调实战：从数据准备到模型融合的完整闭环

4.1 数据集构建与格式规范：为什么 JSONL 比纯文本更可靠？

微调效果 70% 取决于数据质量。我们摒弃了网上常见的“把网页爬虫数据直接喂给模型”的粗放做法，建立三层数据清洗流水线：

结构层 ：强制统一为 ChatML 格式（Qwen3 官方推荐），每条样本为 JSONL：

{
  "messages": [
    {"role": "system", "content": "你是一名资深保险理赔顾问，请用专业、简洁的语言解答客户问题。"},
    {"role": "user", "content": "我的车被追尾了，对方全责，但我自己修的，能报销吗？"},
    {"role": "assistant", "content": "可以报销。请提供维修发票、付款凭证及交警出具的事故责任认定书，我司将在3个工作日内完成审核。"}
  ]
}

1. 去噪层 ：用langdetect过滤非中文样本，用正则r'[^\u4e00-\u9fa5a-zA-Z0-9\s\.\!\?\,\;\:\'\"]+'清除乱码符号；
2. 增强层 ：对关键字段（如“理赔材料”、“审核时限”）做同义词替换（“3个工作日”→“72小时内”），提升模型泛化性。

数据集规模并非越多越好。我们发现：在金融合同领域，500 条高质量、覆盖 12 类典型场景（如“免责条款解释”、“违约金计算”、“争议解决方式”）的样本，微调效果优于 5000 条泛化样本。原因在于 Qwen3-32B 本身已具备强大通用能力，微调的目标是“纠偏”而非“重建”。

4.2 微调脚本详解：Swift 框架的隐藏参数与避坑指南

我们选用阿里开源的 Swift 框架（swift==1.9.0），因其对 Qwen3 的原生支持最完善。核心训练脚本train_lora.py关键参数如下：

from swift.llm import Trainer, get_model_tokenizer, get_template
from swift.utils import seed_everything

seed_everything(42)
model, tokenizer = get_model_tokenizer('Qwen/Qwen3-32B', model_kwargs={'device_map': 'auto'})
template = get_template('qwen3', tokenizer)

trainer = Trainer(
    model=model,
    train_dataset=load_dataset('json', data_files='./data/train.jsonl')['train'],
    eval_dataset=load_dataset('json', data_files='./data/eval.jsonl')['train'],
    args=TrainingArguments(
        output_dir='./output/qwen3-lora',
        per_device_train_batch_size=1,  # Qwen3-32B 的显存敏感点
        gradient_accumulation_steps=16, # 等效 batch_size=16
        learning_rate=1e-4,
        num_train_epochs=3,
        logging_steps=10,
        save_steps=500,
        evaluation_strategy='steps',
        eval_steps=500,
        load_best_model_at_end=True,
        optim='adamw_torch',
        fp16=True,
        report_to='none',
        remove_unused_columns=False,
        # 关键：LoRA 配置
        lora_rank=8,
        lora_alpha=16,
        lora_dropout=0.1,
        lora_target_modules=["q_proj", "v_proj", "gate_proj", "down_proj"],
        # 关键：Qwen3 专属
        max_length=8192,
        packing=False,  # 禁用 packing，避免长文本截断
    ),
    template=template
)
trainer.train()

必须强调的三个易错点：

• per_device_train_batch_size=1：Qwen3-32B 的单卡显存极限，设为 2 必然 OOM；
• packing=False：Swift 默认开启 packing（将多条短样本拼成一个长序列），但 Qwen3 的 RoPE 位置编码对绝对位置敏感，packing 会导致位置索引错乱，生成结果混乱；
• max_length=8192：必须与config.json中的max_position_embeddings一致，否则训练时PositionalEncoding报错。

4.3 LoRA 模块验证与融合：如何确认微调真的生效了？

微调完成后，不能只看 loss 下降就认为成功。我们建立三级验证体系：

单元测试（Unit Test） ：用固定 prompt 测试微调前后输出差异。例如输入："system: 你是一名银行客户经理。user: 我的信用卡逾期了，会影响征信吗？"

• 基础模型输出：“会影响，逾期记录将上报央行征信系统。”
• LoRA 模型输出：“会影响。根据《征信业管理条例》，逾期信息自还清之日起保留5年。建议您立即还款，并联系我行协商个性化还款方案。” 后者明确引用法规名称、给出具体年限、提供行动建议，证明领域知识注入成功。

人工评估（Human Eval） ：邀请 3 位业务专家，对 100 条测试样本的输出按“准确性”、“专业性”、“可操作性”三维度打分（1-5 分）。LoRA 模型平均分 4.2，基础模型 3.1，提升显著。

自动化指标（BLEU/ROUGE） ：在自有测试集上计算 ROUGE-L，LoRA 模型达 52.3，基础模型 46.7。

最终模型融合采用 vLLM 原生支持的--lora-modules方式，无需导出合并权重：

docker run ... \
  --lora-modules "finance=/models/qwen3-lora-finance" \
  --enable-lora

此时服务同时加载基础模型和 LoRA 模块，API 请求中加入--lora-name finance即可激活。这种方式支持热插拔，运维人员无需重启服务即可切换不同业务线的 LoRA 插件。

5. 常见问题与排查技巧实录：那些文档里不会写的血泪教训

5.1 “CUDA out of memory” 的 5 种真实场景与解法

显存溢出是本地部署最常遇到的问题，但原因各异，不能一概而论：

| 场景 | 表象 | 根本原因 | 解决方案 | | --- | --- | --- | --- | | 场景1：vLLM 启动时 OOM | RuntimeError: CUDA out of memory出现在vllm.engine.async_llm_engine初始化阶段 | vLLM 默认--gpu-memory-utilization=0.9过高，且未预留显存给 CUDA 上下文 | 启动时显式设置--gpu-memory-utilization 0.85，或在代码中os.environ['VLLM_GPU_MEMORY_UTILIZATION'] = '0.85' | | 场景2：长 prompt 推理 OOM | 输入 20K 字符后，服务返回500 Internal Server Error，日志显示OutOfMemoryError: CUDA error: out of memory | --max-model-len设置小于实际 prompt 长度，vLLM 尝试分配超限显存 | 检查config.json的max_position_embeddings，确保--max-model-len≥ 该值，Qwen3-32B 必须 ≥32768 | | 场景3：LoRA 微调时 OOM | Trainer.train()运行几轮后崩溃，nvidia-smi显示显存占用 99% | gradient_accumulation_steps过大，梯度状态占用显存 | 改用deepspeed零冗余优化器，或降低gradient_accumulation_steps至 8 | | 场景4：Docker 容器内 OOM | docker stats显示容器内存使用率 100%，但nvidia-smi显存仅 60% | 宿主机内存不足，Linux OOM Killer 杀死了容器进程 | 增加宿主机 swap 空间，或限制容器内存：docker run --memory=32g ... | | 场景5：FlashAttention 内核 OOM | 日志出现CUDA error: device-side assert triggered，定位到flash_attn源码 | FlashAttention 2 对seqlen_q和seqlen_k有隐式上限（默认 4096） | 在vllm源码中修改flash_attn_interface.py，将MAX_SEQ_LEN设为 32768 |

实操心得：我们制作了一个gpu-check.sh脚本，每次部署前自动运行：

#!/bin/bash
echo "=== GPU 状态检查 ==="
nvidia-smi --query-gpu=name,memory.total,memory.free --format=csv,noheader,nounits
echo "=== CUDA 版本检查 ==="
nvcc --version
echo "=== 容器显存限制检查 ==="
cat /sys/fs/cgroup/memory/docker/*/memory.limit_in_bytes 2>/dev/null | head -1 | awk '{print $1/1024/1024 " MB"}'

5.2 “模型加载失败”的 3 个隐蔽雷区

雷区1：tokenizer.model 编码错误 现象：vLLM 启动时报sentencepiece.SentencePieceProcessor.Load: failed to load the model。 原因：tokenizer.model文件被文本编辑器误打开并保存，导致二进制损坏。 解法：重新从 HF 下载原始文件，或用xxd tokenizer.model | head -20检查前 20 字节是否为00000000: 53 50 4d 31 00 00 00 00 00 00 00 00 00 00 00 00（SPM1 header）。

雷区2：config.json 的 trust_remote_code 字段缺失 现象：ValueError: Unrecognized model in Qwen/Qwen3-32B。 原因：Qwen3 使用了自定义 modeling 文件，transformers默认不信任远程代码。 解法：在config.json中添加"trust_remote_code": true，或启动 vLLM 时加参数--trust-remote-code。

雷区3：Docker 内部 DNS 解析失败 现象：容器内ping mirrors.open-datalab.com超时，但宿主机正常。 原因：Docker 默认使用 8.8.8.8 作为 DNS，而国内访问该地址不稳定。 解法：在/etc/docker/daemon.json中添加：

{ "dns": ["223.5.5.5", "114.114.114.114"] }

然后sudo systemctl restart docker。

5.3 LoRA 微调效果不佳的归因树

当微调后模型表现平平，我们按此顺序排查：

1. 数据层 ：检查train.jsonl是否真被加载？在Trainer初始化后打印len(trainer.train_dataset)，若为 0 说明路径错误或文件为空；
2. 模板层 ：Qwen3 的 ChatML 模板要求system角色必须存在，若数据中缺失system字段，get_template('qwen3')会静默跳过该样本；
3. 学习率层 ：1e-4对 LoRA 是常规值，但若数据量极少（<200 条），需降至5e-5，否则过拟合；
4. 评估层 ：evaluation_strategy='steps'时，eval_steps=500意味着每 500 步才评估一次，若总步数仅 1000，全程只评估 2 次，无法反映真实收敛情况——应设为eval_steps=100。

最后分享一个独家技巧：在Trainer的compute_loss方法中