本页面回答了有关 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 时可能会遇到的一些常见的身份验证和权限错误：
错误：
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 配置。
- Google Cloud 项目所有者必须确保在 Google Cloud 项目中为相应用户或服务账号分配了正确的 IAM 角色。部分操作（例如启用 API 或测试其功能）可能需要
错误：具有 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 内都拥有适当的权限，具体取决于数据源和您要执行的操作：
Google Cloud IAM 角色：
- 您需要在 Google Cloud 项目中拥有能够提供足够权限的 IAM 角色才能与
geminidataanalytics.googleapis.comAPI 进行交互。如果未能正确配置 IAM 角色，通常会导致PERMISSION_DENIED错误。 - 所需的具体角色可能取决于您要执行的操作，部分操作可能需要 Project Editor 这样的常规角色。
- 您需要在 Google Cloud 项目中拥有能够提供足够权限的 IAM 角色才能与
Looker 权限和角色：
- 模型级权限：如要让 Looker 用户能够使用对话式分析及 Conversational Analytics API，为相应用户分配的 Looker 角色必须包含他们要与之交互的模型的
gemini_in_looker权限。
- 模型级权限：如要让 Looker 用户能够使用对话式分析及 Conversational Analytics API，为相应用户分配的 Looker 角色必须包含他们要与之交互的模型的
如需详细了解使用 Conversational Analytics API 所需的权限和角色，请参阅授予 Conversational Analytics API IAM 角色和权限文档页面。
此外，您的 Looker 实例必须满足特定要求：
如需将 Conversational Analytics API 与数据洞察 Pro 搭配使用，您的 Pro 订阅必须位于 VPC-SC 边界之外。
使用 Conversational Analytics API 需要满足哪些数据库要求？
如需将对话式分析 API 与 AlloyDB for PostgreSQL、GoogleSQL for Spanner、Cloud SQL for MySQL 和 Cloud SQL for PostgreSQL 等数据库搭配使用，您需要确保已正确进行 IAM 身份验证并启用该 API：
Google Cloud IAM 角色：
- 服务账号或用户必须拥有必要的 IAM 角色，才能连接到特定数据库并查询该数据库。这通常涉及对数据库具有读取权限的角色。
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？
在数据智能体 patch 方法中，updateMask 参数采用 FieldMask 格式的字符串，用于指定更新将覆盖 dataAgent 资源中的哪些 dataAgent 字段。updateMask 参数是必需字段，其验证方式如下：
- 如果
updateMask为空，则会抛出BadRequestException，并且不会更新任何字段。 - 如果
updateMask中的所有字段都是有效的dataAgent字段，则只会更新这些字段。 - 如果同时提供了有效字段和无效字段，系统会忽略无效字段，仅更新有效字段。
如何使用 getIAMPolicy 和 setIAMPolicy 为数据代理设置 IAM 政策？
您可以使用 getIamPolicy 方法和 setIamPolicy 方法为用户分配特定代理的 IAM 角色。
以下代码示例演示了如何获取数据代理的 IAM 政策：
以下代码示例演示了如何为数据代理分配 IAM：
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 中通过编写的上下文引导智能体行为文档页面。
- 对于 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 容器或虚拟机），该沙盒无法访问敏感凭据、内部网络或本地文件系统。
- 在运行代码之前，您应尽可能对代码运行静态分析工具或 Linter，以标记潜在的不安全操作或已知的恶意模式。
我可以将 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 支持哪些数据源？
Conversational Analytics API 支持以下数据源：
- BigQuery（包括包含 BigQuery Graph 的表和图）
- Looker 探索
- 数据洞察
- AlloyDB for PostgreSQL
- 适用于 Spanner 的 GoogleSQL
- Cloud SQL for MySQL 和 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 尚未正式支持英语以外的语言。