排查教程问题

如果您在配置教程时遇到问题，本页面会列出您可能会遇到的问题并提供关于如何解决每个问题的建议。

cloudshell_open 文件夹缺失

如果运行 ls ~ 后无法在主目录中看到 cloudshell_open 文件夹，则该文件夹及其文件将会丢失。 如果在暂存模式下使用 Cloud Shell，并且互联网连接中断或刷新页面，就会出现此问题。 如需解决此问题，请重新运行本教程。为避免文件日后丢失，请考虑切换到默认模式。

在当前环境中无法检测到项目 ID

当您尝试运行代码示例时，会发生以下错误：

ERROR Unable to detect a Project Id in the current environment.

如果未设置 Google Cloud 项目，就会出现此问题。如需解决此问题，请运行以下命令来设置项目：

gcloud config set project <YOUR-PROJECT-ID>

运行代码示例时出现 key.json 错误

运行代码示例时，会出现以下错误之一：

File /home/user/key.json is not a valid json file

no JSON input found

The file at /home/user/key.json does not exist, or it is not a file

Could not find file '/home/user/key.json'

Error reading credential file from location /home/user/key.json: Value cannot be null

当用于对服务帐号进行身份验证的 key.json 文件为空或缺失时，就会出现此问题。您可以通过运行以下命令来检查是否存在这种情况：

cat ~/key.json

这将输出文件的内容或 No such file or directory 消息。空文件表示密钥创建期间发生了错误。如果缺少文件，则意味着之前发生了错误。 如需解决此问题，请按照“准备工作环境”教程步骤操作。

项目之前未使用过或已停用适用于零售业的 Vertex AI Search

当您尝试运行教程时，会发生以下错误：

PERMISSION_DENIED: Vertex AI Search for retail API has not been used in project <YOUR-PROJECT-ID> before or it is disabled

如需解决此问题，请在 Google Cloud 控制台的 API/服务详情页面上启用适用于零售业的 Vertex AI Search，或运行以下命令：

gcloud services enable \
    retail.googleapis.com \
    --project=<YOUR-PROJECT-ID>

服务账号无权访问项目实例

为服务帐号分配角色时发生以下错误：

User [USER@YOUR-PROJECT-ID.iam.gserviceaccount.com] does not have permission to access projects instance [YOUR-PROJECT-ID:setIamPolicy] (or it may not exist): Policy update access denied.

如需解决此问题，请在终端中运行 gcloud auth list 命令，检查您是否已启用正确的帐号。确保活跃帐号是服务帐号。转到 Google Cloud 控制台中的 IAM 页面，检查服务帐号是否是您的 Google Cloud 项目的所有者。

使用最终用户凭据进行的身份验证无效

运行代码示例时，发生以下错误：

PERMISSION_DENIED: Your application has been authenticated using end user credentials from the Google Cloud SDK or Google Cloud Shell which are not supported by the retail.googleapis.com.

如果使用的是最终用户凭据而非服务帐号，就会出现此问题。如果服务帐号处于非活跃状态或未设置所需的环境变量，也可能会发生此问题。重启 Cloud Shell 或打开新的终端窗口后，您可能会看到此错误。

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

  1. 按照“准备工作环境”教程步骤操作，并通过运行 gcloud auth list 确保您拥有有效的服务帐号。

  2. 设置环境变量：

    1. 对于所有语言，请运行以下命令：
    export GOOGLE_APPLICATION_CREDENTIALS=~/key.json
    1. 此外，对于 .NET，请运行以下命令：
    export GOOGLE_PROJECT_ID=<YOUR-PROJECT-ID>

服务帐号没有所需的角色时出现权限错误

运行代码示例时，发生以下错误：

google.api_core.exceptions.PermissionDenied: 403 Permission 'retail.<YOUR-REQUEST>' denied on resource '//retail.googleapis.com/projects/<YOUR-PROJECT-ID>/locations/<YOUR-LOCATION>' (or it may not exist). [reason: "IAM_PERMISSION_DENIED"

如果您的服务帐号没有所需的角色：Retail.admin 和 Editor，就会出现此问题。如需解决此问题，请按照“准备工作环境”教程步骤设置工作环境。

搜索操作未返回任何匹配结果

如果清单中没有任何产品与您的搜索查询匹配，或者产品目录为空，就会出现此问题。 如需解决此问题，请在 Google Cloud 控制台的目录页面上查看您的目录中是否有商品。如果没有，请按照“导入清单数据”教程步骤导入清单数据。

仍然存在问题

尝试重置 Cloud Shell 并从头开始运行教程。