Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

问题排查

为代理启用 Cloud Logging

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

收集对话 ID

发生意外行为时，请收集 Dialogflow 对话 ID。这些 ID 位于对话记录中，可用于跟踪对话的执行路径并检查特定互动。

API 调用获取权限被拒绝

问题

收到 API 调用的 PERMISSION_DENIED 响应。

解决方案

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

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

API 调用提及未知项目

问题

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

解决方案

确保您已完成以下操作：

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

API 调用收到“身份验证凭证无效”错误

问题

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

解决方案

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

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

问题

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

解决方案

当您在请求中指定了区域但未指定端点时，就会发生这种情况。如需相关指导，请参阅以下内容之一：

API 调用响应中缺少字段

问题

API 响应中缺少某些字段。

解决方案

如果您希望在 API 响应中看到特定字段的数值，但返回的值为 0，则该字段可能不会出现在响应中。

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

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

问题

尝试删除 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 面板：
- 在 name 字段中填写您在第 2 步中获取的留置权名称。
- 点击执行。
关停项目。

Dialogflow CX 网络钩子失败，并显示“超出截止时间”错误

问题

从 Dialogflow CX 调用的网络钩子可能会失败，并显示以下错误消息：

Webhook call failed. Error: DEADLINE_EXCEEDED

这可能是因为 webhook 调用超出了 webhook 超时限制。以下是 webhook 调用超出超时限制的可能原因：

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

临时解决方法

默认情况下，Webhook 的超时限制为 5 秒。您可以在创建或修改网络钩子资源时提高网络钩子超时限制，这将为网络钩子提供更多响应时间。

控制台无法设置项目

问题

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

解决方案

您可能无权创建 Google Cloud 项目。检查您是否可以直接从控制台创建 Google Cloud 项目。如果您无法创建项目，请按照出错提示中提供的建议操作。

回答中显示的会话参数引用

问题

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

如果当前会话中未找到参数，或者参数未根据其类型使用，则不会解析参数，并且会显示参数引用。

解决方案

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

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

问题

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

解决方案

按照设置步骤启用 Dialogflow API。

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

问题

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

解决方案

请与贵组织的系统管理员联系，确认贵组织的设置是否允许访问控制台。否则，请检查您从其他组织迁移的账号是否已被 Google 标记为受限账号。如果贵组织中的其他用户可以访问控制台，但您无法访问，则很可能是这个原因。

或者，您也可以联系支持团队寻求帮助。

由于缺少 flow，无法以 JSON 格式导出智能体

问题

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

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

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

解决方案

如需解决此问题，请探索未使用的测试用例，确认出错提示中引用的流程是否在任何测试用例中使用，然后删除确认的测试用例。

电话网关连接

问题

使用 Phone Gateway 时，您会听到忙音或通话中断。

解决方案

此功能存在配额和限制。如果您听到忙音或通话中断，则可能是因为您超出了配额。

尝试创建新手机号码时出现 `RESOURCE_EXHAUSTED` 错误

问题

尝试在 Dialogflow CX、Dialogflow ES 或 Agent Assist 中创建新手机号码时，系统会返回 RESOURCE_EXHAUSTED 错误。

解决方案

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

如果您在 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 步：（可选）识别与对话配置文件关联的智能体

通过对话配置文件获取与手机号码关联的 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

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

对于 Dialogflow ES，一个项目最多只能与五个代理关联，一个 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 Messenger 互动无代理响应。

解决方案

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

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

问题

一般情况：即使与参数对应的实体不包含作为同义词的匹配值，也会在运行时提取参数值。
更具体的情况：从实体中删除同义词并重新训练代理后，此同义词仍会作为此实体的参数值提取。

解决方案

使用搜索选项检查匹配的值是否可能作为隐式实体存在于代理中（Dialogflow CX、Dialogflow ES）。查找具有此参数和实体注释的所有 intent。
通过确保这些注释均未应用于表示不希望匹配的值的文本来修复注释。
在运行时测试代理，以验证问题是否已解决。
如果问题仍然存在，请确保在高级实体设置中取消选中自动扩展和模糊匹配选项，然后再次测试代理。

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

问题

对于同时支持文本和语音的代理，语音机器人不会朗读某些回答。

解决方案

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

SSML 标签未生效

问题

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

解决方案

确保 Dialogflow 控制台中的每个响应卡片或每个响应消息对象（如果响应由 API 或网络钩子提供）仅存在一个 <speak></speak> 对。

语音智能体将数字零读作字母 O

问题

对于专为语音设计的代理，语音代理会将数字零读作字母 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>

合成发音不符合预期

问题

智能体回答的合成发音（例如专有名词、首字母缩写词）不符合预期。

解决方案

如需保证不常用字词的特定发音，请在代理回答中使用 SSML say-as 或 phoneme 标记。

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

问题

向代理发送运行时请求时，在 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" 字段在大多数步骤中具有重复值。
修改代理设计，以移除无限循环转换或减少单个对话轮次的转换次数。

正则表达式匹配范围过广

问题

创建正则表达式实体时收到错误 Regular expression match is too broad (Dialogflow CX、Dialogflow ES)。

解决方案

请考虑以下方法：

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

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

问题

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

解决方案

如果您使用系统实体来匹配数字，请考虑改用正则表达式实体（Dialogflow CX、Dialogflow ES）。
遵循正则表达式实体对字母数字语音识别不准确部分中的所有建议。
对于使用电话集成匹配数字的情况，除了语音识别之外，还可以考虑使用 DTMF 选项。

语音输入的转写内容为空

问题

针对语音输入的 Dialogflow 响应会返回空转写。这些请求会被视为无输入或无匹配。

解决方案

请听一下录音，确认其中是否包含语音。

确保在代理设置（Dialogflow CX、Dialogflow ES）中启用了语音自适应。

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

latest_short
phone_call
command_and_search

对于英语以外的其他语言，请在 Speech-to-Text 支持的语言文档中查找支持的语音模型。

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

对于 API 请求，请在 InputAudioConfig（Dialogflow CX、Dialogflow ES）的 model 字段中提供模型名称。
如果您使用 Phone Gateway（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 集成，请咨询您的电话集成商，了解如何更新集成或单个请求的语音模型。

了解 playbook 循环错误

问题

关联 playbook 时，您遇到了错误 Playbook <playbookID> caused loop in playbook routes。

解决方案

如果您尝试路由到“祖先”playbook（直接或间接调用当前 playbook 的 playbook），则可能会发生循环。如需解决此问题，请验证您的 playbook 路由是单向的，并且不会在同一对话路径中循环回到父级 playbook。

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

问题

尝试比较两个不同的代理版本时，屏幕会变为空白，并显示以下出错提示：

File size exceeds 2MB

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

解决方案

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

正则表达式实体对字母数字语音识别不准确

问题

对于旨在与正则表达式实体匹配的字母数字语音输入，收到了不准确的转写内容（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 示例
确保您的测试遵循测试指南（Dialogflow CX、Dialogflow ES）。
如需移除可能由语音识别器插入的非字母数字字符，请使用以下命令：
- 对于 Dialogflow CX：SUBSTITUTE 系统函数或网络钩子
- 对于 Dialogflow ES：webhook
查看语音自适应限制（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 网络钩子失败，并显示“超出截止时间”错误

控制台无法设置项目

回答中显示的会话参数引用

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

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

由于缺少 flow，无法以 JSON 格式导出智能体

电话网关连接

尝试创建新手机号码时出现 RESOURCE_EXHAUSTED 错误

Dialogflow CX Messenger 无响应

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

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

SSML 标签未生效

语音智能体将数字零读作字母 O

合成发音不符合预期

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

正则表达式匹配范围过广

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

语音输入的转写内容为空

了解 playbook 循环错误

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

正则表达式实体对字母数字语音识别不准确

Dialogflow CX 示例

Dialogflow ES 示例

Dialogflow ES 示例

设计可控的对话

分析日志

尝试使用提示

向支持团队提供完整信息

问题排查

尝试创建新手机号码时出现 `RESOURCE_EXHAUSTED` 错误