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

LLaMA-Factory 作为轻量级大模型微调与推理工具，凭借低配置门槛和全功能支持成为开发者首选。但 Windows 环境下的依赖管理与环境配置常让新手望而却步。本文提供本地部署教程，按步骤操作即可完成搭建。

一、部署前的核心认知：为什么要本地部署？

相比在线平台，本地部署 LLaMA-Factory 有三大优势：

• 数据安全：微调数据无需上传至云端，避免隐私泄露；
• 无网络依赖：部署完成后离线可用，适合网络不稳定场景；
• 高度可控：可自由修改源码、调整参数，适配个性化需求。

核心目标：在本地搭建 WebUI 可视化界面、模型推理和数据集微调的完整工具链，最终实现双击启动、浏览器访问的便捷体验。

二、前置准备：必装工具清单

本地部署需提前安装两个基础工具，用于管理 Python 环境和获取源码，均为免费且轻量化软件。

工具 1：Miniconda3（Python 环境管理器）

作用：创建独立的 Python 虚拟环境，避免不同项目的依赖冲突。

1. 下载：访问 Miniconda 官网下载页，直接点击 Download 即可（Windows 64 位自动匹配）；
2. 安装：勾选 Add Miniconda3 to my PATH environment variable（关键选项，确保 CMD 能直接调用 conda）；
3. 其他选项保持默认，点击 Next 直至安装完成；
4. 验证：打开新的 CMD 窗口（必须新打开，让环境变量生效），输入 conda --version，若输出 conda 版本号，则安装成功。

工具 2：Git（可选，源码获取工具）

作用：快速拉取 LLaMA-Factory 源码，后续更新也更便捷。若不想安装 Git，可直接下载源码压缩包。

1. 下载：访问 Git 官网下载页，点击 64-bit Git for Windows Setup；
2. 安装：全程默认下一步即可，安装完成后在 CMD 输入 git --version，输出 git version 即成功。

三、核心部署步骤：五步完成搭建

按环境准备、源码获取、依赖安装、验证启动的逻辑操作，每一步都附命令说明和验证方法。

步骤 1：创建并激活独立虚拟环境

这是 Windows 环境部署的关键，所有依赖都安装在独立环境中，不会影响电脑其他 Python 程序。

1. 打开 CMD 窗口：按下 Win+R，输入 cmd 后回车，打开命令提示符；
2. 创建虚拟环境：输入以下命令，创建名为 llama-env、基于 Python 3.10 的虚拟环境（Python 3.10 是 Windows 下兼容性最佳的版本）：

   conda create -n llama-env python=3.10 -y
   

   参数说明：-n llama-env 指定环境名，python=3.10 指定 Python 版本，-y 自动确认安装；
3. 激活虚拟环境：输入以下命令，激活创建的环境：

   conda activate llama-env
   

   ✅ 验证：CMD 窗口的前缀从 (base) 变为 (llama-env)，说明环境激活成功，后续所有操作都将在该环境中进行。
4. 应急方案：若激活失败，输入完整路径激活（将路径替换为你的 Miniconda 安装路径）：

   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 的 官方文档。