部分产品和功能正在重命名中。生成式 Playbook 和流程功能也将迁移到单个合并后的控制台。查看详情。

此页面由 Cloud Translation API 翻译。

问题排查

按代理类型标记过滤此文档的内容：

按类别标记过滤此文档的内容：

为代理启用 Cloud Logging

为您的代理启用 Cloud Logging。这对于捕获数据和诊断真实对话中的问题至关重要。

收集对话 ID

发生意外行为时，收集 Dialogflow 对话 ID。这些 ID 位于“对话历史记录”中，可用于跟踪对话的执行路径并检查具体互动。

API 调用获取权限被拒绝

代理类型标记：对话式 AI（Dialogflow CX）、Dialogflow ES
类别标记：API、Auth

问题

收到 API 调用的 PERMISSION_DENIED 响应。

解决方案

确保您已正确设置（对话式客服 (Dialogflow CX)、Dialogflow ES）身份验证和角色。尤其要确保您已完成以下操作：

创建了服务账号，且并未意外删除它。
为服务账号提供了一个角色，该角色可授予调用所需方法的权限。
下载了服务账号私钥文件。
将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置到私钥文件中。

API 调用提及未知项目

代理类型标记：对话式 AI（Dialogflow CX）、Dialogflow ES
类别标记：API、项目

问题

API 调用收到 Dialogflow API has not been used in project 32555940559 错误。

解决方案

确保您已完成以下操作：

设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量（请参阅 PERMISSION_DENIED）。
为 API 调用提供了正确的项目 ID。

API 调用收到无效的身份验证凭据错误

代理类型标记：对话式 AI（Dialogflow CX）、Dialogflow ES
类别标记：API、Auth

问题

API 调用收到 Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential. 响应。

解决方案

这可能是因为在指定非默认区域时，使用您的客户端库手动创建凭据。如需相关指导，请参阅以下内容之一：

API 调用响应请求切换到其他主机

代理类型标记：对话式 AI（Dialogflow CX）、Dialogflow ES
类别标记：API、Auth

问题

API 调用收到 Please switch to 'REGION-dialogflow.googleapis.com' to access resources located in 'REGION' 响应，其中 REGION 是特定区域 ID。

解决方案

如果您在请求中指定了地区，但未指定端点，就会出现这种情况。如需相关指导，请参阅以下内容之一：

API 调用响应中缺少字段

代理类型标记：对话式 AI 助理 (Dialogflow CX)、Dialogflow ES
类别标记：API

问题

API 响应中缺少一些字段。

解决方案

如果您希望 API 响应中的特定字段具有数值，那么如果返回值为 0，该字段可能不会出现在响应中。

如需详细了解默认值行为（包括非数字值），请参阅：

由于安全锁而无法删除项目

代理类型标记：Dialogflow ES
类别标记：项目

问题

尝试删除 Google Cloud 项目时，您会收到通知，指出该项目无法删除，因为它具有安全锁，而且其中一个安全锁与 Dialogflow ES 相关。

解决方案

确保您不再需要与该项目关联的 Dialogflow ES 代理。如果您收到有关代理不存在的通知，则表示代理已被删除。

Dialogflow ES 控制台
打开 https://dialogflow.cloud.google.com/#/agent/project-id/intents。

请注意，此链接不同于 Google Cloud 项目删除对话框中的链接。

Dialogflow API
使用 agent 类型的 search 方法。
获取安全锁名称。
gcloud
使用 gcloud alpha resource-manager liens list 命令（如列出项目的安全锁文档中所述）。
API Explorer
使用方法：liens.list 页面上的试用此 API 面板：
- 填写参数说明中建议的 parent 字段。
- 点击执行。
删除安全锁。
gcloud
使用 gcloud alpha resource-manager liens deleteLIEN_NAME 命令（如移除项目中的安全锁文档中所述）。
API Explorer
使用方法：liens.delete 页面上的试用此 API 面板：
- 使用您在步骤 2 中获得的安全锁名称填写 name 字段。
- 点击执行。
关闭项目。

Dialogflow CX webhook 失败并显示“超出截止期限”错误

代理类型标记：对话式 AI 助理 (Dialogflow CX)
类别标记：运行时

问题

从 Dialogflow CX 调用的 webhook 可能会失败并显示以下错误消息：

Webhook call failed. Error: DEADLINE_EXCEEDED

之所以会出现这种情况，可能是因为网络钩子调用超出了网络钩子超时限制。以下是导致 webhook 调用超出超时限制的可能原因：

尝试触发不存在的 intent。
webhook 后端（例如 Cloud Functions）的冷启动问题。
网络钩子会调用其他服务，从而增加响应时间。
代理与 webhook 后端之间没有连接（例如，负载平衡器配置错误）。
组织政策阻止运行入站流量或 Dialogflow 方法。

临时解决方法

webhook 的超时限制默认为 5 秒。您可以在创建或修改网络钩子资源时延长网络钩子超时限制，从而为网络钩子提供更多响应时间。

控制台无法设置项目

代理类型标记：Dialogflow ES
类别标记：控制台、项目

问题

使用控制台创建代理时，收到 Failed to set up GCP project 错误。

解决方案

您可能没有创建 Google Cloud 项目的权限。检查您是否可以直接从 Google Cloud 控制台创建 Google Cloud 项目。如果您无法创建项目，请按照错误消息中提供的建议进行操作。

响应中显示的会话参数引用

代理类型标记：对话式 AI（Dialogflow CX）
类别标记：控制台

问题

从 Dialogflow 返回的响应包含参数引用，而不是参数值。例如：
Hello, $session.params.customer_name

如果当前会话中未找到参数，或者参数未按其类型使用，系统将不会解析参数，并显示参数引用。

解决方案

出现此问题可能是因为所使用的参数未包含在对话中、存在拼写错误，或者与所使用的类型不同。

控制台在未启用 API 时无法创建代理

代理类型标记：对话式 AI（Dialogflow CX）
类别标记：控制台

问题

使用控制台创建代理时，收到 Dialogflow API has not been enabled for the project. Code: FAILED_PRECONDITION 错误。

解决方案

按照设置步骤启用 Dialogflow API。

尝试通过组织账号访问控制台时收到服务错误

代理类型标记：对话式 AI 助理 (Dialogflow CX)、Dialogflow ES
类别标记：控制台

问题

尝试通过组织账号访问控制台时，收到 You don't have access to this service 错误。

解决方案

请与贵组织的系统管理员联系，并确认贵组织的设置是否提供对该控制台的访问权限。

如果贵组织的设置应允许访问，并且您是从其他组织迁移了账号，那么您的账号可能已被 Google 标记为受限。如果贵组织中的其他用户可以访问该控制台，但您无法访问，则可能是因为这个原因。请与支持团队联系以寻求帮助。

由于缺少流程，无法以 JSON 格式导出代理

代理类型标记：对话式 AI 助理 (Dialogflow CX)
类别标记：控制台

问题

以原始字节导出代理会成功完成，但以 JSON 格式导出代理会失败，并显示类似于以下内容的错误消息：

Flow 'projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/flows/FLOW_ID' does not exist
in the agent

此问题可能是由引用已删除的流程的测试用例所致。

解决方案

如需解决此问题，请浏览未使用的测试用例，确认错误消息中提及的流程是否在任何测试用例中使用。然后删除已确认的测试用例。

电话网关连接

代理类型标记：Dialogflow ES
类别标记：集成

问题

使用电话网关时，您会收到忙碌信号或调用中断。

解决方案

此功能存在配额和限制。如果您收到忙音或通话中断，则表示可能已超出配额。

尝试创建新电话号码时出 `RESOURCE_EXHAUSTED` 错误

代理类型标记：对话式客服 (Dialogflow CX)、Dialogflow ES
类别标记：集成

问题

尝试在 Conversational Agents (Dialogflow CX)、Dialogflow ES 或 Agent Assist 中创建新电话号码时，系统会返回 RESOURCE_EXHAUSTED 错误。

解决方案

此错误表示您超出了每个项目的电话号码数量上限。如需创建新电话号码，请删除与您的项目关联的未使用的电话号码，直到数量低于上限。

如果您在 Conversational Agents (Dialogflow CX) 电话网关或 Dialogflow ES 电话网关中创建了电话号码，则可以在控制台中将其删除。请注意，如果您删除代理，但不删除电话号码，系统不会删除与该代理关联的电话号码。

或者，您也可以按照以下步骤使用该 API。

第 1 步：确定与您的项目关联的所有电话号码

如需识别与您的项目关联的电话号码，请针对您可能已在其中创建电话号码的所有地区使用 projects.phoneNumbers/list 或 projects.locations.phoneNumbers.list API 方法。

对于 global 区域，请使用以下命令：

curl -X GET \
-H "Authorization: Bearer "$(gcloud auth print-access-token) \
-H "X-Goog-User-Project: PROJECT_ID" \
-H "Content-Type: application/json; charset=utf-8" \
https://dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/locations/global/phoneNumbers

对于其他地区，您需要在两个位置指定地区：

curl -X GET \
-H "Authorization: Bearer "$(gcloud auth print-access-token) \
-H "X-Goog-User-Project: PROJECT_ID" \
-H "Content-Type: application/json; charset=utf-8" \
https://REGION_ID-dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/locations/REGION_ID/phoneNumbers

第 2 步：（可选）确定与对话资料关联的客服人员

通过对话资料获取与电话号码关联的 Conversational Agents (Dialogflow CX) 客服 ID，有助于您确定该客服人员是否仍在使用，以及该电话号码是否仍有用。您可以使用 projects.conversationProfiles/get API 方法来执行此操作。您可以在对您在第 1 步中运行的命令的响应中找到对话个人资料 ID。

对于 global 区域，请使用以下命令：

curl -X GET \
-H "Authorization: Bearer "$(gcloud auth print-access-token) \
-H "X-Goog-User-Project: PROJECT_ID" \
-H "Content-Type: application/json; charset=utf-8" \
https://dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/locations/global/conversationProfiles/CONVERSATION_PROFILE_ID

对于其他区域，请在以下两个位置指定区域：

curl -X GET \
-H "Authorization: Bearer "$(gcloud auth print-access-token) \
-H "X-Goog-User-Project: PROJECT_ID" \
-H "Content-Type: application/json; charset=utf-8" \
https://REGION_ID-dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/locations/REGION_ID/conversationProfiles/CONVERSATION_PROFILE_ID

您可以在 Conversational Agents (Dialogflow CX) 控制台中使用查看所有代理页面上的搜索选项，按代理 ID 查找代理。

对于 Dialogflow ES，一个项目最多只能与 5 个代理相关联，一个 Dialogflow ES 代理只能与一个电话号码相关联。因此，您可以通过 https://dialogflow.cloud.google.com/#/editAgent/PROJECT_ID/intents 在 Dialogflow ES 控制台中打开代理。

如果未找到客服人员，但您确定该电话号码不再需要，仍然可以将其删除。

第 3 步：删除未使用的电话号码

如需删除不再需要的电话号码，请使用 projects.phoneNumbers/delete 或 projects.locations.phoneNumbers.delete API 方法。您可以在对您在第 1 步中运行的命令的响应中找到电话号码 ID。

对于 global 区域，请使用以下命令：

curl -X DELETE \
    -H "Authorization: Bearer "$(gcloud auth print-access-token) \
    -H "X-Goog-User-Project: PROJECT_ID" \
    -H "Content-Type: application/json; charset=utf-8" \
    https://dialogflow.googleapis.com/v2beta1/PHONE_NUMBER_ID

对于其他地区，请指定相应地区：

curl -X DELETE \
    -H "Authorization: Bearer "$(gcloud auth print-access-token) \
    -H "X-Goog-User-Project: PROJECT_ID" \
    -H "Content-Type: application/json; charset=utf-8" \
    https://REGION_ID-dialogflow.googleapis.com/v2beta1/PHONE_NUMBER_ID

Dialogflow CX Messenger 无响应

代理类型标记：对话式客服 (Dialogflow CX)
类别标记：集成

问题

Dialogflow CX Messenger 互动无代理响应。

解决方案

如果您没有看到来自 Dialogflow CX Messenger 的任何响应，请确保项目已启用结算功能，并且项目已启用 Dialogflow API。请参阅设置说明。

参数值匹配，但不是实体同义词

代理类型标记：对话式 AI（Dialogflow CX）、Dialogflow ES
类别标记：自然语言理解 (NLU)

问题

一般情况：系统会在运行时提取参数值，即使与参数对应的实体不包含匹配值作为同义词也是如此。

更具体的示例：从实体中删除同义词并重新训练代理后，系统仍会将此同义词提取为此实体的参数值。

解决方案

使用搜索选项检查匹配的值是否可能以隐式实体的形式存在于代理中（对话式 AI 客服 (Dialogflow CX)、Dialogflow ES）。查找包含此参数和实体的注解的所有 intent。
修正注释，确保不将这些注释应用于表示不匹配的值的文本。
在运行时测试代理，以验证问题是否已得到解决。
如果问题仍然存在，请确保在高级实体设置中取消选中自动展开和模糊匹配选项，然后再次测试客服人员。

语音聊天机器人会跳过某些回答

代理类型标记：对话式 AI 助理 (Dialogflow CX)
类别标记：文本转语音

问题

对于同时支持文本和语音的客服人员，语音聊天机器人不会读出某些回复。

解决方案

如果为特定对话轮次定义了至少一个输出音频文本响应，请确保在代理执行方式和该对话轮次的所有步骤中的 webhook 响应中，输出音频文本选项始终存在。

SSML 标记未生效

代理类型标记：对话式 AI（Dialogflow CX）、Dialogflow ES
类别标记：文本转语音

问题

SSML 标记在代理执行方式中定义，但语音聊天机器人会读出不带 SSML 效果的合成文本。

解决方案

确保在 Dialogflow 控制台中，每个响应卡片仅包含一个 <speak></speak> 对；如果通过 API 或 webhook 提供响应，则每个响应消息对象也仅包含一个 <speak></speak> 对。

语音代理将零读作字母 O

代理类型标记：对话式 AI 助理 (Dialogflow CX)
类别标记：文本转语音

问题

对于专为语音设计的客服人员，语音客服人员会将零读作字母 O，而不是零。

解决方案

更改客服人员说的话，以使用“输出音频文本”对话框选项。
勾选 SSML 复选框。

将文本用 SSML 标记括起来：

  <speak>
    <say-as interpret-as='verbatim'>YOUR_TEXT</say-as>
  </speak>

保存。

例如，信用卡号中的零将被拼写为零。

      <speak>
        <say-as interpret-as='verbatim'>5177 7702 8500 4578</say-as>
      </speak>

合成发音意外

代理类型标记：对话式 AI（Dialogflow CX）、Dialogflow ES
类别标记：文本转语音

问题

客服人员回答（例如专有名词、首字母缩写词）的语音合成发音不符合预期。

解决方案

如需确保不常见字词的特定发音，请在客服人员响应中使用 SSML say-as 或 phoneme 标记。

已达到允许的状态机执行步骤上限

代理类型标记：对话式 AI 助理 (Dialogflow CX)
类别标记：运行时

问题

向代理发送运行时请求时，在 Conversational Agents (Dialogflow CX) 控制台或日志中收到以下错误消息：

You have reached the maximum allowed state machine execution steps. You may consider simplifying your agent/flow design. Current execution steps are: [<array_of_objects>]

错误消息中的数组包含请求的执行步骤列表。如果步骤数量过多，列表可能不完整。

解决方案

此错误消息通常表示单次对话转换的数量过多。一个常见的示例是转换到同一页面，这会形成无限循环。

如需解决此问题，请执行以下操作：

从错误消息中复制 JSON 数组。
（可选）将复制的数组格式设置为整洁的 JSON，以提高可读性。如果错误消息被截断，请搜索最后一个“Step”对象，删除未完成的步骤对象和前面的英文逗号，然后在验证和美化 JSON 之前添加一个闭合的方括号。
查看每个步骤的 "TriggeredTransitionRouteId" 和 "TargetPage" 值。如果出现无限循环，"TriggeredTransitionRouteId" 和 "TargetPage" 字段在大多数步骤中都具有重复的值。
修改您的代理设计，以移除无限循环转场效果或减少单次对话回合的转场效果数量。

正则表达式匹配过于宽泛

代理类型标记：对话式代理 (Dialogflow CX)、Dialogflow ES
类别标记：正则表达式

问题

创建正则表达式实体时收到错误 Regular expression match is too broad（对话式客服 [Dialogflow CX]、Dialogflow ES）。

解决方案

不妨考虑以下方法：

在正则表达式中使用 ^ 和 $ 分别表示文本的开头和结尾。
将正则表达式实体与必需参数搭配使用（对话式客服 [Dialogflow CX]、Dialogflow ES）
定义所需的参数提示，要求最终用户仅提供实体值，不提供任何周围字词。

语音识别插入了不必要的非字母数字

代理类型标记：对话式 AI（Dialogflow CX）、Dialogflow ES
类别标记：语音转文字

问题

尝试匹配字母数字时，语音识别器会插入不需要的非字母数字字符（空格、短划线等），导致实体无法匹配。

解决方案

如果您使用系统实体来匹配号码，不妨改用正则表达式实体（对话式客服 (Dialogflow CX)、Dialogflow ES）。
请按照正则表达式实体无法准确识别字母数字部分中的所有建议操作。
对于通过电话集成匹配号码，除了语音识别之外，不妨考虑使用 DTMF 选项。

语音输入的转写内容为空

代理类型标记：对话式 AI（Dialogflow CX）、Dialogflow ES
类别标记：语音转文字

问题

针对语音输入的 Dialogflow 响应会返回空转写内容。系统会将这些请求视为没有输入或没有匹配项。

解决方案

聆听录音，确认其中包含语音内容。

确保在客服设置中启用了语音自适应功能（对话式客服 (Dialogflow CX)、Dialogflow ES）。

如果启用语音自适应功能没有帮助，请在非生产环境设置中试用以下语音模型，并使用效果最佳的模型：

latest_short
phone_call
command_and_search

对于英语以外的语言，请参阅语音转文字支持的语言文档，查找支持的语音模型。

指定语音模型的方式取决于您设置与 Dialogflow 的互动方式。

对于 API 请求，请在 InputAudioConfig 的 model 字段中提供模型名称（对话式客服 (Dialogflow CX)、Dialogflow ES）。
如果您使用电话网关（对话式客服 (Dialogflow CX)、Dialogflow ES），则可以更新 Dialogflow 在您启用集成时创建的对话个人资料中的语音模型：
1. 检索对话个人资料 ID：
  - 使用 conversationProfiles.list 方法检索与您的项目关联的所有对话配置文件。
  - 找到要更新的对话个人资料，然后复制 name 字段值。
  对于 Dialogflow CX 电话网关，对话资料显示名称可在集成设置中找到。对于 Dialogflow ES Phone Gateway，对话资料显示名称与启用了集成的代理名称相对应。
  
  如果您有多个显示名称相同的对话资料，请验证 conversationProfiles.list 方法响应中的 automatedAgentConfig 字段中的客服人员 ID。
2. 使用 conversationProfiles.patch API 方法更新 SpeechToTextConfig 中的 model 字段。
对于 Contact Center AI 集成，请咨询您的电话集成商，了解如何更新集成或个别请求的语音模型。

比较代理版本时出现空白屏幕，并显示“文件大小超过 2MB”错误

代理类型标记：对话式 AI（Dialogflow CX）
类别标记：控制台

问题

尝试比较两个不同的客服人员版本时，屏幕变为空白，并显示以下错误消息：

File size exceeds 2MB

此问题是由于其中一个文件的大小超过了 2MB。

解决方案

如需比较其中一个文件大小超过 2MB 的代理版本，建议使用 API 方法 compareVersion。

正则表达式实体无法准确识别字母数字

代理类型标记：对话式 AI（Dialogflow CX）、Dialogflow ES
类别标记：语音转文字、正则表达式

问题

收到的语音输入转写内容不准确，其中包含字母数字，这些字母数字旨在与正则表达式实体匹配（对话式客服 (Dialogflow CX)、Dialogflow ES）。

解决方案

确保在客服设置中启用了语音自适应功能（对话式客服 (Dialogflow CX)、Dialogflow ES）。
确保至少有一个实体条目符合所有正则表达式条目要求（对话式代理 [Dialogflow CX]、Dialogflow ES）。
对于特定模式，请使用最具体的正则表达式。例如，对于以两个字母开头、后跟五位数字的字母数字，请使用 [a-zA-Z]{2}\d{5}，而不是 [a-zA-Z0-9]{7}。
确保您的正则表达式实体允许匹配语音识别器可能插入的非字母数字字符（空格、短划线等）。如需满足此列表中的第 2 条要求，请创建多个实体条目：一个条目用于满足此列表中的第 2 条要求，另一个条目用于处理非字母数字字符。例如，若要匹配五位数字并允许非字母数字，请使用以下表达式：
```
 \d{5}
 (\d[^a-zA-Z0-9]*){5}
```
确保您的客服遵循参数定义要求（对话式客服 (Dialogflow CX)、Dialogflow ES）。

对话式客服 (Dialogflow CX) 示例

Dialogflow ES 示例
确保您的客服遵循训练短语注释要求（对话式客服 (Dialogflow CX)、Dialogflow ES）。
Dialogflow ES 示例
确保您的测试符合测试准则（对话式 AI 客服 (Dialogflow CX)、Dialogflow ES）。
如需移除语音识别器可能插入的非字母数字字符，请使用以下命令：
- 对于对话式 AI 客服 (Dialogflow CX)：替换系统函数或网络钩子
- 对于 Dialogflow ES：webhook
查看语音自适应限制（对话式 AI 客服 [Dialogflow CX]、Dialogflow ES）。

针对受控对话进行设计

构建您的客服，并明确定义对话路径。确保客服人员可以请求满足用户要求所需的信息。避免对话范围过于宽泛，这可能会导致不可预测的行为。

分析日志

日志中会记录 Playbook、工具和数据存储区的输入和输出。使用收集的对话 ID 跟踪调用链，并确定执行出错的位置。

使用提示进行实验

如果一组特定说明无法按预期运行，请尝试改写说明。或者，您也可以使用 Gemini 生成提示（元提示）。这种迭代方法有助于找到最适合您的使用情形的措辞。

向支持团队提供完整信息

向 Cloud 支持团队提交支持请求时，请附上调查期间收集的相关对话 ID 和日志。这些信息对于高效调试问题至关重要。

问题排查

为代理启用 Cloud Logging

收集对话 ID

API 调用获取权限被拒绝

API 调用提及未知项目

API 调用收到无效的身份验证凭据错误

API 调用响应请求切换到其他主机

API 调用响应中缺少字段

由于安全锁而无法删除项目

Dialogflow ES 控制台

Dialogflow API

gcloud

API Explorer

gcloud

API Explorer

Dialogflow CX webhook 失败并显示“超出截止期限”错误

控制台无法设置项目

响应中显示的会话参数引用

控制台在未启用 API 时无法创建代理

尝试通过组织账号访问控制台时收到服务错误

由于缺少流程，无法以 JSON 格式导出代理

电话网关连接

尝试创建新电话号码时出 RESOURCE_EXHAUSTED 错误

Dialogflow CX Messenger 无响应

参数值匹配，但不是实体同义词

语音聊天机器人会跳过某些回答

SSML 标记未生效

语音代理将零读作字母 O

合成发音意外

已达到允许的状态机执行步骤上限

正则表达式匹配过于宽泛

语音识别插入了不必要的非字母数字

语音输入的转写内容为空

比较代理版本时出现空白屏幕，并显示“文件大小超过 2MB”错误

正则表达式实体无法准确识别字母数字

对话式客服 (Dialogflow CX) 示例

Dialogflow ES 示例

Dialogflow ES 示例

针对受控对话进行设计

分析日志

使用提示进行实验

向支持团队提供完整信息

尝试创建新电话号码时出 `RESOURCE_EXHAUSTED` 错误