Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

使用 Python SDK 或 REST API 管理反馈

本页介绍了如何使用反馈服务 API 和 SDK 来管理反馈条目和上下文。您可以在聊天 widget 或移动应用等界面中实现自定义反馈控件（例如“我喜欢”或“不喜欢”按钮），并使用 Feedback 服务跟踪反馈。

准备工作

请确保您已备好：

Agent Platform User (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 搭配使用，则可以从列出事件响应的 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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

执行以下命令：

$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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

执行以下命令：

$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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

执行以下命令：

$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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

执行以下命令：

$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 后，向上下文子资源 (UpdateFeedbackContext) 发送 PATCH 请求，以填充 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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 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 设置为空列表）。

使用 Python SDK 或 REST API 管理反馈 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

创建 Agent Runtime 实例

Python SDK

REST API

创建反馈条目

Python SDK

REST API

curl

PowerShell

检索反馈条目

Python SDK

REST API

curl

PowerShell

列出反馈条目

Python SDK

REST API

curl

PowerShell

更新反馈条目

Python SDK

REST API

curl

PowerShell

删除反馈条目

Python SDK

REST API

curl

PowerShell

反馈上下文

检索反馈上下文

Python SDK

REST API

curl

PowerShell

创建和更新反馈上下文

Python SDK

REST API

curl

PowerShell

使用 Python SDK 或 REST API 管理反馈