Triton Inference Server 二进制张量数据扩展（Binary Tensor Data Extension）协议完全指南

模型推理服务AI 应用后端【免费下载链接】serverThe Triton Inference Server provides an optimized cloud and edge inferencing solution.项目地址https://gitcode.com/gh_mirrors/server117/server点击查看免费下载本指南系统讲解 Triton Inference Server 的binary_tensor_data扩展如何在 HTTP/REST 推理请求与响应中以二进制形式传输张量数据包括binary_data_size、binary_data、binary_data_output三个核心参数的使用方式、Inference-Header-Content-Length头的语义以及不携带推理头 JSON 的 Raw Binary 请求模式。读完本文你将能够手写任意数据类型的二进制推理请求、正确解析二进制响应并理解该扩展在 src/http_server.cc 中的底层实现与边界校验逻辑。一、扩展概述为什么需要二进制张量数据Triton Inference Server 默认通过 HTTP/REST 的 JSON 表示来承载张量数据每个输入/输出张量的数据都以数组形式嵌入 JSON 对象。当张量元素数量庞大例如图像、嵌入向量、大 Batch 推理结果时JSON 文本编码会带来双重开销——datatype到文本的转换开销与体积膨胀。Binary Tensor Data Extension 允许在 HTTP 请求/响应体中在 JSON 对象之后直接追加一段原始二进制数据来承载张量内容从而消除 JSON 数组中数字到文本的编解码开销大幅缩减请求/响应体体积数值类型二进制表示通常比文本表示小 35 倍保持 HTTP/REST 协议的简单性同时获得接近 gRPC 的传输效率。由于该扩展受支持Triton 会在其 Server Metadata 的extensions字段中报告binary_tensor_data客户端可据此探测服务器能力。二、二进制数据的组织方式与编码规则当张量以二进制形式传输时数据遵循以下严格的组织约定由 src/http_server.cc 中CheckBinaryInputData/ReadDataFromJson/WriteDataToJson等实现印证字节序小端序little-endian内存布局按行主序row-major连续排列元素之间无 stride、无 padding数据类型所有支持的数据类型都以该类型的原生字节宽度表示BOOL 类型true为单个值为1的字节false为单个值为0的字节BYTES 类型每个元素由「4 字节无符号整数长度 实际字节内容」组成即每个元素都带有一个uint32长度前缀。BYTES 类型的这一编码在响应序列化中有直接证据src/http_server.cc的WriteDataToJson分支针对TRITONSERVER_TYPE_BYTES逐元素读取uint32_t长度前缀后再取对应字节在 qa/L0_http/http_test.py 的test_byte用例中客户端解析原始二进制输出时也通过r.content[header_size 4:]跳过 4 字节长度前缀来还原字符串。三、三个核心参数详解二进制扩展通过请求 JSON 中的parameters字段控制数据传输方式共涉及三个参数1.binary_data_sizeint64——输入/输出张量以二进制发送出现在$request_input请求输入与$response_output响应输出的parameters中表示该张量二进制数据占用的字节数。只要该参数存在即宣告该张量以二进制形式传递。从源码看src/http_server.cc 的CheckBinaryInputData约 L944-963在输入的parameters中查找binary_data_size将其解析为无符号整数作为byte_size一旦命中即置is_binary true而ValidateInputContentType约 L1045-1085强制要求每个输入在dataJSON 内联数据、binary_data_size二进制数据、shared_memory_region共享内存三者中只能且必须设置一个否则返回INVALID_ARG错误。2.binary_databool——指定某个输出以二进制返回出现在$request_output的parameters中取值为true表示该输出应返回二进制数据false或省略表示该输出以 JSON 返回。对应的CheckBinaryOutputDatasrc/http_server.cc L965-981解析该布尔值同时ValidateOutputParameter约 L1087-1119校验输出不能同时设置shared_memory_region与binary_data: true否则报错。3.binary_data_outputbool——请求级全局默认出现在$inference_request顶层的parameters中为true时表示所有输出默认以二进制返回除非某个输出通过自身的binary_data参数覆盖此设置。源码中ParseJsonTritonParamssrc/http_server.cc L2894-2984在遍历请求级参数时识别binary_data_output将其解析为布尔值并赋给infer_req-alloc_payload_.default_output_kind_BINARY或JSON作为未显式列出输出时的全局默认输出格式。四、请求/响应体结构JSON 头 二进制数据尾当一个或多个张量以二进制通信时HTTP 请求或响应体由两部分拼接而成JSON 推理请求/响应对象位于体首按 JSON 中张量声明顺序排列的二进制数据块紧跟在 JSON 之后。此时必须提供Inference-Header-Content-Length头其值为 JSON 对象的字节长度而标准 HTTP 的Content-Length继续表示整个请求/响应体的总长度即 JSON 长度 全部二进制数据长度。服务端在 src/http_server.cc 的GetInferenceHeaderLength约 L2490-2534解析该头若未提供则默认取整个Content-Length提供时校验其取值必须落在(0, Content-Length]区间内否则返回INVALID_ARG。测试用例qa/L0_http/http_test.py的test_inference_header_content_length_out_of_range专门验证了该边界。响应侧SetResponseHeader约 L4376-4405在存在二进制数据时将Content-Type设为application/octet-stream并回写Inference-Header-Content-Length无二进制数据时Content-Type为application/json。五、Binary Tensor Request 实战示例下面是一个将输入以二进制发送、并要求输出也以二进制返回的完整请求。两个输入张量二进制数据合计 19 字节16 3必须计入Content-LengthPOST /v2/models/mymodel/infer HTTP/1.1 Host: localhost:8000 Content-Type: application/octet-stream Inference-Header-Content-Length: xx Content-Length: xx19 { model_name : mymodel, inputs : [ { name : input0, shape : [ 2, 2 ], datatype : UINT32, parameters : { binary_data_size : 16 } }, { name : input1, shape : [ 3 ], datatype : BOOL, parameters : { binary_data_size : 3 } } ], outputs : [ { name : output0, parameters : { binary_data : true } } ] } 16 bytes of data for input0 tensor 3 bytes of data for input1 tensorinput0形状[2, 2]、类型UINT324 个元素 × 4 字节 16 字节二进制数据input1形状[3]、类型BOOL3 个元素 × 1 字节 3 字节二进制数据outputs中的binary_data: true要求output0以二进制返回。假设模型返回形状[3, 2]、类型FP32的张量6 元素 × 4 字节 24 字节响应如下HTTP/1.1 200 OK Content-Type: application/octet-stream Inference-Header-Content-Length: yy Content-Length: yy24 { outputs : [ { name : output0, shape : [ 3, 2 ], datatype : FP32, parameters : { binary_data_size : 24 } } ] } 24 bytes of data for output0 tensor注意响应 JSON 中 Triton 会为二进制输出自动填入binary_data_size见 src/http_server.cc L4301-4311BINARY类型的输出在parameters中写入binary_data_size为实际字节数并将对应输出缓冲加入ordered_buffers最终按序追加到 JSON 之后。六、Raw Binary Request不携带推理头的裸二进制请求对于张量元数据可由二进制数据字节数直接推导的模型客户端可以进一步省去推理头 JSON请求体仅包含张量的二进制数据。判定条件为模型只有一个输入输入数据类型非BYTES时可变维度数量至多 1 个即除已知维度外只有一个维度可由字节数反推输入数据类型为BYTES时形状必须为[1]支持的数据类型范围与 KServe Predict V2 协议定义的张量数据类型一致。发送裸二进制请求时Inference-Header-Content-Length头必须显式给出且值为 0用以声明请求体不包含推理头 JSON。服务端逻辑位于 src/http_server.cc 的EVRequestToJsonImpl约 L3004-3106当header_length 0时整个 HTTP 体都被视为原始输入数据随后EVBufferToRawInput约 L3108 起为该请求添加名为raw_input的原始输入并校验字节数不超过--http-max-input-size限制。形状推导失败多输入、BYTES 多元素、多可变维度时返回 400 错误错误信息可参见 qa/L0_http/http_test.py 中的test_byte_too_many_elements、test_multi_variable_dimensions、test_multi_inputs等用例断言。使用裸二进制请求时还需注意两个语义若模型支持 batching由于推理头被省略请求会被视为batch-1请求模型所有输出都将以二进制张量形式返回等效于请求级设置了binary_data_output: true。Raw Binary Request 示例以下请求体为 16 字节输入数据Content-Length即总长POST /v2/models/mymodel/infer HTTP/1.1 Host: localhost:8000 Content-Type: application/octet-stream Inference-Header-Content-Length: 0 Content-Length: 16 16 bytes of data for input tensor假设模型返回两个输出形状均为[3, 1]、类型FP32各 12 字节响应为HTTP/1.1 200 OK Content-Type: application/octet-stream Inference-Header-Content-Length: yy Content-Length: yy24 { outputs : [ { name : output0, shape : [ 3, 1 ], datatype : FP32, parameters : { binary_data_size : 12 } }, { name : output1, shape : [ 3, 1 ], datatype : FP32, parameters : { binary_data_size : 12 } } ] } 12 bytes of data for output0 tensor 12 bytes of data for output1 tensor七、源码级实现剖析二进制输入的处理链路在服务端二进制输入从 HTTP 体解析到推理请求的完整调用链为EVRequestToJsonImpl / EVBufferToJson切分 JSON 头 → ParseJsonTritonRequestID解析 id → ParseJsonTritonParams解析请求级参数含 binary_data_output → ParseJsonTritonIO逐输入处理含二进制数据搬运在ParseJsonTritonIOsrc/http_server.cc L2572 起中对每个输入先调用ValidateInputContentType校验数据来源唯一性调用CheckBinaryInputData解析binary_data_size得到byte_size若为二进制输入且byte_size 0直接追加空数据支持零形状张量否则若header_length 0即请求被当作裸二进制请求会返回INVALID_ARG错误——提示必须同时提供有效的Inference-Header-Content-Length与binary_data_size随后通过evbuffer_iovec分块消费请求体中的二进制数据逐块调用TRITONSERVER_InferenceRequestAppendInputData将数据以TRITONSERVER_MEMORY_CPU追加进推理请求直至消费完byte_size字节若请求体不足以满足声明的大小则返回「unexpected size for input ... expecting N additional bytes」错误。八、客户端验证与最佳实践仓库测试对二进制扩展覆盖相当完整可作为客户端实现的参考qa/L0_http/http_test.pytest_raw_binary/test_raw_binary_longer用numpy.tobytes()生成 FP32 输入、以Inference-Header-Content-Length: 0发送并用响应头中的Inference-Header-Content-Length定位输出二进制数据的起始偏移test_byte验证 BYTES 类型的 4 字节长度前缀test_content_encoding_chunked_manually验证 chunked 编码下裸二进制请求同样可用qa/L0_http/http_request_many_chunks.py验证输入分多个块传输时服务端按binary_data_size精确切分消费qa/L0_http/http_input_size_limit_test.py验证--http-max-input-size对二进制输入的字节数上限约束。实践要点总结二进制输入必须在parameters中给出精确的binary_data_size且与Content-Length中的实际数据字节数一致只要请求/响应含二进制数据就必须携带Inference-Header-Content-Length普通二进制请求为其 JSON 头长度裸二进制请求为0解析二进制响应时先读Inference-Header-Content-Length得到 JSON 头偏移再按输出声明顺序从该偏移开始依次读取各输出的原始字节对于 BYTES 类型输出需按「4 字节长度前缀 内容」逐元素解析仅在模型满足「单输入、形状可由字节数推导」条件时使用 Raw Binary Request否则退化为携带完整 JSON 头的普通二进制请求。九、相关文档与进一步阅读本扩展所属协议目录docs/protocol含分类、generate、共享内存、序列等扩展的并行说明扩展二进制数据在 HTTP 服务端的完整实现src/http_server.cc二进制输入限制校验与参数解析辅助函数CheckBinaryInputData、CheckBinaryOutputData、ValidateInputContentType、ValidateOutputParameter均位于 src/http_server.cc推理协议的整体说明与 gRPC/HTTP 端点约定docs/protocol/README.mdKServe Predict V2 协议张量数据类型定义可作为 Raw Binary 请求支持类型的参考依据赞分享模型推理服务AI 应用后端【免费下载链接】serverThe Triton Inference Server provides an optimized cloud and edge inferencing solution.项目地址https://gitcode.com/gh_mirrors/server117/server点击查看免费下载相关推荐Triton Inference Server 统计扩展Statistics Extension协议深度解析HTTP/REST 与 gRPC 接口全解Triton Inference Server 统计扩展Statistics Extension协议深度解析HTTP/REST 与 gRPC 接口全解 T模型推理服务AI 应用后端Triton Inference Server 的 KServe 协议扩展全景从 HTTP/REST 到 gRPC 的 11 个扩展机制详解Triton Inference Server 的 KServe 协议扩展全景从 HTTP/REST 到 gRPC 的 11 个扩展机制详解 导读 Trito模型推理服务AI 应用后端如何在Triton Inference Server中实现自定义元数据传递推理协议扩展终极指南如何在Triton Inference Server中实现自定义元数据传递推理协议扩展终极指南 Triton Inference Server是一款由NVID模型推理服务AI 应用后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考