Oobabooga 本地大模型部署：安装、模型加载与对话验证

Oobabooga 是 Text Generation WebUI 的常用叫法，实际要做的事是：在本机启动一个 Web 服务，加载下载好的模型文件，然后通过浏览器对话。
它适合有独立显卡、想离线跑模型或对比不同模型效果的用户；
如果显存小于 6GB，建议优先选量化程度更高的 GGUF 模型，否则加载阶段就可能失败。

先确认系统和依赖能不能满足

Oobabooga 本质是 Python 项目，Windows 和 Linux 都能跑，但显卡驱动和 CUDA 版本要提前对齐。
没有 NVIDIA 显卡也可以用 CPU 跑，只是速度慢，适合验证流程，不适合日常对话。

准备清单：

• 操作系统：Windows 10/11 或常见 Linux 发行版，建议 64 位。
• Python：使用项目启动脚本自带的虚拟环境即可，不必手动全局安装。
• 显卡：NVIDIA 显卡需安装较新的驱动；AMD 显卡在 Linux 下支持更好，Windows 下限制较多。
• 磁盘：至少预留 20GB 以上，模型文件通常几个 GB 到十几 GB。
• 内存：建议 16GB 以上，加载大模型时内存和显存都会吃紧。

Linux 下先检查驱动和 CUDA 是否可见：

nvidia-smi

输出里能看到显卡型号和驱动版本，说明驱动正常。
如果命令不存在，先装 NVIDIA 驱动，不要急着往下走。

下载项目并启动 WebUI

在 Linux 或 macOS 终端中执行：

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

Windows 用户双击项目目录里的 start_windows.bat 即可。
首次启动脚本会创建虚拟环境并安装依赖，过程中会询问是否安装 GPU 相关包，按自己的显卡类型选择。
安装完成后终端会输出一个本地地址，通常是：

http://127.0.0.1:7860

用浏览器打开这个地址，能看到 Text Generation WebUI 页面，说明服务已经启动。
如果页面打不开，先在终端看有没有报错，再检查端口是否被占用。

把模型放到正确目录并加载

Oobabooga 加载模型有两种常见方式：GGUF 文件和 Transformers 格式目录。
新手优先用 GGUF，因为对显存更友好，下载后一般是一个 .gguf 文件。

把模型文件放到：

text-generation-webui/models/

例如：

text-generation-webui/models/Qwen2.5-7B-Instruct-Q4_K_M.gguf

回到 WebUI 页面，在 Model 标签页点击刷新按钮，下拉框里选择刚放进去的文件。
加载参数先保持默认，点击 Load。
终端出现加载进度并最终显示模型已加载，才算成功。

如果加载时报显存不足，可以调整两个方向：

• 换更小的量化模型，例如从 Q4 换成 Q3 或更小参数量的模型。
• 在加载设置里减少 GPU 层数，把部分计算放到 CPU，代价是速度变慢。

在 Chat 页发一条消息验证

模型加载完成后，切到 Chat 标签页，在输入框里发一句简单的话，例如“用一句话解释什么是服务器”。
页面能正常返回文字，说明模型、接口和显存链路都通了。

验证时重点看三件事：

• 回复是否完整，没有中途截断。
• 终端没有出现红色报错或显存溢出提示。
• 连续发两到三条消息，服务没有崩溃。

如果回复为空或页面一直转圈，先回终端看日志，常见原因是模型格式选错、显存不足或浏览器缓存了旧页面。

几个容易踩的坑

不要手动全局安装依赖。 项目启动脚本会管理虚拟环境，手动混装容易导致版本冲突。

模型目录不要放错层级。 GGUF 文件直接放在 models/ 下即可，不要多套一层文件夹，否则下拉框可能识别不到。

端口冲突先改启动参数。 如果 7860 被占用，可以在启动命令后加 --listen-port 7861，再访问新端口。

远程访问要谨慎。 默认只监听本机，开放到公网前先加认证和防火墙规则，避免模型接口被随意调用。

常见疑问

CPU 能跑吗？ 可以，启动时选择 CPU 相关选项即可，但生成速度明显慢于显卡，适合测试流程。

模型加载后没有出现在下拉框？ 先确认文件扩展名是 .gguf，再点刷新；
仍然看不到就检查文件权限和目录层级。

对话回复很慢正常吗？ 首次加载和首次生成会慢一些，后续如果仍然很慢，通常是模型参数量超过显存承受范围，部分层回退到了 CPU。

Oobabooga 使用教程的核心不是把所有参数都调一遍，而是先跑通“启动服务、放对模型、加载成功、对话有回复”这条链路。
链路通了之后，再根据显存和速度微调量化版本与 GPU 层数，才不容易在排错时迷失方向。