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

本页面回答了有关 Conversational Analytics API 的常见问题。

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

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

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

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

Conversational Analytics API 旨在以只读方式访问这些数据源。如需详细了解 Conversational Analytics API 的安全性，请参阅放心对话：深度解析 Looker 对话式分析的安全性博文。

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

注意：如需详细了解相关错误及可能的解决方案，请参阅我们的排查 Conversational Analytics API 错误指南。

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

1. 错误：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 配置。

2. 错误：具有 User 角色的 Looker 用户尝试与数据智能体对话时，系统显示 500 Internal Server Error。

   • 可能的原因：该 Looker 用户可能没有足够的权限。
   • 问题排查：确保在 IAM 和 Looker 中授予用户适当的角色，以便他们能够与数据智能体对话。如需了解详情，请参阅此常见问题解答中的 Looker 需要满足哪些要求才能使用 Conversational Analytics API？一问的回答。

为什么我在流式传输响应时会看到 503 或 500 错误？

如果您使用基本的 HTTP 或 REST 客户端（例如 Python requests 库）调用流式传输 :chat 端点，API 可能会返回通用错误消息，例如 503 Connection reset by peer 或 500 Internal error。

之所以会出现这些通用错误，是因为流式传输 API 会在流打开后立即发送 HTTP 200 OK 标头。如果数据智能体在流期间遇到严重错误（例如长时间运行的查询超时或突然拒绝权限），它会终止流并在 HTTP/2 尾部包含特定错误代码。标准 HTTP 或 REST 客户端无法解析这些尾部标头，而是将突然终止解释为套接字崩溃。

为了处理流期间发生的错误，我们强烈建议您使用官方 Google Cloud 客户端库 (SDK)，例如 Python SDK。这些基于 gRPC 的 SDK 会解析 HTTP/2 尾部并返回特定错误代码（例如 DEADLINE_EXCEEDED 或 PERMISSION_DENIED），而不是返回通用网络错误。

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

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

1. Google Cloud IAM 角色：

   • 您需要在 Google Cloud 项目中拥有能够提供足够权限的 IAM 角色才能与 geminidataanalytics.googleapis.com API 进行交互。如果未能正确配置 IAM 角色，通常会导致 PERMISSION_DENIED 错误。
   • 所需的具体角色可能取决于您要执行的操作，部分操作可能需要 Project Editor 这样的常规角色。

2. Looker 权限和角色：

   • 模型级权限：如要让 Looker 用户能够使用对话式分析及 Conversational Analytics API，为相应用户分配的 Looker 角色 必须包含他们要与之交互的模型的 gemini_in_looker 权限。

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

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

• Looker（原始版本）
• Looker (Google Cloud Core)

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

数据库需要满足哪些要求才能使用 Conversational Analytics API？

如需将 Conversational Analytics API 与 AlloyDB for PostgreSQL、GoogleSQL for Spanner、Cloud SQL for MySQL 和 Cloud SQL for PostgreSQL 等数据库搭配使用，您需要确保正确进行 IAM 身份验证并启用 API：

1. Google Cloud **IAM 角色**：

   • 服务帐号或用户必须拥有连接到特定数据库并查询该数据库所需的 IAM 角色。这通常涉及对数据库具有读取权限的角色。

2. 启用 API：

   • 确保已在 Google Cloud 项目中启用 Cloud AI Companion API。

如需详细了解如何启用 IAM 身份验证，请参阅每个数据库的文档：

• AlloyDB：管理 IAM 身份验证。
• Spanner：向 Spanner 进行身份验证。
• Cloud SQL for MySQL：IAM 身份验证。
• Cloud SQL for PostgreSQL：IAM 身份验证。

如何从 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，则会收到“名称格式有误”错误。

在“创建智能体”或“创建对话”中，ID 的可接受格式是什么？

对于数据代理：

projects/{project}/locations/{location}/dataAgents/{data_agent_id}

{data_agent} 是资源 ID，长度不得超过 63 个字符，并且必须符合 https://google.aip.dev/122#resource-id-segments 中所述的格式。

示例：projects/1234567890/locations/us-central1/dataAgents/my-agent

建议在创建智能体期间跳过设置此字段，因为系统会自动推断此字段，然后使用 {parent}/dataAgents/{data_agent_id} 覆盖此字段。

对于对话：

projects/{project}/locations/{location}/conversations/{conversation_id}

{conversation_id} 是资源 ID，长度不得超过 63 个字符，并且必须符合 https://google.aip.dev/122#resource-id-segments 中所述的格式。

示例：projects/1234567890/locations/us-central1/conversations/my-conversation。

建议在创建对话期间跳过设置此字段，因为对话式分析会自动识别此字段，然后使用 {parent}/conversations/{conversation_id} 覆盖此字段。

如何使用更新掩码？

在“更新数据智能体”流程中，updateMask参数采用FieldMask格式的字符串，用于指定更新要在dataAgent资源中覆盖的dataAgent字段。updateMask 参数是必填字段，系统会按如下方式对其进行验证：

• 如果 updateMask 为空，系统会抛出 BadRequestException，并且不会更新任何字段。
• 如果 updateMask 中的所有字段都是有效的 dataAgent 字段，则只会更新这些字段。
• 如果提供的字段既包含有效字段也包含无效字段，系统会忽略无效字段，并且只会更新有效字段。

如何使用 getIAMPolicy 和 setIAMPolicy 为数据代理设置 IAM 政策？

您可以使用 getIamPolicy 方法和 setIamPolicy 方法为用户分配特定代理的 IAM 角色。

重要提示 ：setIamPolicy 方法会替换智能体的现有权限。如需保留现有政策，请先调用 getIAMPolicy 方法来提取现有政策，然后在调用 setIamPolicy 时传递现有政策以及任何其他更改。

以下代码示例演示了如何获取数据代理的 IAM 政策：

• getIAMPolicy（使用 HTTP）
• getIAMPolicy（使用 Python SDK）

以下代码示例演示了如何为数据代理分配 IAM：

• setIAMPolicy（使用 HTTP）
• setIAMPolicy（使用 Python SDK）

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

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

注意：如果 Conversational Analytics API 返回的不是成功响应，您与数据智能体的对话内容可能不会保留。

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

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

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

作为一项尚处于发展早期的技术，Gemini for Google Cloud产品可能会生成看似合理但实际上不正确的输出。我们建议您在使用 Gemini for Google Cloud 产品的输出前先进行验证。 如需了解详情，请参阅 Gemini for Google Cloud 和 Responsible AI。

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

• 在 Looker 语义层，您可以在 LookML 定义中提供上下文。如需了解详情并查看相关示例，请参阅在 Looker 中通过编写的上下文引导智能体行为文档页面。
• 对于 BigQuery 数据源，您可以通过结构化上下文字段（例如表级和列级说明、同义词、标记和示例查询）以及通过系统指令提供编写的上下文。提供此上下文还有助于提高回答的准确性，并使智能体能够在回答中引用来源。如需了解详情，请参阅为 BigQuery 数据源定义数据智能体上下文。
• 在 AlloyDB for PostgreSQL、Cloud SQL for MySQL、Cloud SQL for PostgreSQL 和 Spanner 数据源中，您可以通过添加表、列、架构说明和约束来提供上下文，以此作为数据和如何解读该数据的指南。

• 创建数据智能体时，您可以提供系统指令、经过验证的查询和高级上下文：

  • 系统指令，即用户定义的准则，可用于引导数据智能体的行为。这些准则可以包括业务特定逻辑、回答格式或数据呈现形式。
  • 您可以提供经过验证的查询（也称为黄金查询 具体取决于数据源），即相应 SQL 或 Looker 查询所对应的自然语言 问题的示例。
  • 对于 AlloyDB、Cloud SQL for MySQL、Cloud SQL for PostgreSQL 和 Spanner 数据源，您可以提供高级上下文，这有助于优化智能体的数据理解能力和准确性。

  如需了解详情，请参阅 使用编写的上下文来引导智能体行为。

如需获得有关如何提出问题以获得更有效、更准确回答的指导，请参阅提出有效问题页面。

如何安全地检查和处理智能体生成的 Python 代码？

如果您启用了使用 Python 进行高级分析，数据智能体可能会返回 Python 代码。数据智能体返回的 Python 代码旨在安全地在 Google 管理的沙盒中执行。在本地或其他未经验证的环境中执行此代码会绕过沙盒的安全保护，并可能使您的系统面临安全风险，例如执行恶意代码。

如需安全地检查和处理智能体生成的 Python 代码，请遵循以下准则：

• 在运行生成的代码之前，请先手动检查该代码。查找可疑模式，例如意外的网络请求（例如 socket、requests 或 urllib）、系统级命令（例如 os.system 或 subprocess）或经过大量混淆处理的字符串字面量和变量。
• 切勿在本地机器上或生产环境中直接运行未经验证的代码。使用安全、隔离的沙盒（例如 Colaboratory 笔记本、临时 Docker 容器或虚拟机），这些沙盒无权访问敏感凭据、内部网络或本地文件系统。
• 如果可以，在运行代码之前，您应先对代码运行静态分析工具或代码检查工具，以标记可能不安全的操作或已知的恶意模式。

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

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

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

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

Conversational Analytics API 的费用是多少？

Conversational Analytics API 现已正式发布 (GA)。如需详细了解价格，请参阅价格指南。

此外，数据智能体针对 BigQuery 等数据源执行的查询可能会产生这些服务的费用。对于 BigQuery，您可以通过设置配额或使用 bigquery_max_billed_bytes 参数限制每个查询的计费字节数来管理费用。

Conversational Analytics API 支持哪些数据源？

注意 ：QueryData 方法不支持 BigQuery 或 Looker 数据源。Chat 和 DataAgent 方法不支持数据库数据源，例如 AlloyDB for PostgreSQL、GoogleSQL for Spanner、Cloud SQL 和 Cloud SQL for PostgreSQL。

Conversational Analytics API 支持以下数据源：

• BigQuery（包括表或图表）
• Looker 探索
• 数据洞察
• AlloyDB for PostgreSQL
• GoogleSQL for Spanner
• Cloud SQL 和 Cloud SQL for PostgreSQL

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

Conversational Analytics API 有哪些已知限制？

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

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

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

Conversational Analytics API 是否支持数据驻留？

是，Conversational Analytics API 支持数据驻留。如需控制数据的处理和存储位置，请在发出 API 请求时指定区域级或多区域级服务端点。如需详细了解特定位置支持和配置详情，请参阅数据驻留。

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

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