Text Generation Inference 源码安装与本地部署完全指南【免费下载链接】text-generation-inferenceLarge Language Model Text Generation Inference项目地址: https://gitcode.com/GitHub_Trending/te/text-generation-inference本指南以 Text Generation InferenceTGI官方文档中的《Installation from source》为核心系统讲解如何从源码编译安装 TGI 的命令行工具CLI与完整服务端涵盖 Rust、Python、Protoc 等前置依赖的搭建以及make install、BUILD_EXTENSIONSTrue等关键构建命令的底层原理与实战用法。读完本文你将掌握在 Linux/macOS 上从零编译 TGI、正确配置自定义内核、并基于text-generation-launcher在 8080 端口本地部署 Falcon 7B Instruct 等模型的完整技能。一、安装方式总览为什么官方建议优先使用 Docker在进入源码安装之前必须先理解 TGI 官方对安装方式的态度。关联文档开篇即给出明确警告从源码安装并不是官方推荐的用法。官方强烈建议通过 Docker 使用 TGI理由在于 Docker 镜像已经预编译好全部依赖CUDA 内核、flash-attention、量化算子等可以显著降低环境搭建的复杂度与踩坑概率。如果你只是希望快速部署模型服务请优先参考以下仓库内文档快速上手Docker 一键部署以teknium/OpenHermes-2.5-Mistral-7B为例演示容器启动例如docker run --gpus all --shm-size 1g -p 8080:80 -v $PWD/data:/data ghcr.io/huggingface/text-generation-inference:3.3.5 --model-id $modelNVIDIA GPU 部署指南覆盖 H100、A100、A10G、T4 等 GPU 的容器化部署要求 CUDA 12.2 与 NVIDIA Container ToolkitAMD GPU 部署指南 以及 Intel GPU、Gaudi、Inferentia、TPU 等各硬件平台专属指南。而本文要讲解的源码安装路径适用于以下场景需要二次开发、需要调试自定义内核、需要离线编译、或希望精确控制每个组件的版本。它是理解 TGI 内部结构launcher、router、server 三进程协作的最佳途径。二、TGI 的组成结构三个可执行文件与一个 Makefile从源码安装前先弄清仓库的构建产物。查看仓库根目录 Makefile 可以看到make install实际由三个子目标串联而成install: install-server install-router install-launcher对应三个独立组件组件安装命令产物语言职责server推理服务器cd server make installtext-generation-serverPython CUDA 自定义内核加载模型权重、执行 prefill/decode、管理 KV Cache 与量化router路由/Web 服务器cargo install --path backends/v3/text-generation-routerRust对外提供 HTTP/gRPC 接口、请求校验、批处理调度launcher启动器cargo install --path launcher/text-generation-launcherRust编排以上两者下载权重、按 GPU 数量分片、拉起 shard 进程并监控健康状态从 launcher/src/main.rs 的main()函数可以清晰看到启动流程解析 CLI 参数 → 调用download_convert_model下载并转换模型权重仅.safetensors格式→ 通过spawn_shards按 GPU 分片启动多个text-generation-server进程 → 通过spawn_webserver启动text-generation-router→ 主循环监控各进程状态任一 shard 崩溃或 webserver 退出都会触发整体 graceful shutdown。三个产物缺一不可launcher 启动时若找不到text-generation-server或text-generation-router会分别提示Please install it withmake install-server/make install-router。三、安装 CLI两条命令完成构建3.1 标准安装TGI 的命令行接口CLI可用于下载权重、提供服务、量化模型以及查询服务参数。安装 CLI 的第一步是克隆仓库然后执行makegit clone https://github.com/huggingface/text-generation-inference.git cd text-generation-inference make install注意make install默认不编译自定义 CUDA 内核自定义内核仓库位于 server/custom_kernels、server/exllama_kernels、server/exllamav2_kernels 等目录。如果你需要为某些模型使用 TGI 实现的专用加速算子必须显式开启扩展构建BUILD_EXTENSIONSTrue make install3.2 底层拆解make install到底做了什么仅执行顶层make install往往不足以理解构建全貌。真实链路如下install-server进入 server/ 目录执行其中的make install见 server/Makefilegen-server用grpc_tools.protoc编译 proto/v3/generate.proto 生成 Python gRPC 桩代码到server/text_generation_server/pb/uv sync --inexact --extra accelerate --extra compressed-tensors --extra quantize --extra peft --extra outlines --active通过 uv 安装 Python 依赖TGI 服务器本体是 Python 包见 server/pyproject.tomlinstall-cuda目标还会追加install-flash-attention-v2-cuda、install-flash-attention、--extra attention --extra bnb、nvidia-nccl-cu12与kernels download .下载预编译内核。flash-attention 的固定版本定义在 server/Makefile-flash-att-v2CUDA 侧为flash-attn2.6.1AMD ROCm 侧则编译指定的 flash-attention fork如果你在 AMD 平台应使用make install-rocm而非install-cuda。install-routercargo install --path backends/v3/编译 Rust 路由服务源码在 backends/v3/src含backend.rs、queue.rs、radix.rs、block_allocator.rs等核心模块。install-launchercargo install --path launcher/编译启动器源码在 launcher/src/main.rs。仓库还提供了 CPU 专用安装目标make install-cpu见根 Makefile它使用install-server-cpu跳过 CUDA 相关扩展。四、本地源码安装完整环境准备4.1 前置要求TGI 在Python 3.9上经过测试可从 pypi、conda 与 GitHub 三种渠道获取。源码安装需要准备以下环境依赖用途版本要求Rust 工具链编译 router 与 launcherRust 组件通过 rustup 锁定Python 3.9运行 serverPython 组件≥ 3.9Protoc从.proto生成 gRPC 桩代码Linux 建议 protoc 21.12对应官方文档示例macOS 用 Homebrew 安装OpenSSL 库 gcc部分机器编译 Rust/Python 原生扩展需要Linux 下libssl-dev与gcc4.2 第一步安装 Rust 并创建虚拟环境curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh conda create -n text-generation-inference python3.9 conda activate text-generation-inference使用 conda 创建隔离的 Python 3.9 环境是最稳妥的做法——TGI 的 Python 依赖较多torch、transformers、grpc 等虚拟环境可以避免与系统 Python 包冲突。也可以使用python -m venv或 uv 替代 conda只要保证 Python 版本 ≥ 3.9 即可。4.3 第二步安装 ProtocLinux官方文档给出 21.12 版本的安装示例PROTOC_ZIPprotoc-21.12-linux-x86_64.zip curl -OL https://github.com/protocolbuffers/protobuf/releases/download/v21.12/$PROTOC_ZIP sudo unzip -o $PROTOC_ZIP -d /usr/local bin/protoc sudo unzip -o $PROTOC_ZIP -d /usr/local include/* rm -f $PROTOC_ZIP该操作将protoc可执行文件安装到/usr/local/bin并将 protobuf 的 include 头文件安装到/usr/local/include这两部分缺一不可——缺少 include 文件时grpc_tools.protoc编译 proto/v3/generate.proto 会因找不到标准 import 而失败。macOSHomebrew一条命令即可brew install protobuf4.4 第三步补齐编译工具链部分机器上还会缺少编译原生扩展所需的库。在 Linux 上执行sudo apt-get install libssl-dev gcc -ylibssl-dev提供 OpenSSL 头文件Rust 的hf-hub、reqwest等依赖在编译时需要它gcc编译 Python 的 CUDA 内核扩展如 exllama、flash-attention 的 Python 绑定以及部分 Rust 依赖的 C 代码。五、源码安装执行构建克隆仓库并执行完整安装git clone https://github.com/huggingface/text-generation-inference.git cd text-generation-inference BUILD_EXTENSIONSTrue make install几点说明BUILD_EXTENSIONSTrue会触发自定义内核的编译。内核源码分布在 server/custom_kernels融合注意力算子、server/exllama_kernelsGPTQ 4bit 推理、server/exllamav2_kernelsEXL2 变长位宽量化等目录编译过程较长Rust 组件需要拉取并编译数百个 crateCargo.lock 位于仓库根目录Python 侧需要编译 flash-attention 等 CUDA 算子如果只做 CPU 推理或无需自定义算子可用make install-cpu缩短构建时间。六、验证部署一条命令启动 Falcon 7B Instruct安装完成后TGI 提供了一条开箱即用的验证命令见根 Makefilemake run-falcon-7b-instruct该目标的真实命令是text-generation-launcher --model-id tiiuae/falcon-7b-instruct --port 8080这条命令会在8080 端口启动 Falcon 7B Instruct 推理服务。启动过程分三个阶段对应 launcher/src/main.rs权重下载launcher 调用text-generation-server download-weights tiiuae/falcon-7b-instruct --extension .safetensors从 Hugging Face Hub 拉取模型只下载 safetensors 格式期间默认启用HF_HUB_ENABLE_HF_TRANSFER以加速下载分片启动launcher 通过nvidia-smi探测 GPU 数量默认按所有可用 GPU 分片num_shard每个 shard 是独立的text-generation-server进程通过 UDS默认/tmp/text-generation-server-{rank}与 router 通信Web 服务所有 shard 就绪后launcher 启动text-generation-router对外监听 8080。启动成功后即可查询服务。仓库 docs/source/quicktour.md 给出了标准请求示例curl 127.0.0.1:8080/generate \ -X POST \ -d {inputs:What is Deep Learning?,parameters:{max_new_tokens:20}} \ -H Content-Type: application/json关于如何消费/generate端点包括 Python/JS 客户端、流式输出、OpenAI 兼容 Messages API可进一步阅读 消费 TGI 指南。七、深入理解launcher 的核心参数与自动调优text-generation-launcher是源码部署时最常直接使用的入口理解它的参数能帮助你精准控制部署行为。以下参数全部定义在 launcher/src/main.rs 的Args结构中均支持命令行参数与同名环境变量7.1 模型与硬件参数默认值说明--model-idbigscience/bloom-560m模型 IDHub 上的模型名或本地目录路径--revision无Hub 上的具体 revision可以是 commit id 或分支如refs/pr/2--sharded无是否跨多 GPU 分片默认使用所有可用 GPU--num-shard无分片数量可用CUDA_VISIBLE_DEVICES0,1 text-generation-launcher ... --num-shard 2配合控制 GPU 子集--quantize无量化方法awq、gptq、marlin、exl2、eetq、fp8、bitsandbytes等预量化模型会自动从配置读取无需显式指定--dtype无强制模型 dtypefloat16或bfloat16不能与--quantize同时使用--kv-cache-dtype无KV Cache 精度CUDA 上支持fp8_e4m3fn、fp8_e5m2--cuda-memory-fraction1.0限制 CUDA 可用显存比例从源码看shard 数量由find_num_shards计算launcher/src/main.rs未显式指定时默认等于可用 CUDA 设备数--sharded为 true 但只有一个 GPU 时会直接报错。此外EXL2 量化当前不支持张量并行num_shard 1。7.2 批处理与内存预算核心调优项参数默认值说明--max-concurrent-requests128最大并发请求数用于背压控制--max-best-of2客户端可设置best_of的上限--max-stop-sequences4客户端可设置 stop 序列数量的上限--max-top-n-tokens5返回 top-n token 概率信息的上限--max-input-tokens自动用户可发送的最大输入 token 数默认取min(可分配显存, max_position_embeddings) - 1--max-total-tokens自动内存预算核心参数输入 生成的 token 总和上限默认min(可分配显存, max_position_embeddings)--max-batch-prefill-tokens自动prefill 阶段的最大 token 数默认约max_input_tokens 50launcher 会根据 GPU 算力与显存自动估算--max-batch-total-tokens自动单个 batch 内的总 token 预算未指定时 TGI 根据剩余显存自动推断尽可能大的值--waiting-served-ratio0.3等待请求与运行请求的比值阈值触发动态批处理插入--max-waiting-tokens20等待请求被强制加入 batch 前的最大等待 token 数值得说明的是max_batch_prefill_tokens的自动值并非拍脑袋launcher 会读取模型的config.jsonget_config见 launcher/src/main.rs结合 GPU 型号的 FP16 算力表f16_flop与nvidia-smi查询的显存总量调用compute_optimal和vram_maximum计算可容纳的 token 数并在显存不足时自动下调。因此源码部署时你不一定需要手动设置这些内存参数但理解它们有助于在显存吃紧时精准干预。7.3 网络与服务参数默认值说明--hostname0.0.0.0监听地址--port3000make run-falcon-7b-instruct中显式指定 8080HTTP 服务端口--prometheus-port9000Prometheus 指标端口--api-key无服务鉴权 API Key--cors-allow-origin无CORS 白名单可传多次--json-output关以 JSON 格式输出日志便于接入日志系统--otlp-endpoint/--otlp-service-name无 /text-generation-inference.routerOpenTelemetry 链路追踪--usage-statson匿名使用统计on、off、no-stack7.4 高级功能参数说明--speculate投机解码speculative decoding的猜测 token 数Medusa 模型会自动加载其 heads否则使用 n-gram 投机--trust-remote-code允许执行 Hub 模型的自定义 modeling 代码建议同时显式指定--revision以规避恶意代码风险--lora-adapters启动时预加载的 LoRA 适配器列表格式repo/adapter1,repo/adapter2客户端可通过请求中的adapter_id字段调用--cuda-graphsCUDA Graph 的 batch size 集合默认1,2,4,8,16,32传0禁用bitsandbytes 与 exl2 量化会自动禁用--rope-scaling/--rope-factorRoPE 长度外推linear或dynamic配合--rope-factor 2.0使用--disable-grammar-support关闭基于 outlines 的语法约束生成--enable-prefill-logprobs允许请求 prefill 阶段提示词部分的 logprobs默认关闭以节省显存--watermark-gamma/--watermark-delta水印生成参数--env打印详细的运行环境信息--graceful-termination-timeout优雅退出超时默认 90 秒所有参数都可以通过text-generation-launcher --help查看完整列表与说明。八、常见问题与排错text-generation-server not found in PATHlauncher 找不到 server 进程。说明make install-server未成功执行或 Python 环境的 bin 目录不在PATH中——请确保安装时激活了正确的 conda/venv 环境。text-generation-router not found in PATHRust 组件未安装或~/.cargo/bin不在PATH中执行make install-router并检查 cargo 环境。Protoc 编译失败gen-server目标需要protoc在PATH中且 include 目录完整。Linux 用户请确认 21.12 安装命令中的两个unzip步骤都执行成功。libssl-dev缺失导致的编译错误Rust 依赖如hf-hub编译时找不到 OpenSSL执行sudo apt-get install libssl-dev gcc -y后重新构建。显存不足导致启动失败启动日志中如果出现Not enough VRAM to run the model说明模型超过单卡显存可尝试--num-shard增加分片、--quantize开启量化如eetq、或通过--cuda-memory-fraction调整显存占用比例。自定义内核报错如果你在非 A100 等硬件上遇到自定义 CUDA 内核问题可添加--disable-custom-kernels禁用它们该选项最初针对 Bloom 等模型的专用算子设计仅在 A100 上充分测试。重新构建Rust 组件改动后执行make install-router install-launcher即可增量重编Python 侧改动可复用server-dev/router-dev开发目标见根 Makefile。九、总结从源码安装 TGI 的完整链路可以概括为准备 Rust Python 3.9 Protoc OpenSSL/gcc →git clone仓库 →BUILD_EXTENSIONSTrue make install依次构建 server/router/launcher→make run-falcon-7b-instruct或自定义text-generation-launcher --model-id ... --port ...启动服务。这条路径虽然比 Docker 部署繁琐但它让你能够触及 TGI 的三进程架构launcher 编排、router 调度、server 推理与参数调优机制的本质——例如 launcher/src/main.rs 中根据 GPU 算力和显存自动计算批处理预算的逻辑、server/Makefile 中 CUDA 内核与 flash-attention 的编译绑定、以及 Makefile 顶层目标对三大组件的组装。掌握这些知识后无论是二次开发、内核定制还是生产调优你都将具备从源码层面精准控制 TGI 的能力。【免费下载链接】text-generation-inferenceLarge Language Model Text Generation Inference项目地址: https://gitcode.com/GitHub_Trending/te/text-generation-inference创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Text Generation Inference 源码安装与本地部署完全指南
Text Generation Inference 源码安装与本地部署完全指南【免费下载链接】text-generation-inferenceLarge Language Model Text Generation Inference项目地址: https://gitcode.com/GitHub_Trending/te/text-generation-inference本指南以 Text Generation InferenceTGI官方文档中的《Installation from source》为核心系统讲解如何从源码编译安装 TGI 的命令行工具CLI与完整服务端涵盖 Rust、Python、Protoc 等前置依赖的搭建以及make install、BUILD_EXTENSIONSTrue等关键构建命令的底层原理与实战用法。读完本文你将掌握在 Linux/macOS 上从零编译 TGI、正确配置自定义内核、并基于text-generation-launcher在 8080 端口本地部署 Falcon 7B Instruct 等模型的完整技能。一、安装方式总览为什么官方建议优先使用 Docker在进入源码安装之前必须先理解 TGI 官方对安装方式的态度。关联文档开篇即给出明确警告从源码安装并不是官方推荐的用法。官方强烈建议通过 Docker 使用 TGI理由在于 Docker 镜像已经预编译好全部依赖CUDA 内核、flash-attention、量化算子等可以显著降低环境搭建的复杂度与踩坑概率。如果你只是希望快速部署模型服务请优先参考以下仓库内文档快速上手Docker 一键部署以teknium/OpenHermes-2.5-Mistral-7B为例演示容器启动例如docker run --gpus all --shm-size 1g -p 8080:80 -v $PWD/data:/data ghcr.io/huggingface/text-generation-inference:3.3.5 --model-id $modelNVIDIA GPU 部署指南覆盖 H100、A100、A10G、T4 等 GPU 的容器化部署要求 CUDA 12.2 与 NVIDIA Container ToolkitAMD GPU 部署指南 以及 Intel GPU、Gaudi、Inferentia、TPU 等各硬件平台专属指南。而本文要讲解的源码安装路径适用于以下场景需要二次开发、需要调试自定义内核、需要离线编译、或希望精确控制每个组件的版本。它是理解 TGI 内部结构launcher、router、server 三进程协作的最佳途径。二、TGI 的组成结构三个可执行文件与一个 Makefile从源码安装前先弄清仓库的构建产物。查看仓库根目录 Makefile 可以看到make install实际由三个子目标串联而成install: install-server install-router install-launcher对应三个独立组件组件安装命令产物语言职责server推理服务器cd server make installtext-generation-serverPython CUDA 自定义内核加载模型权重、执行 prefill/decode、管理 KV Cache 与量化router路由/Web 服务器cargo install --path backends/v3/text-generation-routerRust对外提供 HTTP/gRPC 接口、请求校验、批处理调度launcher启动器cargo install --path launcher/text-generation-launcherRust编排以上两者下载权重、按 GPU 数量分片、拉起 shard 进程并监控健康状态从 launcher/src/main.rs 的main()函数可以清晰看到启动流程解析 CLI 参数 → 调用download_convert_model下载并转换模型权重仅.safetensors格式→ 通过spawn_shards按 GPU 分片启动多个text-generation-server进程 → 通过spawn_webserver启动text-generation-router→ 主循环监控各进程状态任一 shard 崩溃或 webserver 退出都会触发整体 graceful shutdown。三个产物缺一不可launcher 启动时若找不到text-generation-server或text-generation-router会分别提示Please install it withmake install-server/make install-router。三、安装 CLI两条命令完成构建3.1 标准安装TGI 的命令行接口CLI可用于下载权重、提供服务、量化模型以及查询服务参数。安装 CLI 的第一步是克隆仓库然后执行makegit clone https://github.com/huggingface/text-generation-inference.git cd text-generation-inference make install注意make install默认不编译自定义 CUDA 内核自定义内核仓库位于 server/custom_kernels、server/exllama_kernels、server/exllamav2_kernels 等目录。如果你需要为某些模型使用 TGI 实现的专用加速算子必须显式开启扩展构建BUILD_EXTENSIONSTrue make install3.2 底层拆解make install到底做了什么仅执行顶层make install往往不足以理解构建全貌。真实链路如下install-server进入 server/ 目录执行其中的make install见 server/Makefilegen-server用grpc_tools.protoc编译 proto/v3/generate.proto 生成 Python gRPC 桩代码到server/text_generation_server/pb/uv sync --inexact --extra accelerate --extra compressed-tensors --extra quantize --extra peft --extra outlines --active通过 uv 安装 Python 依赖TGI 服务器本体是 Python 包见 server/pyproject.tomlinstall-cuda目标还会追加install-flash-attention-v2-cuda、install-flash-attention、--extra attention --extra bnb、nvidia-nccl-cu12与kernels download .下载预编译内核。flash-attention 的固定版本定义在 server/Makefile-flash-att-v2CUDA 侧为flash-attn2.6.1AMD ROCm 侧则编译指定的 flash-attention fork如果你在 AMD 平台应使用make install-rocm而非install-cuda。install-routercargo install --path backends/v3/编译 Rust 路由服务源码在 backends/v3/src含backend.rs、queue.rs、radix.rs、block_allocator.rs等核心模块。install-launchercargo install --path launcher/编译启动器源码在 launcher/src/main.rs。仓库还提供了 CPU 专用安装目标make install-cpu见根 Makefile它使用install-server-cpu跳过 CUDA 相关扩展。四、本地源码安装完整环境准备4.1 前置要求TGI 在Python 3.9上经过测试可从 pypi、conda 与 GitHub 三种渠道获取。源码安装需要准备以下环境依赖用途版本要求Rust 工具链编译 router 与 launcherRust 组件通过 rustup 锁定Python 3.9运行 serverPython 组件≥ 3.9Protoc从.proto生成 gRPC 桩代码Linux 建议 protoc 21.12对应官方文档示例macOS 用 Homebrew 安装OpenSSL 库 gcc部分机器编译 Rust/Python 原生扩展需要Linux 下libssl-dev与gcc4.2 第一步安装 Rust 并创建虚拟环境curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh conda create -n text-generation-inference python3.9 conda activate text-generation-inference使用 conda 创建隔离的 Python 3.9 环境是最稳妥的做法——TGI 的 Python 依赖较多torch、transformers、grpc 等虚拟环境可以避免与系统 Python 包冲突。也可以使用python -m venv或 uv 替代 conda只要保证 Python 版本 ≥ 3.9 即可。4.3 第二步安装 ProtocLinux官方文档给出 21.12 版本的安装示例PROTOC_ZIPprotoc-21.12-linux-x86_64.zip curl -OL https://github.com/protocolbuffers/protobuf/releases/download/v21.12/$PROTOC_ZIP sudo unzip -o $PROTOC_ZIP -d /usr/local bin/protoc sudo unzip -o $PROTOC_ZIP -d /usr/local include/* rm -f $PROTOC_ZIP该操作将protoc可执行文件安装到/usr/local/bin并将 protobuf 的 include 头文件安装到/usr/local/include这两部分缺一不可——缺少 include 文件时grpc_tools.protoc编译 proto/v3/generate.proto 会因找不到标准 import 而失败。macOSHomebrew一条命令即可brew install protobuf4.4 第三步补齐编译工具链部分机器上还会缺少编译原生扩展所需的库。在 Linux 上执行sudo apt-get install libssl-dev gcc -ylibssl-dev提供 OpenSSL 头文件Rust 的hf-hub、reqwest等依赖在编译时需要它gcc编译 Python 的 CUDA 内核扩展如 exllama、flash-attention 的 Python 绑定以及部分 Rust 依赖的 C 代码。五、源码安装执行构建克隆仓库并执行完整安装git clone https://github.com/huggingface/text-generation-inference.git cd text-generation-inference BUILD_EXTENSIONSTrue make install几点说明BUILD_EXTENSIONSTrue会触发自定义内核的编译。内核源码分布在 server/custom_kernels融合注意力算子、server/exllama_kernelsGPTQ 4bit 推理、server/exllamav2_kernelsEXL2 变长位宽量化等目录编译过程较长Rust 组件需要拉取并编译数百个 crateCargo.lock 位于仓库根目录Python 侧需要编译 flash-attention 等 CUDA 算子如果只做 CPU 推理或无需自定义算子可用make install-cpu缩短构建时间。六、验证部署一条命令启动 Falcon 7B Instruct安装完成后TGI 提供了一条开箱即用的验证命令见根 Makefilemake run-falcon-7b-instruct该目标的真实命令是text-generation-launcher --model-id tiiuae/falcon-7b-instruct --port 8080这条命令会在8080 端口启动 Falcon 7B Instruct 推理服务。启动过程分三个阶段对应 launcher/src/main.rs权重下载launcher 调用text-generation-server download-weights tiiuae/falcon-7b-instruct --extension .safetensors从 Hugging Face Hub 拉取模型只下载 safetensors 格式期间默认启用HF_HUB_ENABLE_HF_TRANSFER以加速下载分片启动launcher 通过nvidia-smi探测 GPU 数量默认按所有可用 GPU 分片num_shard每个 shard 是独立的text-generation-server进程通过 UDS默认/tmp/text-generation-server-{rank}与 router 通信Web 服务所有 shard 就绪后launcher 启动text-generation-router对外监听 8080。启动成功后即可查询服务。仓库 docs/source/quicktour.md 给出了标准请求示例curl 127.0.0.1:8080/generate \ -X POST \ -d {inputs:What is Deep Learning?,parameters:{max_new_tokens:20}} \ -H Content-Type: application/json关于如何消费/generate端点包括 Python/JS 客户端、流式输出、OpenAI 兼容 Messages API可进一步阅读 消费 TGI 指南。七、深入理解launcher 的核心参数与自动调优text-generation-launcher是源码部署时最常直接使用的入口理解它的参数能帮助你精准控制部署行为。以下参数全部定义在 launcher/src/main.rs 的Args结构中均支持命令行参数与同名环境变量7.1 模型与硬件参数默认值说明--model-idbigscience/bloom-560m模型 IDHub 上的模型名或本地目录路径--revision无Hub 上的具体 revision可以是 commit id 或分支如refs/pr/2--sharded无是否跨多 GPU 分片默认使用所有可用 GPU--num-shard无分片数量可用CUDA_VISIBLE_DEVICES0,1 text-generation-launcher ... --num-shard 2配合控制 GPU 子集--quantize无量化方法awq、gptq、marlin、exl2、eetq、fp8、bitsandbytes等预量化模型会自动从配置读取无需显式指定--dtype无强制模型 dtypefloat16或bfloat16不能与--quantize同时使用--kv-cache-dtype无KV Cache 精度CUDA 上支持fp8_e4m3fn、fp8_e5m2--cuda-memory-fraction1.0限制 CUDA 可用显存比例从源码看shard 数量由find_num_shards计算launcher/src/main.rs未显式指定时默认等于可用 CUDA 设备数--sharded为 true 但只有一个 GPU 时会直接报错。此外EXL2 量化当前不支持张量并行num_shard 1。7.2 批处理与内存预算核心调优项参数默认值说明--max-concurrent-requests128最大并发请求数用于背压控制--max-best-of2客户端可设置best_of的上限--max-stop-sequences4客户端可设置 stop 序列数量的上限--max-top-n-tokens5返回 top-n token 概率信息的上限--max-input-tokens自动用户可发送的最大输入 token 数默认取min(可分配显存, max_position_embeddings) - 1--max-total-tokens自动内存预算核心参数输入 生成的 token 总和上限默认min(可分配显存, max_position_embeddings)--max-batch-prefill-tokens自动prefill 阶段的最大 token 数默认约max_input_tokens 50launcher 会根据 GPU 算力与显存自动估算--max-batch-total-tokens自动单个 batch 内的总 token 预算未指定时 TGI 根据剩余显存自动推断尽可能大的值--waiting-served-ratio0.3等待请求与运行请求的比值阈值触发动态批处理插入--max-waiting-tokens20等待请求被强制加入 batch 前的最大等待 token 数值得说明的是max_batch_prefill_tokens的自动值并非拍脑袋launcher 会读取模型的config.jsonget_config见 launcher/src/main.rs结合 GPU 型号的 FP16 算力表f16_flop与nvidia-smi查询的显存总量调用compute_optimal和vram_maximum计算可容纳的 token 数并在显存不足时自动下调。因此源码部署时你不一定需要手动设置这些内存参数但理解它们有助于在显存吃紧时精准干预。7.3 网络与服务参数默认值说明--hostname0.0.0.0监听地址--port3000make run-falcon-7b-instruct中显式指定 8080HTTP 服务端口--prometheus-port9000Prometheus 指标端口--api-key无服务鉴权 API Key--cors-allow-origin无CORS 白名单可传多次--json-output关以 JSON 格式输出日志便于接入日志系统--otlp-endpoint/--otlp-service-name无 /text-generation-inference.routerOpenTelemetry 链路追踪--usage-statson匿名使用统计on、off、no-stack7.4 高级功能参数说明--speculate投机解码speculative decoding的猜测 token 数Medusa 模型会自动加载其 heads否则使用 n-gram 投机--trust-remote-code允许执行 Hub 模型的自定义 modeling 代码建议同时显式指定--revision以规避恶意代码风险--lora-adapters启动时预加载的 LoRA 适配器列表格式repo/adapter1,repo/adapter2客户端可通过请求中的adapter_id字段调用--cuda-graphsCUDA Graph 的 batch size 集合默认1,2,4,8,16,32传0禁用bitsandbytes 与 exl2 量化会自动禁用--rope-scaling/--rope-factorRoPE 长度外推linear或dynamic配合--rope-factor 2.0使用--disable-grammar-support关闭基于 outlines 的语法约束生成--enable-prefill-logprobs允许请求 prefill 阶段提示词部分的 logprobs默认关闭以节省显存--watermark-gamma/--watermark-delta水印生成参数--env打印详细的运行环境信息--graceful-termination-timeout优雅退出超时默认 90 秒所有参数都可以通过text-generation-launcher --help查看完整列表与说明。八、常见问题与排错text-generation-server not found in PATHlauncher 找不到 server 进程。说明make install-server未成功执行或 Python 环境的 bin 目录不在PATH中——请确保安装时激活了正确的 conda/venv 环境。text-generation-router not found in PATHRust 组件未安装或~/.cargo/bin不在PATH中执行make install-router并检查 cargo 环境。Protoc 编译失败gen-server目标需要protoc在PATH中且 include 目录完整。Linux 用户请确认 21.12 安装命令中的两个unzip步骤都执行成功。libssl-dev缺失导致的编译错误Rust 依赖如hf-hub编译时找不到 OpenSSL执行sudo apt-get install libssl-dev gcc -y后重新构建。显存不足导致启动失败启动日志中如果出现Not enough VRAM to run the model说明模型超过单卡显存可尝试--num-shard增加分片、--quantize开启量化如eetq、或通过--cuda-memory-fraction调整显存占用比例。自定义内核报错如果你在非 A100 等硬件上遇到自定义 CUDA 内核问题可添加--disable-custom-kernels禁用它们该选项最初针对 Bloom 等模型的专用算子设计仅在 A100 上充分测试。重新构建Rust 组件改动后执行make install-router install-launcher即可增量重编Python 侧改动可复用server-dev/router-dev开发目标见根 Makefile。九、总结从源码安装 TGI 的完整链路可以概括为准备 Rust Python 3.9 Protoc OpenSSL/gcc →git clone仓库 →BUILD_EXTENSIONSTrue make install依次构建 server/router/launcher→make run-falcon-7b-instruct或自定义text-generation-launcher --model-id ... --port ...启动服务。这条路径虽然比 Docker 部署繁琐但它让你能够触及 TGI 的三进程架构launcher 编排、router 调度、server 推理与参数调优机制的本质——例如 launcher/src/main.rs 中根据 GPU 算力和显存自动计算批处理预算的逻辑、server/Makefile 中 CUDA 内核与 flash-attention 的编译绑定、以及 Makefile 顶层目标对三大组件的组装。掌握这些知识后无论是二次开发、内核定制还是生产调优你都将具备从源码层面精准控制 TGI 的能力。【免费下载链接】text-generation-inferenceLarge Language Model Text Generation Inference项目地址: https://gitcode.com/GitHub_Trending/te/text-generation-inference创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考