text-generation-inference 启动器完全指南：text-generation-launcher 全部参数详解与源码级解析-创锋一号

text-generation-inference 启动器完全指南：text-generation-launcher 全部参数详解与源码级解析

【免费下载链接】text-generation-inferenceLarge Language Model Text Generation Inference项目地址: https://gitcode.com/GitHub_Trending/te/text-generation-inference

本文是 Hugging Face text-generation-inference（TGI）项目中text-generation-launcher启动器的参数权威参考。TGI 部署的核心入口就是text-generation-launcher可执行程序，它负责模型下载、跨 GPU 分片（sharding）、量化、批处理策略、HTTP 服务与可观测性配置等全部部署层面的工作。读完本文，你将掌握启动器的每一个命令行参数、同名环境变量、默认值与取值约束，并能结合源码理解这些参数如何影响推理性能、显存预算与请求调度，从而为你的生产环境做出正确的部署调优决策。

启动器在 TGI 架构中的角色

在深入参数之前，先明确text-generation-launcher在 TGI 整体架构中的位置。从 launcher/src/main.rs 的main函数（第 2038 行起）可以看到，启动器是一个进程编排器，其核心职责依次是：

解析配置：通过 clap 框架解析命令行参数与环境变量（Args::parse()，launcher/src/main.rs）；
读取模型配置：从本地目录或 Hugging Face Hub 读取config.json，用于推断量化方法、head 维度、显存占用等（get_config，launcher/src/main.rs）；
决定注意力实现：根据模型类型与硬件计算能力自动选择flashinfer/paged/flashdecoding注意力后端，并决定是否启用 prefix caching（resolve_attention，launcher/src/main.rs）；
下载并转换权重：调用text-generation-server download-weights子命令（download_convert_model，launcher/src/main.rs）；
启动分片进程：为每个 GPU shard 启动一个text-generation-server serve进程，并通过 Unix Domain Socket（UDS）与它们通信（shard_manager/spawn_shards，launcher/src/main.rs）；
启动 Web 服务器：最后拉起text-generation-router进程对外提供 HTTP/gRPC 服务（spawn_webserver，launcher/src/main.rs）。

因此，所有部署相关的旋钮都集中在启动器这一层，本文档列出的每一个参数都对应 launcher/src/main.rs 中Args结构体的一个字段。

参数通用约定

所有参数既可作为 CLI 参数传入，也可通过同名环境变量设置（源码中每个字段都标注了env，例如MODEL_ID对应--model-id）；
环境变量的优先级与 CLI 参数相同（clap 的env特性），实际部署中（尤其是 Docker 场景）常用环境变量方式注入；
每个参数都有明确默认值或为可选项，未显式配置时按默认值生效。

一、模型加载参数

MODEL_ID

--model-id <MODEL_ID>

指定要加载的模型。可以是在 hf.co/models 上列出的模型 ID（如gpt2、OpenAssistant/oasst-sft-1-pythia-12b），也可以是包含 transformerssave_pretrained(...)所保存文件的本地目录。

环境变量：MODEL_ID
默认值：bigscience/bloom-560m

从源码看（launcher/src/main.rs），get_config会先检查model_id是否为本地已存在的路径；若不是，则假定为 Hub ID，通过hf-hub的ApiBuilder下载config.json，并支持通过HF_TOKEN环境变量携带访问令牌（加载 gated 模型时必需）。

REVISION

--revision <REVISION>

当引用 Hub 上的模型时指定实际 revision，可以使用具体的 commit id 或分支名（如refs/pr/2）。

环境变量：REVISION

源码中该值同时被用于下载权重（launcher/src/main.rs）、启动 shard（第 1011-1014 行）与启动 router（第 1916-1919 行），保证三个进程加载的是同一版本的模型文件。

TRUST_REMOTE_CODE

--trust-remote-code

是否允许执行 Hub 上的建模代码。当模型带有自定义 modeling 代码时需要开启。官方强烈建议：加载带自定义代码的模型时显式指定revision，以确保不会运行到新提交中可能混入的恶意代码。

环境变量：TRUST_REMOTE_CODE
默认值：false

TOKENIZER_CONFIG_PATH

--tokenizer-config-path <TOKENIZER_CONFIG_PATH>

指定 tokenizer 配置文件的路径，用于加载可能包含chat_template的 tokenizer 配置。未提供时使用模型 Hub 上的默认配置。

环境变量：TOKENIZER_CONFIG_PATH

该参数会透传给 router（launcher/src/main.rs），用于对话模板的渲染与请求校验。

HUGGINGFACE_HUB_CACHE 与 WEIGHTS_CACHE_OVERRIDE

--huggingface-hub-cache <HUGGINGFACE_HUB_CACHE> --weights-cache-override <WEIGHTS_CACHE_OVERRIDE>

两者均用于覆盖 Hugging Face Hub 缓存位置，典型场景是把缓存放到挂载的独立磁盘上。源码注释说明weights_cache_override主要用于 HuggingFace Inference Endpoint 场景（launcher/src/main.rs），会以WEIGHTS_CACHE_OVERRIDE环境变量形式传给下载与 shard 进程。

环境变量：HUGGINGFACE_HUB_CACHE、WEIGHTS_CACHE_OVERRIDE

二、并行与分片参数（Tensor Parallelism）

SHARDED

--sharded <SHARDED>

是否将模型分片到多张 GPU 上运行。默认情况下 TGI 会使用机器上所有可用 GPU；设置为false会取消num_shard的作用。

环境变量：SHARDED
可选值：true、false
默认值：未设置时根据 GPU 数量推断

NUM_SHARD

--num-shard <NUM_SHARD>

如果不想使用机器上全部 GPU，可指定分片数量。官方示例：在一台 4 卡机器上，可以用如下命令启动两个各占 2 卡的实例：

CUDA_VISIBLE_DEVICES=0,1 text-generation-launcher ... --num_shard 2 CUDA_VISIBLE_DEVICES=2,3 text-generation-launcher ... --num_shard 2

环境变量：NUM_SHARD

从源码find_num_shards（launcher/src/main.rs）可以看到完整的解析逻辑：

`--sharded`	`--num-shard`	行为
`true`	未设置	从`CUDA_VISIBLE_DEVICES`/`NVIDIA_VISIBLE_DEVICES`/`ZE_AFFINITY_MASK`推断 GPU 数量；少于 2 卡时报错
`true`	设置了	使用指定数量，但`num_shard <= 1`会报错
`false`	设置了	使用指定数量（不强制要求 > 1）
`false`	未设置	1
未设置	未设置	GPU 数量（无 GPU 时为 1）
未设置	设置了	指定数量

此外，源码还在main中做了约束：exl2量化不支持分片（num_shard > 1时直接报错，launcher/src/main.rs）。

SHARD_UDS_PATH

--shard-uds-path <SHARD_UDS_PATH>

Web 服务器与各 shard 之间 gRPC 通信使用的 Unix Domain Socket 名称。每个 shard 会在该路径后追加-{rank}后缀（launcher/src/main.rs），router 连接的是 rank 0 的 socket（{path}-0，第 1868-1869 行）。

环境变量：SHARD_UDS_PATH
默认值：/tmp/text-generation-server

MASTER_ADDR 与 MASTER_PORT

--master-addr <MASTER_ADDR> --master-port <MASTER_PORT>

torch distributed 使用的 master 地址与端口，用于分片进程间的集合通信（NCCL）。源码中会以RANK、WORLD_SIZE、MASTER_ADDR、MASTER_PORT环境变量注入每个 shard 进程，并额外设置TORCH_NCCL_AVOID_RECORD_STREAMS=1（launcher/src/main.rs）。

环境变量：MASTER_ADDR、MASTER_PORT
默认值：localhost、29500

三、量化参数

QUANTIZE

--quantize <QUANTIZE>

指定模型的量化方法。对于预量化模型无需指定——量化方法会从模型配置中自动读取（源码中Config::quantize由quantization_config.quant_method解析而来，launcher/src/main.rs）。对于 GPTQ/AWQ 模型会自动使用 Marlin 内核。

完整取值如下（与 launcher/src/main.rs 的Quantization枚举一一对应）：

取值	说明
`awq`	4 bit 量化。需要特定的 AWQ 量化模型（hf.co/models?search=awq）。延迟表现优于 GPTQ，应尽可能替代 GPTQ 使用
`compressed-tensors`	Compressed tensors，可以是多种量化方法的混合
`eetq`	8 bit 量化，不需要特定模型。可作为 bitsandbytes 的即插即用替代品，性能显著更好（内核来自 EETQ 项目）
`exl2`	可变 bit 量化。需要特定 EXL2 量化模型。需要 exllama2 内核，不支持张量并行（`num_shard > 1`）
`gptq`	4 bit 量化。需要特定 GPTQ 量化模型。TGI 会优先使用 exllama（更快）内核，不支持时回退到 triton 内核（覆盖更广）。AWQ 内核更快
`marlin`	4 bit 量化。需要特定的 Marlin 量化模型
`bitsandbytes`	Bitsandbytes 8bit。可应用于任意模型，显存需求减半，但运行速度明显慢于原生 f16（源码中已标注 deprecated，建议改用`eetq`，launcher/src/main.rs）
`bitsandbytes-nf4`	Bitsandbytes 4bit。可应用于任意模型，显存需求降至 1/4，但速度明显慢于原生 f16
`bitsandbytes-fp4`	Bitsandbytes 4bit。多数场景优先使用 nf4，但 fp4 可能对某些模型有更好的困惑度表现
`fp8`	FP8（e4m3）量化，适用于 H100 及以上。该 dtype 有原生算子，应是最快的选择；但目前由于本地解包与矩阵乘法限制的 padding，尚未达到最快

环境变量：QUANTIZE

重要约束：--quantize不能与--dtype同时使用（见下文）。

DTYPE

--dtype <DTYPE>

强制指定模型权重 dtype。

环境变量：DTYPE
可选值：float16、bfloat16
不能与--quantize同时使用

源码中Dtype枚举定义了float16与bfloat16两个值（launcher/src/main.rs）。

KV_CACHE_DTYPE

--kv-cache-dtype <KV_CACHE_DTYPE>

指定 KV 缓存的 dtype。未指定时使用模型的 dtype（通常是float16或bfloat16）。目前仅 CUDA 上支持fp8_e4m3fn和fp8_e5m2。

环境变量：KV_CACHE_DTYPE
可选值：fp8_e4m3fn、fp8_e5m2

CUDA_MEMORY_FRACTION

--cuda-memory-fraction <CUDA_MEMORY_FRACTION>

限制 CUDA 可用显存比例，实际可用显存 = 总可见显存 ×cuda-memory-fraction。

环境变量：CUDA_MEMORY_FRACTION
默认值：1.0

该值会以同名环境变量传给 shard 进程（launcher/src/main.rs），同时也参与启动器侧自动计算max_batch_prefill_tokens时的显存预算估算（vram_maximum，launcher/src/main.rs）。显存计算还受TGI_WIGGLE_ROOM环境变量影响（默认 0.95，作为安全余量系数，见 launcher/src/main.rs）。

四、投机解码参数

SPECULATE

--speculate <SPECULATE>

投机解码（speculative decoding）时要预测的input_ids数量。若使用 Medusa 模型，heads 会被自动识别；否则使用 n-gram 投机，该方法计算开销相对较小，但加速效果高度依赖任务类型。

环境变量：SPECULATE

五、序列长度与显存预算参数

这一组参数直接决定请求能占用的显存与批处理效率，是部署调优的核心。

MAX_INPUT_TOKENS

--max-input-tokens <MAX_INPUT_TOKENS>

用户允许发送的最大输入长度（以 token 数计）。值越大，可接受的 prompt 越长，但会直接影响处理负载所需的整体显存。注意部分模型对序列长度有上限。默认值为min(max_allocatable, max_position_embeddings) - 1。

环境变量：MAX_INPUT_TOKENS

MAX_INPUT_LENGTH

--max-input-length <MAX_INPUT_LENGTH>

max_input_tokens的旧版名称，仅为了命名一致性而保留。源码中两者不能同时设置，否则报错并提示只使用max_input_tokens（launcher/src/main.rs）。

环境变量：MAX_INPUT_LENGTH

MAX_TOTAL_TOKENS

--max-total-tokens <MAX_TOTAL_TOKENS>

最重要的参数之一，它定义了运行客户端请求的"显存预算"。客户端发送输入序列并在其上请求生成max_new_tokens。例如设为1512时，用户既可以发送 1000 token 的 prompt 并请求生成 512 个新 token，也可以发送 1 token 的 prompt 并请求 1511 个新 token。该值越大，每个请求占用的显存越多、批处理的有效性越低。默认值为min(max_allocatable, max_position_embeddings)。

环境变量：MAX_TOTAL_TOKENS

MAX_BATCH_TOTAL_TOKENS

--max-batch-total-tokens <MAX_BATCH_TOTAL_TOKENS>

官方标注 IMPORTANT：这是让硬件利用率最大化的关键控制项之一。

它代表一个 batch 内的潜在 token 总量。在使用 padding（不推荐）时，它等价于batch_size × max_total_tokens；而在非 padding（flash attention）版本中可以精细得多。例如max_batch_total_tokens=1000时，可以容纳 10 个total_tokens=100的请求，或 1 个 1000 token 的请求。

总体而言，该值应设置为（模型加载后）剩余显存能容纳的最大值。由于实际显存开销取决于量化方式、flash attention、模型实现等参数，未提供时 TGI 会自动推断该值，确保尽可能大。

环境变量：MAX_BATCH_TOTAL_TOKENS

源码中还做了交叉校验：max_total_tokens必须<= max_batch_total_tokens，否则直接报错（launcher/src/main.rs）。

MAX_BATCH_PREFILL_TOKENS

--max-batch-prefill-tokens <MAX_BATCH_PREFILL_TOKENS>

限制 prefill 操作的最大 token 数。prefill 是显存占用最大且计算密集的操作，限制它可以控制同时进入 prefill 的请求规模。默认值为max_input_tokens + 50（留一点余量）。

环境变量：MAX_BATCH_PREFILL_TOKENS

如果未提供，源码会自动计算默认值（launcher/src/main.rs）：基于 GPU 的 f16 算力与模型总计算量估算compute_optimal（默认 4096，qwen2_vl/qwen2_5_vl 为 10000，gemma3 为 8000），再取min(默认值, max_position_embeddings)，并与基于显存预算估算的vram_maximum取较小值；若显存不足还会打印告警提示降低 prefill 上限。

MAX_BATCH_SIZE

--max-batch-size <MAX_BATCH_SIZE>

强制限制每个 batch 的最大请求数。这是针对不支持非 padding 推理的硬件目标的特殊参数（例如某些后端）。

环境变量：MAX_BATCH_SIZE

六、动态批处理与并发控制参数

WAITING_SERVED_RATIO

--waiting-served-ratio <WAITING_SERVED_RATIO>

等待中的请求数与运行中请求数的比值，用于决定何时考虑暂停当前运行批次、把等待请求并入同一 batch。例如waiting_served_ratio=1.2表示：当 12 个请求在等待、而当前批次只剩 10 个请求在运行（12/10 > 1.2）时，检查能否将这 12 个等待请求塞入批处理策略；如果可以，则执行 batching——用一次 prefill 运行来延迟当前 10 个运行中的请求。

该设置仅在 batch 内还有空间（由max_batch_total_tokens定义）时生效。

环境变量：WAITING_SERVED_RATIO
默认值：0.3

MAX_WAITING_TOKENS

--max-waiting-tokens <MAX_WAITING_TOKENS>

定义在强制将等待请求放入 batch 之前最多能"放行"多少 token（前提是 batch 容量允许）。新请求需要 1 次 prefill 前向，这与 decode 不同，因此必须暂停当前运行批次以执行 prefill，才能为等待请求生成正确的 KV 状态以加入批次。

调参要诀：

值过小：请求会频繁"抢占"计算资源执行 prefill，导致运行中的请求被严重延迟；
值过大：等待请求可能等待过久才获得批次槽位。服务繁忙时，原本空载 2 秒就能跑完的请求可能因为等待 18 秒而最终耗时 20 秒。

该值以 token 数表示，使其更具"模型无关性"；但最终应关注的是端到端延迟。

环境变量：MAX_WAITING_TOKENS
默认值：20

MAX_CONCURRENT_REQUESTS

--max-concurrent-requests <MAX_CONCURRENT_REQUESTS>

部署实例允许的最大并发请求数。设低可以让客户端请求被拒绝而不是长时间等待，通常有利于正确的背压（backpressure）处理。

环境变量：MAX_CONCURRENT_REQUESTS
默认值：128

MAX_CLIENT_BATCH_SIZE

--max-client-batch-size <MAX_CLIENT_BATCH_SIZE>

控制单个客户端请求中最多能携带的输入数量。

环境变量：MAX_CLIENT_BATCH_SIZE
默认值：4

VALIDATION_WORKERS

--validation-workers <VALIDATION_WORKERS>

router 内用于 payload 校验与截断的 tokenizer worker 进程数。源码要求必须大于 0（validation_workers == 0直接报错，launcher/src/main.rs）。

环境变量：VALIDATION_WORKERS
默认值：2

七、客户端能力上限参数

这类参数定义了客户端在单个请求中可使用的"高级能力"上限。

MAX_BEST_OF

--max-best-of <MAX_BEST_OF>

客户端可设置best_of的最大允许值。best_of会同时做n次生成，并返回整段生成序列整体对数概率最优的那一个。

环境变量：MAX_BEST_OF
默认值：2

MAX_STOP_SEQUENCES

--max-stop-sequences <MAX_STOP_SEQUENCES>

客户端可设置stop_sequences的最大允许值。stop sequences 让模型不只依赖 EOS token 停止，还支持更复杂的"提示工程"——用户可以按特定方式预置 prompt 并定义与 prompt 对齐的"自定义"停止 token。

环境变量：MAX_STOP_SEQUENCES
默认值：4

MAX_TOP_N_TOKENS

--max-top-n-tokens <MAX_TOP_N_TOKENS>

客户端可设置top_n_tokens的最大允许值。top_n_tokens用于在每个生成步返回最可能的n个 token 的信息（而不只是采样得到的 token），这些信息可用于分类、排序等下游任务。

环境变量：MAX_TOP_N_TOKENS
默认值：5

PAYLOAD_LIMIT

--payload-limit <PAYLOAD_LIMIT>

请求 payload 的大小上限（字节）。

环境变量：PAYLOAD_LIMIT
默认值：2000000（2MB）

ENABLE_PREFILL_LOGPROBS

--enable-prefill-logprobs

启用 prefill logprobs。prompt 的 logprobs 默认关闭，因为它们会消耗大量显存（尤其是长 prompt）。开启该标志后，用户才被允许请求 prompt 的 logprobs。

环境变量：ENABLE_PREFILL_LOGPROBS
默认值：false

源码中该标志会以REQUEST_LOGPROBS=1环境变量传给 shard 进程（launcher/src/main.rs）。

八、内核与精度调优参数

CUDA_GRAPHS

--cuda-graphs <CUDA_GRAPHS>

指定要为哪些 batch size 预计算 CUDA graphs。设为"0"可禁用。

环境变量：CUDA_GRAPHS
默认值：1,2,4,8,16,32

源码中 CUDA graphs 的启用逻辑（launcher/src/main.rs）：

显式指定时使用指定值（自动过滤掉 0）；
未指定且使用bitsandbytes或exl2量化时自动禁用（两者与 CUDA graphs 不兼容）；
其余情况使用默认的[1, 2, 4, 8, 16, 32]。

DISABLE_CUSTOM_KERNELS

--disable-custom-kernels

TGI 为部分模型（如 bloom）实现了自定义 CUDA 内核以加速推理，但这些内核只在 A100 上测试过。如果运行在其他硬件上遇到问题，可用此标志禁用。

环境变量：DISABLE_CUSTOM_KERNELS
默认值：false

ROPE_SCALING 与 ROPE_FACTOR

--rope-scaling <ROPE_SCALING> --rope-factor <ROPE_FACTOR>

仅对 RoPE 模型生效，用于重新缩放位置旋转编码以容纳更长的 prompt。两者配合使用：

--rope-factor 2.0：因子 2.0 的线性缩放；
--rope-scaling dynamic：因子 1.0 的动态缩放；
--rope-scaling linear：因子 1.0 的线性缩放（基本不改变任何东西）；
--rope-scaling linear --rope-factor X：完整描述你想要的缩放方式。
环境变量：ROPE_SCALING、ROPE_FACTOR
ROPE_SCALING可选值：linear、dynamic

源码中若只提供rope_factor而未提供rope_scaling，会自动按linear处理（launcher/src/main.rs），并以环境变量ROPE_SCALING/ROPE_FACTOR形式传给 shard（第 1080-1083 行）。

九、网络与服务参数

HOSTNAME 与 PORT

--hostname <HOSTNAME> -p, --port <PORT>

HTTP 服务监听的 IP 地址与端口。

环境变量：HOSTNAME、PORT
默认值：0.0.0.0、3000

PROMETHEUS_PORT

-p, --prometheus-port <PROMETHEUS_PORT>

Prometheus 指标端口。TGI 会在此端口暴露监控指标（可配合 assets/tgi_grafana.json 的 Grafana 面板使用）。

环境变量：PROMETHEUS_PORT
默认值：9000

CORS_ALLOW_ORIGIN

--cors-allow-origin <CORS_ALLOW_ORIGIN>

允许的 CORS 来源，可指定多个（源码中为Vec<String>，launcher/src/main.rs）。

环境变量：CORS_ALLOW_ORIGIN

API_KEY

--api-key <API_KEY>

为服务设置 API 密钥（用于鉴权）。

环境变量：API_KEY

NGROK、NGROK_AUTHTOKEN、NGROK_EDGE

--ngrok --ngrok-authtoken <NGROK_AUTHTOKEN> --ngrok-edge <NGROK_EDGE>

启用 ngrok 隧道（便于本地服务对外暴露）。启用--ngrok时，ngrok-authtoken与ngrok-edge都必须设置，否则启动报错（launcher/src/main.rs）。router 的 Cargo 特性中ngrok默认开启（router/Cargo.toml）。

环境变量：NGROK、NGROK_AUTHTOKEN、NGROK_EDGE

十、可观测性与日志参数

JSON_OUTPUT

--json-output

以 JSON 格式输出日志（适合遥测采集）。

环境变量：JSON_OUTPUT
默认值：false

源码中该标志同时作用于启动器自身日志（tracing_subscriber的 json 格式，launcher/src/main.rs）与 router 进程（第 1925-1927 行），并且 shard 进程总是以 JSON 日志启动（第 977 行），由启动器统一解析后按日志级别转发（log_lines/PythonLogMessage，第 1344-1372 行）。

OTLP_ENDPOINT 与 OTLP_SERVICE_NAME

--otlp-endpoint <OTLP_ENDPOINT> --otlp-service-name <OTLP_SERVICE_NAME>

OpenTelemetry（OTLP）上报端点与服务名，用于分布式追踪与指标采集。

环境变量：OTLP_ENDPOINT、OTLP_SERVICE_NAME
OTLP_SERVICE_NAME默认值：text-generation-inference.router

两者会同时透传给 shard 与 router 进程（launcher/src/main.rs、第 1930-1938 行）。

ENV

-e, --env

打印大量关于运行时环境的信息（GPU、驱动、系统环境等）。从源码看，它调用env_runtime::Env::new()并以日志形式输出（launcher/src/main.rs），运行时信息还包括nvidia-smi的详细查询结果（参见 router/src/usage_stats.rs 中定义的信息结构）。

USAGE_STATS

--usage-stats <USAGE_STATS>

控制是否收集匿名使用统计。三个取值：

on：默认选项，匿名收集使用统计；
off：关闭所有统计收集；
no-stack：不发送错误堆栈与错误类型，但仍允许发送崩溃事件。
环境变量：USAGE_STATS
默认值：on

该值会传给 router（launcher/src/main.rs），router 中对应UsageStatsLevel枚举与上报实现（router/src/usage_stats.rs）。

十一、扩展功能参数

LORA_ADAPTERS

--lora-adapters <LORA_ADAPTERS>

LoRA adapter 列表（如repo/adapter1,repo/adapter2），在启动时加载，调用方可通过请求中的adapter_id字段使用。源码支持adapter_id=path@revision的增强格式，并在启动时逐一下载每个 adapter（launcher/src/main.rs）；若 adapter id 中出现多个@会报格式错误。adapter 会以LORA_ADAPTERS环境变量传给 shard（第 1096-1098 行）。

环境变量：LORA_ADAPTERS

DISABLE_GRAMMAR_SUPPORT

--disable-grammar-support

禁用 outlines 语法约束生成（grammar constrained generation），该功能允许按特定语法生成文本（如 JSON Schema 约束）。

环境变量：DISABLE_GRAMMAR_SUPPORT
默认值：false

WATERMARK_GAMMA 与 WATERMARK_DELTA

--watermark-gamma <WATERMARK_GAMMA> --watermark-delta <WATERMARK_DELTA>

文本水印（watermarking）算法的两个参数，以环境变量WATERMARK_GAMMA/WATERMARK_DELTA传给 shard 进程（launcher/src/main.rs）。

环境变量：WATERMARK_GAMMA、WATERMARK_DELTA

GRACEFUL_TERMINATION_TIMEOUT

-g, --graceful-termination-timeout <GRACEFUL_TERMINATION_TIMEOUT>

TGI 服务器优雅终止的超时时间（秒）。源码中收到终止信号后先发SIGTERM等待进程自行退出，超过超时时间后强制kill（terminate函数，launcher/src/main.rs），对 webserver 与各 shard 均适用。

环境变量：GRACEFUL_TERMINATION_TIMEOUT
默认值：90

HELP 与 VERSION

-h, --help # 打印帮助（-h 显示精简版） -V, --version # 打印版本

所有参数均可用text-generation-launcher --help查看；-V打印启动器版本。

十二、参数校验规则与启动流程中的自动推断

除了逐项配置外，启动器在真正拉起服务前还会做一系列校验与自动推断（均位于 launcher/src/main.rs 的main函数）：

max_input_tokens与max_input_length互斥：两者同时设置会报错（第 2100-2112 行）；
输入必须小于总量：max_input_tokens < max_total_tokens，否则报错（第 2157-2163 行）；
总量不能超过 batch 预算：max_total_tokens <= max_batch_total_tokens（第 2199-2208 行）；
validation_workers必须大于 0（第 2187-2191 行）；
exl2与分片互斥（第 2091-2096 行）；
ngrok需要 authtoken 与 edge（第 2210-2222 行）；
注意力后端与 prefix caching 自动推断：根据模型 head_dim（64/128/256 支持 flashinfer，否则回退paged/flashdecoding）、VLM/seq2seq 模型、LoRA adapter 等条件自动禁用或启用 prefix caching（resolve_attention，第 131-200 行）；
max_batch_prefill_tokens自动计算：结合 GPU 算力、模型 FLOPs、显存与cuda_memory_fraction综合估算（第 2114-2154 行）；
CUDA graphs 自动降级：bitsandbytes/exl2下自动禁用（第 2169-2185 行）。

十三、典型部署示例

以下命令综合演示了本文档中主要参数的组合用法：

text-generation-launcher \ --model-id meta-llama/Llama-3.1-8B-Instruct \ --revision main \ --num-shard 4 \ --max-input-tokens 4096 \ --max-total-tokens 8192 \ --max-batch-prefill-tokens 8192 \ --max-batch-total-tokens 65536 \ --max-concurrent-requests 256 \ --waiting-served-ratio 1.2 \ --max-waiting-tokens 20 \ --max-best-of 4 \ --max-stop-sequences 6 \ --max-top-n-tokens 20 \ --port 3000 \ --prometheus-port 9000 \ --json-output \ --cors-allow-origin https://example.com \ --api-key <your-api-key> \ --huggingface-hub-cache /mnt/hf-cache

等效的环境变量写法（适合 Docker 注入）：

export MODEL_ID=meta-llama/Llama-3.1-8B-Instruct export NUM_SHARD=4 export MAX_INPUT_TOKENS=4096 export MAX_TOTAL_TOKENS=8192 export MAX_BATCH_PREFILL_TOKENS=8192 export MAX_BATCH_TOTAL_TOKENS=65536 export MAX_CONCURRENT_REQUESTS=256 export WAITING_SERVED_RATIO=1.2 export PORT=3000 export PROMETHEUS_PORT=9000 export JSON_OUTPUT=true text-generation-launcher

企业官网建设流程全解析