创建和管理预测结果

本页面介绍如何创建和管理 AML AI 预测结果。预测结果会保存到 BigQuery 表中。

此时，您只需创建预测结果并导出关联的元数据。为方便起见，我们还提供了其他预测结果方法。

准备工作

创建预测结果

某些 API 方法会返回长时间运行的操作 (LRO)。这些方法是异步的。当该方法返回响应时，操作可能尚未完成。对于这些方法，请发送请求，然后检查结果。

发送请求

如需创建预测结果，请使用 projects.locations.instances.predictionResults.create 方法。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：IAM 设置中列出的 Google Cloud 项目 ID
  • LOCATION：实例的位置；请使用支持的区域之一：
    • us-central1
    • us-east1
    • asia-south1
    • europe-west1
    • europe-west2
    • europe-west4
    • northamerica-northeast1
    • southamerica-east1
  • INSTANCE_ID：用户定义的实例标识符
  • PREDICTION_RESULTS_ID：用户定义的预测结果标识符
  • MODEL_ID：用户定义的模型标识符
  • DATASET_ID：用于预测的数据集的用户定义的标识符；表不应包含训练标签列
  • PREDICTION_END_DATE：使用数据生成用于预测的特征的最晚时间。此日期应与数据集的结束时间相同或更早。请使用 RFC3339 世界协调时间 (UTC)“祖鲁语”格式（例如 2014-10-02T15:01:23Z）。
  • PREDICTION_PERIODS：要生成预测的连续月份数，结束于预测结束日期之前的最后一个完整月份（采用数据集的时区）。
  • BQ_OUTPUT_DATASET_NAME：用于预测的输出 BigQuery 数据集的名称
  • BQ_OUTPUT_PREDICTION_TABLE：用于预测的 BigQuery 输出表的用户定义的标识符
  • BQ_OUTPUT_PREDICTION_EXPLAINABILITY_TABLE：用于预测的输出可解释性 BigQuery 表的用户定义的标识符；如果您不想导出到 BigQuery 表，请从请求 JSON 中移除可选的 explainabilityDestination 对象
  • WRITE_DISPOSITION：在目标表已存在时发生的操作；请使用以下某个值：
    • WRITE_EMPTY：仅在 BigQuery 表为空时导出数据。
    • WRITE_TRUNCATE：先清空 BigQuery 表中的所有现有数据，然后再写入表。

请求 JSON 正文：

{
    "model": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models/MODEL_ID",
    "dataset": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/datasets/DATASET_ID",
    "endTime": "PREDICTION_END_DATE",
    "predictionPeriods": "PREDICTION_PERIODS",
    "outputs": {
      "predictionDestination": {
        "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.BQ_OUTPUT_PREDICTION_TABLE",
        "writeDisposition": "WRITE_DISPOSITION"
      },
      "explainabilityDestination": {
        "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.BQ_OUTPUT_PREDICTION_EXPLAINABILITY_TABLE",
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令，在当前目录中创建或覆盖此文件：

cat > request.json << 'EOF'
{
    "model": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models/MODEL_ID",
    "dataset": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/datasets/DATASET_ID",
    "endTime": "PREDICTION_END_DATE",
    "predictionPeriods": "PREDICTION_PERIODS",
    "outputs": {
      "predictionDestination": {
        "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.BQ_OUTPUT_PREDICTION_TABLE",
        "writeDisposition": "WRITE_DISPOSITION"
      },
      "explainabilityDestination": {
        "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.BQ_OUTPUT_PREDICTION_EXPLAINABILITY_TABLE",
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
}
EOF

然后，执行以下命令以发送 REST 请求：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "http://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/predictionResults?prediction_result_id=PREDICTION_RESULTS_ID"

PowerShell

将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令，在当前目录中创建或覆盖此文件：

@'
{
    "model": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models/MODEL_ID",
    "dataset": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/datasets/DATASET_ID",
    "endTime": "PREDICTION_END_DATE",
    "predictionPeriods": "PREDICTION_PERIODS",
    "outputs": {
      "predictionDestination": {
        "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.BQ_OUTPUT_PREDICTION_TABLE",
        "writeDisposition": "WRITE_DISPOSITION"
      },
      "explainabilityDestination": {
        "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.BQ_OUTPUT_PREDICTION_EXPLAINABILITY_TABLE",
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
}
'@  | Out-File -FilePath request.json -Encoding utf8

然后，执行以下命令以发送 REST 请求：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "http://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/predictionResults?prediction_result_id=PREDICTION_RESULTS_ID" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata",
    "createTime": CREATE_TIME,
    "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/predictionResults/PREDICTION_RESULTS_ID",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

查看结果

使用 projects.locations.operations.get 方法检查是否已创建预测结果。如果响应包含 "done": false，请重复该命令，直到响应包含 "done": true。这些操作可能需要几分钟到几小时才能完成。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：IAM 设置中列出的 Google Cloud 项目 ID
  • LOCATION：实例的位置；请使用支持的区域之一：
    • us-central1
    • us-east1
    • asia-south1
    • europe-west1
    • europe-west2
    • europe-west4
    • northamerica-northeast1
    • southamerica-east1
  • OPERATION_ID：操作的标识符

如需发送请求，请选择以下方式之一：

curl

执行以下命令： 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "http://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"

PowerShell

执行以下命令： 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "http://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata",
    "createTime": CREATE_TIME,
    "endTime": END_TIME,
    "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/predictionResults/PREDICTION_RESULTS_ID",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/dataresidency.monitoring.DataResidencyAugmentedView",
    "tpIds": [
      "i608e8cf4abb2a7d9-tp"
    ]
  }
}

导出元数据

如需从预测结果中导出元数据，请使用 projects.locations.instances.predictionResults.exportMetadata 方法。

如需了解详情，请参阅 AML 输出数据模型中导出的元数据。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：IAM 设置中列出的 Google Cloud 项目 ID
  • LOCATION：实例的位置；请使用支持的区域之一：
    • us-central1
    • us-east1
    • asia-south1
    • europe-west1
    • europe-west2
    • europe-west4
    • northamerica-northeast1
    • southamerica-east1
  • INSTANCE_ID：用户定义的实例标识符
  • PREDICTION_RESULTS_ID：用户定义的预测结果标识符
  • BQ_OUTPUT_DATASET_NAME：BigQuery 数据集，用于导出描述预测结果的结构化元数据的表
  • STRUCTURED_METADATA_TABLE：要向其中写入结构化元数据的表
  • WRITE_DISPOSITION：在目标表已存在时发生的操作；请使用以下某个值：
    • WRITE_EMPTY：仅在 BigQuery 表为空时导出数据。
    • WRITE_TRUNCATE：先清空 BigQuery 表中的所有现有数据，然后再写入表。

请求 JSON 正文：

{
  "structuredMetadataDestination": {
    "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.STRUCTURED_METADATA_TABLE",
    "writeDisposition": "WRITE_DISPOSITION"
  }
}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令，在当前目录中创建或覆盖此文件：

cat > request.json << 'EOF'
{
  "structuredMetadataDestination": {
    "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.STRUCTURED_METADATA_TABLE",
    "writeDisposition": "WRITE_DISPOSITION"
  }
}
EOF

然后，执行以下命令以发送 REST 请求：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "http://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/predictionResults/PREDICTION_RESULTS_ID:exportMetadata"

PowerShell

将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令，在当前目录中创建或覆盖此文件：

@'
{
  "structuredMetadataDestination": {
    "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.STRUCTURED_METADATA_TABLE",
    "writeDisposition": "WRITE_DISPOSITION"
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

然后，执行以下命令以发送 REST 请求：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "http://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/predictionResults/PREDICTION_RESULTS_ID:exportMetadata" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata",
    "createTime": CREATE_TIME,
    "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/predictionResults/PREDICTION_RESULTS_ID",
    "verb": "exportMetadata",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

如需详细了解如何获取长时间运行的操作 (LRO) 的结果，请参阅检查结果。

可选方法

为方便起见，我们提供以下预测结果方法。

获取预测结果

如需获取预测结果，请使用 projects.locations.instances.predictionResults.get 方法。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：IAM 设置中列出的 Google Cloud 项目 ID
  • LOCATION：实例的位置；请使用支持的区域之一：
    • us-central1
    • us-east1
    • asia-south1
    • europe-west1
    • europe-west2
    • europe-west4
    • northamerica-northeast1
    • southamerica-east1
  • INSTANCE_ID：用户定义的实例标识符
  • PREDICTION_RESULTS_ID：用户定义的预测结果标识符

如需发送请求，请选择以下方式之一：

curl

执行以下命令： 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "http://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/predictionResults/PREDICTION_RESULTS_ID"

PowerShell

执行以下命令： 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "http://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/predictionResults/PREDICTION_RESULTS_ID" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应：

{
    "name": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/predictionResults/PREDICTION_RESULTS_ID",
    "createTime": CREATE_TIME,
    "updateTime": UPDATE_TIME,
    "state": "ACTIVE",
    "model": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models/MODEL_ID",
    "dataset": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/datasets/DATASET_ID",
    "endTime": "PREDICTION_END_DATE",
    "predictionPeriods": PREDICTION_PERIODS,
    "outputs": {
      "predictionDestination": {
        "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.BQ_OUTPUT_PREDICTION_TABLE",
        "writeDisposition": "WRITE_DISPOSITION"
      },
      "explainabilityDestination": {
        "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.BQ_OUTPUT_PREDICTION_EXPLAINABILITY_TABLE",
        "writeDisposition": "WRITE_DISPOSITION"
      }
    },
    "lineOfBusiness": "RETAIL"
}

更新预测结果

如需更新预测结果，请使用 projects.locations.instances.predictionResults.patch 方法。

预测结果中的部分字段无法更新。以下示例会更新与预测结果关联的键值对用户标签。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：IAM 设置中列出的 Google Cloud 项目 ID
  • LOCATION：实例的位置；请使用支持的区域之一：
    • us-central1
    • us-east1
    • asia-south1
    • europe-west1
    • europe-west2
    • europe-west4
    • northamerica-northeast1
    • southamerica-east1
  • INSTANCE_ID：用户定义的实例标识符
  • PREDICTION_RESULTS_ID：用户定义的预测结果标识符
  • KEY：键值对中的键，用于整理预测结果。如需了解详情，请参阅 labels。
  • VALUE：键值对中的值，用于整理预测结果。如需了解详情，请参阅 labels。

请求 JSON 正文：

{
  "labels": {
    "KEY": "VALUE"
  }
}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令，在当前目录中创建或覆盖此文件：

cat > request.json << 'EOF'
{
  "labels": {
    "KEY": "VALUE"
  }
}
EOF

然后，执行以下命令以发送 REST 请求：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "http://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/predictionResults/PREDICTION_RESULTS_ID?updateMask=labels"

PowerShell

将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令，在当前目录中创建或覆盖此文件：

@'
{
  "labels": {
    "KEY": "VALUE"
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

然后，执行以下命令以发送 REST 请求：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "http://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/predictionResults/PREDICTION_RESULTS_ID?updateMask=labels" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata",
    "createTime": CREATE_TIME,
    "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/predictionResults/PREDICTION_RESULTS_ID",
    "verb": "update",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

如需详细了解如何获取长时间运行的操作 (LRO) 的结果，请参阅检查结果。

列出预测结果

如需列出给定实例的预测结果，请使用 projects.locations.instances.predictionResults.list 方法。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：IAM 设置中列出的 Google Cloud 项目 ID
  • LOCATION：实例的位置；请使用支持的区域之一：
    • us-central1
    • us-east1
    • asia-south1
    • europe-west1
    • europe-west2
    • europe-west4
    • northamerica-northeast1
    • southamerica-east1
  • INSTANCE_ID：用户定义的实例标识符

如需发送请求，请选择以下方式之一：

curl

执行以下命令： 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "http://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/predictionResults"

PowerShell

执行以下命令： 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "http://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/predictionResults" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应：

{
  "predictionResults": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/predictionResults/PREDICTION_RESULTS_ID",
      "createTime": CREATE_TIME,
      "updateTime": UPDATE_TIME,
      "state": "ACTIVE",
      "model": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/models/MODEL_ID",
      "dataset": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/datasets/DATASET_ID",
      "endTime": "PREDICTION_END_DATE",
      "predictionPeriods": PREDICTION_PERIODS,
      "outputs": {
        "predictionDestination": {
          "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.BQ_OUTPUT_PREDICTION_TABLE",
          "writeDisposition": "WRITE_DISPOSITION"
        },
        "explainabilityDestination": {
          "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.BQ_OUTPUT_PREDICTION_EXPLAINABILITY_TABLE",
          "writeDisposition": "WRITE_DISPOSITION"
        }
      },
      "lineOfBusiness": "RETAIL"
    }
  ]
}

删除预测结果

如需删除预测结果，请使用 projects.locations.instances.predictionResults.delete 方法。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：IAM 设置中列出的 Google Cloud 项目 ID
  • LOCATION：实例的位置；请使用支持的区域之一：
    • us-central1
    • us-east1
    • asia-south1
    • europe-west1
    • europe-west2
    • europe-west4
    • northamerica-northeast1
    • southamerica-east1
  • INSTANCE_ID：用户定义的实例标识符
  • PREDICTION_RESULTS_ID：用户定义的预测结果标识符

如需发送请求，请选择以下方式之一：

curl

执行以下命令： 

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "http://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/predictionResults/PREDICTION_RESULTS_ID"

PowerShell

执行以下命令： 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "http://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/predictionResults/PREDICTION_RESULTS_ID" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata",
    "createTime": CREATE_TIME,
    "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/predictionResults/PREDICTION_RESULTS_ID",
    "verb": "delete",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

如需详细了解如何获取长时间运行的操作 (LRO) 的结果，请参阅检查结果。