本頁面說明如何使用意見回饋服務 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。
現在說明一下操作方式:
向代理傳送查詢,並找出要提供意見回饋的回覆。
取得工作階段 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_timeupdate_time
支援排序的欄位:
create_timeupdate_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
如要填入或修改與意見回饋項目相關聯的對話記錄,請按照下列兩步驟流程更新意見回饋情境:
- 建立意見回饋項目:呼叫標準方法來建立主要意見回饋記錄。
- 更新意見回饋內容:取得意見回饋項目 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
如要填入或修改與意見回饋項目相關聯的對話記錄,請按照下列兩步驟流程更新意見回饋情境:
- 建立意見回饋項目:呼叫
CreateFeedbackEntry建立主要意見回饋記錄。 - 更新意見回饋內容:取得意見回饋項目 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 設為空白清單)。