TextGen（原 Text Generation WebUI）：本地大模型桌面应用，多后端 + OpenAI 兼容 API 的离线 WebUI｜部署与使用全指南

项目仓库： https://github.com/oobabooga/text-generation-webui（已更名为 TextGen，当前规范仓库 oobabooga/textgen，旧路径自动跳转）

开源协议：AGPL-3.0 · 主要语言：Python · 交付形态：跨平台便携桌面包（CUDA / Vulkan / ROCm / CPU-only）、Gradio 浏览器 Web UI、本地 API 服务 · Web UI 默认端口 7860，API 默认端口 5000 · 模型目录 user_data/models · 官方文档：GitHub Wiki

非官方声明：TextGen 由开发者 oobabooga 独立维护，与 OpenAI、Anthropic、Google、Meta、Hugging Face、NVIDIA、AMD、llama.cpp、Transformers 等公司与开源项目不存在隶属或授权关系；文中模型、后端与硬件名称仅用于说明兼容目标。项目本体不打包模型权重，模型许可证由对应发布方决定。品牌已由 Text Generation WebUI 更名为 TextGen，本文沿用历史称谓便于检索，界面与命令以当前安装版本为准。

1 项目简介

TextGen 是一款面向本地大模型的桌面应用与 Web UI：把下载到本机的 GGUF、Transformers、EXL3 等格式模型接入统一界面，完成对话、指令跟随、自由文本续写、视觉理解、工具调用、LoRA 微调与图像生成；同时对外提供 OpenAI / Anthropic 兼容的本地 API。项目强调 100% 离线运行、零遥测、不加载外部资源、不发起远程更新请求。

1.1 核心信息一览

1.2 适用场景

• 在本机或内网运行开源大模型，对话与续写数据不离开自有环境，替代需要上传上下文的云端助手。
• 同一块显卡上对比不同模型、量化等级、采样参数与后端表现，调试提示词模板与角色设定。
• 通过 OpenAI / Anthropic 兼容 API 把本地模型接入其他脚本、聊天客户端、自动化工作流或 Agent 框架。
• 使用自定义工具函数（单文件 .py）与 MCP 服务器扩展模型能力，例如网页搜索、页面抓取、数学计算。
• 在多轮聊天或原始文本数据集上微调 LoRA，支持中断后续训；使用 diffusers 模型在独立标签页生成图片。
• 开发者基于扩展机制接入 TTS、语音输入、翻译等社区扩展。

1.3 能力边界（官方口径）

• 官方 README 自述定位为 “A desktop app for local LLMs. Open source, no telemetry. Text, vision, tool-calling, web search. UI + API.”；能力覆盖文本、视觉、工具调用与网页搜索。
• 模型与权重不随项目分发：GGUF 需从 Hugging Face 等来源下载放入 user_data/models；多文件格式模型需要完整安装版，便携包仅覆盖 GGUF（llama.cpp）路线。
• 便携桌面包以快速上手为目标，训练、图像生成、ExLlamaV3 / Transformers 等额外后端与部分扩展需要完整安装（约 10GB 磁盘并下载 PyTorch）。
• 本地推理速度与质量取决于显卡显存、内存、量化等级与模型规模；官方提供 LocalBench 推荐量化与 GGUF 显存计算器辅助选型，本文不臆造具体显存数字。
• 项目不内置联网搜索结果与模型回答事实；工具调用结果与模型输出都需要使用者核对。

2 功能特性

2.1 对话与文本生成

• 三种模式：instruct 面向指令跟随（类似 ChatGPT），chat-instruct / chat 用于与自定义角色对话；提示词自动套用模型自带或指定的 Jinja2 聊天模板。
• 可编辑历史消息、在消息版本间导航、在任意节点分支会话；Notebook 标签用于对话轮次之外的自由文本续写。
• 深色 / 浅色主题、代码块语法高亮、数学表达式 LaTeX 渲染。

2.2 视觉与文件附件

• 视觉（多模态）：可在消息中附加图片，让模型做视觉理解；视觉模型需要配套 mmproj 文件。
• 文件附件：上传文本文件、PDF 与 .docx 文档，围绕其内容对话。

2.3 多后端与本地 API

• 后端覆盖 llama.cpp、ik_llama.cpp、Transformers、ExLlamaV3、TensorRT-LLM；后端与模型之间可在界面内切换而不必重启进程。
• 提供 OpenAI / Anthropic 兼容的 Chat、Completions、Messages 端点，支持工具调用；可作为 OpenAI / Anthropic API 的本地替代，通过 --api-key 鉴权。
• --public-api 可借助 Cloudflare 生成公网 API 地址；--nowebui 可只启动 API、不加载 Gradio 界面。

2.4 工具调用与 MCP

• 模型在聊天中可调用自定义函数，内置网页搜索、页面抓取、数学计算等示例；每个工具就是一个独立 .py 文件，便于二次编写。
• 支持接入 MCP（Model Context Protocol）服务器；可开启“每次工具调用前询问批准”的确认模式。

2.5 训练与图像生成

• 训练：在多轮聊天或原始文本数据集上微调 LoRA，支持中断后续训；完整安装后在 Training 标签操作。
• 图像生成：独立标签页运行 diffusers 模型（如 Z-Image-Turbo），支持 4-bit / 8-bit 量化与持久图库，图片元数据随结果保存。

2.6 隐私与扩展

• 100% 离线、零遥测、无外部资源加载、无远程更新请求；界面内不主动上报使用数据。
• 内置与社区扩展涵盖 TTS、语音输入、翻译等；完整列表见扩展仓库，扩展依赖由更新向导统一安装。

3 官方界面预览

3.1 Chat 模式与工具调用

下图为桌面端 Chat 标签：左侧为历史会话列表，中间为对话区——模型在思考后依次调用 web_search 与多个 fetch_webpage 工具抓取资料，再汇总给出 16GB 显存 + 32GB 内存机型的本地模型选型建议；右侧为工具勾选、MCP 服务器与 instruct / chat-instruct / chat 模式切换面板。

3.2 Instruct 模式

下图为浏览器 Web UI 的 Instruct 模式：右侧工具区勾选 fetch_webpage、web_search 并开启 Confirm tool calls；下方 Mode 单选 instruct，模型按指令回答“几何纹样陶器在人类史前哪个时期达到顶峰”，回答中区分了不同考古文化时期。

3.3 Notebook 自由续写

下图为 Notebook 标签：左侧 Input 输入草稿，右侧 Output 支持 Raw、Markdown、HTML、Logits、Tokens 多种视图；Continue 在续写位置追加，Generate 从头生成，底部 Prompt 下拉可切换保存的提示词模板。

3.4 Parameters 采样面板

下图为 Parameters 标签的 Generation 子页：左侧为 Curve shape（temperature、top-p、top-k、min-p、top-n-sigma、typical_p、XTC）、Curve cutoff 与重复抑制（DRY、重复惩罚等），中间为 mirostat、adaptive-p 与采样优先级；右侧为 max_new_tokens、上下文截断长度、Seed、自定义系统消息、停止字符串、Token 禁用与 GBNF 语法文件；顶部 Preset 可保存采样预设，Filter by loader 按后端过滤参数项。

4 官方跳转链接汇总

5 前置要求与服务器配置

5.1 软件前提

• Python：便携 venv 方式要求 Python 3.9 及以上；完整安装由启动脚本通过 Miniforge 在 installer_files/ 内自建 Conda 环境，不污染系统 Python。
• 显卡驱动 / CUDA（NVIDIA）：CUDA 后端需要与 PyTorch 版本匹配的显卡驱动；AMD 走 ROCm，Apple Silicon 走 MPS，其余可使用 CPU / Vulkan。
• 磁盘空间：便携包体积较小；完整安装约需 10GB 并下载 PyTorch；模型文件通常数 GB 到数十 GB，按模型规模预留独立磁盘空间。
• 网络：首次下载模型、PyTorch 与依赖需要访问 Hugging Face 与 PyTorch 源；运行过程本身不强制联网。
• Docker（可选）：Docker 部署需要 Docker Compose v2.17 或更高版本。

5.2 硬件建议

5.3 目录、端口与环境变量

6 方式一：Docker Compose 部署（官方 Dockerfile）

官方仓库 docker/ 目录按厂商提供 Dockerfile 与 Compose 文件；先根据显卡型号选择对应软链，再拷贝环境变量模板并构建。

6.1 选择后端软链

git clone https://github.com/oobabooga/textgen.git
cd textgen

# NVIDIA 显卡
ln -s docker/{nvidia/Dockerfile,nvidia/docker-compose.yml,.dockerignore} .

# AMD 显卡
ln -s docker/{amd/Dockerfile,amd/docker-compose.yml,.dockerignore} .

# Intel 显卡
ln -s docker/{intel/Dockerfile,intel/docker-compose.yml,.dockerignore} .

# 纯 CPU
ln -s docker/{cpu/Dockerfile,cpu/docker-compose.yml,.dockerignore} .

6.2 准备环境变量与目录

cp docker/.env.example .env
mkdir -p user_data/logs user_data/cache

按需编辑 .env：

• TORCH_CUDA_ARCH_LIST：按 NVIDIA 显卡型号填写对应算力代号；
• APP_RUNTIME_GID：宿主机用户组 ID，在终端执行 id -g 获取；
• BUILD_EXTENIONS：可选，填写逗号分隔的扩展名称，构建时一并安装。

在 user_data/CMD_FLAGS.txt 中写入需要的启动参数，例如只监听本机、使用 CPU 模式：

--listen
--cpu

6.3 构建并启动

docker compose up --build

• 需要 Docker Compose v2.17 或更高版本；更多 Docker 说明见 Wiki 的 Docker 页面，第三方额外镜像可参考社区维护的 text-generation-webui-docker 仓库。
• 构建完成后按 --listen-port 与 --api-port 访问 Web UI 与 API；容器内模型、配置与日志通过 user_data 卷持久化。
• 公网暴露前先配置 --gradio-auth 账号密码或 --api-key，不要把无鉴权界面直接发布到不可信网络。

7 方式二：便携包、本地脚本与 Conda 安装

7.1 桌面便携包（最快上手）

1. 到 Releases 下载对应操作系统与硬件（CUDA / Vulkan / ROCm / CPU-only）的便携构建，依赖已内置。
2. 解压后双击 textgen 可执行文件，桌面窗口直接打开。
3. 便携包面向 GGUF（llama.cpp）模型；训练、图像生成与额外后端请使用完整安装。

7.2 venv 便携安装（任意 Python 3.9+）

git clone https://github.com/oobabooga/textgen
cd textgen

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# macOS / Linux:
source venv/bin/activate

# 按硬件选择 requirements/portable/ 下对应文件安装依赖
pip install -r requirements/portable/requirements.txt --upgrade

# 启动服务器（便携模式、开启 API、自动打开浏览器）
python server.py --portable --api --auto-launch

# 工作结束后退出虚拟环境
deactivate

7.3 完整安装：一键启动脚本

1. 克隆仓库或下载源码压缩包并解压。
2. 运行对应系统脚本：start_windows.bat、start_linux.sh、start_macos.sh。
3. 按提示选择显卡厂商；脚本在 installer_files/ 内用 Miniforge 创建 Conda 环境并安装完整依赖。
4. 安装完成后浏览器打开 http://127.0.0.1:7860。

常用后续操作：

# 再次启动：运行同一个 start_ 脚本即可
./start_linux.sh

# 直接向脚本传命令行参数
./start_linux.sh --help

# 把参数持久化到 user_data/CMD_FLAGS.txt，例如开启 API
# --api

# 更新：运行对应系统的更新向导
# Windows: update_wizard_windows.bat
# Linux:   update_wizard_linux.sh
# macOS:   update_wizard_macos.sh

# 从干净状态重装：删除 installer_files 目录后重新运行 start_ 脚本

自动化安装可预先设置环境变量：GPU_CHOICE、LAUNCH_AFTER_INSTALL、INSTALL_EXTENSIONS，示例：

GPU_CHOICE=A LAUNCH_AFTER_INSTALL=FALSE INSTALL_EXTENSIONS=TRUE ./start_linux.sh

需要在自建环境中执行命令时，用 cmd_linux.sh、cmd_windows.bat、cmd_macos.sh 进入交互式 shell。start_、update_wizard_、cmd_ 脚本都不需要管理员 / root 权限。

7.4 完整安装：手动 Conda 环境

先安装 Miniforge，然后：

conda create -n textgen python=3.13
conda activate textgen

按系统安装 PyTorch（示例版本以官方 Wiki 与 pytorch.org 最新指令为准）：

git clone https://github.com/oobabooga/textgen
cd textgen

# 按显卡选择 requirements/full/ 下对应文件：
#   NVIDIA          requirements.txt
#   AMD             requirements_amd.txt
#   CPU only        requirements_cpu_only.txt
#   Apple Intel     requirements_apple_intel.txt
#   Apple Silicon   requirements_apple_silicon.txt
pip install -r requirements/full/requirements.txt

# 启动 Web UI
python server.py

浏览器访问 http://127.0.0.1:7860。需要 nvcc 手动编译某些库时，再按 Wiki 说明安装对应版本 CUDA 工具包。官方 requirements*.txt 使用 GitHub Actions 预编译 wheel；硬件无对应 wheel 时改用 requirements_nowheels.txt 并手动安装目标加载器。

7.5 放置模型并自动加载

GGUF 单文件模型直接放入 user_data/models，界面自动识别：

textgen
└── user_data
    └── models
        └── my-model.gguf

多文件 Transformers / EXL3 模型放入 user_data/models 下的子文件夹：

textgen
└── user_data
    └── models
        └── Qwen_Qwen3-8B
            ├── config.json
            ├── generation_config.json
            ├── model-00001-of-00004.safetensors
            ├── ...
            ├── tokenizer_config.json
            └── tokenizer.json

跳过每次启动的 Model 标签，把参数写入 user_data/CMD_FLAGS.txt：

--model my-model.gguf
--cache-type q8_0

8 配置项说明

8.1 配置文件与启动参数

• user_data/settings.yaml：界面默认参数模板参考 user_data/settings-template.yaml；创建 user_data/settings.yaml 后无需 --settings 即自动加载。
• user_data/CMD_FLAGS.txt：每行一条命令行参数，等价于在 server.py 后追加；适合持久化模型名、量化类型、API 开关等常用项。
• 命令行参数分组如下，完整选项以 python server.py --help 为准。

8.2 基础与模型参数

8.3 加载器、上下文与缓存

8.4 llama.cpp 后端常用参数

8.5 Transformers / 量化参数

8.6 Gradio 界面与网络

8.7 API 参数

8.8 采样与生成默认值

Parameters 面板与 API 默认生成参数一一对应：temperature、动态温度 dynatemp-low/high/exponent、top-p、top-k、min-p、top-n-sigma、typical-p、XTC、epsilon / eta cutoff、tfs、top-a、adaptive-p、DRY、repetition-penalty、frequency-penalty、presence-penalty、encoder-repetition-penalty、no-repeat-ngram-size、mirostat-mode/tau/eta、guidance-scale、enable-thinking、reasoning-effort、preserve-thinking 等；--chat-template-file 可指定 .jinja / .jinja2 / .yaml 模板覆盖模型内置指令模板。

9 常用运维命令

# ---- 一键脚本（完整安装）----
./start_linux.sh                    # 启动
./start_linux.sh --help             # 查看可传参数
./start_linux.sh --api              # 直接传参启动并开启 API
./cmd_linux.sh                      # 进入 Conda 交互式 shell
update_wizard_linux.sh              # 更新依赖与扩展需求

# ---- venv 便携安装 ----
source venv/bin/activate
python server.py --portable --api --auto-launch
deactivate

# ---- Conda 手动安装 ----
conda activate textgen
python server.py
pip install -r requirements/full/requirements.txt --upgrade   # 更新依赖

# ---- Docker ----
docker compose up --build
docker compose logs -f

# ---- 模型与配置 ----
# user_data/models/        模型目录
# user_data/CMD_FLAGS.txt   持久化启动参数
# user_data/settings.yaml   界面默认设置
# user_data/logs/           运行日志

备份与迁移：复制整个 user_data 目录即可带走模型配置、聊天历史、LoRA、设置与日志；模型体量大时可单独备份配置与历史，模型目录重新下载。多用户场景使用 --multi-user，该模式不保存聊天历史，仅适合小型可信团队。

10 常见故障排查

10.1 启动后浏览器打不开 7860

• 确认 python server.py / 启动脚本已完成模型与依赖加载，终端未报错；首次启动需要解压模型与初始化环境。
• 局域网访问必须加 --listen，并核对 --listen-host 与 --listen-port；端口被占用时用 --listen-port 改端口。
• Docker 部署核对 Compose 端口映射与 user_data/CMD_FLAGS.txt 中的 --listen 选项。

10.2 API 连接被拒绝

• API 必须显式加 --api；确认 --api-port（默认 5000）与客户端请求地址一致。
• 需要鉴权时在客户端填入 --api-key；加载 / 卸载模型等管理请求使用 --admin-key。
• --nowebui 只启动 API；反之未加 --api 时 5000 端口不会监听。

10.3 模型在 Model 列表中看不到

• GGUF 单文件直接放进 user_data/models；多文件模型必须放进 user_data/models 下的子文件夹，且 config.json、tokenizer.json 等文件齐全。
• 启动日志核对 --model-dir 是否指向正确目录；模型文件损坏或未下载完整时重新下载。
• 多文件 Transformers / EXL3 模型在便携包中不可用，需切换到完整安装与对应后端。

10.4 显存不足（OOM）

• 换用量化等级更低的 GGUF，或减小 --ctx-size；用 --gpu-layers 控制卸载层数，必要时开启 --cpu-moe、--cpu-memory 或 --disk 把部分层放到内存 / 磁盘。
• Transformers 后端尝试 --load-in-8bit / --load-in-4bit；关闭不必要的图像模型与扩展。
• 先用官方 GGUF 显存计算器按模型与量化等级估算占用，再选择模型。

10.5 模型不输出或回答异常

• 核对 instruct / chat-instruct / chat 模式与模型类型是否匹配；必要时用 --chat-template-file 指定正确 Jinja2 模板。
• 部分模型需要 --trust-remote-code；tokenizer 异常时尝试 --no_use_fast。
• 多轮上下文过长会挤压输出空间，缩小 --ctx-size、清理历史或开启 --streaming-llm 后重试。
• 工具调用未触发时检查工具是否勾选、MCP 服务器是否配置成功，以及模型本身是否支持工具调用格式。

10.6 视觉模型无反应

确认已通过 --mmproj 指定视觉投影文件；图片格式与模型视觉能力匹配；多模态教程见 Wiki Multimodal Tutorial。

10.7 显卡 / 后端不被识别

• NVIDIA 核对驱动版本与 PyTorch CUDA 构建是否匹配；AMD 使用 ROCm 对应依赖；Apple Silicon 使用 MPS 依赖；无合适后端时退到 --cpu 或 Vulkan 构建。
• 多卡时按后端文档配置 --tensor-split、--split-mode、--gpu-split 或 ExLlamaV3 张量并行参数。

10.8 扩展功能异常或安装失败

在更新向导中选择 “Install/update extensions requirements”，向导会在末尾重装主项目依赖，确保主项目版本优先于冲突的扩展依赖；扩展兼容问题先禁用 --extensions 列表逐项排查。

10.9 更新后启动报错

先备份 user_data；删除 installer_files 目录后重新运行 start_ 脚本做干净安装；依赖升级后按所选显卡重新安装 requirements/full/ 对应文件。升级前参考 Wiki 更新说明与依赖变更提示。

10.10 工具搜索 / 页面抓取不工作

网页搜索与页面抓取工具需要对应外部服务或密钥配置，按 Wiki Tool-Calling Tutorial 设置；离线内网环境下相关工具不可用属正常现象，关闭对应工具勾选即可。

11 风险与合规说明

以下条款整理自官方 README、AGPL-3.0 许可证、Wiki 与当前 main 分支代码口径；如与官方原文不一致，以仓库 LICENSE、README 与 Wiki 为准。

11.1 AGPL-3.0 协议义务

项目采用 GNU AGPL-3.0，具有强 copyleft 与网络服务条款：修改后的版本在公网作为服务运行时，必须向访问该服务的用户提供对应完整源码。把 TextGen 二次开发后对外提供网页或 API 服务、嵌入商业产品或分发修改版前，务必通读 AGPL-3.0 全文并履行源码开放义务；扩展、工具与 LoRA 加载方式不改变核心程序的协议归属。

11.2 模型权重与第三方许可

• 项目本体不含模型权重；下载的 GGUF、Transformers、EXL3 模型分别遵循 BigCode-OpenRAIL、Llama、Mistral、Gemma、Qwen 等各自许可证，部分限定非生产用途、署名或商用授权条件。
• 后端依赖（llama.cpp、Transformers、ExLlamaV3、TensorRT-LLM、bitsandbytes、PyTorch 等）沿用其自身许可证；企业集成时逐项核对。

11.3 隐私与离线边界

• 官方承诺本体 100% 离线、零遥测、不加载外部资源、不发起远程更新；但启用网页搜索、页面抓取、远程模型 API、--public-api 公网隧道或第三方扩展后，数据会按所选工具与端点外发。
• 处理涉密代码、个人信息或未公开文档时，保持纯本地模型与本地工具，不开启公网 API 与搜索扩展；user_data 目录包含聊天历史与配置，按敏感数据加密备份。

11.4 生成内容可靠性

• 模型可能产生幻觉、错误代码、不安全建议与事实性错误；代码、配置与回答在采纳前必须人工审阅、测试与安全扫描，不要把未验证的本地模型输出直接用于生产系统。
• 工具调用结果未经模型核验；涉及网页抓取、系统命令与文件操作时优先开启 Confirm tool calls 确认机制。

11.5 商业使用与免责

TextGen 按现状（AS-IS）提供，不保证与特定硬件、模型格式、后端或操作系统组合持续兼容，也不保证输出正确性；使用者自行承担模型选型、数据泄露、服务中断、许可违约与业务损失风险。如认为仓库内特定文件侵犯合法权益，请通过 GitHub Issues 提交说明，不要在公开 Issue、模型目录截图或配置示例中提交 API 密钥、内网地址或私有对话记录。