oobabooga/textgen · 上手攻略

• 仓库：oobabooga/textgen
• 链接：https://github.com/oobabooga/textgen
• 分类：llm · local-ai · desktop-app
• 作者：Tom
• 更新：2026-08-17

这是什么

textgen（全称 oobabooga/text-generation-webui）是一个开源本地大模型桌面应用，支持文本生成、视觉理解（多模态）、工具调用、网页搜索、LoRA 微调，以及 OpenAI / Anthropic 兼容 API。口号是「100% 离线、零遥测」——不需要任何外部服务，所有模型和数据都在你自己的机器上。

它是原本大名鼎鼎的「text-generation-webui」的延续，由 oobabooga 维护，功能极为全面。最新版本（v4.x）引入了 Electron 桌面封装、MTP（Multi-Token Prediction）投机解码、多模态 mmproj 自动检测，以及 DGX Spark 支持。

解决什么问题

• 想在本地跑大模型，但不想写代码、不想搭 API 服务
• 需要多模态（视觉）能力，同时跑文本对话
• 希望用自己的 LoRA 做风格微调或指令微调
• 需要一个本地 OpenAI API 兼容端点，让现有应用（Cursor、Continue、Open Interpreter）无缝切换到本地模型
• 对隐私要求极高，数据不能离开本机

快速安装

方式一：桌面便携版（推荐新手）

直接下载解压，双击即用，无需配置。

# 1. 前往 releases 页面下载对应系统的版本
#    https://github.com/oobabooga/textgen/releases
#    选择你的 OS + 硬件加速类型（CUDA / Vulkan / ROCm / CPU）

# 2. 解压后运行
# Windows: 双击 textgen.exe
# Linux/macOS: 运行 start_linux.sh / start_macos.sh

# 3. 打开浏览器访问 http://127.0.0.1:7860

便携版包含所有依赖，无需 Python 环境。适合只想快速上手、不想折腾配置的用户。

方式二：从源码安装（支持更多后端）

需要 Python 3.9+，推荐 conda/miniforge 管理环境。

# 克隆仓库
git clone https://github.com/oobabooga/textgen
cd textgen

# 创建虚拟环境
python -m venv venv
source venv/bin/activate    # Linux/macOS
# venv\Scripts\activate     # Windows

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

# 启动（--portable 模式 + API + 自动打开浏览器）
python server.py --portable --api --auto-launch

# 访问 http://127.0.0.1:7860

方式三：Miniforge 完整安装（需要额外后端）

支持 ExLlamaV3、Transformers、TensorRT-LLM 等后端，以及 LoRA 训练功能：

# 安装 Miniforge
curl -sL "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh" > Miniforge3.sh
bash Miniforge3.sh

# 创建环境并安装 PyTorch
conda create -n textgen python=3.13
conda activate textgen

# NVIDIA GPU（示例 CUDA 12.8，建议查官方最新）
pip3 install torch==2.9.1 --index-url https://download.pytorch.org/whl/cu128

# AMD GPU（Linux）
pip3 install torch --index-url https://repo.radeon.com/rocm/manylinux/rocm/

# CPU only
pip3 install torch==2.9.1 --index-url https://download.pytorch.org/whl/cpu

# 启动脚本（选择 GPU 类型后会提示安装对应依赖）
./start_linux.sh

⚠️ 建议安装前查看官方 GPU 对照表；Python 3.13 支持情况需以实际测试为准。

模型下载

GGUF 格式模型放到 user_data/models/ 目录，UI 会自动识别：

# 示例：用 huggingface-cli 下载 Qwen3-8B GGUF
huggingface-cli download Qwen/Qwen3-8B-Q4_K_M.gguf \
  --local-dir user_data/models/Qwen3-8B-Q4_K_M

# 或手动从 https://huggingface.co/models?pipeline_tag=text-generation&sort=downloads&search=gguf 下载

多文件模型（如 Transformers 格式、EXL3）放在子目录：

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

核心用法

基础对话

1. 打开浏览器 http://127.0.0.1:7860
2. 在「Model」标签页加载模型（首次下载后会自动出现）
3. 选择模式：Instruct（指令模式，类似 ChatGPT）、Chat-instruct / Chat（角色扮演对话）
4. 直接输入对话

开启 API（OpenAI 兼容）

启动时加 --api 参数，或在 user_data/CMD_FLAGS.txt 中写入 --api：

# 启动命令加入 --api
python server.py --portable --api --listen

⚠️ --listen 会开放局域网访问，注意安全；默认仅 localhost 可访问。

API 端点示例：

# Chat 接口（OpenAI Chat Completions 兼容）
curl http://localhost:7860/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen3-8B-Q4_K_M",
    "messages": [{"role": "user", "content": "你好，解释一下量子纠缠"}]
  }'

# Completions 接口
curl http://localhost:7860/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen3-8B-Q4_K_M",
    "prompt": "量子纠缠是指"
  }'

工具调用（Tool Calling）

工具调用让模型在对话中执行函数（如网页搜索、计算、文件操作）。每个工具是一个 .py 文件，也支持 MCP 服务器：

# 示例：定义一个简单工具（保存为 user_data/tools/search.py）
"""
from typing import List

def search(query: str) -> List[str]:
    \"\"\"执行网页搜索\"\"\"
    import requests
    resp = requests.get(f"https://api.example.com/search?q={query}")
    return resp.json()["results"]
"""

# 在 UI 的参数面板中开启 "Tool calling"

LoRA 微调训练

# 1. 在 UI 的「Training」标签页准备数据集（JSONL 格式）
# 2. 配置参数：学习率、batch size、epoch 数
# 3. 点击开始训练，进度保存到 user_data/training/
# 4. 训练完成后在 Model 标签页加载：基础模型 + LoRA

# 中断后恢复训练：选择同一个输出目录即可

多模态（Vision）

1. 在聊天输入框点击「附件」图标，上传图片
2. 模型会自动识别图片内容（需要多模态模型，如 llava 系列 gguf 或带有 mmproj 的模型）
3. 可以在同一个对话中混合文本和图片

⚠️ mmproj 文件（如 mmproj-*.gguf）需要放在模型文件夹中，v4.x 会自动检测并显示在 mmproj 下拉菜单。

典型适用场景

坑与注意

1. Python 3.13 兼容性：部分依赖尚未完全适配 Python 3.13，遇到 import 错误建议降到 Python 3.11/3.12。
2. 显存估算：不同量化版本显存占用差异极大，使用 官方 VRAM Calculator 预先估算。Q4_K_M 通常 8B 模型需要 ~6 GB，Q8 需要 ~10 GB。
3. macOS GPU 支持：Apple Silicon Mac 用的是 Metal（Vulkan 兼容），不是 CUDA，需选 Vulkan 版或 CPU 版；M 系列芯片推荐先用 portable Vulkan 版测试。
4. AMD GPU on Windows：textgen 的 ROCm 支持主要面向 Linux，Windows AMD 卡兼容性问题较多，建议用 WSL2 或 Linux。
5. API 安全：默认 --api 仅监听 localhost；加 --listen 后局域网可访问，但无认证——生产环境务必配防火墙或加一层反向代理认证。
6. LoRA 训练显存：训练比推理需要更多显存，8B 模型建议 12 GB 以上显存；便携版不含训练依赖，需要完整安装。
7. mmproj 多模态文件：部分模型（如 CogVLM）的 mmproj 文件必须与主模型放同一目录，且文件名需匹配，v4.x 之前的版本需要手动选择。

与同类对比

核心差异：textgen 是这些方案中界面最丰富、功能最全的选择——同时具备训练、工具调用、多模态、MCP 支持，但相应地配置复杂度也最高。Ollama 和 LM Studio 更适合只想「下载模型、聊天」的用户；如果你需要深度定制（LoRA 训练、工具调用开发、自定义后端），textgen 更合适。

一句话结论

如果你需要一款功能最全面的本地大模型桌面工具，同时追求 OpenAI API 兼容性、LoRA 训练、工具调用和视觉理解，textgen 是开源社区最成熟的选择——但准备好花一点时间理解它的参数体系，回报是几乎无限的扩展能力。