构建数据代理并与数据对话

开发者可以使用通过 geminidataanalytics.googleapis.com 或区域端点访问的 Conversational Analytics API 构建由人工智能 (AI) 提供支持的对话界面或数据代理 。该 API 使用自然语言回答有关 BigQuery、Looker 和数据洞察中结构化数据的问题，还支持通过 QueryData 方法查询 AlloyDB、GoogleSQL for Spanner、Cloud SQL 和 Cloud SQL for PostgreSQL 中的数据。

借助 Conversational Analytics API，您可以向数据代理提供商家信息和数据（上下文 ），以及 SQL、Python 和可视化库等工具的访问权限。这些代理回答会呈现给用户，并且可以由客户端应用记录日志，从而打造无缝且可审核的数据对话体验。

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

Conversational Analytics API 使用入门

如需开始使用 Conversational Analytics API，请查看以下文档，了解可用的集成方法和核心概念：

  • 架构和关键概念：了解数据代理如何处理请求、代理创建者和用户的工作流、对话模式以及所需的 Identity and Access Management (IAM) 角色。
  • 数据代理的集成模式：比较架构方法，以确定最适合您应用的连接方法。
  • 状态管理：了解有状态和无状态对话模式、API 如何管理对话记录以及 ADK 会话状态范围。

如需开始构建数据代理，请完成设置和前提条件文档中的步骤。如需了解引导式演练、示例应用、SDK 和其他开发工具，请参阅 Conversational Analytics API 教程、演示和工具。

设置和前提条件

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

构建数据代理并与之交互

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

最佳做法

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

API 参考文档和客户端库

关键 API 操作

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

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

支持与反馈

如需获得帮助或报告问题，请与客户服务团队联系。请按照创建和管理支持请求中的说明打开支持请求。创建支持请求时，请遵循以下准则：

  • 如需获得有关 Conversational Analytics API with BigQuery 的支持，请在选择产品 列表中选择 BigQuery ，然后在功能 字段中选择 AI 和机器学习::BigQuery 中的 Conversational Analytics API 。
  • 如需获得有关 Conversational Analytics API with Looker 的支持，请在选择产品 列表中选择 Looker（原版） ，然后在功能 字段中选择 Gemini in Looker::Conversational Analytics API 。

如果您对 Conversational Analytics API 有一般反馈或疑问，请发送电子邮件至 conversational-analytics-api-feedback@google.com。我们不保证回复电子邮件通信，但我们会阅读电子邮件，并在路线图规划期间参考这些反馈。

您还可以提交功能请求以获取新的 Conversational Analytics API 功能。