LlamaFactory 部署说明文档

大模型微调框架 · Docker GPU (sm_120 Blackwell) 部署手册

部署方式 ：Docker Compose（CUDA 版本）

项目名 ：llamafactory（小写，Compose 项目名规则）

主容器名 ：LlamaFactory（大写，按需求命名）

WebUI 地址 ：http://localhost:7860

目标 GPU ：NVIDIA GeForce RTX 5060 Ti · 17.1 GB · sm_120 Blackwell

撰写日期：2026-07-31

项目概述
[环境要求（GPU 模式）](#环境要求（GPU 模式）)
目录结构与文件位置
[⚠️ 核心根因：RTX 5060 Ti (sm_120) 为什么会报错？](#⚠️ 核心根因：RTX 5060 Ti (sm_120) 为什么会报错？)
推荐版本矩阵（实测通过）
[完整 Wheel 下载清单](#完整 Wheel 下载清单)
[6 步操作流程 · C:\DL → 容器 → pip 离线](#6 步操作流程 · C:\DL → 容器 → pip 离线)
[避坑 5 原则](#避坑 5 原则)
[7 大踩坑报错 & 修复方案](#7 大踩坑报错 & 修复方案)
[快速验证脚本（10 秒出结果）](#快速验证脚本（10 秒出结果）)
[WebUI 启动与端口](#WebUI 启动与端口)
[故障排查对照表（8 大常见错误）](#故障排查对照表（8 大常见错误）)
[下载链接 & 参考来源](#下载链接 & 参考来源)

01. 项目概述

LLaMA-Factory 是一款开源的大模型微调框架，支持 LoRA / QLoRA / 全量参数微调，兼容 Llama、Qwen、Baichuan、ChatGLM、Mistral 等主流开源模型。本部署使用官方 docker-cuda compose 文件，在 Docker 容器内启用 GPU 训练。

官方仓库：https://github.com/hiyouga/LLaMA-Factory

02. 环境要求（GPU 模式）

项目	最低要求	当前配置
操作系统	Windows 10/11 或 Linux	Windows 11 Pro
Docker	Docker Desktop 4.20+ WSL2 后端	Docker Desktop 最新版
NVIDIA 驱动	≥ 535.x（支持 CUDA 12.x）	最新 Game Ready / Studio
GPU	≥ 12GB 显存的 NVIDIA GPU	RTX 5060 Ti · 17.1 GB
GPU 计算能力	sm_80+（Ampere 及以后）	sm_120 (Blackwell)
NVIDIA Container Toolkit	必须安装（docker --gpus 生效）	Docker Desktop 默认带
CPU	8 核	8 核及以上
内存	16 GB	32 GB 推荐
磁盘	100 GB SSD（含模型文件）	200 GB SSD

💡 Windows 下 Docker Desktop 的 --gpus all 开箱即用（前提：驱动装好 + WSL2 后端）。

验证 GPU：docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi 能看到显卡即通过。

03. 目录结构与文件位置

复制代码

C:\project\LlamaFactory-main\
└── docker\
    └── docker-cuda\
        ├── docker-compose.yml        ← GPU 版主 Compose 文件（编辑此文件）
        └── Dockerfile                ← 镜像构建文件（如需改 PyTorch 基础版本）

C:\DL\                              ← 💡 约定：大 wheel 下载缓存目录（宿主机）

关键文件路径

用途	路径
GPU 版 Compose 文件	`C:\project\LlamaFactory-main\docker\docker-cuda\docker-compose.yml`
下载缓存目录（约定）	`C:\DL\`（纯英文无空格路径）

04. ⚠️ 核心根因：RTX 5060 Ti (sm_120) 为什么会报错？

关键数字

指标	值	说明
GPU 计算能力	12.0	→ sm_120（Blackwell 新架构）
基础镜像原 torch	2.6.0 + cu124	❌ `get_arch_list()` 最高到 sm_90，不认识 sm_120
要求的最低 torch	2.11.0+ + cu128	✅ 首次官方支持 Blackwell sm_120
需同步升级 nvidia-*	15 个	cublas / cupti / cudart / nvrtc / cudnn / cufft / curand / cusolver / cusparse / cusparselt / nccl / nvjitlink / nvshmem / nvtx / cccl

三层不兼容（必须全部解决）

第 1 层 · 计算能力层

原容器内 torch 2.6.0+cu124 的 torch.cuda.get_arch_list() 最高只到 sm_90。对 sm_120 根本未做 kernel 编译，torch.cuda.mem_get_info()、torch.zeros(1).cuda() 等调用直接返回：

RuntimeError: CUDA error: unknown error

第 2 层 · CUDA 工具链 ABI 层

torch 2.11.0+cu128 是用 CUDA 12.8 新工具链编译的，内部 C++ 符号 c10::cuda::*、cupti 函数签名、nvshmem 接口全变了。但容器基础镜像还是 CUDA 12.4，pip 包是 nvidia-cuda-cupti-cu12==12.4.127 等老版本，会出现：

undefined symbol: cuptiActivityEnableDriverApi, version libcupti.so.12

ImportError: libnvshmem_host.so.3: cannot open shared object file

Inconsistency detected by ld.so: dl-version.c（新旧版本混装断言崩溃）

第 3 层 · torch 生态 ABI 层

torchaudio 2.9.1+cu128 与 torch 2.11.0+cu128 不是同期发布，内部 C++ 符号对不上，libtorchaudio.so 加载直接失败：

undefined symbol: _ZN3c104cuda29c10_cuda_check_implementationEiPKcS2_ib

故障链路示意

复制代码

用户启动 llamafactory webui
  ↓
旧 torch 2.6 + cu124（get_arch_list 无 sm_120）
  ├─→ torch.cuda.mem_get_info()
  │     └─→ CUDA unknown error / sm_120 kernel 无法编译
  └─→ 升级 torch 2.11+cu128 ✅
        ├─→ ❌ 缺 libnvshmem_host.so.3 → 升级 nvshmem → 3.7.2
        ├─→ ❌ cuptiActivityEnableDriverApi 未定义 → 升级 14 个 nvidia-* → CUDA 12.8/12.9
        └─→ ❌ torchaudio 2.9 缺 c10_cuda_check → 升级 torchaudio 到 2.11.0
                                                              ↓
                                    ✅ zeros(1).cuda() + fp16 matmul + mem_get_info 全链路通过
                                                              ↓
                                                  webui:7860 GPU 模式启动 ✅

05. 推荐版本矩阵（实测通过）

容器 Python 固定 3.11 （cp311），架构 Linux x86_64 manylinux_2_28。

组件	推荐版本 ✅（实测通过）	大小	不推荐版本 ❌（实测踩坑）	踩坑原因
`torch`	2.11.0 + cu128	782 MB	2.6.0 + cu124	get_arch_list 无 sm_120，unknown error
`torchvision`	0.26.0 + cu128	7.7 MB	任何其它主版本	同 torch ABI 绑定，错代即崩
`torchaudio`	2.11.0 + cu128	1.9 MB	2.9.1 + cu128	libtorchaudio.so 缺 c10_cuda_check_implementation
`nvidia-cublas-cu12`	12.9.2.10	~554 MB	12.4.5.8	libcublasLt.so 符号版本错配，ld.so 断言崩溃
`nvidia-cuda-cupti-cu12`	12.9.79	~10 MB	12.4.127	缺 cuptiActivityEnableDriverApi 等 12.8 新增符号
`nvidia-cuda-nvrtc-cu12`	12.9.86	~85 MB	12.4.127	JIT 编译 sm_120 kernel 时内部链接失败
`nvidia-cuda-runtime-cu12`	12.9.79	~3.4 MB	12.4.127	libcudart 版本与 cublas/cupti 不同步
`nvidia-cudnn-cu12`	9.24.0.43	~799 MB	9.19.0.56（严格匹配）	9.19 最匹配但 9.24 向下兼容；不能低于 9.x
`nvidia-cufft-cu12`	11.4.1.4	~220 MB	11.2.1.3	与 cublas 12.9 内部 cufft 回调签名不匹配
`nvidia-curand-cu12`	10.3.10.19	~54 MB	10.3.5.147	curand philox4x32_10 系列内部签名升级
`nvidia-cusolver-cu12`	11.7.5.82	~125 MB	11.6.1.9	gesvdj_bufferSize 等函数符号版本缺失
`nvidia-cusparse-cu12`	12.5.10.65	~300 MB	12.3.1.170	SpMM/SpGEMM 新版 ABI 与 torch 2.11 链接失败
`nvidia-cusparselt-cu12`	0.8.1	~35 MB	0.7.1（严格匹配）	0.8.1 实测兼容；严格匹配建议 0.7.1
`nvidia-nccl-cu12`	2.30.7	~560 MB	2.21.5	ncclAllReduce symbol 版本绑定 libcuda 12.4
`nvidia-nvjitlink-cu12`	12.9.86	~19 MB	12.4.127	PTX → sm_120 cubin JIT 链路需要新版 nvJitLink
`nvidia-nvshmem-cu12`	3.7.2	~40 MB	（旧镜像未装）	libnvshmem_host.so.3 是 torch 2.11 硬依赖
`nvidia-nvtx-cu12`	12.9.79	~1.6 MB	12.4.127	NVTX v3 域 API 与 torch 2.11 profiler 不匹配
`nvidia-cuda-cccl-cu12`	12.9.27	~2.1 MB	（未装）	nvshmem 3.7+ 新增依赖（Thrust/CUB 头）

06. 完整 Wheel 下载清单

📌 下载约定 ：所有 wheel 统一放到宿主机的 C:\DL\ 目录（不要有中文路径、不要有空格）。

主下载源优先级：① download-r2.pytorch.org（直连 S3，无 CloudFront 切断） → ② download.pytorch.org → ③ pypi.org（nvidia-* 包）。

A · torch 三件套（3 个 · download-r2.pytorch.org）

#	wheel 文件名（cp311 · manylinux_2_28_x86_64）	大小	大小校验（字节）
1	`torch-2.11.0+cu128-cp311-cp311-manylinux_2_28_x86_64.whl`	782.2 MB	820,214,272
2	`torchvision-0.26.0+cu128-cp311-cp311-manylinux_2_28_x86_64.whl`	7.7 MB	8,056,489
3	`torchaudio-2.11.0+cu128-cp311-cp311-manylinux_2_28_x86_64.whl`	1.9 MB	1,989,347

宿主机下载命令（aria2c · 16 连接断点续传）

powershell 复制代码

# 安装 aria2（未装时）
winget install aria2.aria2

# 3 个 torch wheel 一起拉（推荐 download-r2 源，无 CloudFront 切断）
aria2c -x 16 -s 16 -d C:\DL `
  "https://download-r2.pytorch.org/whl/cu128/torch-2.11.0%2Bcu128-cp311-cp311-manylinux_2_28_x86_64.whl" `
  "https://download-r2.pytorch.org/whl/cu128/torchvision-0.26.0%2Bcu128-cp311-cp311-manylinux_2_28_x86_64.whl" `
  "https://download-r2.pytorch.org/whl/cu128/torchaudio-2.11.0%2Bcu128-cp311-cp311-manylinux_2_28_x86_64.whl"

# 下载后校验字节数（少 1 字节 zip 都坏）
Get-ChildItem C:\DL\*.whl | Select-Object Name, Length

⚠️ 大小校验 = 安装前最后一道防线 。如果下载后的文件大小与上表不一致，一定不要 docker cp，直接重下。

B · 15 个 nvidia 依赖（推荐容器内 pip 在线装）

这 15 个包 pypi CDN 相对稳定，可以直接在线装。复制下面整段命令：

bash 复制代码

# nvidia 14 + cccl 1，统一版本基线：CUDA 12.8/12.9 同代
pip install --no-deps --force-reinstall \
  nvidia-cublas-cu12==12.9.2.10 \
  nvidia-cuda-cupti-cu12==12.9.79 \
  nvidia-cuda-nvrtc-cu12==12.9.86 \
  nvidia-cuda-runtime-cu12==12.9.79 \
  nvidia-cudnn-cu12==9.24.0.43 \
  nvidia-cufft-cu12==11.4.1.4 \
  nvidia-curand-cu12==10.3.10.19 \
  nvidia-cusolver-cu12==11.7.5.82 \
  nvidia-cusparse-cu12==12.5.10.65 \
  nvidia-cusparselt-cu12==0.8.1 \
  nvidia-nccl-cu12==2.30.7 \
  nvidia-nvjitlink-cu12==12.9.86 \
  nvidia-nvshmem-cu12==3.7.2 \
  nvidia-nvtx-cu12==12.9.79 \
  nvidia-cuda-cccl-cu12==12.9.27

💡 如果容器网络不通 pypi，加 -i https://pypi.tuna.tsinghua.edu.cn/simple 切清华镜像。

07. 6 步操作流程 · C:\DL → 容器 → pip 离线

按顺序执行，中间任何一步验证不通过都不要进入下一步。

Step 1 · 宿主机下载 wheel 并校验大小

见 ch6-A：用 aria2 把 3 个 torch wheel 下到 C:\DL\，对照字节数校验。

Step 2 · 启动 LlamaFactory 容器并拷贝 wheel

powershell 复制代码

# 1. 启动容器（项目名必须小写！）
cd C:\project\LlamaFactory-main\docker\docker-cuda
docker compose -p llamafactory up -d

# 2. 确认 GPU 可见
docker exec LlamaFactory nvidia-smi

# 3. 拷贝 3 个 torch wheel 进容器
docker exec LlamaFactory mkdir -p /tmp/wheels
docker cp "C:\DL\torch-2.11.0+cu128-cp311-cp311-manylinux_2_28_x86_64.whl" LlamaFactory:/tmp/wheels/
docker cp "C:\DL\torchvision-0.26.0+cu128-cp311-cp311-manylinux_2_28_x86_64.whl" LlamaFactory:/tmp/wheels/
docker cp "C:\DL\torchaudio-2.11.0+cu128-cp311-cp311-manylinux_2_28_x86_64.whl" LlamaFactory:/tmp/wheels/

Step 3 · 卸载旧 torch 三件套 + 旧 nvidia 全家桶（关键）

bash 复制代码

docker exec -it LlamaFactory /bin/bash

# 容器内执行 ------ 全部卸掉再装新版，避免版本混装导致 ld.so 断言崩溃
pip uninstall -y torch torchvision torchaudio
pip uninstall -y nvidia-cublas-cu12 nvidia-cuda-cupti-cu12 nvidia-cuda-nvrtc-cu12 \
  nvidia-cuda-runtime-cu12 nvidia-cudnn-cu12 nvidia-cufft-cu12 nvidia-curand-cu12 \
  nvidia-cusolver-cu12 nvidia-cusparse-cu12 nvidia-cusparselt-cu12 nvidia-nccl-cu12 \
  nvidia-nvjitlink-cu12 nvidia-nvshmem-cu12 nvidia-nvtx-cu12 nvidia-cuda-cccl-cu12
pip cache purge

Step 4 · 离线安装 torch 三件套（--no-deps）

bash 复制代码

cd /tmp/wheels
pip install --no-deps --force-reinstall \
  torch-2.11.0+cu128-cp311-cp311-manylinux_2_28_x86_64.whl \
  torchvision-0.26.0+cu128-cp311-cp311-manylinux_2_28_x86_64.whl \
  torchaudio-2.11.0+cu128-cp311-cp311-manylinux_2_28_x86_64.whl

--no-deps 防止 pip 又去拉旧版 nvidia 包。

Step 5 · 在线安装 15 个 nvidia 包

粘贴 ch6-B 的整段 pip install --no-deps --force-reinstall nvidia-*==版本 命令。

（需要清华镜像就在最后加 -i https://pypi.tuna.tsinghua.edu.cn/simple。）

Step 6 · 4 条验证 → 启动 WebUI

先跑 [ch10 快速验证脚本](#ch10 快速验证脚本)，必须输出 4 PASS。通过后再启动 webui：

bash 复制代码

# 容器内后台启动（推荐用 nohup 避免 ssh 断开）
nohup llamafactory-cli webui --host 0.0.0.0 --port 7860 > /tmp/webui.log 2>&1 &
sleep 10 && tail -n 30 /tmp/webui.log

# 检查端口是否监听
ss -lntp | grep 7860

正常情况下 ss 显示 0.0.0.0:7860 LISTEN，浏览器打开 http://localhost:7860 即可看到 LlamaFactory WebUI。

08. 避坑 5 原则

🔷 原则 1 · 先查 arch_list，再谈升级

任何新 GPU 第一次部署，先跑：

bash 复制代码

python3 -c "import torch; print(torch.cuda.get_arch_list(), torch.cuda.get_device_properties(0))"

看 get_arch_list() 是否包含你 GPU 的 sm_xx。对 RTX 5060 Ti 必须包含 sm_120，不包含就直接换 torch，别再去怀疑驱动 / nvidia-container-toolkit。

🔷 原则 2 · 三件套 + 15 个 nvidia 包"同车"升级

把 torch / torchvision / torchaudio 三件套和 15 个 nvidia-* 视作一个整体。要么全不换，要么一次全换，绝不能"只升几个"。

⚠️ 原则 3 · 大 wheel 永远先宿主机下载再 docker cp

torch 782MB、cudnn 800MB、cublas 550MB、nccl 600MB。任何 ≥ 100MB 的 wheel，都别让 pip 在容器里直接拉（CloudFront + 代理链路 = 高概率截断）。

🔷 原则 4 · 三件套版本号必须"同代同季"

torch	torchvision	torchaudio	说明
2.11.x	0.26.x	2.11.x	✅ 官方同季发布组合（本次使用）

内部 C++ 符号差异是二进制级的不兼容，无补丁可打。

🟢 原则 5 · 每次改动后跑 3 条验证

bash 复制代码

# ① CUDA 初始化
python3 -c "import torch; torch.zeros(1).cuda()"

# ② fp16 矩阵乘
python3 -c "import torch; b=torch.randn(512,512,dtype=torch.float16,device='cuda'); print((b@b.T).shape)"

# ③ 显存查询
python3 -c "import torch; print(torch.cuda.mem_get_info())"

三条全过才算 CUDA 链路 OK，不要直接去启动 webui（启动慢，报错点被 import 淹没）。

09. 7 大踩坑报错 & 修复方案

PIT #1 · 最常见

复制代码

RuntimeError: CUDA error: unknown error

根因：原 torch 2.6+cu124 没有 sm_120 条目。
修复：换 torch-2.11.0+cu128-cp311-manylinux_2_28_x86_64.whl（及同版本配套）。

PIT #2 · 升级 torch 后立刻报

复制代码

ImportError: libnvshmem_host.so.3: cannot open shared object file

根因：libtorch_nvshmem.so 硬依赖 libnvshmem_host.so.3。
修复：pip install nvidia-nvshmem-cu12==3.7.2。

PIT #3 · 最隐蔽

复制代码

undefined symbol: cuptiActivityEnableDriverApi, version libcupti.so.12

根因：torch 2.11+cu128 用 CUDA 12.8 CUPTI 编译，但 cupti pip 包仍是 12.4。
修复：升到 12.9.79 以上，同时升级 15 个 nvidia- 同版本号*（避免 ld.so 断言崩溃）。

PIT #4 · 版本错配

复制代码

undefined symbol: _ZN3c104cuda29c10_cuda_check_implementationEiPKcS2_ib

根因：torchaudio 2.9.1 与 torch 2.11 不是同期发布，内部符号对不上。
修复：换成 torchaudio-2.11.0+cu128（与 torch 同主版本 + 同 cu128）。

PIT #5 · 下载阶段

复制代码

zipfile.BadZipFile / "Wheel ... is invalid"

根因：容器网络经过 CloudFront CDN，HTTPS 中途被切断，zip 中央目录损坏。
修复：在宿主机 用 aria2 下载完整 wheel → 放 C:\DL\ → docker cp → pip 离线装。永远不要在容器内直接 pip 拉 500MB+ 文件。

PIT #6 · 版本混装

复制代码

Inconsistency detected by ld.so: dl-version.c / dl-lookup.c

根因：一半 nvidia 包 12.4.x、另一半 12.9.x，内部符号版本对不上。
修复：执行 ch7 Step 3 把全部 15 个 nvidia-* 包一次卸掉 → 用 ch6-B 整串命令统一装新版。

PIT #7 · Docker 命名

复制代码

project name ... must be lowercase

根因：Docker project name 规则是 [a-z0-9\-]，不允许大写。
修复：docker compose -p llamafactory up -d（小写） + docker-compose.yaml 中写 container_name: LlamaFactory（保持大写）。

10. 快速验证脚本（10 秒出结果）

保存为宿主机 verify_cuda.py，任何 CUDA 改动后跑一次。输出 4 PASS 才算通过。

python 复制代码

#!/usr/bin/env python3
"""CUDA + sm_120 快速验证脚本（4 条断言，10 秒出结果）"""
import sys

ok = []
fail = []

def check(name, cond, detail=""):
    (ok if cond else fail).append((name, detail))

# 1. import 三件套不崩（nvshmem / cupti / c10 符号都在 import 时被解析）
try:
    import torch, torchvision, torchaudio
    check("1. import torch/torchvision/torchaudio", True)
except Exception as e:
    check("1. import 三件套", False, repr(e))

# 2. arch_list 包含 sm_120 + device_properties 正确识别
if not fail:
    arch = torch.cuda.get_arch_list()
    has_sm120 = "sm_120" in arch
    try:
        props = torch.cuda.get_device_properties(0)
        gpu_ok = props.total_memory > 15 * 1024**3 and "5060" in props.name
    except Exception as e:
        gpu_ok = False
        props = None
    check(f"2. arch_list 含 sm_120 (当前: {arch})", has_sm120)
    gpu_name = props.name if props else "N/A"
    check(f"3. GPU 识别 (5060 Ti, 17GB) => {gpu_name}", gpu_ok)

# 4. zeros(1).cuda() + fp16 matmul + mem_get_info 三连
if not fail:
    try:
        a = torch.zeros(1).cuda()
        b = torch.randn(512, 512, dtype=torch.float16, device="cuda")
        c = b @ b.T
        free, tot = torch.cuda.mem_get_info()
        calc_ok = (a.device.type == "cuda"
                   and c.shape == (512, 512)
                   and tot > 15 * 1024**3
                   and free < tot)
        check(f"4. CUDA 计算 (mem_free={free/1024**3:.2f}GB, tot={tot/1024**3:.2f}GB)", calc_ok)
    except Exception as e:
        check("4. CUDA 计算链路", False, repr(e))

print("\n" + "=" * 52)
for n, d in ok:   print(f"  [PASS] {n}" + (f"  {d}" if d else ""))
for n, d in fail: print(f"  [FAIL] {n}" + (f"  {d}" if d else ""))
print("=" * 52)
print(f"共 {len(ok)} 通过 / {len(fail)} 失败")
sys.exit(0 if not fail else 1)

容器内执行方式

powershell 复制代码

docker cp verify_cuda.py LlamaFactory:/tmp/verify_cuda.py
docker exec LlamaFactory python3 /tmp/verify_cuda.py

🟢 理想输出示例

复制代码

====================================================
  [PASS] 1. import torch/torchvision/torchaudio
  [PASS] 2. arch_list 含 sm_120 (当前: ['sm_50', ..., 'sm_120'])
  [PASS] 3. GPU 识别 (5060 Ti, 17GB) => NVIDIA GeForce RTX 5060 Ti
  [PASS] 4. CUDA 计算 (mem_free=16.20GB, tot=17.05GB)
====================================================
共 4 通过 / 0 失败

11. WebUI 启动与端口

Docker 命名约定

层级	值	说明
Compose 项目名 (`-p`)	`llamafactory`	必须全小写
容器名 (`container_name`)	`LlamaFactory`	保留大写

服务端口

服务	端口	地址
LlamaFactory WebUI	`0.0.0.0:7860` → `7860`	http://localhost:7860
训练 API（同端口）	`7860`	浏览器 / 脚本都走同一端口

后台启动 / 日志 / 停止

bash 复制代码

# 后台启动
nohup llamafactory-cli webui --host 0.0.0.0 --port 7860 > /tmp/webui.log 2>&1 &

# 查看日志
tail -n 50 -f /tmp/webui.log

# 停止 webui
pkill -f "llamafactory-cli webui"

12. 故障排查对照表（8 大常见错误）

#	错误关键词	最可能根因	排错步骤（按顺序）
1	`CUDA unknown error`	torch 版本不支持 sm_120（仍在用 cu124 旧版）	① `print(torch.__version__)` 必须是 `2.11.0+cu128` ② 否则重走 Step 3-4
2	`libnvshmem_host.so.3`	未装 nvidia-nvshmem-cu12 ≥ 3.4.5	① `pip show nvidia-nvshmem-cu12` ② 装 `==3.7.2` ③ `ldconfig`
3	`cuptiActivityEnableDriverApi`	cupti 版本太低（12.4 vs 编译用的 12.8）	① 重装 `nvidia-cuda-cupti-cu12==12.9.79` ② 同时升所有 nvidia-*（整串命令）
4	`c10_cuda_check_implementation`	torchaudio 与 torch 不是同期发布	① `pip show torchaudio` 必须 `2.11.0+cu128` ② 不是就离线重装同版本
5	`ld.so: dl-lookup.c` / 段错误	nvidia 包新旧版本混装	① 完整卸载 15 个 nvidia-*（Step 3）② 一次性重装 Step 5 整串命令
6	`zipfile.BadZipFile` / wheel 无效	下载被截断，大小不对	① `Get-ChildItem C:\DL*.whl
7	浏览器访问 `localhost:7860` 拒绝连接	webui 进程未启动 / 未绑定 0.0.0.0	① `docker exec LlamaFactory ss -lntp
8	`project name must be lowercase`	Docker compose -p 项目名用了大写	① 用小写 `-p llamafactory` ② yaml 里写 `container_name: LlamaFactory` 保持大写

13. 下载链接 & 参考来源

A · 核心 wheel 下载链接

Wheel	链接	备注
torch-2.11.0+cu128 (782 MB)	https://download-r2.pytorch.org/whl/cu128/torch-2.11.0%2Bcu128-cp311-cp311-manylinux_2_28_x86_64.whl	✅ download-r2 源（首选）
torchvision-0.26.0+cu128 (7.7 MB)	https://download-r2.pytorch.org/whl/cu128/torchvision-0.26.0%2Bcu128-cp311-cp311-manylinux_2_28_x86_64.whl	✅ download-r2 源
torchaudio-2.11.0+cu128 (1.9 MB)	https://download-r2.pytorch.org/whl/cu128/torchaudio-2.11.0%2Bcu128-cp311-cp311-manylinux_2_28_x86_64.whl	✅ download-r2 源
$备用$ download.pytorch.org torch	https://download.pytorch.org/whl/cu128/torch-2.11.0%2Bcu128-cp311-cp311-manylinux_2_28_x86_64.whl	⚠️ CloudFront 可能截断
PyPI 搜索 nvidia-* 15 个包	https://pypi.org/search/?q=nvidia-cublas-cu12	pypi.org

B · 辅助工具 & 镜像源

工具 / 源	链接	备注
aria2c 官网	https://aria2.github.io/	16 连接断点续传 · `winget install aria2.aria2`
清华 PyPI 镜像	https://pypi.tuna.tsinghua.edu.cn/simple	`-i` 参数
清华 Docker Hub 镜像	https://mirrors.tuna.tsinghua.edu.cn/help/dockerhub/	pull 加速

C · 项目官方仓库 & 文档

项目	链接	备注
LLaMA-Factory 官方仓库	https://github.com/hiyouga/LLaMA-Factory	大模型微调框架
LLaMA-Factory Docker CUDA 部署	https://github.com/hiyouga/LLaMA-Factory/blob/main/docker/docker-cuda/docker-compose.yml	本次部署的 compose 源
PyTorch 安装向导	https://pytorch.org/get-started/locally/	get-started / locally
PyTorch 版本兼容矩阵	https://github.com/pytorch/pytorch/wiki/PyTorch-Versions	torch / torchvision / torchaudio 对应关系
NVIDIA GPU 计算能力查询	https://developer.nvidia.com/cuda-gpus	确认 sm_xx
NVIDIA CUDA Toolkit Release Notes	https://docs.nvidia.com/cuda/cuda-toolkit-release-notes/	12.8 / 12.9 新符号与 CUPTI 变更
NVIDIA NVSHMEM 发行说明	https://docs.nvidia.com/nvshmem/release-notes.html	libnvshmem_host.so.3 引入版本
NVIDIA Container Toolkit	https://docs.nvidia.com/deploy/nvidia-container-toolkit/install-guide.html	`docker --gpus all` 前置条件