text-generation-webui本地部署指南

一、项目基础信息

• 定位：面向本地AI的权威Web UI，基于Gradio构建，主打强大功能与简易部署，专注于本地大语言模型（LLM）的文本生成及拓展应用。
• https://github.com/oobabooga/text-generation-webui

二、核心功能

1. 多后端与兼容性

支持多种本地文本生成后端，覆盖主流模型运行框架，包括llama.cpp、Transformers、ExLlamaV3、ExLlamaV2，以及通过专属Dockerfile实现的TensorRT-LLM。

2. 便捷部署与隐私保障

• 零门槛安装：提供Windows/Linux/macOS系统的“便携版构建包”（解压即运行，含全部依赖，适配GGUF模型），以及“一键安装脚本”（生成独立installer_files目录，支持多后端与拓展功能）。
• 全离线隐私性：无任何遥测数据、外部资源调用或远程更新请求，确保本地数据安全。

3. 多元交互与拓展能力

• 多模态支持：可上传文本、PDF、docx文件并基于内容对话；支持图片附件（视觉理解，需参考教程）；新增“图像生成”标签页，适配Z-Image-Turbo等diffusers模型，支持4bit/8bit量化与带元数据的持久化图库。
• 网络与格式优化：可选“网页搜索”功能（通过LLM生成查询词补充对话上下文）；支持代码块语法高亮、LaTeX数学公式渲染；自动用Jinja2模板格式化提示词，无需手动调整格式。

4. 灵活的对话与生成控制

• 多模式切换：含instruct（指令跟随，类似ChatGPT）、chat-instruct、chat（自定义角色对话）模式，以及Notebook标签页的“自由文本生成”（不受对话轮次限制）。
• 精细化操作：可编辑消息、回溯消息版本、分支对话；支持多采样参数与生成选项调节；无需重启即可切换模型；NVIDIA GPU用户可自动分配GGUF模型的GPU层。

5. API与拓展生态

• OpenAI兼容API：提供Chat与Completions接口，支持工具调用功能（含示例参考）。
• 拓展插件支持：内置多款拓展工具，同时支持用户贡献拓展，详情可查看项目wiki与extensions目录。

三、安装部署方案

提供4种主流安装方式，适配不同技术背景与硬件环境：

便携版构建包安装方法：

步骤 1：解压压缩包

1. 新建纯英文路径文件夹（关键：路径不能有中文、空格、特殊字符，例如 D:\AI\textgen）

2. 右键压缩包 → 解压到当前文件夹，等待解压完成

3. 解压后核心文件：

   • start_windows.bat：启动脚本（Vulkan 加速）
   • models/：模型存放目录
   • settings.yaml：配置文件

步骤 2：配置国内镜像（解决 Hugging Face 下载失败）

便携版内置了环境配置，我们先添加 HF 镜像源，加速模型下载：

1. 打开解压目录，找到 start_windows.bat，右键选择编辑（用记事本 / VS Code 打开）
2. 在脚本开头添加镜像环境变量，保存文件：

1
2
3
4

@echo off
:: 添加Hugging Face国内镜像，解决下载超时
set HF_ENDPOINT=https://hf-mirror.com
:: 原有启动代码保持不变

步骤 3：启动 WebUI 服务

1. 双击 start_windows.bat 启动程序

2. 首次启动会自动初始化环境，等待终端输出：

   1	Running on local URL: http://localhost:7860

3. 浏览器会自动打开Web 界面，若未自动打开，手动访问 http://localhost:7860

四、模型管理

1. 模型存放路径

• GGUF模型：单个文件直接放入text-generation-webui/user_data/models目录。
• 其他类型模型（如16-bit Transformers、EXL3）：需放在models目录下的独立子文件夹（含所有模型相关文件，如config.json、pytorch_model.bin等）。

2. 模型下载方式

• UI下载：通过Web UI的“Model”标签页，从Hugging Face自动下载。
• 命令行下载：执行python download-model.py organization/model（运行python download-model.py --help查看更多参数）。
• 硬件适配工具：提供“Accurate GGUF VRAM Calculator”，可提前测算GGUF模型是否适配本地硬件。

五、关键配置与命令行参数

1. 核心参数分类

• 基础设置：--model（默认加载模型名）、--extensions（加载拓展列表）、--verbose（终端打印提示词）、--idle-timeout（闲置后自动卸载模型时间）。
• 模型加载与硬件优化：--loader（手动指定加载器）、--gpu-layers（GPU卸载层数，llama.cpp专用）、--load-in-4bit/8bit（4/8位精度加载）、--cpu（纯CPU运行）、--disk（模型超限时将多余层存到磁盘）。
• 网络与访问控制：--listen（局域网可访问）、--listen-port（指定端口）、--share（生成公网URL，适合Colab）、--gradio-auth（Gradio访问密码，格式“用户名:密码”）。
• API相关：--api（启用API拓展）、--api-port（API端口）、--api-key（API认证密钥）、--nowebui（仅启动API，不加载Gradio UI）。

2. 参数使用方式

• 临时使用：启动脚本时直接追加参数（如./start_linux.sh --help）。
• 持久化配置：将参数写入user_data/CMD_FLAGS.txt（如写入--api永久启用API）。

六、辅助资源与社区

• 文档与教程：官方wiki（https://github.com/oobabooga/text-generation-webui/wiki）、图像生成/视觉理解等功能的专项教程。
• Colab notebook：提供云端试用环境，地址为https://colab.research.google.com/github/oobabooga/text-generation-webui/blob/main/Colab-TextGen-GPU.ipynb。