开发者可以使用通过 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) 角色。然后，如需开始构建数据智能体，您可以选择通过 Colaboratory 笔记本获得引导式体验，也可以按照设置和前提条件中的步骤以自助方式完成。
交互式 Colaboratory 笔记本
如需获取有关设置环境、构建数据智能体和进行 API 调用的互动式分步指南，请参阅以下 Colaboratory 笔记本：
- Conversational Analytics API HTTP Colaboratory 笔记本
- Conversational Analytics API SDK Colaboratory 笔记本
设置和前提条件
在使用 API 或示例之前，请完成以下步骤：
- 启用 Conversational Analytics API：介绍了启用 Conversational Analytics API 的前提条件。
- 授予 Conversational Analytics API IAM 角色和权限：介绍了用于管理对数据代理的访问权限的预定义 IAM 角色。
- 使用 Conversational Analytics API 对数据源进行身份验证并连接到数据源：提供有关向 API 进行身份验证以及配置与 BigQuery、Looker 和 Looker Studio 数据的连接的说明。
构建数据代理并与之交互
完成上述步骤后，请使用 Conversational Analytics API 按照以下步骤构建数据代理并与之交互：
- 使用 HTTP 构建数据代理：提供一个完整的示例，展示如何使用 Python 通过直接 HTTP 请求构建数据代理并与之交互。
- 使用 Python SDK 构建数据代理：提供一个完整的示例，展示如何使用 Python SDK 构建数据代理并与之交互。
- 撰写有效的系统指令：了解如何为
system_instruction参数构建 YAML 内容，以指导智能体行为并提高回答准确性。您还可以在 BigQuery 数据源和 Looker 数据源中查看系统指令示例。 - 将 Conversational Analytics API 代理回答呈现为可视化图表：提供一个示例，展示如何使用 Python SDK 和 Vega-Altair 库处理 API 响应中的图表规范，并将其呈现为可视化图表。
最佳做法
- 管理智能体的 BigQuery 费用：了解如何通过设置项目级、用户级和查询级开支限额来监控和管理 Conversational Analytics API 智能体的 BigQuery 费用。
关键 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 |
列出项目中的可用数据代理。 |
| 删除代理 | 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 参考文档：详细介绍了请求和响应结构的方法、端点以及类型定义。
- 排查 Conversation Analytics API 错误：排查常见的 Conversation Analytics API 错误。