Text Generation WebUI 安装配置：本地运行大模型并验证

Text Generation WebUI 是一个开源的本地大模型交互界面，装好之后可以在浏览器里加载 GGUF 或 Transformers 格式的模型并直接对话。
本文按实际安装顺序，讲清楚环境准备、启动脚本、模型放置和访问验证，适合刚接触本地部署的用户。

安装前需要确认的环境

Text Generation WebUI 对 Python 版本比较敏感，推荐使用 Python 3.10，过新的版本可能导致部分依赖编译失败。
同时需要安装 Git，用来拉取项目代码。

Linux 上可以用系统包管理器检查：

python3 --version
git --version

如果 Python 版本不是 3.10，建议用 conda 或 pyenv 单独建一个 3.10 环境，不要直接改动系统默认 Python。
Windows 用户从 Python 官网下载 3.10 安装包时，记得勾选 Add Python to PATH。

磁盘空间方面，项目本身不大，但一个 7B 的 GGUF 模型通常需要 4GB 以上空间，建议预留 20GB 以上。

拉取项目并完成首次启动

选一个空间充足的目录，执行克隆：

git clone https://github.com/oobabooga/text-generation-webui.git
cd text-generation-webui

Linux 下给启动脚本执行权限并运行：

chmod +x start_linux.sh
./start_linux.sh

Windows 直接双击 start_windows.bat。
首次运行脚本会询问显卡类型，按实际硬件选择 CPU、NVIDIA 或 AMD。
脚本会自动创建虚拟环境并安装依赖，这个过程可能需要十几分钟，取决于网络速度。

避坑点：如果依赖安装卡在下载环节，可以先配置 pip 国内镜像，再重新执行启动脚本。
安装过程中不要关闭终端窗口，否则虚拟环境可能不完整。

放置模型并启动 WebUI

依赖装完后，把下载好的 GGUF 模型文件放到 models 目录下，建议按模型名建子目录，例如：

text-generation-webui/models/Llama-3-8B-GGUF/

然后重新运行启动脚本。
终端出现类似 Running on local URL: http://127.0.0.1:7860 的提示，说明服务已经起来。

在浏览器打开 http://服务器IP:7860 即可进入界面。
如果部署在远程服务器上，需要在启动命令后加 --listen 参数，否则默认只监听本机地址：

./start_linux.sh --listen

加载模型并验证对话

进入 WebUI 后，在顶部 Model 选项卡中选择刚放入的模型目录，点击 Load。
加载成功后，切到 Chat 选项卡输入一句测试内容，例如“你好，请用一句话介绍你自己”，能正常返回文字就说明链路通了。

如果模型列表为空，检查文件是否放在 models 目录下、扩展名是否为 .gguf。
如果加载时报显存不足，可以在 Model 加载参数里调低 n-gpu-layers，或改用更小的量化版本。

常见问题与检查顺序

• 浏览器打不开 7860 端口：先确认启动日志没有报错，再检查服务器防火墙或安全组是否放行 7860；远程访问必须带 --listen。
• 启动脚本报 Python 版本错误：确认当前终端里的 python3 指向 3.10，必要时用 which python3 检查路径。
• 模型加载后回复乱码或空内容：优先确认模型格式与加载器匹配，GGUF 模型应在 Model 选项卡选择对应的加载方式。

完成以上步骤后，Text Generation WebUI 就可以在本地稳定运行。
后续换模型只需把新模型放进 models 目录并在界面刷新选择，不需要重复安装依赖。