Conversational Analytics API：构建数据代理并与数据对话

开发者可以使用通过 geminidataanalytics.googleapis.com 访问的 Conversational Analytics API 构建由人工智能 (AI) 提供支持的对话界面或数据代理，以便使用自然语言回答有关 BigQuery、Looker 和 Looker Studio 中结构化数据的问题。借助 Conversational Analytics API，您可以向数据代理提供业务信息和数据（上下文），以及 SQL、Python 和可视化库等工具的访问权限。这些代理回答会呈现给用户，并且可以由客户端应用记录日志，从而打造无缝且可审核的数据对话体验。

了解 Gemini for Google Cloud 如何以及何时使用您的数据。

Conversational Analytics API 使用入门

如需开始使用 Conversational Analytics API，您可以先查看架构和关键概念文档，了解智能体如何处理请求、智能体创建者和用户的工作流、对话模式以及 Identity and Access Management (IAM) 角色。然后，如需开始构建数据智能体，您可以选择通过快速入门、Codelab 和笔记本获得引导式体验，也可以按照设置和前提条件中的步骤以自助方式完成。

快速入门、Codelab 和笔记本

以下资源提供引导式体验，可帮助您开始使用 Conversational Analytics API：

  • 快速入门应用：使用此 Streamlit 快速入门应用可在本地测试环境中与 Conversational Analytics API 集成。
  • Conversational Analytics API Codelab：按照分步教程了解如何将 Python SDK 与 BigQuery 数据搭配使用。
  • Conversational Analytics API Colaboratory 笔记本：
    • HTTP Colaboratory 笔记本：提供一个互动式分步指南，介绍如何使用 HTTP 请求设置环境、构建数据智能体和进行 API 调用。
    • Python SDK Colaboratory 笔记本：提供有关如何使用 Python SDK 设置环境、构建数据代理和进行 API 调用的互动式分步指南。

设置和前提条件

在使用 API 或示例之前，请完成以下步骤：

构建数据代理并与之交互

完成上述步骤后，请使用 Conversational Analytics API 按照以下步骤构建数据代理并与之交互：

最佳做法

请查看以下指南，了解使用 Conversational Analytics API 的最佳实践：

  • 管理智能体的 BigQuery 费用：了解如何通过设置项目级、用户级和查询级开支限额来监控和管理 Conversational Analytics API 智能体的 BigQuery 费用。
  • 提出有效的问题：了解如何为代理精心设计有效的问题，以便充分利用 Conversational Analytics API。
  • 排查 Conversational Analytics API 错误：排查常见的 Conversational Analytics API 错误。
  • 已知限制：详细介绍了 Conversational Analytics API 的已知限制，包括查询、数据、可视化图表和问题的限制。

关键 API 操作

API 提供了以下用于管理数据代理和对话的核心端点：

操作 HTTP 方法 端点 说明
创建代理 POST /v1beta/projects/*/locations/*/dataAgents 创建新的数据代理。
获取智能体 GET /v1beta/projects/*/locations/*/dataAgents/* 检索特定数据智能体的详细信息。
获取 Identity and Access Management 政策 POST /v1beta/projects/*/locations/*/dataAgents/*:getIamPolicy 获取为特定数据智能体分配给每个用户的 Identity and Access Management 权限。具有 Data Agent Owner 角色的用户可以调用此端点查看数据智能体的 Identity and Access Management 策略，再使用 setIAMpolicy 端点与其他用户共享数据智能体。
设置 Identity and Access Management 政策 POST /v1beta/projects/*/locations/*/dataAgents/*:setIamPolicy 为特定数据智能体设置 Identity and Access Management 政策。具有 Data Agent Owner 角色的用户应调用此端点，与其他用户共享数据智能体，从而更新这些用户的 Identity and Access Management 权限。
更新智能体 PATCH /v1beta/projects/*/locations/*/dataAgents/* 修改现有数据代理。
列出代理 GET /v1beta/projects/*/locations/*/dataAgents 列出项目中的可用数据代理。
列出可访问的代理 GET /v1beta/projects/*/locations/*/dataAgents:listaccessible 列出项目中可访问的数据代理。如果调用此 API 的用户对数据代理具有 get 权限，则认为该数据代理可访问。您可以使用 creator_filter 字段来管理此方法返回哪些代理：
  • NONE（默认）：返回用户可访问的所有数据代理，无论这些代理是由谁创建的。
  • CREATOR_ONLY：仅返回用户可访问且由该用户创建的数据代理。
  • NOT_CREATOR_ONLY：仅返回用户可访问且由他人创建的数据代理。
删除代理 DELETE /v1beta/projects/*/locations/*/dataAgents/* 移除数据代理。
创建对话 POST /v1beta/projects/*/locations/*/conversations 启动新的永久性对话。
使用对话引用进行对话 POST /v1beta/projects/*/locations/*:chat 通过发送引用现有对话及其关联代理上下文的对话消息，继续进行有状态对话。对于多轮对话， Google Cloud 会存储和管理对话记录。
使用数据代理引用进行对话 POST /v1beta/projects/*/locations/*:chat 发送引用已保存的数据代理以获取上下文的无状态对话消息。对于多轮对话，您的应用必须管理对话记录，并在每次请求中提供该记录。
使用内嵌上下文进行对话 POST /v1beta/projects/*/locations/*:chat 通过直接在请求中提供所有上下文来发送无状态对话消息，而不使用已保存的数据代理。对于多轮对话，您的应用必须管理对话记录，并在每次请求中提供该记录。
获取对话 GET /v1beta/projects/*/locations/*/conversations/* 检索特定对话的详细信息。
列出对话 GET /v1beta/projects/*/locations/*/conversations 列出特定项目中的对话。
列出对话中的消息 GET /v1beta/projects/*/locations/*/conversations/*/messages 列出特定对话中的消息。

发送反馈

您可以使用以下链接提交错误报告或功能请求。

其他资源

以下资源提供了参考文档、示例和工具，可帮助您使用 Conversational Analytics API 构建应用：