記錄要求與回應

Vertex AI 可為 Gemini 和支援的合作夥伴模型記錄要求和回應的樣本。記錄會儲存至 BigQuery 表格，方便您查看及分析。本頁面說明如何為基礎模型和精細調整模型設定要求-回應記錄。

支援的記錄 API 方法

所有使用 generateContent 或 streamGenerateContent 的 Gemini 模型都支援要求-回應記錄。

系統也支援使用 rawPredict 或 streamrawPredict 的下列合作夥伴模型：

  • Anthropic Claude

基礎模型的要求/回應記錄

您可以使用 REST API 或 Python SDK，為基礎模型設定要求-回應記錄。記錄設定可能需要幾分鐘才會生效。

啟用要求/回應記錄

請選取下列任一分頁，瞭解如何為基礎模型啟用要求回應記錄。

對於人類模型，只有 REST 支援記錄設定。將發布者設為 anthropic，並將模型名稱設為 支援的 Claude 模型，即可透過 REST API 啟用記錄設定。

Python SDK

這個方法可用來建立或更新 PublisherModelConfig。

publisher_model = GenerativeModel('gemini-2.0-pro-001')

# Set logging configuration
publisher_model.set_request_response_logging_config(
    enabled=True,
    sampling_rate=1.0,
    bigquery_destination="bq://PROJECT_ID.DATASET_NAME.TABLE_NAME",
    enable_otel_logging=True
    )

REST API

使用 setPublisherModelConfig 建立或更新 PublisherModelConfig：

使用任何要求資料之前，請先替換以下項目：

  • ENDPOINT_PREFIX：模型資源的區域，後面接著 -。例如 us-central1-。如果使用全域端點，請留空。系統支援模型支援的所有地區的請求-回應記錄功能。
  • PROJECT_ID：您的專案 ID。
  • LOCATION：模型資源的區域。如果使用全域端點，請輸入 global。
  • PUBLISHER：發布者名稱。例如：google。
  • MODEL：基礎模型名稱。例如：gemini-2.0-flash-001。
  • SAMPLING_RATE：為降低儲存空間費用，您可以設定介於 0 到 1 之間的數字，用於定義要記錄之要求的比例。舉例來說，值為 1 會記錄所有要求，值為 0.1 則會記錄 10% 的要求。
  • BQ_URI：用於記錄的 BigQuery 資料表。如果您只指定專案名稱，系統會建立名為 logging_ENDPOINT_DISPLAY_NAME\_ENDPOINT_ID 的新資料集，其中 ENDPOINT_DISPLAY_NAME 會遵循 BigQuery 命名規則。如果未指定資料表名稱，系統會建立名為 request_response_logging 的新資料表。

HTTP 方法和網址：

POST https://ENDPOINT_PREFIXaiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/PUBLISHER/models/MODEL:setPublisherModelConfig

JSON 要求主體：

{
  "publisherModelConfig": {
     "loggingConfig": {
       "enabled": true,
       "samplingRate": SAMPLING_RATE,
       "bigqueryDestination": {
         "outputUri": "BQ_URI"
       },
       "enableOtelLogging": true
     }
   }
 }

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://ENDPOINT_PREFIXaiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/PUBLISHER/models/MODEL:setPublisherModelConfig"

PowerShell

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$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 "https://ENDPOINT_PREFIXaiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/PUBLISHER/models/MODEL:setPublisherModelConfig" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

取得記錄設定

使用 REST API 取得基礎模型的要求-回應記錄設定。

REST API

使用 fetchPublisherModelConfig 取得要求/回應記錄設定：

使用任何要求資料之前，請先替換以下項目：

  • PROJECT_ID：您的專案 ID。
  • LOCATION：模型資源的位置。
  • PUBLISHER：發布者名稱。例如：google。
  • MODEL：基礎模型名稱。例如：gemini-2.0-flash-001。

HTTP 方法和網址：

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/PUBLISHER/models/MODEL:fetchPublisherModelConfig

如要傳送要求，請選擇以下其中一個選項：

curl

執行下列指令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/PUBLISHER/models/MODEL:fetchPublisherModelConfig"

PowerShell

執行下列指令：

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/PUBLISHER/models/MODEL:fetchPublisherModelConfig" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

停用記錄

使用 REST API 或 Python SDK，停用基礎模型的要求回應記錄功能。

Python SDK

publisher_model.set_request_response_logging_config(
  enabled=False,
  sampling_rate=0,
  bigquery_destination=''
  )

REST API

使用 setPublisherModelConfig 停用記錄功能：

使用任何要求資料之前，請先替換以下項目：

  • PROJECT_ID：您的專案 ID。
  • LOCATION：模型資源的位置。
  • PUBLISHER：發布者名稱。例如：google。
  • MODEL：基礎模型名稱。例如：gemini-2.0-flash-001。

HTTP 方法和網址：

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/PUBLISHER/models/MODEL:setPublisherModelConfig

JSON 要求主體：

{
  "publisherModelConfig": {
     "loggingConfig": {
       "enabled": false
     }
  }
}

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/PUBLISHER/models/MODEL:setPublisherModelConfig"

PowerShell

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$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 "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/PUBLISHER/models/MODEL:setPublisherModelConfig" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

經過微調的模型要求/回應記錄

您可以使用 REST API 或 Python SDK，為精細調整的模型設定要求/回應記錄。

啟用要求/回應記錄

請選取下列任一分頁，瞭解如何為精調模型啟用要求-回應記錄。

Python SDK

這個方法可用於更新端點的要求/回應記錄設定。

tuned_model = GenerativeModel("projects/PROJECT_ID/locations/REGION/endpoints/ENDPOINT_ID")

# Set logging configuration
tuned_model.set_request_response_logging_config(
    enabled=True,
    sampling_rate=1.0,
    bigquery_destination="bq://PROJECT_ID.DATASET_NAME.TABLE_NAME",
    enable_otel_logging=True
    )

REST API

您只能使用 projects.locations.endpoints.create 建立端點，或使用 projects.locations.endpoints.patch 修補現有端點時，才能啟用要求/回應記錄。

要求和回應會在端點層級記錄，因此系統會記錄傳送至相同端點下任何已部署模型的要求。

建立或修補端點時，請在端點資源的 predictRequestResponseLoggingConfig 欄位中填入以下項目：

  • enabled：設為 True 可啟用要求/回應記錄。

  • samplingRate：為降低儲存空間費用，您可以設定介於 0 到 1 之間的數字，用於定義要記錄之要求的比例。舉例來說，值為 1 會記錄所有要求，值為 0.1 則會記錄 10% 的要求。

  • BigQueryDestination：用於記錄的 BigQuery 資料表。如果您只指定專案名稱，系統會建立名為 logging_ENDPOINT_DISPLAY_NAME_ENDPOINT_ID 的新資料集，其中 ENDPOINT_DISPLAY_NAME 會遵循 BigQuery 命名規則。如果未指定資料表名稱，系統會建立名為 request_response_logging 的新資料表。

  • enableOtelLogging：將其設為 true，即可啟用 OpenTelemetry (OTEL) 記錄，以及預設的要求-回應記錄。

如要查看 BigQuery 資料表結構定義，請參閱「記錄資料表結構定義」。

以下為設定範例：

{
  "predictRequestResponseLoggingConfig": {
    "enabled": true,
    "samplingRate": 0.5,
    "bigqueryDestination": {
      "outputUri": "bq://PROJECT_ID.DATASET_NAME.TABLE_NAME"
    },
    "enableOtelLogging": true
  }
}

取得記錄設定

使用 REST API 取得精細調整模型的要求-回應記錄設定。

REST API

使用任何要求資料之前，請先替換以下項目：

  • PROJECT_ID：您的專案 ID。
  • LOCATION：端點資源的位置。
  • MODEL：基礎模型名稱。例如：gemini-2.0-flash-001。
  • ENDPOINT_ID：端點的 ID。

HTTP 方法和網址：

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/endpoints/ENDPOINT_ID

如要傳送要求，請選擇以下其中一個選項：

curl

執行下列指令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/endpoints/ENDPOINT_ID"

PowerShell

執行下列指令：

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/endpoints/ENDPOINT_ID" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

停用記錄設定

停用端點的要求/回應記錄設定。

Python SDK

tuned_model = GenerativeModel("projects/PROJECT_ID/locations/REGION/endpoints/ENDPOINT_ID")

# Set logging configuration
tuned_model.set_request_response_logging_config(
    enabled=False,
    sampling_rate=1.0,
    bigquery_destination="bq://PROJECT_ID.DATASET_NAME.TABLE_NAME",
    enable_otel_logging=False
    )

REST API

{
"predictRequestResponseLoggingConfig": {
  "enabled": false
}
}

記錄資料表結構定義

在 BigQuery 中，記錄會使用以下結構定義記錄：

欄位名稱 類型 附註
endpoint STRING 要部署調整後模型的端點資源名稱。
deployed_model_id STRING 已部署至端點的調整過的模型的部署模型 ID。
logging_time TIMESTAMP 記錄的時間。這大致是回應傳回的時間。
request_id NUMERIC 根據 API 要求自動產生的整數要求 ID。
request_payload STRING 這項功能可記錄合作夥伴模型，並與 Vertex AI 端點要求-回應記錄相容。
response_payload STRING 這項功能可記錄合作夥伴模型，並與 Vertex AI 端點要求-回應記錄相容。
模型 STRING 模型資源名稱。
model_version STRING 模型版本。這通常是 Gemini 模型的「預設」值。
api_method STRING generateContent、streamGenerateContent、rawPredict、streamRawPredict
full_request JSON 完整的 GenerateContentRequest。
full_response JSON 完整的 GenerateContentResponse。
中繼資料 JSON 呼叫的任何中繼資料；包含要求延遲時間。
otel_log JSON 以 OpenTelemetry 結構定義格式記錄的記錄。只有在記錄設定中啟用 otel_logging 時，才能使用這個選項。

請注意，如果要求-回應組合大於 BigQuery 寫入 API 10 MB 資料列限制，系統就不會記錄。

後續步驟