有关 Conversational Analytics API 的常见问题解答

Conversational Analytics API 能否更改或删除我的数据？

Conversational Analytics API 采用多重保障措施，可防止您的数据被更改或删除。

以下是针对不同数据源的数据安全处理方式：

BigQuery：该 API 会阻止数据定义语言 (DDL) 和数据操纵语言 (DML) 语句。具体来说，系统会对生成的 SQL 进行试运行，并且仅允许执行 SELECT 类型的查询。
Looker：该 API 通过使用 run_inline_query 等方法与 Looker 进行交互，这些方法仅限于读取操作，例如选择、过滤和限制。这些方法不支持 DDL 或 DML 操作，也不包括删除或丢弃操作。
Looker Studio（适用于 CSV 文件和 Google 表格）：Looker Studio 使用结构化格式来定义和提取数据，以便生成可视化图表和报告。使用此方法执行的所有查询都是只读类型的查询，不支持对数据进行任何更改。

Conversational Analytics API 旨在以只读方式访问这些数据源。

如何处理身份验证和权限错误？

以下是您在使用 Conversational Analytics API 时可能会遇到的一些常见的身份验证和权限错误：

错误：PERMISSION_DENIED 或 403 Write access to project ... was denied
- 可能的原因：此消息通常表示存在 Google Cloud IAM 角色相关的问题。即，尝试使用该 API 的用户或服务账号缺少对 Google Cloud 项目的必要权限。
- 问题排查：
  - Google Cloud 项目所有者必须确保在 Google Cloud 项目中为相应用户或服务账号分配了正确的 IAM 角色。部分操作（例如启用 API 或测试其功能）可能需要 Project Editor 等角色。
  - 如果您在切换区域时遇到 403 错误（例如 Write access to project 'us-gcp-project-name' was denied），请验证项目的 IAM 配置。
错误：具有 User 角色的 Looker 用户尝试与数据智能体对话时，系统显示 500 Internal Server Error。
- 可能的原因：该 Looker 用户可能没有足够的权限。
- 问题排查：确保在 IAM 和 Looker 中授予用户适当的角色，以便他们能够与数据智能体对话。如需了解详情，请参阅此常见问题解答中的 Looker 需要满足哪些要求才能使用 Conversational Analytics API？一问的回答。

Looker 需要满足哪些要求才能使用 Conversational Analytics API？

如要使用 Conversational Analytics API，您需要在 Google Cloud IAM 中和 Looker 内都拥有适当的权限，具体取决于数据源和您要执行的操作：

Google Cloud IAM 角色：
- 您需要在 Google Cloud 项目中拥有能够提供足够权限的 IAM 角色才能与 geminidataanalytics.googleapis.com API 进行交互。如果未能正确配置 IAM 角色，通常会导致 PERMISSION_DENIED 错误。
- 所需的具体角色可能取决于您要执行的操作，部分操作可能需要 Project Editor 这样的常规角色。
Looker 权限和角色：
- 模型级权限：如要让 Looker 用户能够使用对话式分析及 Conversational Analytics API，为相应用户分配的角色必须包含他们要与之交互的模型的 gemini_in_looker 权限。

如需详细了解使用 Conversational Analytics API 所需的权限和角色，请参阅授予 Conversational Analytics API IAM 角色和权限文档页面。

此外，您的 Looker 实例必须满足特定要求：

如需将 Conversational Analytics API 与 Looker Studio Pro 搭配使用，您的 Pro 订阅必须位于 VPC-SC 边界之外。

如何从 Data QnA API 迁移到 Conversational Analytics API？

如果您使用的是旧版实验性 Data QnA API (dataqna.googleapis.com)，请参阅迁移指南，了解如何迁移到新版 Conversational Analytics API (geminidataanalytics.googleapis.com)，这是该功能的正式版端点。

数据智能体的名称和 ID 有何区别？

数据智能体的 ID（定义为 data_agent_id 的值）是数据智能体的唯一标识符。数据智能体的名称 data_agent.name 是自动从 data_agent_id 派生的完全限定名称 (FQN)，采用 projects/<project>/locations/<location>/dataAgents/<data_agent_id> 格式。

创建数据智能体时，系统会忽略您为 data_agent.name 输入的任何值。执行 get、update 或 delete 操作时，完整的 data_agent.name 会被视为数据智能体的唯一标识符。

使用 Conversational Analytics API 创建数据智能体时，以下情况适用：

如果您未定义 data_agent_id，系统会自动生成一个唯一 ID。
如果您将 data_agent_id 定义为某个值，例如 TestID，那么您为 data_agent.name 输入的任何值都会被 projects/<project>/locations/<location>/dataAgents/TestID 覆盖。
如果您使用 FQN 定义 data_agent_id，则会收到“名称格式有误”错误。

Conversational Analytics API 数据智能体有哪些记忆功能？

在单个会话中：Conversational Analytics API 支持多轮对话，这意味着它可以引用当前对话较早部分的内容。
跨多个会话：Conversational Analytics API 包含用于管理对话记录的功能，让用户能够保留跨多个会话的聊天记录。此外，还通过 Google 管理的多轮对话支持实现有状态智能体。
长期记忆：Conversational Analytics API 数据智能体不支持显式长期记忆功能。

如果我每次都问相同的问题，Conversational Analytics API 数据智能体每次都会给出相同的回答吗？

Conversational Analytics API 数据智能体提供的是自然语言回答，它们并非确定性的，因此即便是措辞完全相同的问题，智能体提供的自然语言回答也可能会有所不同。
针对数据查询的回答：不过，对于特定的数据查询问题，生成的底层查询（SQL 或 Looker 查询）应该能够提供一定的确定性。假如底层数据未发生变化，检索到的数据应该是相同的。

如何提高 Conversational Analytics API 数据智能体回答的准确性？

提高数据智能体回答准确性的一种方法是为数据智能体提供可靠的上下文信息。您可以通过以下方式添加上下文信息：

在 Looker 语义层，您可以在 LookML 定义中提供上下文。如需了解详情并查看相关示例，请参阅在 Looker 中通过编写的上下文引导智能体行为文档页面。
您可以在创建数据智能体时提供系统指令（即用户定义的准则），来引导数据智能体的行为。这些准则可以包括业务特定逻辑、回答格式或数据呈现形式。您还可以提供“黄金查询”，即相应 SQL 或 Looker 查询所对应的自然语言问题的示例。如需详细了解系统指令，请参阅通过编写的上下文引导智能体行为文档页面。

我可以将 Conversational Analytics API 与第三方应用集成吗？

用户可以将 Conversational Analytics API 与第三方应用集成，这样用户便可直接在自己日常使用的工具中与数据交互。

与 geminidataanalytics.googleapis.com API 端点交互的任何第三方应用都必须能够将用户消息从应用发送到智能体并显示回答。

如需构建集成，请参阅对话式分析快速入门代码库，获取相关示例或库。您还可以访问 Google Developers 论坛，搜索其他用户分享的示例。

Conversational Analytics API 的费用是多少？

Conversational Analytics API 目前处于预览版阶段，Google 不会针对预览版产品收取费用。如果日后有任何价格变动，我们会提前通知您。

Conversational Analytics API 支持哪些数据源？

Conversational Analytics API 支持以下数据源：

BigQuery
Looker 探索
Looker Studio

您还可以通过 BigQuery 连接到 SAP 和 Salesforce 等来源，或者通过 Looker Studio 连接到 CSV 文件和 Google 表格。

Conversational Analytics API 有哪些已知限制？

如需详细了解 Conversational Analytics API 的已知限制，请参阅 Conversational Analytics API 的已知限制文档页面。

Google Cloud 项目有哪些配额需要注意？

Google Cloud 项目的选择或位置不受任何限制。您可以创建数据智能体来对任何项目或区域中的受支持数据源进行查询。

Conversational Analytics API 是否支持数据区域化？

由于 Conversational Analytics API 尚不支持数据驻留 (DRZ) 或 Service Controls 边界 (VPC-SC)，因此您目前还无法在特定地理区域中托管智能体。即，不支持数据区域化。

Conversational Analytics API 是否支持英语以外的语言？

Conversational Analytics API 唯一正式支持的语言是英语。虽然底层 Gemini 模型支持多种语言，并且一些用户报告称，他们使用非英语查询时也取得了不错的成效，不过 Conversational Analytics API 尚未正式支持英语以外的语言。