企业官网建设流程全解析

• 人工智能
• 大模型
• MLOps
• LLMOps
• 模型推理服务
• 云原生
• 后端

本篇技术指南以 seldon-core 仓库中 Open Inference Protocol 规范文档 为骨架，系统讲解框架无关的 V2 推理协议：从健康检查、服务器/模型元数据到推理请求的完整 HTTP/REST 与 GRPC API 定义、全部 JSON 与 protobuf 消息结构、张量数据编码规则与数据类型表。读完本文，你将能够按规范实现或对接 V2 协议客户端/服务端，并了解该协议在 Seldon Core 的 Pipeline Gateway、Agent 反向代理中的真实落地方式。

协议定位：框架无关的统一推理接口

Open Inference Protocol（旧称 "V2 Inference Protocol"）是一套与具体 ML/DL 框架和模型服务器无关的预测/推理 API。它同时兼顾"开箱即用"的易用性与高性能场景：协议层面既支持直观的 JSON 数组表达张量，也支持 GRPC raw bytes 的高吞吐表达。该协议已获得 NVIDIA Triton Inference Server、TensorFlow Serving 与 ONNX Runtime Server 的认可与支持。

协议的设计目标非常明确：只要推理客户端与服务端都实现了这套协议，双方就能在任何围绕该 API 标准化的平台上无缝互通，提升彼此的实用性与可移植性。对 Seldon 而言，一个推理服务器只要实现了下述全部 API（明确标注为可选的除外），即可视为协议合规；合规服务器可以选择只实现 HTTP/REST 与 GRPC 中的一种或两者都实现。

协议还要求实现一种扩展机制（extensions字段），但规范本身不预定义任何具体扩展，具体扩展由各推理服务器自行提出与文档化。

HTTP/REST 接口：端点总览与 JSON 约定

HTTP/REST 部分使用 JSON 作为数据交换格式，因为它被广泛支持且与语言无关。规范中的$number、$string、$boolean、$object、$array指 JSON 基础类型，#optional表示可选字段。需要特别注意的是：所有上下文中所有字符串均区分大小写。

对于 Seldon，服务器必须识别以下 URL。versions段是可选的，以兼容不支持版本化的实现，或当用户不指定模型版本时（此时由服务器按自身策略选择版本）：

Health（健康检查）：

GET v2/health/live GET v2/health/ready GET v2/models/${MODEL_NAME}[/versions/${MODEL_VERSION}]/ready

Server Metadata（服务器元数据）：

GET v2

Model Metadata（模型元数据）：

GET v2/models/${MODEL_NAME}[/versions/${MODEL_VERSION}]

Inference（推理）：

POST v2/models/${MODEL_NAME}[/versions/${MODEL_VERSION}]/infer

健康检查 API

健康检查请求通过 HTTP GET 发往健康端点，HTTP 响应状态码即布尔结果：200表示 true，4xx表示 false，响应体应为空。共三类健康 API：

• Server Live（服务器存活）：GET v2/health/live，指示推理服务器是否能接收并响应元数据与推理请求。该 API 可直接用于实现 KuberneteslivenessProbe。
• Server Ready（服务器就绪）：GET v2/health/ready，指示所有模型是否已就绪可用于推理。该 API 可直接用于实现 KubernetesreadinessProbe。
• Model Ready（模型就绪）：GET v2/models/${MODEL_NAME}[/versions/${MODEL_VERSION}]/ready，指示指定模型是否已就绪可用于推理。模型名（以及可选的版本）必须出现在 URL 中；若未提供版本，服务器可按自身策略选择。

仓库中的 OpenAPI 3.0.3 定义 open-inference-protocol-v2.openapi.yaml 完整覆盖了这些路径，并对模型级健康端点给出了重要的实战警告：模型级就绪端点只是向客户暴露模型状态，不应被用作 MLServer 容器的 KubernetesreadinessProbe。原因在于 Seldon 的加载流程存在依赖死锁风险：Seldon Agent 要等到 Pod IP 出现在 endpoints 中才开始下载模型；而 Pod IP 只有在 Pod Ready 或内部就绪检查通过后才发布；MLServer 容器又要等模型加载完才 Ready。因此容器级就绪检查应使用服务器级就绪端点（/v2/health/ready），它只表示 MLServer 进程已启动并可接受健康检查，不会阻塞模型加载流程。

服务器元数据 API

GET v2返回服务器信息。成功的请求以 200 状态码响应，HTTP body 包含$metadata_server_response对象：

$metadata_server_response = { "name" : $string, "version" : $string, "extensions" : [ $string, ... ] }

• name：服务器的描述性名称。
• version：服务器版本。
• extensions：服务器支持的扩展列表。目前没有定义标准扩展，各推理服务器可自行定义并文档化自己的扩展。

失败的元数据请求必须返回 HTTP 错误状态（通常为 400），body 包含$metadata_server_error_response对象：

$metadata_server_error_response = { "error": $string }

• error：错误的描述性消息。

模型元数据 API

GET v2/models/${MODEL_NAME}[/versions/${MODEL_VERSION}]提供单个模型的信息。模型名与（可选的）版本必须出现在 URL 中；若未提供版本，服务器可按自身策略选择版本或返回错误。成功响应（200）返回$metadata_model_response：

$metadata_model_response = { "name" : $string, "versions" : [ $string, ... ] #optional, "platform" : $string, "inputs" : [ $metadata_tensor, ... ], "outputs" : [ $metadata_tensor, ... ] }

• name：模型名称。
• versions：可通过相应端点显式请求的模型版本。对不支持版本化的服务器可选；对不允许显式请求版本的模型可选。
• platform：模型的框架/后端，取值见下文 平台（Platforms） 一节。
• inputs：模型所需的输入张量。
• outputs：模型产生的输出张量。

每个模型输入/输出张量的元数据由$metadata_tensor对象描述：

$metadata_tensor = { "name" : $string, "datatype" : $string, "shape" : [ $number, ... ] }

• name：张量名称。
• datatype：张量元素的数据类型，取值见下文 张量数据类型 一节。
• shape：张量形状，可变尺寸维度用 -1 表示。

失败的模型元数据请求返回 HTTP 错误状态（通常为 400），body 包含$metadata_model_error_response：

$metadata_model_error_response = { "error": $string }

推理 API

POST v2/models/${MODEL_NAME}[/versions/${MODEL_VERSION}]/infer发起一次推理请求。请求 body 为$inference_request，响应 body 为$inference_response（成功）或$inference_error_response（失败）。模型名与可选版本必须在 URL 中；未提供版本时服务器可按策略选择或返回错误。

推理请求对象（Inference Request）

$inference_request = { "id" : $string #optional, "parameters" : $parameters #optional, "inputs" : [ $request_input, ... ], "outputs" : [ $request_output, ... ] #optional }

• id：请求标识符。可选，但一旦指定就必须在响应中原样返回。
• parameters：零个或多个以键值对表达的推理请求参数，见下文 参数 一节。
• inputs：输入张量数组，每个输入遵循$request_input结构。
• outputs：请求返回的输出张量数组，遵循$request_output结构。可选；若不指定，则返回模型产生的全部输出（使用默认$request_output设置）。

Request Input

$request_input描述模型的一个输入。若输入是批量的，shape 与 data 必须表示整个批次的完整形状与内容：

$request_input = { "name" : $string, "shape" : [ $number, ... ], "datatype" : $string, "parameters" : $parameters #optional, "data" : $tensor_data }

• name：输入张量名称。
• shape：输入张量形状，每一维必须是可表示为无符号 64 位整数的整数。
• datatype：输入张量元素的数据类型。
• parameters：零个或多个输入参数键值对。
• data：张量内容，见下文 张量数据 一节。

Request Output

$request_output用于请求模型应返回哪些输出张量：

$request_output = { "name" : $string, "parameters" : $parameters #optional, }

• name：输出张量名称。
• parameters：零个或多个输出参数键值对。

推理响应对象（Inference Response）

成功的推理请求以 200 状态码响应，body 为$inference_response：

$inference_response = { "model_name" : $string, "model_version" : $string #optional, "id" : $string, "parameters" : $parameters #optional, "outputs" : [ $response_output, ... ] }

• model_name：用于推理的模型名称。
• model_version：实际用于推理的模型版本。未实现版本化的推理服务器不应在响应中提供该字段。
• id：请求中给定的id（如有）。
• parameters：零个或多个响应参数键值对。
• outputs：输出张量数组，每个输出遵循$response_output结构。

Response Output

$response_output描述模型的一个输出。若输出是批量的，shape 与 data 表示整个批次的完整形状：

$response_output = { "name" : $string, "shape" : [ $number, ... ], "datatype" : $string, "parameters" : $parameters #optional, "data" : $tensor_data }

• name：输出张量名称。
• shape：输出张量形状，每维必须是可表示为无符号 64 位整数的整数。
• datatype：输出张量元素的数据类型。
• parameters：零个或多个输出参数键值对。
• data：张量内容。

推理错误响应

失败的推理请求必须返回 HTTP 错误状态（通常为 400），body 为$inference_error_response：

$inference_error_response = { "error": <error message string> }

HTTP/REST 推理请求示例

以下示例展示向一个具有两个输入、一个输出的模型发起推理请求，Content-Length头给出了 JSON 对象的大小：

POST /v2/models/mymodel/infer HTTP/1.1 Host: localhost:8000 Content-Type: application/json Content-Length: <xx> { "id" : "42", "inputs" : [ { "name" : "input0", "shape" : [ 2, 2 ], "datatype" : "UINT32", "data" : [ 1, 2, 3, 4 ] }, { "name" : "input1", "shape" : [ 3 ], "datatype" : "BOOL", "data" : [ true ] } ], "outputs" : [ { "name" : "output0" } ] }

对于上述请求，推理服务器必须返回output0输出张量。假设模型返回一个 FP32 数据类型的[3, 2]张量，则响应如下：

HTTP/1.1 200 OK Content-Type: application/json Content-Length: <yy> { "id" : "42" "outputs" : [ { "name" : "output0", "shape" : [ 3, 2 ], "datatype" : "FP32", "data" : [ 1.0, 1.1, 2.0, 2.1, 3.0, 3.1 ] } ] }

注意：上述请求中的input1形状为[3]，但data只包含一个元素[true]，这属于示例原文的表述方式，实际使用时数据元素数量应与形状推断的元素数一致。该示例对应当前仓库 OpenAPI 文件中的 InferenceRequest 示例定义。

参数（Parameters）

$parameters描述零个或多个name/value键值对，name为参数名，value为$string、$number或$boolean：

$parameters = { $parameter, ... } $parameter = $string : $string | $number | $boolean

规范目前未定义任何标准参数。未来提案可能会定义一个或多个标准参数，以在不同推理服务器之间实现可移植功能；各服务器也可以实现服务器专属参数以提供非标准能力。

张量数据（Tensor Data）

张量数据必须以**行主序（row-major order）**呈现，元素值按"线性"顺序给出，元素之间不得有 stride 或 padding。张量元素既可以采用其自然的多维表示，也可以采用扁平化的一维表示。

显式给出的张量数据放在 JSON 数组中，每个元素可以是整数、浮点数、字符串或布尔值。服务器可以决定将每个元素强制转换为所需类型，或在收到意外值时返回错误。需要说明的是fp16 很难显式传输，因为各后端之间没有标准的 fp16 表示，通常也缺少为 JSON 数字构造 fp16 表示的编程支持。

例如 2 维矩阵：

[ 1 2 4 5 ]

既可以自然形式表示为：

"data" : [ [ 1, 2 ], [ 4, 5 ] ]

也可以扁平化为一维表示：

"data" : [ 1, 2, 4, 5 ]

GRPC 接口：GRPCInferenceService 服务

GRPC API 与 HTTP/REST 的概念一一对应，合规服务器必须实现本节描述的健康、元数据与推理 API。同样地，所有上下文中的字符串都区分大小写。

GRPC 服务定义如下：

// // Inference Server GRPC endpoints. // service GRPCInferenceService { // Check liveness of the inference server. rpc ServerLive(ServerLiveRequest) returns (ServerLiveResponse) {} // Check readiness of the inference server. rpc ServerReady(ServerReadyRequest) returns (ServerReadyResponse) {} // Check readiness of a model in the inference server. rpc ModelReady(ModelReadyRequest) returns (ModelReadyResponse) {} // Get server metadata. rpc ServerMetadata(ServerMetadataRequest) returns (ServerMetadataResponse) {} // Get model metadata. rpc ModelMetadata(ModelMetadataRequest) returns (ModelMetadataResponse) {} // Perform inference using a specific model. rpc ModelInfer(ModelInferRequest) returns (ModelInferResponse) {} }

这个服务定义与仓库中的 v2_dataplane.proto 完全对应，后者还额外扩展了ModelStreamInfer（双向流式推理）以及来自 Triton 模型仓库控制面的RepositoryIndex、RepositoryModelLoad、RepositoryModelUnload三个 RPC。

健康检查（Health）

健康请求通过ServerLive、ServerReady或ModelReady端点发起，错误通过请求返回的google.rpc.Status指示，OK码表示成功，其他码表示失败。

ServerLive指示推理服务器是否能够接收并响应元数据与推理请求：

message ServerLiveRequest {} message ServerLiveResponse { // True if the inference server is live, false if not live. bool live = 1; }

ServerReady指示服务器是否已就绪可用于推理：

message ServerReadyRequest {} message ServerReadyResponse { // True if the inference server is ready, false if not ready. bool ready = 1; }

ModelReady指示指定模型是否已就绪可用于推理：

message ModelReadyRequest { // The name of the model to check for readiness. string name = 1; // The version of the model to check for readiness. If not given the // server will choose a version based on the model and internal policy. string version = 2; } message ModelReadyResponse { // True if the model is ready, false if not ready. bool ready = 1; }

服务器元数据（Server Metadata）

ServerMetadata提供服务器信息，错误通过google.rpc.Status指示：

message ServerMetadataRequest {} message ServerMetadataResponse { // The server name. string name = 1; // The server version. string version = 2; // The extensions supported by the server. repeated string extensions = 3; }

模型元数据（Model Metadata）

ModelMetadata提供单个模型的信息：

message ModelMetadataRequest { // The name of the model. string name = 1; // The version of the model to check for readiness. If not given the // server will choose a version based on the model and internal policy. string version = 2; } message ModelMetadataResponse { // Metadata for a tensor. message TensorMetadata { // The tensor name. string name = 1; // The tensor data type. string datatype = 2; // The tensor shape. A variable-size dimension is represented // by a -1 value. repeated int64 shape = 3; } // The model name. string name = 1; // The versions of the model available on the server. repeated string versions = 2; // The model's platform. See Platforms. string platform = 3; // The model's inputs. repeated TensorMetadata inputs = 4; // The model's outputs. repeated TensorMetadata outputs = 5; }

需要说明的是，Seldon 的 v2_dataplane.proto 在标准TensorMetadata与ModelMetadataResponse基础上增加了map<string, InferParameter> parameters扩展字段（注释明确标注 "NOTE: This is an extension to the standard"），用于携带输入默认参数与请求/响应默认参数——这正是协议扩展机制的落地示例。

推理（Inference）

ModelInfer使用指定模型执行推理，错误通过google.rpc.Status指示：

message ModelInferRequest { // An input tensor for an inference request. message InferInputTensor { // The tensor name. string name = 1; // The tensor data type. string datatype = 2; // The tensor shape. repeated int64 shape = 3; // Optional inference input tensor parameters. map<string, InferParameter> parameters = 4; // The tensor contents using a>赞分享