text-generation-inference 的 HTTP API 全面指南从 TGI 自定义 API 到 OpenAI Messages API 兼容调用【免费下载链接】text-generation-inferenceLarge Language Model Text Generation Inference项目地址: https://gitcode.com/GitHub_Trending/te/text-generation-inferenceTGIText Generation Inference通过一个 RESTful HTTP 服务对外提供文本生成能力路由层同时暴露两套端点TGI 自定义 API 与 OpenAI Messages API。本文以 docs/source/reference/api_reference.md 为骨架结合 router/src/server.rs 中的真实路由注册与处理逻辑系统讲解端点布局、curl 与 OpenAI Python 客户端的调用方式、流式与同步请求、Hugging Face Inference Endpoints 集成以及 Amazon SageMaker 部署帮助你在一小时内将任意兼容 Chat Completions 的客户端接入 TGI 服务。一、两套 HTTP API 的端点总览TGI 的 HTTP API 是 RESTful 设计由 RouterRust/axum 实现统一对外提供两类接口Text Generation Inference 自定义 APITGI 原生的生成接口包含/generate、/generate_stream、/tokenize、/info、/health等端点。OpenAI Messages API自TGI 1.4.0 起提供的/v1/chat/completions兼容端点完全兼容 OpenAI Chat Completion API 的请求与响应 Schema可直接使用 OpenAI 官方客户端库或任何按 OpenAI Schema 编写的第三方库。从 router/src/server.rs 可以看到基础路由的完整注册清单let mut base_routes Router::new() .route(/, post(compat_generate)) .route(/generate, post(generate)) .route(/generate_stream, post(generate_stream)) .route(/v1/chat/completions, post(chat_completions)) .route(/v1/completions, post(completions)) .route(/vertex, post(vertex_compatibility)) .route(/invocations, post(sagemaker_compatibility)) .route(/tokenize, post(tokenize));信息类路由router/src/server.rs则包含let info_routes Router::new() .route(/, get(health)) .route(/chat_tokenize, post(get_chat_tokenize)) .route(/info, get(get_model_info)) .route(/health, get(health)) .route(/ping, get(health)) .route(/metrics, get(metrics)) .route(/v1/models, get(openai_get_model_info));整理成表格如下端点方法说明响应类型/POSTTGI 兼容生成入口CompatGenerateRequest按stream字段分流JSON / SSE/generatePOST非流式生成JSON/generate_streamPOST流式生成Server-Sent Eventstext/event-stream/v1/chat/completionsPOSTOpenAI Chat Completions 兼容接口JSON / SSE/v1/completionsPOSTOpenAI Completions 兼容接口JSON / SSE/v1/modelsGETOpenAI 风格模型信息ModelsInfoJSON/tokenizePOST对输入做分词JSON/chat_tokenizePOST对 ChatRequest 应用聊天模板并分词返回ChatTokenizeResponseJSON/infoGET被服务模型的元信息InfoJSON/health、/ping、/(GET)GET健康检查JSON/metricsGETPrometheus 指标文本/vertex、/invocationsPOSTGoogle Vertex AI、Amazon SageMaker 兼容入口JSON/docsGETSwagger UI 交互式文档HTML/api-doc/openapi.jsonGETOpenAPI 规范文件JSON关于自定义 API 的完整请求/响应字段BestOf、Temperature、TopP、RepetitionPenalty等生成参数官方提供独立 API 文档本文重点展开仓库源码中可验证的 Messages API 兼容实现。二、使用 curl 发起第一次 Chat Completions 请求假设 TGI 已在本机 3000 端口启动默认端口由 router/src/config.rs 中的参数解析控制可通过 CLI 参数--port调整一个最小的 OpenAI 兼容请求如下curl localhost:3000/v1/chat/completions \ -X POST \ -d { model: tgi, messages: [ { role: system, content: You are a helpful assistant. }, { role: user, content: What is deep learning? } ], stream: true, max_tokens: 20 } \ -H Content-Type: application/json几个要点说明model字段源码中 chat_completions 处理器 对model做了特殊处理——当其为tgi或缺失时会替换为实际被服务模型的model_id若传入其他字符串则原样保留。所以示例中的model: tgi是一个占位符服务端会返回真实模型名。stream字段为true时返回text/event-stream的 SSE 流为false或省略时返回单次 JSON 响应。max_tokens控制最大生成 token 数语义与 OpenAI 一致。请求鉴权如果启动时配置了 API Keyserver.rs 的认证中间件 会要求请求头携带Authorization: Bearer api_key否则返回401 Unauthorized。本地无鉴权部署时可不带该头。三、使用 OpenAI Python 客户端流式与同步调用由于/v1/chat/completions完全遵循 OpenAI Schema可以直接复用openai官方 Python 库只需把base_url指向 TGI 即可。3.1 流式请求Streamingfrom openai import OpenAI # init the client but point it to TGI client OpenAI( base_urlhttp://localhost:3000/v1, api_key- ) chat_completion client.chat.completions.create( modeltgi, messages[ {role: system, content: You are a helpful assistant. }, {role: user, content: What is deep learning?} ], streamTrue ) # iterate and print stream for message in chat_completion: print(message)服务端在流式路径上会持续推送data:形式的 SSE 事件并在结束时发送data: [DONE]。这个终止事件在 server.rs 的流式组装代码 中显式产出yield Ok::Event, Infallible(Event::default().data([DONE]));3.2 同步请求Synchronousfrom openai import OpenAI # init the client but point it to TGI client OpenAI( base_urlhttp://localhost:3000/v1, api_key- ) chat_completion client.chat.completions.create( modeltgi, messages[ {role: system, content: You are a helpful assistant. }, {role: user, content: What is deep learning?} ], streamFalse ) print(chat_completion)同步路径内部会调用generate_internal一次性完成生成然后组装出ChatCompletion响应包含id、created、model、choices、usage等 OpenAI 标准字段system_fingerprint由服务版本与 Docker 标签拼接而成见 server.rs。3.3 流式响应中的增量语义流式模式下每个 chunk 的choices[0].delta携带增量内容。在 router/src/chat.rs 的create_event_from_stream_token中可以看到普通 token 会被包装成role: assistant的文本增量当请求携带logprobs时还会附带ChatCompletionLogprobs由当前 token 与top_tokens生成。这意味着客户端可以像消费 OpenAI 流式接口一样直接读取message.choices[0].delta.content逐字拼接结果例如for message in chat_completion: print(message.choices[0].delta.content, end)四、Hugging Face Inference Endpoints 集成Messages API 已与 Hugging Face Inference Endpoints 深度集成。任何基于 Text Generation Inference 服务、且模型自带chat template的推理端点都可以直接通过 OpenAI 客户端调用。用法与本地部署完全一致只是base_url换成端点地址from openai import OpenAI # init the client but point it to TGI client OpenAI( # replace with your endpoint url, make sure to include v1/ at the end base_urlhttps://vlzz10eq3fol3429.us-east-1.aws.endpoints.huggingface.cloud/v1/, # replace with your API key api_keyhf_XXX ) chat_completion client.chat.completions.create( modeltgi, messages[ {role: system, content: You are a helpful assistant. }, {role: user, content: What is deep learning?} ], streamTrue ) # iterate and print stream for message in chat_completion: print(message.choices[0].delta.content, end)使用要点base_url必须以v1/结尾因为 OpenAI 客户端会在其后拼接chat/completions。api_key替换为你的 Hugging Face API Keyhf_...。端点上托管的大语言模型必须带有 chat template从源码看chat_completions 处理器 会读取infer.chat_template来把消息列表渲染成模型输入这一步骤对应的可观测端点正是/chat_tokenize——它会返回应用聊天模板后的templated_text与 token 序列见 server.rs可用于排查模板渲染问题。五、Cloud Providers以 Amazon SageMaker 为例TGI 可部署到多种云厂商以获得弹性与高可用Amazon SageMaker 原生支持 Messages API。下面的示例展示了使用sagemakerSDK 部署 TGI 大模型推理端点并直接发送messages格式的请求import json import sagemaker import boto3 from sagemaker.huggingface import HuggingFaceModel, get_huggingface_llm_image_uri try: role sagemaker.get_execution_role() except ValueError: iam boto3.client(iam) role iam.get_role(RoleNamesagemaker_execution_role)[Role][Arn] # Hub Model configuration. https://huggingface.co/models hub { HF_MODEL_ID:HuggingFaceH4/zephyr-7b-beta, SM_NUM_GPUS: json.dumps(1), } # create Hugging Face Model Class huggingface_model HuggingFaceModel( image_uriget_huggingface_llm_image_uri(huggingface,version3.3.5), envhub, rolerole, ) # deploy model to SageMaker Inference predictor huggingface_model.deploy( initial_instance_count1, instance_typeml.g5.2xlarge, container_startup_health_check_timeout300, ) # send request predictor.predict({ messages: [ {role: system, content: You are a helpful assistant. }, {role: user, content: What is deep learning?} ] })关键配置解释HF_MODEL_ID指定要加载的 Hugging Face Hub 模型 ID示例为HuggingFaceH4/zephyr-7b-beta。SM_NUM_GPUS每个实例上用于张量并行Tensor Parallelism的 GPU 数量示例为 1多卡部署时需与实例规格匹配。image_uri使用get_huggingface_llm_image_uri(huggingface, version3.3.5)拉取带 TGI 的官方推理镜像。instance_typeml.g5.2xlargeGPU 实例规格可按模型规模调整。container_startup_health_check_timeout300容器启动健康检查超时秒大模型首次加载权重时建议给足时间。SageMaker 场景下路由层对应的兼容入口是/invocations见上文路由表它接收与 Messages API 相同的消息结构。仓库同时提供了独立的兼容层实现文件 router/src/sagemaker.rs以及面向 Google Vertex AI 的 router/src/vertex.rs说明 TGI 在设计上就为多云部署保留了 Schema 级兼容。六、源码视角chat_completions 的处理链路与工具调用要深入理解 Messages API 的可靠性值得看一下POST /v1/chat/completions在 router/src/server.rs 中的完整处理流程解析与模板渲染ChatRequest通过try_into_generate(infer)转换为内部的GenerateRequest这一步会应用 chat template 与可选的 tool schema/grammar返回值中的using_tools标记本次请求是否启用了工具调用。分流stream true时进入generate_stream_internal产出 SSE 事件流否则走generate_internal一次性生成。流式状态机ChatState定义于 router/src/chat.rs维护三种状态Buffering启用工具调用时先缓冲文本尝试把累积内容解析为{function: {...}}的 JSON 工具调用Tool正在输出工具调用的参数片段Content普通文本增量输出。工具调用识别parse_outputrouter/src/chat.rs解析生成文本若函数名为no_tool则视为普通回复触发ChatEvent::NoTool服务端会清除 tools 后重新生成见 server.rs否则把参数组装为 OpenAI 风格的tool_calls增量事件。usage 统计若请求携带stream_options: {include_usage: true}ChatState::push会在流末尾追加一个携带prompt_tokens、completion_tokens、total_tokens的 usage chunkrouter/src/chat.rs该数字来自StreamDetails中的input_length与generated_tokens。错误语义与自定义 API 一致Messages API 同样采用标准错误码424生成错误、429模型过载、422输入校验失败、500生成不完整。仓库内单元测试见 router/src/chat.rs 中的test_chat_stream、test_chat_stream_usage对增量事件结构与 usage 行为做了直接验证。七、快速自查清单确认 TGI 版本 ≥ 1.4.0Messages API 的最低版本要求。本地调用base_urlhttp://localhost:3000/v1IE 端点base_url以v1/结尾并替换 API Key。流式响应以data: [DONE]结束工具调用流式解析由服务端ChatState状态机自动完成。模型名占位符传tgi即可服务端会替换为真实model_id也可通过GET /v1/models查询。需要交互式调试时可直接访问http://localhost:3000/docsSwagger UI或读取/api-doc/openapi.json。排查模板问题时用POST /chat_tokenize查看聊天模板渲染后的实际输入文本。通过上述端点布局、调用示例与源码链路你可以把 TGI 无缝嵌入任何 OpenAI 生态的工具链LangChain、LlamaIndex、Open WebUI 等并在一套消息格式下自由切换本地部署、Hugging Face Inference Endpoints 与 Amazon SageMaker 等多种运行环境。【免费下载链接】text-generation-inferenceLarge Language Model Text Generation Inference项目地址: https://gitcode.com/GitHub_Trending/te/text-generation-inference创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考