使用 Python SDK 或 REST API 管理意見回饋

本頁面說明如何使用意見回饋服務 API 和 SDK 管理意見回饋項目和內容。您可以在使用者介面 (例如即時通訊小工具或行動應用程式) 中實作自訂意見回饋控制項 (例如「喜歡」或「不喜歡」按鈕),並使用意見回饋服務追蹤意見回饋。

事前準備

請確認你已具備以下條件:

  • Agent Platform 使用者 (roles/aiplatform.user) 角色。
  • 按照「驗證」步驟設定驗證。
  • 已部署的 Agent Runtime 執行個體。如果沒有已部署的執行個體,請參閱「部署代理程式」一文,或按照下一節的步驟初始化及建立執行個體。
  • 選用:如要在控制台中查看追蹤事件旁的意見回饋項目,請確認 Agent Runtime 執行個體已啟用追蹤功能。

建立 Agent Runtime 執行個體

如果沒有現有的 Agent Runtime 執行個體,可以初始化用戶端並建立執行個體:

Python SDK

import os
import vertexai

# Set this environment variable to enable the Enterprise features.
os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION"
)
# If you don't have an Agent Engine instance already, create an instance.
agent_engine = client.agent_engines.create()

# Optionally, print out the Agent Engine resource name. You will need the
# resource name to interact with the Feedback service later on.
print(agent_engine.api_resource.name)

REST API

Agent Runtime 資源名稱的格式如下: projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID

更改下列內容:

  • PROJECT_ID:專案 ID。
  • LOCATION:您的區域。如需 Runtime 支援的區域,請參閱這篇文章
  • AGENT_ENGINE_ID:Agent Runtime 執行個體的資源 ID。

建立意見回饋項目

提交意見回饋前,您必須先與服務專員進行對話,且對話內容不得太少。找出要提供意見回饋的回覆,並取得其事件 ID 和工作階段 ID。

現在說明一下操作方式:

  1. 與代理建立互動工作階段

  2. 向代理傳送查詢,並找出要提供意見回饋的回覆。

  3. 取得工作階段 ID 和回應事件的 ID (做為意見回饋項目的事件 ID)。如果您使用 ADK 管理的 Session Service,可以從清單事件回應的 raw_event.id 欄位取得事件 ID (請參閱「列出工作階段中的事件」)。

以程式輔助方式記錄直接繫結至目標 session_id 的意見回饋項目,並透過 event_id 定義使用者代理程式對話事件。

Python SDK

import os
import vertexai

# Set this environment variable to enable the Enterprise features.
os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION"
)

operation = client.feedback_entries.create(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID",
    session_id="SESSION_ID",
    event_id="EVENT_ID",
    feedback_type="THUMBS_UP",
    config={
        "feedback_text": "The response was helpful and accurate.",
        "feedback_labels": ["accurate"],
        "user_id": "user-123",
        "source": "Chat UI",
        "custom_metadata": {"model_temperature": "0.7"},
    }
)

# Retrieve the created feedback entry details
feedback_entry = operation.response
print(f"Created feedback entry: {feedback_entry.name}")

支援的 feedback_type 值如下:

  • "THUMBS_UP"
  • "THUMBS_DOWN"
  • "FEEDBACK_TYPE_UNSPECIFIED"

REST API

使用任何要求資料之前,請先修改下列項目的值:

  • PROJECT_ID:專案 ID。
  • LOCATION:Agent Engine 執行個體所在的區域。
  • AGENT_ENGINE_ID:Agent Engine 執行個體的資源 ID。
  • SESSION_ID:工作階段 ID,用於定義與意見回饋相關聯的對話。
  • EVENT_ID:事件 ID,用於識別意見回饋所指的特定訊息或節點。

HTTP 方法和網址:

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries

JSON 要求內文:

{
  "sessionId": "SESSION_ID",
  "eventId": "EVENT_ID",
  "feedbackType": "THUMBS_DOWN",
  "feedbackLabels": ["inaccurate"],
  "feedbackText": "The answer was incorrect.",
  "userId": "user-123",
  "source": "Chat UI",
  "customMetadata": {
    "temperature": "0.7"
  }
}

如要傳送要求,請選擇以下其中一個選項:

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/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries"

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/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries" | Select-Object -Expand Content

您會收到長時間執行的作業,指出意見回饋項目建立作業的狀態。

擷取意見回饋項目

使用獨立意見回饋記錄的專屬資源位址,擷取完整的結構化酬載。

Python SDK

import os
import vertexai

# Set this environment variable to enable the Enterprise features.
os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION"
)

feedback_entry = client.feedback_entries.get(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID"
)

print(f"Feedback Type: {feedback_entry.feedback_type}")
print(f"Feedback Text: {feedback_entry.feedback_text}")

REST API

使用任何要求資料之前,請先修改下列項目的值:

  • PROJECT_ID:專案 ID。
  • LOCATION:Agent Engine 執行個體所在的區域。
  • AGENT_ENGINE_ID:Agent Engine 執行個體的資源 ID。
  • FEEDBACK_ENTRY_ID:意見回饋項目的資源 ID。

HTTP 方法和網址:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID

如要傳送要求,請選擇以下其中一個選項:

curl

執行下列指令:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_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/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID" | Select-Object -Expand Content

回應會包含意見回饋項目的詳細資料,例如工作階段 ID、類型、標籤和文字。

列出意見回饋項目

列出 Agent Runtime 執行個體中的意見回饋項目。你可以套用篩選器和排序屬性。

Python SDK

import os
import vertexai

# Set this environment variable to enable the Enterprise features.
os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION"
)

response = client.feedback_entries.list(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID",
    config={
        "filter": 'session_id="SESSION_ID"',
        "order_by": "create_time desc"
    }
)

for entry in response:
    print(f"Entry name: {entry.name}, Type: {entry.feedback_type}")

REST API

使用任何要求資料之前,請先修改下列項目的值:

  • PROJECT_ID:專案 ID。
  • LOCATION:Agent Engine 執行個體所在的區域。
  • AGENT_ENGINE_ID:Agent Engine 執行個體的資源 ID。

HTTP 方法和網址:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries

如要傳送要求,請選擇以下其中一個選項:

curl

執行下列指令:

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

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/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries" | Select-Object -Expand Content

回應會包含符合所有已套用篩選條件的意見回饋項目清單,以及分頁符記 (如有其他項目)。

您可以使用 filter 查詢參數,依特定屬性查詢。如要排序,請使用 order_by 查詢參數。

支援篩選的欄位:

  • session_id,例如 session_id="SESSION_ID"
  • user_id,例如 user_id="YOUR_USER_ID"
  • feedback_type,例如 feedback_type="THUMBS_DOWN"
  • feedback_labels,例如 feedback_labels: "inaccurate"
  • create_time
  • update_time

支援排序的欄位:

  • create_time
  • update_time

更新意見回饋項目

更新現有意見回饋項目的詳細資料,例如修改標籤、留言或自訂中繼資料。

Python SDK

import os
import vertexai

# Set this environment variable to enable the Enterprise features.
os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION"
)

operation = client.feedback_entries.update(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID",
    feedback_type="THUMBS_DOWN",
    config={
        "feedback_text": "Actually, this response was not accurate.",
        "feedback_labels": ["inaccurate"],
    }
)

updated_entry = operation.response
print(f"Updated entry: {updated_entry.name}")

REST API

使用任何要求資料之前,請先修改下列項目的值:

  • PROJECT_ID:專案 ID。
  • LOCATION:Agent Engine 執行個體所在的區域。
  • AGENT_ENGINE_ID:Agent Engine 執行個體的資源 ID。
  • FEEDBACK_ENTRY_ID:要更新的回饋項目資源 ID。

HTTP 方法和網址:

PATCH https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID?updateMask=feedbackType,feedbackLabels,feedbackText

JSON 要求內文:

{
  "feedbackType": "THUMBS_DOWN",
  "feedbackLabels": ["inaccurate", "incomplete"],
  "feedbackText": "The response was details-lacking and inaccurate."
}

如要傳送要求,請選擇以下其中一個選項:

curl

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

curl -X PATCH \
-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/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID?updateMask=feedbackType,feedbackLabels,feedbackText"

PowerShell

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

$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 "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID?updateMask=feedbackType,feedbackLabels,feedbackText" | Select-Object -Expand Content

您會收到長時間執行的作業,指出更新作業的進度。

刪除意見回饋項目

從專案中永久刪除意見回饋項目。

Python SDK

import os
import vertexai

# Set this environment variable to enable the Enterprise features.
os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION"
)

client.feedback_entries.delete(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID"
)

print("Feedback entry deleted.")

REST API

使用任何要求資料之前,請先修改下列項目的值:

  • PROJECT_ID:專案 ID。
  • LOCATION:Agent Engine 執行個體所在的區域。
  • AGENT_ENGINE_ID:Agent Engine 執行個體的資源 ID。
  • FEEDBACK_ENTRY_ID:要刪除的回饋項目資源 ID。

HTTP 方法和網址:

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID

如要傳送要求,請選擇以下其中一個選項:

curl

執行下列指令:

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID"

PowerShell

執行下列指令:

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

Invoke-WebRequest `
-Method DELETE `
-Headers $headers `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID" | Select-Object -Expand Content

您會收到長時間執行的作業,顯示刪除狀態。

意見回饋脈絡

意見回饋內容 (FeedbackContext) 是意見回饋項目 (FeedbackEntry) 的子項資源,會與父項意見回饋項目一起自動建立及刪除。根據預設,意見回饋內容包含空白的事件清單。

意見回饋內容會儲存與意見回饋項目相關的轉錄稿或事件狀態。這種資源分離方式:

  • 保留對話記錄:即使刪除原始工作階段,系統仍會保留儲存在意見回饋內容中的轉錄稿或記錄。
  • 縮減回覆大小:擷取意見回饋項目時,不需要擷取詳細的脈絡詳細資料。

FeedbackContext 資源的結構如下:

projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID/feedbackContext

擷取意見回饋內容

取得儲存在意見回饋內容中的詳細資料和對話事件:

Python SDK

import os
import vertexai

# Set this environment variable to enable the Enterprise features.
os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION"
)

feedback_context = client.feedback_entries.feedback_contexts.get(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID/feedbackContext"
)

# Point to event list
for event in feedback_context.context_events:
    print(f"Author: {event.author}")
    if event.content and event.content.parts:
        print(f"Content: {event.content.parts[0].text}")

REST API

使用任何要求資料之前,請先修改下列項目的值:

  • PROJECT_ID:專案 ID。
  • LOCATION:Agent Engine 執行個體所在的區域。
  • AGENT_ENGINE_ID:Agent Engine 執行個體的資源 ID。
  • FEEDBACK_ENTRY_ID:意見回饋項目的資源 ID。

HTTP 方法和網址:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID/feedbackContext

如要傳送要求,請選擇以下其中一個選項:

curl

執行下列指令:

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

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/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID/feedbackContext" | Select-Object -Expand Content

回應會包含所要求意見回饋內容的詳細資料,包括與父項意見回饋項目相關聯的對話事件清單。

建立及更新意見回饋脈絡

Python SDK

如要填入或修改與意見回饋項目相關聯的對話記錄,請按照下列兩步驟流程更新意見回饋情境:

  1. 建立意見回饋項目:呼叫標準方法來建立主要意見回饋記錄。
  2. 更新意見回饋內容:取得意見回饋項目 ID 後,傳送要求來填入內容事件。
import os
import vertexai

# Set this environment variable to enable the Enterprise features.
os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION"
)

# Construct conversation events
session_event = {
    "author": "user",
    "content": {
        "role": "user",
        "parts": [{"text": "Hello Agent"}]
    }
}

operation = client.feedback_entries.feedback_contexts.update(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID",
    context_events=[session_event]
)

updated_context = operation.response
print("Feedback context updated successfully.")

REST API

如要填入或修改與意見回饋項目相關聯的對話記錄,請按照下列兩步驟流程更新意見回饋情境:

  1. 建立意見回饋項目:呼叫 CreateFeedbackEntry 建立主要意見回饋記錄。
  2. 更新意見回饋內容:取得意見回饋項目 ID 後,請將 PATCH 要求傳送至內容子項資源 (UpdateFeedbackContext),以填入 contextEvents

使用任何要求資料之前,請先修改下列項目的值:

  • PROJECT_ID:專案 ID。
  • LOCATION:Agent Engine 執行個體所在的區域。
  • AGENT_ENGINE_ID:Agent Engine 執行個體的資源 ID。
  • FEEDBACK_ENTRY_ID:意見回饋項目的資源 ID。

HTTP 方法和網址:

PATCH https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID/feedbackContext?updateMask=contextEvents

JSON 要求內文:

{
  "contextEvents": [
    {
      "author": "user",
      "content": {
        "role": "user",
        "parts": [
          {
            "text": "What is the capital of France?"
          }
        ]
      }
    },
    {
      "author": "agent",
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Paris is the capital of France."
          }
        ]
      }
    }
  ]
}

如要傳送要求,請選擇以下其中一個選項:

curl

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

curl -X PATCH \
-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/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID/feedbackContext?updateMask=contextEvents"

PowerShell

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

$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 "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID/feedbackContext?updateMask=contextEvents" | Select-Object -Expand Content

您會收到長時間執行的作業,顯示意見回饋內容的更新進度。

如要移除意見回饋內容,請傳送空白更新 (例如將 context_events 設為空白清單)。