Method: projects.predict

Performs online prediction on the data in the request.

AI Explanations 可以在 HTTP POST 方法的基础上实现自定义 predict 谓词。predict 方法会根据请求中的数据执行预测。

网址采用 Google API HTTP 注释语法:

POST https://ml.googleapis.com/v1/{name=projects/**}:predict

name 为必需参数,其中必须包含模型名称,您也可选择性地加入版本。如果您指定了模型而未指定版本,则系统将使用该模型的默认版本。

以下是同时指定了模型和版本的示例:

POST https://ml.googleapis.com/v1/projects/your-project-id/models/your-model-name/versions/your-version-name:predict

以下是仅指定了模型的示例,其中使用的是模型的默认版本:

POST https://ml.googleapis.com/v1/projects/your-project-id/models/your-model-name:predict

本页面介绍预测请求正文和响应正文的格式。如需查看展示如何发送预测请求的代码示例,请参阅请求在线预测指南。

请求正文详情

TensorFlow

请求正文包含的数据采用以下结构(JSON 表示法):

{
  "instances": [
    <value>|<simple/nested list>|<object>,
    ...
  ]
}

instances[] 是必需对象,而且必须包含待预测实例的列表。

实例列表中每个元素的结构由模型的输入定义决定。实例可包含命名输入(作为对象),或者仅包含未加标签的值。

并非所有数据都包含命名输入。有些实例是简单的 JSON 值(布尔值、数字或字符串)。但是,实例通常是简单值列表或复杂的嵌套列表。

以下是请求正文的一些示例。

CSV 数据,其中每行编码为字符串值:

{"instances": ["1.0,true,\\"x\\"", "-2.0,false,\\"y\\""]}

纯文本:

{"instances": ["the quick brown fox", "the lazy dog"]}

编码为字词列表的句子(字符串矢量):

{
  "instances": [
    ["the","quick","brown"],
    ["the","lazy","dog"],
    ...
  ]
}

浮点标量值:

{"instances": [0.0, 1.1, 2.2]}

整数矢量:

{
  "instances": [
    [0, 1, 2],
    [3, 4, 5],
    ...
  ]
}

张量(在本示例中为二维张量):

{
  "instances": [
    [
      [0, 1, 2],
      [3, 4, 5]
    ],
    ...
  ]
}

图片,可通过不同方式来表示。在本编码方案中,前两个维度表示图片的行和列,第三个维度包含每个像素的 R、G 和 B 值的列表(矢量):

{
  "instances": [
    [
      [
        [138, 30, 66],
        [130, 20, 56],
        ...
      ],
      [
        [126, 38, 61],
        [122, 24, 57],
        ...
      ],
      ...
    ],
    ...
  ]
}

数据编码

JSON 字符串必须采用 UTF-8 编码。如要发送二进制数据,您必须对数据进行 base64 编码并将数据标记为二进制。如要将 JSON 字符串标记为二进制,请将其替换为具有单一 b64 特性的 JSON 对象:

{"b64": "..."} 

以下示例展示了两个需要 base64 编码的序列化 tf.Examples 实例(虚构的数据,仅作说明之用):

{"instances": [{"b64": "X5ad6u"}, {"b64": "IA9j4nx"}]}

以下示例显示两个需要 base64 编码的 JPEG 图片字节字符串(虚构的数据,仅作说明之用):

{"instances": [{"b64": "ASa8asdf"}, {"b64": "JLK7ljk3"}]}

多个输入张量

一些模型具有可接受多个输入张量的底层 TensorFlow 图。在这种情况下,请使用 JSON 名称/值对的名称来识别输入张量。

对于带有输入张量别名“tag”(字符串)和“image”(base64 编码的字符串)的图,请使用以下代码:

{
  "instances": [
    {
      "tag": "beach",
      "image": {"b64": "ASa8asdf"}
    },
    {
      "tag": "car",
      "image": {"b64": "JLK7ljk3"}
    }
  ]
}

对于带有输入张量别名“tag”(字符串)和“image”(8 位整数的三维数组)的图,请使用以下代码:

{
  "instances": [
    {
      "tag": "beach",
      "image": [
        [
          [138, 30, 66],
          [130, 20, 56],
          ...
        ],
        [
          [126, 38, 61],
          [122, 24, 57],
          ...
        ],
        ...
      ]
    },
    {
      "tag": "car",
      "image": [
        [
          [255, 0, 102],
          [255, 0, 97],
          ...
        ],
        [
          [254, 1, 101],
          [254, 2, 93],
          ...
        ],
        ...
      ]
    },
    ...
  ]
}

scikit-learn

请求正文包含的数据采用以下结构(JSON 表示法):

{
  "instances": [
    <simple list>,
    ...
  ]
}

instances[] 是必需对象,而且必须包含待预测实例的列表。在以下示例中,每个输入实例都是一个浮点数列表:

{
  "instances": [
    [0.0, 1.1, 2.2],
    [3.3, 4.4, 5.5],
    ...
  ]
}

输入实例的维度必须与模型所期望的维度一致。例如,如果模型需要三个特征,则每个输入实例的长度必须为 3。

XGBoost

请求正文包含的数据采用以下结构(JSON 表示法):

{
  "instances": [
    <simple list>,
    ...
  ]
}

instances[] 是必需对象,而且必须包含待预测实例的列表。在以下示例中,每个输入实例都是一个浮点数列表:

{
  "instances": [
    [0.0, 1.1, 2.2],
    [3.3, 4.4, 5.5],
    ...
  ]
}

输入实例的维度必须与模型所期望的维度一致。例如,如果模型需要三个特征,则每个输入实例的长度必须为 3。

对于 XGBoost 的输入实例,AI Platform 不支持稀疏表示法。

在线预测服务以不同方式解析零和 NaN。如果特征值为零,请使用 0.0 作为相应的输入。如果缺少特征值,请使用 NaN 作为相应的输入。

以下示例表示具有单个输入实例的预测请求,其中第一个特征的值是 0.0,第二个特征的值是 1.1,第三个特征的值缺失:

{"instances": [[0.0, 1.1, NaN]]}

自定义预测例程

请求正文包含的数据采用以下结构(JSON 表示法):

{
  "instances": [
    <value>|<simple/nested list>|<object>,
    ...
  ],
  "<other-key>": <value>|<simple/nested list>|<object>,
  ...
}

instances[] 是必需对象,而且必须包含待预测实例的列表。

您可以选择提供任何其他有效的 JSON 键值对。 AI Platform Prediction 会解析 JSON,并将这些字段作为 **kwargs 字典中的条目提供给 Predictor 类别predict 方法。

如何设计实例列表的结构

实例列表中每个元素的结构取决于 Predictor 类别predict 方法。 实例可包含命名输入(作为对象),或者仅包含未加标签的值。

并非所有数据都包含命名输入。有些实例是简单的 JSON 值(布尔值、数字或字符串)。但是,实例通常是简单值列表或复杂的嵌套列表。

以下是请求正文的一些示例。

CSV 数据,其中每行编码为字符串值:

{"instances": ["1.0,true,\\"x\\"", "-2.0,false,\\"y\\""]}

纯文本:

{"instances": ["the quick brown fox", "the lazy dog"]}

编码为字词列表的句子(字符串矢量):

{
  "instances": [
    ["the","quick","brown"],
    ["the","lazy","dog"],
    ...
  ]
}

浮点标量值:

{"instances": [0.0, 1.1, 2.2]}

整数矢量:

{
  "instances": [
    [0, 1, 2],
    [3, 4, 5],
    ...
  ]
}

张量(在本示例中为二维张量):

{
  "instances": [
    [
      [0, 1, 2],
      [3, 4, 5]
    ],
    ...
  ]
}

图片,可通过不同方式来表示。在本编码方案中,前两个维度表示图片的行和列,第三个维度包含每个像素的 R、G 和 B 值的列表(矢量):

{
  "instances": [
    [
      [
        [138, 30, 66],
        [130, 20, 56],
        ...
      ],
      [
        [126, 38, 61],
        [122, 24, 57],
        ...
      ],
      ...
    ],
    ...
  ]
}

多个输入张量

一些模型具有可接受多个输入张量的底层 TensorFlow 图。在这种情况下,请使用 JSON 名称/值对的名称来识别输入张量。

对于带有输入张量别名“tag”(字符串)和“image”(8 位整数的三维数组)的图,请使用以下代码:

{
  "instances": [
    {
      "tag": "beach",
      "image": [
        [
          [138, 30, 66],
          [130, 20, 56],
          ...
        ],
        [
          [126, 38, 61],
          [122, 24, 57],
          ...
        ],
        ...
      ]
    },
    {
      "tag": "car",
      "image": [
        [
          [255, 0, 102],
          [255, 0, 97],
          ...
        ],
        [
          [254, 1, 101],
          [254, 2, 93],
          ...
        ],
        ...
      ]
    },
    ...
  ]
}

响应正文详情

响应与请求十分相似。

如果调用成功,则对于请求正文中的每个实例,响应正文都包含一个预测条目,并按相同顺序列出:

{
  "predictions": [
    {
      object
    }
  ]
}

如有任何实例的预测失败,则响应正文不会包含任何预测条目, 而是包含一个错误条目:

{
  "error": string
}

predictions[] 对象包含预测结果列表,其中每个预测结果对应请求中的一个实例。对于自定义预测例程(Beta 版),predictions 包含 Predictor 类别 predict 方法的返回值(已序列化为 JSON 格式)。

如果发生错误,error 字符串会包含一条描述问题的消息。如果在处理任何实例时发生错误,则系统会返回错误,而非预测结果列表。

即使每个实例只有一个预测结果,预测结果的格式也与实例的格式没有直接关联。预测结果的格式是由模型中定义的输出集合所指定。预测结果集合会以 JSON 列表的形式返回。列表的每个成员可以是简单值、列表或任何复杂度的 JSON 对象。如果模型具有多个输出张量,则每个预测结果将为 JSON 对象,其中包含每个输出的名称/值对。这些名称可标识图中的输出别名。

响应正文示例

TensorFlow

以下示例展示了一些可能的响应:

  • 三个输入实例的一组简单预测结果,其中每个预测结果均为一个整数值:

    {"predictions": [5, 4, 3]}
    
  • 一组较复杂的预测结果,各包含两个与输出张量相对应的命名值,分别名为 labelscoreslabel 的值是预测的类别(“car”或“beach”),scores 包含该实例在各可能类别之间的概率列表。

    {
      "predictions": [
        {
          "label": "beach",
          "scores": [0.1, 0.9]
        },
        {
          "label": "car",
          "scores": [0.75, 0.25]
        }
      ]
    }
    
  • 处理输入实例出错时的响应:

    {"error": "Divide by zero"}
    

scikit-learn

以下示例展示了一些可能的响应:

  • 三个输入实例的一组简单预测结果,其中每个预测结果均为一个整数值:

    {"predictions": [5, 4, 3]}
    
  • 处理输入实例出错时的响应:

    {"error": "Divide by zero"}
    

XGBoost

以下示例展示了一些可能的响应:

  • 三个输入实例的一组简单预测结果,其中每个预测结果均为一个整数值:

    {"predictions": [5, 4, 3]}
    
  • 处理输入实例出错时的响应:

    {"error": "Divide by zero"}
    

自定义预测例程

以下示例展示了一些可能的响应:

  • 三个输入实例的一组简单预测结果,其中每个预测结果均为一个整数值:

    {"predictions": [5, 4, 3]}
    
  • 一组较复杂的预测结果,各包含两个与输出张量相对应的命名值,分别名为 labelscoreslabel 的值是预测的类别(“car”或“beach”),scores 包含该实例在各可能类别之间的概率列表。

    {
      "predictions": [
        {
          "label": "beach",
          "scores": [0.1, 0.9]
        },
        {
          "label": "car",
          "scores": [0.75, 0.25]
        }
      ]
    }
    
  • 处理输入实例出错时的响应:

    {"error": "Divide by zero"}
    

API 规范

以下部分介绍了 AI Platform Training and Prediction API 发现文档中定义的 predict 方法规范。如需详细了解此方法,请参阅本文档前面的部分。

HTTP request

POST https://{endpoint}/v1/{name=projects/**}:predict

Where {endpoint} is one of the supported service endpoints.

The URLs use gRPC Transcoding syntax.

Path parameters

Parameters
name

string

Required. The resource name of a model or a version.

Authorization: requires the predict permission on the specified resource.

Authorization requires one or more of the following IAM permissions on the specified resource name:

  • ml.models.predict
  • ml.versions.predict

Request body

The request body contains data with the following structure:

JSON representation
{
  "httpBody": {
    object (HttpBody)
  }
}
Fields
httpBody

object (HttpBody)

Required. The prediction request body. Refer to the request body details section for more information on how to structure your request.

Response body

If successful, the response is a generic HTTP response whose format is defined by the method.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.