腾讯云部署 LLaMAFactory：DeepSeek-R1-Distill-Qwen-1.5B 微调实战

前言

最近在腾讯云 Windows GPU 服务器上部署 LLaMAFactory，并使用 DeepSeek-R1-Distill-Qwen-1.5B 模型进行 LoRA 微调。在部署过程中，遇到了一个比较隐蔽的问题：执行 llamafactory-cli webui 后终端没有任何报错，鼠标转圈两次后直接回到命令行，WebUI 无法启动。

经过排查发现，问题并不是 CUDA、PyTorch、Node.js、Gradio 或腾讯云端口导致的，而是 pyarrow / pandas / numpy / datasets 版本组合在 Windows 环境下触发了底层崩溃。最终通过降级这几个包解决。

本文记录完整部署流程，包括：

1. 腾讯云 Windows GPU 服务器环境准备；
2. CUDA、Miniconda、PyTorch 安装；
3. LLaMAFactory 安装；
4. WebUI 启动异常及解决方法；
5. DeepSeek-R1-Distill-Qwen-1.5B 模型加载；
6. 自定义数据集配置；
7. 使用 LLaMAFactory 进行 LoRA 微调；
8. 微调后模型测试。

---

一、实验环境

本次实验环境如下：

项目	配置
云平台	腾讯云 GPU 云服务器
操作系统	Windows Server
GPU	NVIDIA GPU，显存约 32GB
CUDA	12.2
Python	3.11
PyTorch	2.5.1
微调框架	LLaMAFactory
基座模型	DeepSeek-R1-Distill-Qwen-1.5B
微调方式	LoRA / SFT
WebUI	LLaMA Board，基于 Gradio

---

二、检查 CUDA 环境

首先打开 CMD，输入：

nvidia-smi

查看显卡驱动和 CUDA Version。

如果显示类似：

CUDA Version: 12.2

说明显卡驱动正常。

如果需要安装 CUDA 12.2，可以前往 NVIDIA 官网下载对应版本：

https://developer.nvidia.com/cuda-12-2-1-download-archive

安装完成后，可以继续检查 CUDA 编译器版本：

nvcc -V

如果能正常输出 CUDA 版本信息，说明 CUDA Toolkit 安装成功。

---

三、安装 Miniconda

为了避免 Python 包冲突，建议使用 Miniconda 管理虚拟环境。

安装完成后，需要将 Miniconda 添加到系统环境变量。一般需要添加以下路径：

C:\ProgramData\miniconda3
C:\ProgramData\miniconda3\Scripts
C:\ProgramData\miniconda3\Library\bin
C:\ProgramData\miniconda3\Library\mingw-w64\bin

然后重新打开 CMD，执行：

conda init

之后关闭终端，重新打开 CMD。

---

四、创建 Python 虚拟环境

建议使用 Python 3.11。之前使用 Python 3.12 时，部分依赖包可能会出现兼容性问题。

创建环境：

conda create -n llama python=3.11 -y

激活环境：

conda activate llama

确认 Python 路径：

where python
python -c "import sys; print(sys.executable)"

正常情况下，应该指向当前 conda 环境，例如：

C:\ProgramData\miniconda3\envs\llama\python.exe

---

五、安装 PyTorch

由于服务器 CUDA Version 是 12.2，而 PyTorch 2.5.1 没有专门的 cu122 版本，因此可以安装 cu121 版本。

推荐命令如下：

pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu121

安装完成后验证：

python -c "import torch; print(torch.__version__); print(torch.version.cuda); print(torch.cuda.is_available())"

如果输出类似：

2.5.1+cu121
12.1
True

说明 PyTorch GPU 版本安装成功。

这里需要注意：torch.version.cuda 显示 12.1 是正常的，表示 PyTorch 自带 CUDA Runtime 是 12.1，并不影响在 CUDA 12.2 驱动环境下运行。

---

六、安装 Git

如果系统没有 Git，可以直接使用 conda 安装：

conda install git -y

安装完成后验证：

git --version

---

七、下载 LLaMAFactory

进入工作目录，例如：

cd C:\Users\Administrator

克隆 LLaMAFactory 项目：

git clone --depth 1 https://github.com/hiyouga/LLaMA-Factory.git LlamaFactory

进入项目目录：

cd LlamaFactory

---

八、安装 LLaMAFactory

在项目根目录执行：

pip install -e .

安装评估指标相关依赖：

pip install -r requirements/metrics.txt

安装完成后，检查 LLaMAFactory 是否安装成功：

llamafactory-cli version

如果能正常输出版本号，说明安装成功。

---

九、启动 WebUI

正常情况下，直接执行：

llamafactory-cli webui

LLaMAFactory 会启动基于 Gradio 的 WebUI，终端会显示类似：

Running on local URL: http://127.0.0.1:7860

然后在服务器浏览器中访问：

http://127.0.0.1:7860

如果是在本地电脑访问腾讯云服务器，需要使用：

http://服务器公网IP:7860

同时需要在腾讯云安全组和 Windows 防火墙中放行 7860 端口。

也可以手动指定监听地址和端口：

set GRADIO_SERVER_NAME=0.0.0.0
set GRADIO_SERVER_PORT=7860
llamafactory-cli webui

---

十、LLaMAFactory WebUI 无反应问题解决

1. 问题现象

我遇到的问题是：

llamafactory-cli webui

执行后没有任何报错，也没有任何输出，鼠标转圈两次后直接回到命令行。

表现如下：

(llama) C:\Users\Administrator\LlamaFactory>llamafactory-cli webui

(llama) C:\Users\Administrator\LlamaFactory>

一开始怀疑是 Node.js、Gradio、端口、防火墙或者腾讯云安全组问题，但排查后都不是。

---

2. 排查 Gradio 是否正常

先单独测试 Gradio：

python -u -c "import gradio as gr; print('gradio import ok', gr.__version__, flush=True); demo=gr.Interface(lambda x:x, 'text', 'text'); print('before launch', flush=True); demo.launch(server_name='0.0.0.0', server_port=7860, inbrowser=False)"

如果输出：

gradio import ok 5.50.0
before launch
* Running on local URL:  http://0.0.0.0:7860

说明 Gradio 本身可以启动，端口也没有问题。

---

3. 检查 LLaMAFactory 和 Python 路径

继续检查命令路径：

where llamafactory-cli
where python
python -c "import sys; print(sys.executable)"
python -c "import llamafactory; print(llamafactory.__file__)"

如果输出类似：

C:\ProgramData\miniconda3\envs\llama\Scripts\llamafactory-cli.exe
C:\ProgramData\miniconda3\envs\llama\python.exe
C:\Users\Administrator\LlamaFactory\src\llamafactory\__init__.py

说明命令入口和 Python 环境都没有问题。

---

4. 使用 faulthandler 定位错误

由于普通启动没有任何输出，可以使用下面命令直接导入 WebUI 模块：

python -u -X faulthandler -c "import torch; print('1 torch ok', torch.__version__, torch.cuda.is_available(), flush=True); import gradio; print('2 gradio ok', gradio.__version__, flush=True); import transformers; print('3 transformers ok', transformers.__version__, flush=True); import peft; print('4 peft ok', peft.__version__, flush=True); from llamafactory.webui.interface import create_ui; print('5 create_ui import ok', flush=True); demo=create_ui(); print('6 ui created ok', flush=True); demo.queue().launch(server_name='0.0.0.0', server_port=7860, inbrowser=False)"

当时输出如下：

1 torch ok 2.5.1 True
2 gradio ok 5.50.0
3 transformers ok 4.56.2
4 peft ok 0.18.1
Windows fatal exception: access violation

调用栈中出现：

pyarrow
pandas
datasets
llamafactory\data\data_utils.py
llamafactory\webui\interface.py

最终定位到：pyarrow 在 Windows 环境下导入时发生底层崩溃，导致 Python 进程直接退出。

---

5. 最终解决方法

卸载以下包：

pip uninstall -y pyarrow pandas numpy datasets

重新安装稳定版本：

pip install --no-cache-dir ^
"numpy==1.26.4" ^
"pandas==2.2.3" ^
"pyarrow==17.0.0" ^
"datasets==3.2.0"

如果使用 PowerShell，可以写成：

pip install --no-cache-dir `
"numpy==1.26.4" `
"pandas==2.2.3" `
"pyarrow==17.0.0" `
"datasets==3.2.0"

安装完成后测试：

python -c "import pyarrow; print('pyarrow ok', pyarrow.__version__)"
python -c "import pandas; print('pandas ok', pandas.__version__)"
python -c "import datasets; print('datasets ok', datasets.__version__)"

如果都能正常输出版本号，再启动：

llamafactory-cli webui

此时 WebUI 就可以正常打开了。

---

十一、加载 DeepSeek-R1-Distill-Qwen-1.5B 模型

WebUI 打开后，进入 Chat 页面。

在模型选择位置输入或选择：

DeepSeek-R1-Distill-Qwen-1.5B

如果是第一次加载模型，LLaMAFactory 会自动从 Hugging Face 或 ModelScope 下载模型。

如果服务器访问 Hugging Face 较慢，可以考虑使用 ModelScope 或者提前手动下载模型到本地。

加载模型后，可以在 Chat 页面输入测试问题，点击 Submit 进行对话测试。

---

十二、准备微调数据集

本次示例使用一个自定义 JSON 数据集，例如：

hwtcm.json

将数据集放入 LLaMAFactory 项目的 data 目录下，例如：

C:\Users\Administrator\LlamaFactory\data\hwtcm.json

数据集格式可以是 alpaca 格式，例如：

[
  {
    "instruction": "请介绍中医里的阴阳理论。",
    "input": "",
    "output": "阴阳理论是中医基础理论的重要组成部分，用于解释人体生理、病理变化以及疾病诊断和治疗原则。"
  },
  {
    "instruction": "什么是气血？",
    "input": "",
    "output": "气血是中医理论中维持人体生命活动的重要物质基础。气具有推动、温煦、防御等作用，血具有濡养和滋润作用。"
  }
]

---

十三、修改 dataset_info.json

打开：

C:\Users\Administrator\LlamaFactory\data\dataset_info.json

添加自定义数据集配置：

"hwtcm": {
  "file_name": "hwtcm.json"
}

注意 JSON 格式要正确，如果不是最后一个数据集配置，后面需要加逗号。

例如：

{
  "identity": {
    "file_name": "identity.json"
  },
  "hwtcm": {
    "file_name": "hwtcm.json"
  },
  "alpaca_zh_demo": {
    "file_name": "alpaca_zh_demo.json"
  }
}

保存后重新进入 WebUI，数据集列表中就可以看到 hwtcm。

---

十四、使用 LLaMAFactory 进行 LoRA 微调

进入 LLaMAFactory WebUI 的 Train 页面。

主要参数可以参考：

参数	示例
Stage	Supervised Fine-Tuning
Model name	DeepSeek-R1-Distill-Qwen-1.5B
Dataset	hwtcm
Finetuning type	LoRA
Epochs	1 或 30
Batch size	根据显存设置
Gradient accumulation	根据显存设置
Learning rate	默认或根据需求调整
Output dir	saves/DeepSeek-R1-Distill-Qwen-1.5B/lora

如果只是演示流程，可以先把 Epochs 设置为 1，这样训练速度较快。

如果希望效果更明显，可以把 Epochs 设置为 30，但是训练时间会明显增加。

---

十五、训练时间说明

大模型微调对显存和时间都有一定要求。

例如在 32GB 显存 GPU 上，使用较大的 batch size 和 30 个 Epochs 训练时，可能需要十几个小时。

如果只是教学演示，可以把 Epochs 设置为 1，训练时间可能缩短到几十分钟。

但需要注意：

• Epochs 越少，训练越快；
• Epochs 越少，模型学习效果越弱；
• Epochs 越多，损失下降更充分；
• 训练过多也可能过拟合。

实际使用时需要根据数据集规模、任务难度和显卡资源进行调整。

---

十六、缩短训练时间的方法

如果训练时间太长，可以从以下几个方面优化：

1. 降低 Epochs

例如从：

Epochs = 30

改为：

Epochs = 1

2. 减小数据集规模

教学演示可以先使用几十条或几百条样本跑通流程。

3. 降低 batch size

如果显存不足，可以适当降低 batch size。

4. 使用 LoRA 或 QLoRA

相比全参数微调，LoRA 和 QLoRA 更节省显存，更适合单卡实验。

5. 使用更小模型

DeepSeek-R1-Distill-Qwen-1.5B 模型相对较小，适合教学和入门实验。

---

十七、加载微调后的 LoRA 模型

训练完成后，进入 Chat 页面。

在模型位置选择原始基座模型：

DeepSeek-R1-Distill-Qwen-1.5B

在 LoRA adapter 位置选择刚才训练得到的 LoRA 权重目录。

一般路径类似：

saves/DeepSeek-R1-Distill-Qwen-1.5B/lora

然后点击：

Load model

加载完成后，就可以输入问题测试微调效果。

---

十八、微调前后效果对比

微调前，模型对特定领域问题可能回答比较泛化，不一定符合数据集中的表达方式。

微调后，模型会更倾向于学习数据集中的知识、格式和回答风格。

例如，如果数据集是中医领域内容，微调后模型在回答中医相关问题时，通常会更加贴近训练数据。

需要注意的是：

• 少量数据微调主要改变回答风格和部分知识倾向；
• 如果想显著提升领域能力，需要更高质量、更大规模的数据；
• 微调不能保证模型完全记住所有知识；
• 对事实性强的任务，还需要结合 RAG 或知识库检索。

---

十九、自己制作数据集

如果没有现成数据集，可以使用 Easy Dataset 等工具辅助制作。

Easy Dataset 项目地址：

https://github.com/ConardLi/easy-dataset

基本流程如下：

1. 安装 Easy Dataset；
2. 创建项目；
3. 配置大模型 API；
4. 上传原始文档；
5. 自动生成问答数据；
6. 人工检查和清洗；
7. 导出 JSON 数据集；
8. 放入 LLaMAFactory 的 data 目录；
9. 修改 dataset_info.json；
10. 在 WebUI 中选择数据集进行微调。

如果有 API Key，可以使用在线大模型生成数据集，速度和质量通常更好。

如果希望完全本地化，也可以使用 Ollama 部署本地模型生成数据集。

---

二十、使用 Ollama 辅助生成数据集

如果服务器显存充足，可以使用 Ollama 本地部署大模型。

Ollama 官网：

https://ollama.com/

安装后，可以运行模型，例如：

ollama run qwen3.5:27b

第一次运行会自动下载模型，下载完成后可以直接对话。

在 Easy Dataset 中配置 Ollama 地址后，可以使用本地模型辅助生成问答数据。

这种方式的优点是：

• 数据不需要上传到第三方 API；
• 本地可控；
• 适合私有文档处理。

缺点是：

• 下载模型较慢；
• 本地推理速度受显卡影响；
• 大模型显存占用较高。

---

二十一、常见问题总结

1. LLaMAFactory 需要 Node.js 吗？

正常使用不需要。

LLaMAFactory WebUI 是基于 Gradio 的 Python Web 应用，不需要单独安装 Node.js。

2. CUDA 12.2 可以安装 PyTorch cu121 吗？

可以。

PyTorch 2.5.1 没有专门的 cu122 安装包，使用 cu121 是可行的。只要：

torch.cuda.is_available()

返回：

True

就说明 GPU 可用。

3. llamafactory-cli webui 没反应怎么办？

优先排查：

python -c "import pyarrow; print(pyarrow.__version__)"
python -c "import pandas; print(pandas.__version__)"
python -c "import datasets; print(datasets.__version__)"

如果出现静默退出或 access violation，可以尝试：

pip uninstall -y pyarrow pandas numpy datasets

pip install --no-cache-dir ^
"numpy==1.26.4" ^
"pandas==2.2.3" ^
"pyarrow==17.0.0" ^
"datasets==3.2.0"

4. WebUI 在服务器里能打开，本地打不开怎么办？

需要检查两处：

第一，腾讯云安全组是否开放 7860 端口。

第二，Windows 防火墙是否允许 7860 入站。

Windows 防火墙可以执行：

netsh advfirewall firewall add rule name="LLaMAFactory WebUI 7860" dir=in action=allow protocol=TCP localport=7860

启动时建议设置：

set GRADIO_SERVER_NAME=0.0.0.0
set GRADIO_SERVER_PORT=7860
llamafactory-cli webui

5. DeepSpeed 必须安装吗？

不必须。

如果只是 WebUI、单卡 LoRA 或 QLoRA 微调，可以先不装 DeepSpeed。

DeepSpeed 更多用于多卡训练、ZeRO 优化等场景。Windows 原生环境下安装 DeepSpeed 容易遇到编译问题。

---

二十二、完整安装命令汇总

下面给出一套相对稳定的安装流程。

创建环境：

conda create -n llama python=3.11 -y
conda activate llama

安装 PyTorch：

pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu121

安装 Git：

conda install git -y

下载 LLaMAFactory：

cd C:\Users\Administrator
git clone --depth 1 https://github.com/hiyouga/LLaMA-Factory.git LlamaFactory
cd LlamaFactory

安装 LLaMAFactory：

pip install -e .
pip install -r requirements/metrics.txt

修复 Windows 下 pyarrow 可能导致的 WebUI 静默退出问题：

pip uninstall -y pyarrow pandas numpy datasets

pip install --no-cache-dir ^
"numpy==1.26.4" ^
"pandas==2.2.3" ^
"pyarrow==17.0.0" ^
"datasets==3.2.0"

启动 WebUI：

set GRADIO_SERVER_NAME=0.0.0.0
set GRADIO_SERVER_PORT=7860
llamafactory-cli webui

---

二十三、总结

本文记录了在腾讯云 Windows GPU 服务器上部署 LLaMAFactory，并对 DeepSeek-R1-Distill-Qwen-1.5B 进行 LoRA 微调的完整流程。

整体流程如下：

1. 检查 CUDA 和 GPU；
2. 安装 Miniconda；
3. 创建 Python 3.11 虚拟环境；
4. 安装 PyTorch 2.5.1 cu121；
5. 下载并安装 LLaMAFactory；
6. 启动 WebUI；
7. 解决 pyarrow 导致的 WebUI 静默退出问题；
8. 加载 DeepSeek-R1-Distill-Qwen-1.5B；
9. 准备自定义数据集；
10. 修改 dataset_info.json；
11. 使用 LoRA 进行微调；
12. 加载 LoRA 权重并测试模型效果。

本次踩坑最关键的问题是：

llamafactory-cli webui 执行后无反应，不一定是 Gradio、端口或 CUDA 问题，也可能是 pyarrow 在 Windows 下发生底层崩溃。

最终解决命令是：

pip uninstall -y pyarrow pandas numpy datasets

pip install --no-cache-dir ^
"numpy==1.26.4" ^
"pandas==2.2.3" ^
"pyarrow==17.0.0" ^
"datasets==3.2.0"

如果你也在 Windows 服务器上部署 LLaMAFactory，并遇到 WebUI 一闪而过、终端没有任何报错的情况，可以优先检查 pyarrow / pandas / datasets 这几个包。