开发者可以使用通过 geminidataanalytics.googleapis.com 访问的对话式分析 API 构建由人工智能 (AI) 提供支持的对话界面或数据代理 。该 API 使用自然语言回答有关 BigQuery、Looker 和数据洞察中结构化数据的问题，还支持通过新的 QueryData 方法查询 AlloyDB、GoogleSQL for Spanner、Cloud SQL 和 Cloud SQL for PostgreSQL 中的数据。借助对话式分析 API，您可以向数据代理提供业务信息和数据（上下文 ），以及 SQL、Python 和可视化库等工具的访问权限。这些代理回答会呈现给用户，并且可以由客户端应用记录日志，从而打造无缝且可审核的数据对话体验。
了解 Gemini for Google Cloud 如何以及何时使用您的数据。
对话式分析 API 使用入门
如需开始使用对话式分析 API，请查看以下文档，了解可用的集成方法和核心概念：
- 架构和关键概念：了解数据代理如何处理请求、代理创建者和用户的工作流、对话模式以及所需的 Identity and Access Management (IAM) 角色。
- 数据代理的集成模式：比较架构方法，以确定最适合您应用的连接方法。
- 状态管理：了解有状态和无状态对话模式、API 如何管理对话记录以及 ADK 会话状态范围。
如需开始构建数据代理，请完成设置和前提条件文档中的步骤。如需了解引导式演练、示例应用、SDK 和其他开发者工具，请参阅 对话式分析 API 教程、演示和工具。
设置和前提条件
在使用 API 或示例之前，请完成以下步骤：
- 启用 Conversational Analytics API：介绍了启用 Conversational Analytics API 的前提条件。
- 使用 IAM 进行对话式分析 API 访问权限控制：介绍了如何使用 Identity and Access Management 来共享和管理对数据代理的访问权限。
使用对话式分析 API 对数据源进行身份验证并连接到数据源：提供有关向 API 进行身份验证以及配置与 BigQuery、Lakehouse、Looker、数据洞察和 Cloud Databases 数据（AlloyDB、GoogleSQL for Spanner、Cloud SQL 和 Cloud SQL for PostgreSQL）的连接的说明。
客户管理的加密密钥 (CMEK)：介绍了如何在 Cloud Key Management Service 中使用自己的加密密钥来保护使用 Looker 数据源的数据代理和对话。
构建数据代理并与之交互
完成上述步骤后，请使用 Conversational Analytics API 按照以下步骤构建数据代理并与之交互：
- 使用 HTTP 构建数据代理：提供一个完整的示例，展示如何使用 Python 通过直接 HTTP 请求构建数据代理并与之交互。
- 使用 Python SDK 构建数据代理：提供一个完整的示例，展示如何使用 Python SDK 构建数据代理并与之交互。
- 使用编写的上下文来引导代理行为：了解如何提供编写的上下文来引导代理行为并提高回答准确性。您还可以查看使用 BigQuery 数据源 和 Looker 数据源 的编写的上下文示例。
- 将对话式分析 API 代理回答呈现为可视化图表：提供一个示例，展示如何使用 Python SDK 和 Vega-Altair 库处理 API 响应中的图表规范，并将其呈现为可视化图表。
最佳做法
请查看以下指南，了解使用 Conversational Analytics API 的最佳实践：
- 管理智能体的 BigQuery 费用：了解如何通过设置项目级、用户级和查询级开支限额来监控和管理 Conversational Analytics API 智能体的 BigQuery 费用。
- 提出有效的问题：了解如何为代理精心设计有效的问题，以便充分利用对话式分析 API。
- 数据保留和删除：了解对话式分析 API 数据代理和对话的数据保留和删除。
- 配额和限制：了解 Conversational Analytics API 的配额和限制。
- 排查对话式分析 API 错误：排查常见的对话式分析 API 错误。
- 已知限制：详细介绍了 Conversational Analytics API 的已知限制，包括查询、数据、可视化图表和问题的限制。
- 呈现 Looker 数据源的代理回答：了解在使用 Looker 数据源时，在用户界面中呈现对话式分析 API 回答的最佳实践。
API 参考文档和客户端库
- Gemini Data Analytics REST 参考文档：详细介绍了 API 版本、方法、端点和类型定义。
- SDK 和开发工具：列出了特定于语言的客户端库。
关键 API 操作
API 提供了以下用于管理数据代理和对话的核心端点：
| 操作 | HTTP 方法 | 端点 | 说明 |
|---|---|---|---|
| 创建代理 | POST |
/v1beta/projects/*/locations/*/dataAgents |
创建新的数据代理。 |
| 同步创建代理 | POST |
/v1beta/projects/*/locations/*/dataAgents:createSync |
同步创建新的数据代理。 |
| 获取智能体 | 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/* |
修改现有数据代理。 |
| 同步更新智能体 | PATCH |
/v1beta/projects/*/locations/*/dataAgents/*:updateSync |
同步修改现有数据代理。 |
| 列出代理 | GET |
/v1beta/projects/*/locations/*/dataAgents |
列出项目中的可用数据代理。 |
| 列出可访问的代理 | GET |
/v1beta/projects/*/locations/*/dataAgents:listaccessible |
列出项目中可访问的数据代理。如果调用此 API 的用户对代理具有 get 权限，则该数据代理被视为可访问。您可以使用 creator_filter 字段来管理此方法返回哪些代理：
|
| 删除代理 | DELETE |
/v1beta/projects/*/locations/*/dataAgents/* |
移除数据代理。 |
| 同步删除代理 | DELETE |
/v1beta/projects/*/locations/*/dataAgents/*:deleteSync |
同步移除数据代理。 |
| 创建对话 | 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 |
列出特定对话中的消息。 |
| 删除对话 | DELETE |
/v1beta/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 数据库中的数据。 |
发送反馈
您可以使用以下链接提交错误报告或功能请求。