Windows 环境 LLaMA-Factory 本地部署与配置指南

步骤 2：获取 LLaMA-Factory 源码

选择以下一种方式获取源码，推荐 Git 方式（后续更新只需执行'git pull'即可）。

方式 1：Git 拉取（推荐，已安装 Git）

1. 在 CMD 中输入以下命令，进入你想存放源码的目录（以'E:\pc-project\LLaMA'为例）：

cd /d E:\pc-project\LLaMA

说明：/d参数用于跨盘符切换目录，若你的目录在 C 盘，可省略该参数； 2. 拉取源码：输入以下命令，Git 会自动将源码下载到'LLaMA-Factory'文件夹中：

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

等待执行完成，若出现'Receiving objects: 100%'，说明拉取成功。

方式 2：ZIP 包解压（无 Git，简单直接）

1. 访问 LLaMA-Factory 的 GitHub 主页，点击右上角的'Code'按钮，选择'Download ZIP'；
2. 将下载的 ZIP 压缩包右键解压到'E:\pc-project\LLaMA'目录；
3. 将解压后的文件夹重命名为'LLaMA-Factory'（确保文件夹名无中文、空格或特殊字符，否则后续会报错）。

步骤 3：安装核心依赖（PyTorch+LLaMA-Factory）

核心依赖分为两部分：PyTorch（深度学习框架）和 LLaMA-Factory 本身及配套工具。按顺序安装，避免依赖解析混乱。

第一步：安装 CPU 版 PyTorch（无显卡必选）

PyTorch 是 LLaMA-Factory 的运行基础，Windows CPU 环境下优先选择 2.1.0 版本（经过实测，该版本无 DLL 冲突问题，且满足功能需求）。

pip install torch==2.1.0 torchvision==0.16.0 --index-url https://download.pytorch.org/whl/cpu

参数说明：--index-url指定从 PyTorch 官方 CPU 源下载，避免下载到 GPU 版本导致冲突；

若你有 NVIDIA 显卡（支持 CUDA 11.8 及以上），可替换为 GPU 版命令，推理和微调速度会大幅提升：

pip install torch==2.1.0 torchvision==0.16.0 --index-url https://download.pytorch.org/whl/cu118

第二步：安装 LLaMA-Factory 及配套依赖

1. 先切换到 LLaMA-Factory 源码目录（替换为你的实际路径）：

cd /d E:\pc-project\LLaMA\LLaMA-Factory

2. 执行以下命令，安装 LLaMA-Factory 及所有配套依赖（使用清华源加速，避免国内下载超时）：

pip install llamafactory[torch,metrics] -i https://pypi.tuna.tsinghua.edu.cn/simple

说明：[torch,metrics]表示安装 LLaMA-Factory 的完整依赖，包括 transformers（模型库）、peft（参数高效微调工具）等，无需手动逐个安装。

步骤 4：验证依赖安装是否成功

安装完成后，通过简单命令验证核心依赖是否正常加载，这是避免后续启动失败的关键一步。

python -c "import torch; import transformers; import llamafactory; print('PyTorch 版本:', torch.__version__); print('LLaMA-Factory 版本:', llamafactory.__version__)"

✅ 验证成功：若输出类似以下内容，且无报错，说明依赖安装正常：

PyTorch 版本：2.1.0+cpu
LLaMA-Factory 版本：0.9.3

❌ 常见问题：若提示'ModuleNotFoundError: No module named xxx'，说明该依赖未安装成功，重新执行步骤 3 的安装命令即可。

步骤 5：启动 LLaMA-Factory WebUI

这是最后一步，启动后将通过浏览器访问可视化界面，完成本地部署。

1. 启动命令：在 LLaMA-Factory 源码目录下，输入以下命令（指定端口 7861，避免与其他工具冲突）：

llamafactory-cli webui --server-port 7861

2. 等待启动完成：首次启动需加载 Gradio 前端资源，耗时约 10-30 秒（取决于网络速度）；
3. 若出现'jeage pkg_resources is deprecated'等警告，无需理会，不影响功能；
4. 启动成功后，CMD 会输出'Running on local URL: http://localhost:7861'。
5. 访问 WebUI：打开任意浏览器，在地址栏输入'http://localhost:7861'，即可看到 LLaMA-Factory 的可视化界面，本地部署正式完成！

四、优化体验：创建'一键启动'脚本

每次启动都输入命令较繁琐，可创建批处理脚本，双击即可完成'激活环境→启动 WebUI'全流程。

1. 新建批处理文件：在 LLaMA-Factory 源码目录（E:\pc-project\LLaMA\LLaMA-Factory）下，右键'新建→文本文档'，将文件名改为'start_llamafactory.bat'（确保后缀是.bat，而非.txt）；
2. 写入脚本内容：用记事本打开该文件，粘贴以下内容（将路径替换为你的实际路径）：

@echo off
echo ============== 正在激活虚拟环境 ==============
call D:\python\miniconda3\Scripts\activate.bat D:\python\miniconda3\envs\llama-env
echo ============== 正在切换到源码目录 ==============
cd /d E:\pc-project\LLaMA\LLaMA-Factory
echo ============== 正在启动 LLaMA-Factory ==============
llamafactory-cli webui --server-port 7861
echo ============== 启动完成，按任意键关闭 ==============
pause

3. 使用方式：双击'start_llamafactory.bat'，等待 CMD 执行完成后，直接在浏览器访问'http://localhost:7861'即可。

五、常见问题排查（避坑宝典）

部署过程中可能遇到各类问题，以下是高频问题及解决方案，覆盖 90% 以上的启动失败场景。

问题 1：'llamafactory-cli'不是内部或外部命令

根源：虚拟环境未激活，或 LLaMA-Factory 未安装成功。

解决方案：

1. 确保 CMD 前缀是'(llama-env)'，若不是，重新执行激活命令；
2. 重新安装 LLaMA-Factory：pip install --force-reinstall llamafactory -i 清华源。

问题 2：DLL 初始化例程失败（c10.dll）

根源：PyTorch 版本与 Windows 系统 VC++运行库不兼容。

解决方案：

1. 安装/修复 VC++ 2019-2022 运行库：下载 vc_redist.x64.exe，选择'修复'后重启电脑；
2. 重新安装 PyTorch 2.1.0 CPU 版（步骤 3 的命令）。

问题 3：浏览器访问'localhost:7861'无响应

根源：端口被占用，或 WebUI 未完成启动。

解决方案：

1. 更换端口启动：llamafactory-cli webui --server-port 7862，访问'http://localhost:7862'；
2. 耐心等待：确保 CMD 输出'Running on local URL'后再访问，避免启动中途访问。

问题 4：虚拟环境找不到（EnvironmentNameNotFound）

根源：虚拟环境未创建成功，或 conda 缓存异常。

解决方案：重新创建虚拟环境（步骤 1 的命令），确保执行过程无报错。

六、后续使用：快速上手 LLaMA-Factory

部署完成后，可通过 WebUI 快速实现核心功能：

1. 模型加载：在'Model'标签页的'Model Name or Path'中，输入本地模型路径（如'E:\models\llama2-7b'）或 Hugging Face 模型名（如'llama2-7b'，会自动下载）；
2. 对话推理：切换到'Chat'标签页，输入问题即可与模型对话；
3. 数据集微调：在'Train'标签页上传自定义数据集，配置微调参数（CPU 模式建议将'Batch Size'设为 2-4），点击'Start Training'即可。

七、总结

Windows 环境下 LLaMA-Factory 的本地部署，核心是'虚拟环境隔离 + 稳定版本选择 + 依赖自动解析'。只要遵循本文步骤，避开'未激活环境''版本不兼容''端口冲突'这三大坑，即使是零基础也能顺利完成搭建。

部署完成后，你将拥有一个本地的大模型工具链，无论是用于学术研究、项目开发还是兴趣探索，都能实现高效、安全的大模型开发。若在使用过程中遇到新问题，可查看 LLaMA-Factory 的 官方文档。