一键安装程序

该脚本使用 Miniforge 在 installer_files 文件夹中设置 Conda 环境。

如果您需要在 installer_files 环境中手动安装某些内容，可以使用命令行脚本启动交互式 shell：cmd_linux.sh、cmd_windows.bat 或 cmd_macos.sh。

• 无需以管理员或 root 权限运行这些脚本（start_、update_wizard_ 或 cmd_）。
• 要安装扩展的依赖项，建议使用更新向导脚本中的“安装/更新扩展依赖项”选项。该脚本最后会安装项目的主要依赖项，以确保在版本冲突时优先使用这些依赖项。
• 对于自动化安装，可以使用 GPU_CHOICE、LAUNCH_AFTER_INSTALL 和 INSTALL_EXTENSIONS 环境变量。例如：GPU_CHOICE=A LAUNCH_AFTER_INSTALL=FALSE INSTALL_EXTENSIONS=TRUE ./start_linux.sh。

使用 Conda 的完整安装

0. 安装 Conda

https://github.com/conda-forge/miniforge

在 Linux 或 WSL 上，可以通过以下两条命令自动安装 Miniforge：

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

对于其他平台，请从以下链接下载：https://github.com/conda-forge/miniforge/releases/latest

1. 创建一个新的 Conda 环境

conda create -n textgen python=3.13
conda activate textgen

2. 安装 PyTorch

最新命令可在以下页面找到：https://pytorch.org/get-started/locally/。

如果您需要 nvcc 手动编译某些库，则还需额外安装：

conda install -y -c "nvidia/label/cuda-12.8.1" cuda

3. 安装 Web UI

git clone https://github.com/oobabooga/text-generation-webui
cd text-generation-webui
pip install -r requirements/full/<根据下表选择的依赖文件>

应使用的依赖文件：

启动 Web UI

conda activate textgen
cd text-generation-webui
python server.py

然后访问：

http://127.0.0.1:7860

手动安装

上述 requirements*.txt 文件包含通过 GitHub Actions 预编译的各种轮子包。如果您希望手动编译某些内容，或者因为您的硬件没有合适的轮子包而必须手动编译，可以使用 requirements_nowheels.txt，然后手动安装您所需的加载器。

替代方案：Docker

对于 NVIDIA GPU：
ln -s docker/{nvidia/Dockerfile,nvidia/docker-compose.yml,.dockerignore} .
对于 AMD GPU：
ln -s docker/{amd/Dockerfile,amd/docker-compose.yml,.dockerignore} .
对于 Intel GPU：
ln -s docker/{intel/Dockerfile,intel/docker-compose.yml,.dockerignore} .
对于仅 CPU：
ln -s docker/{cpu/Dockerfile,cpu/docker-compose.yml,.dockerignore} .
cp docker/.env.example .env
# 创建日志/缓存目录：
mkdir -p user_data/logs user_data/cache
# 编辑 .env 并设置：
#   TORCH_CUDA_ARCH_LIST 根据您的 GPU 型号
#   APP_RUNTIME_GID      您主机用户的组 ID（在终端中运行 `id -g`）
#   BUILD_EXTENIONS      可选地添加要构建的扩展列表，用逗号分隔
# 编辑 user_data/CMD_FLAGS.txt，并添加您想要执行的选项（如 --listen --cpu）
#
docker compose up --build

• 您需要安装 Docker Compose v2.17 或更高版本。有关说明，请参阅此指南。
• 如需更多 Docker 文件，请查看此仓库。

更新依赖项

requirements*.txt 文件会不时更新。要更新，请使用以下命令：

conda activate textgen
cd text-generation-webui
pip install -r <您之前使用的依赖文件> --upgrade

用法：server.py [-h] [--user-data-dir USER_DATA_DIR] [--multi-user] [--model MODEL] [--lora LORA [LORA ...]] [--model-dir MODEL_DIR] [--lora-dir LORA_DIR] [--model-menu] [--settings SETTINGS]
                 [--extensions EXTENSIONS [EXTENSIONS ...]] [--verbose] [--idle-timeout IDLE_TIMEOUT] [--image-model IMAGE_MODEL] [--image-model-dir IMAGE_MODEL_DIR] [--image-dtype {bfloat16,float16}]
                 [--image-attn-backend {flash_attention_2,sdpa}] [--image-cpu-offload] [--image-compile] [--image-quant {none,bnb-8bit,bnb-4bit,torchao-int8wo,torchao-fp4,torchao-float8wo}]
                 [--loader LOADER] [--ctx-size N] [--cache-type N] [--model-draft MODEL_DRAFT] [--draft-max DRAFT_MAX] [--gpu-layers-draft GPU_LAYERS_DRAFT] [--device-draft DEVICE_DRAFT]
                 [--ctx-size-draft CTX_SIZE_DRAFT] [--spec-type {none,ngram-mod,ngram-simple,ngram-map-k,ngram-map-k4v,ngram-cache}] [--spec-ngram-size-n SPEC_NGRAM_SIZE_N]
                 [--spec-ngram-size-m SPEC_NGRAM_SIZE_M] [--spec-ngram-min-hits SPEC_NGRAM_MIN_HITS] [--gpu-layers N] [--cpu-moe] [--mmproj MMPROJ] [--streaming-llm] [--tensor-split TENSOR_SPLIT]
                 [--row-split] [--no-mmap] [--mlock] [--no-kv-offload] [--batch-size BATCH_SIZE] [--ubatch-size UBATCH_SIZE] [--threads THREADS] [--threads-batch THREADS_BATCH] [--numa]
                 [--parallel PARALLEL] [--fit-target FIT_TARGET] [--extra-flags EXTRA_FLAGS] [--cpu] [--cpu-memory CPU_MEMORY] [--disk] [--disk-cache-dir DISK_CACHE_DIR] [--load-in-8bit] [--bf16]
                 [--no-cache] [--trust-remote-code] [--force-safetensors] [--no_use_fast] [--attn-implementation IMPLEMENTATION] [--load-in-4bit] [--use_double_quant] [--compute_dtype COMPUTE_DTYPE]
                 [--quant_type QUANT_TYPE] [--gpu-split GPU_SPLIT] [--enable-tp] [--tp-backend TP_BACKEND] [--cfg-cache] [--listen] [--listen-port LISTEN_PORT] [--listen-host LISTEN_HOST] [--share]
                 [--auto-launch] [--gradio-auth GRADIO_AUTH] [--gradio-auth-path GRADIO_AUTH_PATH] [--ssl-keyfile SSL_KEYFILE] [--ssl-certfile SSL_CERTFILE] [--subpath SUBPATH] [--old-colors]
                 [--portable] [--api] [--public-api] [--public-api-id PUBLIC_API_ID] [--api-port API_PORT] [--api-key API_KEY] [--admin-key ADMIN_KEY] [--api-enable-ipv6] [--api-disable-ipv4]
                 [--nowebui] [--temperature N] [--dynatemp-low N] [--dynatemp-high N] [--dynatemp-exponent N] [--smoothing-factor N] [--smoothing-curve N] [--min-p N] [--top-p N] [--top-k N]
                 [--typical-p N] [--xtc-threshold N] [--xtc-probability N] [--epsilon-cutoff N] [--eta-cutoff N] [--tfs N] [--top-a N] [--top-n-sigma N] [--adaptive-target N] [--adaptive-decay N]
                 [--dry-multiplier N] [--dry-allowed-length N] [--dry-base N] [--repetition-penalty N] [--frequency-penalty N] [--presence-penalty N] [--encoder-repetition-penalty N]
                 [--no-repeat-ngram-size N] [--repetition-penalty-range N] [--penalty-alpha N] [--guidance-scale N] [--mirostat-mode N] [--mirostat-tau N] [--mirostat-eta N]
                 [--do-sample | --no-do-sample] [--dynamic-temperature | --no-dynamic-temperature] [--temperature-last | --no-temperature-last] [--sampler-priority N] [--dry-sequence-breakers N]
                 [--enable-thinking | --no-enable-thinking] [--reasoning-effort N] [--chat-template-file CHAT_TEMPLATE_FILE]

文本生成 Web UI

选项：
  -h, --help                                           显示此帮助信息并退出

基本设置：
  --user-data-dir USER_DATA_DIR                        用户数据目录路径。默认：自动检测。
  --multi-user                                         多用户模式。聊天记录不会保存或自动加载。最适合小型可信团队使用。
  --model MODEL                                        默认加载的模型名称。
  --lora LORA [LORA ...]                               要加载的 LoRA 列表。如果要加载多个 LoRA，请用空格分隔名称。
  --model-dir MODEL_DIR                                包含所有模型的目录路径。
  --lora-dir LORA_DIR                                  包含所有 LoRA 的目录路径。
  --model-menu                                         在首次启动 Web UI 时，在终端中显示模型菜单。
  --settings SETTINGS                                  从该 YAML 文件加载默认界面设置。示例请参见 user_data/settings-template.yaml。如果您创建名为
                                                       user_data/settings.yaml 的文件，系统将默认加载该文件，无需使用 --settings 标志。
  --extensions EXTENSIONS [EXTENSIONS ...]             要加载的扩展列表。如果要加载多个扩展，请用空格分隔名称。
  --verbose                                            将提示信息打印到终端。
  --idle-timeout IDLE_TIMEOUT                          在不活动达到此时间（分钟）后卸载模型。再次尝试使用时会自动重新加载。

图像模型：
  --image-model IMAGE_MODEL                            启动时选择的图像模型名称（覆盖已保存的设置）。
  --image-model-dir IMAGE_MODEL_DIR                    包含所有图像模型的目录路径。
  --image-dtype {bfloat16,float16}                     图像模型的数据类型。
  --image-attn-backend {flash_attention_2,sdpa}        图像模型的注意力机制后端。
  --image-cpu-offload                                  启用图像模型的 CPU 卸载。
  --image-compile                                      编译图像模型以加快推理速度。
  --image-quant {none,bnb-8bit,bnb-4bit,torchao-int8wo,torchao-fp4,torchao-float8wo}
                                                       图像模型的量化方法。

模型加载器：
  --loader LOADER                                      手动选择模型加载器，否则将自动检测。有效选项：Transformers、llama.cpp、ExLlamav3_HF、ExLlamav3、TensorRT-
                                                       LLM。

上下文与缓存：
  --ctx-size, --n_ctx, --max_seq_len N                 上下文大小（以 token 为单位）。0 表示 llama.cpp 自动调整（需要 gpu-layers=-1），其他加载器则为 8192。
  --cache-type, --cache_type N                         KV 缓存类型；有效选项：llama.cpp - fp16、q8_0、q4_0；ExLlamaV3 - fp16、q2 至 q8（可分别指定 k_bits 和 v_bits，例如 q4_q8）。

推测解码：
  --model-draft MODEL_DRAFT                            推测解码用草稿模型的路径。
  --draft-max DRAFT_MAX                                推测解码时要草拟的标记数。
  --gpu-layers-draft GPU_LAYERS_DRAFT                  草稿模型中卸载到GPU的层数。
  --device-draft DEVICE_DRAFT                          用于卸载草稿模型的设备列表，以逗号分隔。例如：CUDA0,CUDA1
  --ctx-size-draft CTX_SIZE_DRAFT                      草稿模型的提示上下文大小。若为0，则与主模型相同。
  --spec-type {none,ngram-mod,ngram-simple,ngram-map-k,ngram-map-k4v,ngram-cache}
                                                       无草稿推测解码类型。推荐：ngram-mod。
  --spec-ngram-size-n SPEC_NGRAM_SIZE_N                ngram推测解码的n-gram查找大小。
  --spec-ngram-size-m SPEC_NGRAM_SIZE_M                ngram推测解码的草稿n-gram大小。
  --spec-ngram-min-hits SPEC_NGRAM_MIN_HITS            ngram-map推测解码所需的最小n-gram命中次数。

llama.cpp：
  --gpu-layers, --n-gpu-layers N                       卸载到GPU的层数。-1 = 自动。
  --cpu-moe                                            将专家层移动到CPU（适用于MoE模型）。
  --mmproj MMPROJ                                      视觉模型mmproj文件的路径。
  --streaming-llm                                      启用StreamingLLM，以避免在移除旧消息时重新评估整个提示。
  --tensor-split TENSOR_SPLIT                          将模型拆分到多个GPU上。以逗号分隔的比例列表。例如：60,40。
  --row-split                                          按行将模型拆分到不同GPU上。这可能会提升多GPU性能。
  --no-mmap                                            禁止使用mmap。
  --mlock                                              强制系统将模型保留在RAM中。
  --no-kv-offload                                      不将K、Q、V卸载到GPU。这可以节省显存，但会降低性能。
  --batch-size BATCH_SIZE                              调用llama-server时，最多可将多少个提示标记合并为一批。这是应用层的批处理大小。
  --ubatch-size UBATCH_SIZE                            调用llama-server时，最多可将多少个提示标记合并为一批。这是计算的最大物理批处理大小（设备级）。
  --threads THREADS                                    使用的线程数。
  --threads-batch THREADS_BATCH                        用于批处理/提示处理的线程数。
  --numa                                               为llama.cpp启用NUMA任务分配。
  --parallel PARALLEL                                  并发请求槽位的数量。上下文大小会平均分配到各个槽位。例如，若要设置4个槽位，每个槽位8192个上下文，则将ctx_size设为32768。
  --fit-target FIT_TARGET                              自动GPU层分配时，每个设备的目标显存余量，以MiB为单位的逗号分隔列表。单个值会广播到所有设备。
                                                       默认：1024。
  --extra-flags EXTRA_FLAGS                            传递给llama-server的额外参数。格式：“flag1=value1,flag2,flag3=value3”。例如：“override-tensor=exps=CPU”。

Transformers/Accelerate：
  --cpu                                                使用CPU生成文本。警告：在CPU上训练极其缓慢。
  --cpu-memory CPU_MEMORY                              最大CPU内存，单位为GiB。用于CPU卸载。
  --disk                                               如果模型体积过大，超出GPU和CPU的总容量，则将剩余层发送到磁盘。
  --disk-cache-dir DISK_CACHE_DIR                      保存磁盘缓存的目录。
  --load-in-8bit                                       使用8位精度加载模型（使用bitsandbytes）。
  --bf16                                               使用bfloat16精度加载模型。需要NVIDIA Ampere GPU。
  --no-cache                                           在生成文本时将use_cache设为False。这会略微减少显存占用，但会牺牲性能。
  --trust-remote-code                                  加载模型时将trust_remote_code设为True。对某些模型是必要的。
  --force-safetensors                                  加载模型时将use_safetensors设为True。这可以防止任意代码执行。
  --no_use_fast                                        加载分词器时将use_fast设为False（默认为True）。如果遇到与use_fast相关的问题，请使用此选项。
  --attn-implementation IMPLEMENTATION                 注意力实现方式。有效选项：sdpa、eager、flash_attention_2。

bitsandbytes 4位：
  --load-in-4bit                                       使用4位精度加载模型（使用bitsandbytes）。
  --use_double_quant                                   对4位使用双量化。
  --compute_dtype COMPUTE_DTYPE                        4位计算的数据类型。有效选项：bfloat16、float16、float32。
  --quant_type QUANT_TYPE                              4位量化类型。有效选项：nf4、fp4。

ExLlamaV3：
  --gpu-split GPU_SPLIT                                每个GPU设备用于模型层的显存（单位：GB），以逗号分隔。例如：20,7,7。
  --enable-tp, --enable_tp                             启用张量并行（TP）以将模型拆分到多个GPU上。
  --tp-backend TP_BACKEND                              张量并行的后端。有效选项：native、nccl。默认：native。
  --cfg-cache                                          为CFG负向提示创建额外缓存。使用该加载器时必须启用CFG。

Gradio：
  --listen                                             使 Web UI 可通过本地网络访问。
  --listen-port LISTEN_PORT                            服务器将使用的监听端口。
  --listen-host LISTEN_HOST                            服务器将使用的主机名。
  --share                                              创建一个公共 URL。这在 Google Colab 或类似平台上运行 Web UI 时非常有用。
  --auto-launch                                        启动时在默认浏览器中打开 Web UI。
  --gradio-auth GRADIO_AUTH                            设置 Gradio 身份验证密码，格式为“用户名:密码”。也可以使用“u1:p1,u2:p2,u3:p3”格式提供多个凭据。
  --gradio-auth-path GRADIO_AUTH_PATH                  设置 Gradio 身份验证文件路径。该文件应包含一个或多个用户:密码对，格式与上述相同。
  --ssl-keyfile SSL_KEYFILE                            SSL 证书密钥文件的路径。
  --ssl-certfile SSL_CERTFILE                          SSL 证书证书文件的路径。
  --subpath SUBPATH                                    自定义 Gradio 的子路径，用于反向代理。
  --old-colors                                         使用 2024 年 12 月更新之前的旧版 Gradio 颜色。
  --portable                                           隐藏便携模式下不可用的功能，例如训练。

API：
  --api                                                启用 API 扩展。
  --public-api                                         使用 Cloudflare 为 API 创建公共 URL。
  --public-api-id PUBLIC_API_ID                        命名式 Cloudflare 隧道的隧道 ID。需与 public-api 选项一起使用。
  --api-port API_PORT                                  API 的监听端口。
  --api-key API_KEY                                    API 身份验证密钥。
  --admin-key ADMIN_KEY                                用于加载和卸载模型等管理任务的 API 身份验证密钥。若未设置，则与 --api-key 相同。
  --api-enable-ipv6                                    为 API 启用 IPv6。
  --api-disable-ipv4                                   禁用 API 的 IPv4。
  --nowebui                                            不启动 Gradio UI。适用于以独立模式启动 API。

API 生成默认参数：
  --temperature N                                      温度
  --dynatemp-low N                                     动态温度下限
  --dynatemp-high N                                    动态温度上限
  --dynatemp-exponent N                                动态温度指数
  --smoothing-factor N                                 平滑因子
  --smoothing-curve N                                  平滑曲线
  --min-p N                                            Min P
  --top-p N                                            Top P
  --top-k N                                            Top K
  --typical-p N                                        Typical P
  --xtc-threshold N                                    XTC 阈值
  --xtc-probability N                                  XTC 概率
  --epsilon-cutoff N                                   Epsilon 截断
  --eta-cutoff N                                       Eta 截断
  --tfs N                                              TFS
  --top-a N                                            Top A
  --top-n-sigma N                                      Top N Sigma
  --adaptive-target N                                  自适应目标
  --adaptive-decay N                                   自适应衰减
  --dry-multiplier N                                   DRY 乘数
  --dry-allowed-length N                               DRY 允许长度
  --dry-base N                                         DRY 基础
  --repetition-penalty N                               重复惩罚
  --frequency-penalty N                                频率惩罚
  --presence-penalty N                                 存在惩罚
  --encoder-repetition-penalty N                       编码器重复惩罚
  --no-repeat-ngram-size N                             不重复 n-gram 大小
  --repetition-penalty-range N                         重复惩罚范围
  --penalty-alpha N                                    惩罚 alpha
  --guidance-scale N                                   引导尺度
  --mirostat-mode N                                    米罗斯特模式
  --mirostat-tau N                                     米罗斯特 tau
  --mirostat-eta N                                     米罗斯特 eta
  --do-sample, --no-do-sample                          是否采样
  --dynamic-temperature, --no-dynamic-temperature      是否启用动态温度
  --temperature-last, --no-temperature-last            是否使用最后的温度
  --sampler-priority N                                 采样器优先级
  --dry-sequence-breakers N                            DRY 序列中断符
  --enable-thinking, --no-enable-thinking              是否启用思考
  --reasoning-effort N                                 思考力度
  --chat-template-file CHAT_TEMPLATE_FILE              用于作为 API 请求默认指令模板的聊天模板文件路径（.jinja、.jinja2 或 .yaml）。会覆盖模型自带的模板。

由多个文件组成的模型（如 16 位 Transformers 模型和 EXL3 模型）应放置在 user_data/models 文件夹内的子文件夹中：

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

这些格式需要使用一键安装程序（而非便携版）。