튜토리얼 문제 해결

튜토리얼을 구성하는 데 문제가 발생할 경우 이 페이지에서는 발생할 수 있는 문제를 나열하고 각 문제의 해결 방법을 제안합니다.

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.] 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 및 편집자)이 없는 경우에 발생합니다. 이 문제를 해결하려면 '작업 환경 준비' 튜토리얼 단계에 따라 작업 환경을 설정하세요.

검색 작업이 일치하는 결과를 반환하지 않음

이 문제는 카탈로그에 검색어와 일치하는 제품이 없거나 제품 카탈로그가 비어 있을 때 발생합니다. 이 문제를 해결하려면 Google Cloud 콘솔의 카탈로그 페이지에서 카탈로그에 있는 제품이 있는지 확인하세요. 그렇지 않은 경우 '카탈로그 데이터 가져오기' 튜토리얼 단계에 따라 카탈로그 데이터를 가져오세요.

아직 문제가 있는 경우

Cloud Shell을 재설정하고 튜토리얼을 처음부터 실행합니다.