Windows 环境 LLaMA-Factory 本地部署教程：从零搭建大模型工具链

D:\python\miniconda3\Scripts\activate.bat D:\python\miniconda3\envs\llama-env

步骤 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. 若出现 jieba 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 的 官方文档。