Text Generation WebUI 完整指南：从本地部署到角色定制-创锋一号

Text Generation WebUI 完整指南：从本地部署到角色定制

【免费下载链接】textgenOpen-source desktop app for local LLMs. Text, vision, tool-calling, OpenAI/Anthropic-compatible API. 100% private.项目地址: https://gitcode.com/GitHub_Trending/te/textgen

Text Generation WebUI（TextGen）是一个开源免费的本地大模型界面：模型离线跑在 GGUF 等格式上，支持多轮对话、视觉理解、工具调用，并提供 OpenAI 兼容 API。以下内容全部来自仓库实际文件，照做即可复现。

它是什么，能帮你做什么

🏠数据不出本机：推理完全在本地运行，100% 离线、零遥测，界面同时提供 Web UI 和 API 两种入口，不需要任何账号。
💬多种对话形态：Chat 页签支持 instruct / chat-instruct / chat 三种模式，Notebook 页签可自由生成文本，消息可附带图片，也能上传文本、PDF、.docx 文件让模型解读。
🔌后端与量化自由：支持 llama.cpp、ik_llama.cpp、Transformers、ExLlamaV3、TensorRT-LLM 五类后端，兼容 GGUF 量化模型，切换模型和后端无需重启。
🧩对开发者开放：OpenAI/Anthropic 兼容 API（含 tool-calling）、内置 LoRA 训练与图像生成页签，插件机制可扩展 TTS、语音输入等功能。

十分钟跑起来：三种系统各一条命令

第一步：克隆代码（三平台通用）

git clone https://gitcode.com/GitHub_Trending/te/text-generation-webui cd text-generation-webui

做完后你应该看到：目录下有server.py、start_linux.sh、start_windows.bat、start_macos.sh以及user_data/等文件。

第二步：运行一键安装脚本

脚本会自动下载 Miniforge，在installer_files/里建好隔离的 Python 环境，全程不用手动配依赖；安装过程中会提示你选择 GPU 厂商。注意：仓库所在路径不要包含空格。

Linux：

./start_linux.sh

Windows（双击或在终端中运行均可）：

start_windows.bat

macOS：

./start_macos.sh

做完后你应该看到：打开浏览器访问http://127.0.0.1:7860，页面顶部出现 Chat、Default、Notebook、Parameters、Model、Training、Session 的页签栏，即安装成功。

如果你机器上已有 Python 3.9+，也可以跳过一键脚本，走 README 里的 venv 便携路线：

python -m venv venv # macOS/Linux: source venv/bin/activate Windows: venv\Scripts\activate pip install -r requirements/portable/requirements.txt python server.py --portable --api --auto-launch

第三步：放入模型并验证

从模型站下载一个 GGUF 格式的量化模型文件，放进user_data/models/目录即可，UI 会自动检测。

做完后你应该看到：Model 页签的模型列表中出现该模型，点击加载后就能在 Chat 页签开始对话。

日常使用三条小抄：

再次启动：直接重跑同一个start_脚本即可。
固定启动参数：把 flag 写进 user_data/CMD_FLAGS.txt（例如--api），不必每次手输。
更新项目：运行对应系统的update_wizard_脚本。

核心功能怎么用：从多轮对话到工具调用

场景：日常问答与角色对话

场景：既想让模型按指令干活，又想像 ChatGPT 那样和一个自定义角色聊天。
操作：在 Chat 页签的侧边栏选择 Mode——instruct适合指令模型；chat/chat-instruct适合自定义角色，提示词会由 Jinja2 模板自动格式化，不需要手写格式。
效果：每段对话自动存入 Past chats，可以分支（Branch）、重命名、删除、搜索；历史消息可编辑回退。详细按钮说明见 docs/01 - Chat Tab.md。

场景：给模型看图片、读文档

场景：想问图片里的内容，或者讨论一份 PDF/Word 文档。
操作：在消息里直接附带图片做视觉理解；或上传文本文件、PDF、.docx。
效果：模型基于附件内容作答，例如解释图表、总结文档要点。用法见 docs/Multimodal Tutorial.md。

场景：让模型自己用工具

场景：希望模型回答前先联网查资料、算数或掷骰子。
操作：每个工具就是一个.py文件，放进 user_data/tools/ 目录，仓库自带calculate.py、web_search.py、roll_dice.py等示例；也支持 MCP 服务器。
效果：聊天过程中模型按需调用这些函数，例如先搜索网页再组织答案。教程见 docs/Tool Calling Tutorial.md。

进阶玩法与个性化定制

量化怎么选

最省事的路线是 GGUF 量化模型：放进user_data/models/就能被便携版直接运行。要用全精度 Transformers、EXL3 等格式，则需要完整安装，requirements/full/ 目录按硬件提供了对应依赖文件：requirements.txt（NVIDIA）、requirements_amd.txt（AMD）、requirements_cpu_only.txt、requirements_apple_intel.txt、requirements_apple_silicon.txt。更多--gpu-layers、--ctx-size等 flag 说明见 README.md 的 Command-line flags 一节。

LoRA 微调：让模型学会你的数据

在 Training 页签选择基座模型和数据集（多轮对话或纯文本均可），即可训练一个 LoRA，中断的训任务还能断点续训。数据集放在 user_data/training/datasets/（仓库自带example_messages.json等示例），训练逻辑在 modules/training.py，操作细节见 docs/05 - Training Tab.md。

角色定制：用 YAML 写一个人物

user_data/characters/ 目录下每个 YAML 文件就是一个角色，包含名字、开场白（greeting）、背景上下文（context）与性格描述；Example.yaml是开箱即用的样例，Assistant.yaml是默认助手。在 Chat 页签把 Mode 切到chat或chat-instruct，即可与该角色对话。

用参数预设切换生成风格

user_data/presets/ 内置三个预设：Creative.yaml（偏创意）、Deterministic.yaml（偏确定）、Top-P.yaml，在 Parameters 页签加载即可，你也可以把自己的温度、top-p 等组合另存为 YAML。说明见 docs/03 - Parameters Tab.md。

扩展插件：TTS、语音输入、知识库

extensions/ 目录自带多个插件：silero_tts/coqui_tts做文本转语音、whisper_stt做语音输入、google_translate做翻译、superboogav2基于本地知识库问答、gallery展示生成的图片、ngrok用于临时共享。自研插件放进 user_data/extensions/，依赖可用更新向导里的 "Install/update extensions requirements" 选项安装。说明见 docs/07 - Extensions.md。

对外暴露 OpenAI 兼容 API

在 user_data/CMD_FLAGS.txt 中写入--api即可启用，提供 Chat、Completions、Messages 三类端点且支持 tool-calling，可以当 OpenAI/Anthropic API 的本地替代使用。实现代码在 modules/api/，调用示例见 docs/12 - OpenAI API.md。

下一步

想深入使用，建议按页签顺序阅读 docs/ 目录下的文档；选模型前先查 docs/What Works.md 里的已知可用组合。遇到无法解决的 bug，先检索项目 issues，没有现成答案再新建一个 issue 描述你的系统和报错。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析