이 문서에서는 에이전트를 배포할 때 발생할 수 있는 오류를 해결하는 방법을 보여줍니다.
사전 빌드된 템플릿 오류
배포 중에 LangchainAgent 템플릿에 문제가 발생하면 이 섹션의 문제 중 하나 때문일 수 있습니다.
내부 서버 오류
문제:
다음과 유사한 오류 메시지가 표시됩니다.
InternalServerError: 500 Revision XXX is not ready and cannot serve traffic.
안타깝게도 이 오류는 런타임 시 컨테이너와 관련된 모든 문제에 대한 포괄적인 오류이며 발생할 수 있는 여러 오류 중 하나가 원인일 수 있습니다.
가능한 원인
LangchainAgent의 더티 상태 이는 에이전트를 배포하기 전에LangchainAgent에서.set_up()이 호출된 경우에 발생할 수 있습니다.- 일관되지 않은 패키지 버전 이는 개발 환경에 설치된 패키지가 Vertex AI Agent Engine의 원격 환경에 설치된 패키지와 다르면 발생할 수 있습니다.
추천 해결 방법
LangchainAgent의 더티 상태 에이전트를 배포하기 전에LangchainAgent의 새 인스턴스를 인스턴스화하거나 코드에서agent.set_up()을 삭제합니다.- 일관되지 않은 패키지 사양 직렬화 오류 문제 해결 섹션을 참조하세요.
직렬화 오류
일반적으로 에이전트를 배포할 때 '로컬' 및 '원격' 환경이 동기화되어 있는지 확인하는 것이 중요합니다. 에이전트를 배포할 때 requirements=를 지정하면 동기화 여부를 확인할 수 있습니다.
직렬화에 문제가 발생하는 경우('pickle' 또는 'pickling'과 관련된 오류는 'serialization' 오류와 동의어임) 이 섹션에 설명된 문제 중 하나가 원인일 수 있습니다.
Pydantic 버전
문제:
다음과 유사한 오류 메시지가 표시됩니다.
PicklingError: Can't pickle <cyfunction str_validator at 0x7ca030133d30>: it's
not the same object as pydantic.validators.str_validator
가능한 원인:
pydantic 패키지가 2.6.4 이전 버전이면 이러한 문제가 발생할 수 있습니다. 사용 중인 버전을 확인하려면 터미널에서 다음 명령어를 실행합니다.
pip show pydantic추천 솔루션:
터미널에서 다음 명령어를 실행하여 패키지를 업데이트합니다.
pip install pydantic --upgrade터미널에서 다음 명령어를 실행하여 사용 중인 버전이 2.6.4 이상인지 확인합니다.
pip show pydantic노트북 인스턴스(예: Jupyter, Colab 또는 Workbench)를 사용하는 경우 런타임을 다시 시작하여 업데이트된 패키지를 사용해야 할 수 있습니다.
Cloudpickle 버전
문제:
다음과 유사한 오류 메시지가 표시됩니다.
AttributeError: Can't get attribute '_class_setstate' on <module 'cloudpickle.cloudpickle'
from '/usr/local/lib/python3.10/site-packages/cloudpickle/cloudpickle.py'>
가능한 원인:
이는 개발 환경과 배포 환경에서 cloudpickle 패키지 버전이 다르면 발생할 수 있습니다. 개발에서 사용 중인 버전을 확인하려면 터미널에서 다음 명령어를 실행합니다.
pip show cloudpickle추천 솔루션:
에이전트를 배포할 때 requirements=를 지정하여 두 환경(로컬 개발 환경과 원격으로 배포된 에이전트 등)에 동일한 버전의 cloudpickle을 배포합니다.
내부 서버 오류
문제:
다음과 유사한 오류 메시지가 표시됩니다.
InternalServerError: 500 Revision XXX is not ready and cannot serve traffic.
가능한 원인:
이는 에이전트를 배포할 때 sys_version=이 개발 환경과 다르면 발생할 수 있습니다.
추천 솔루션:
에이전트를 배포한 후 입력 인수에서 sys_version=을 삭제하는 것이 좋습니다.
문제가 여전히 해결되지 않으면 버그 신고를 제출합니다.
Cloud Storage 버킷 오류
배포 시 에이전트를 수집하고 업로드하는 데 사용되는 Cloud Storage 스테이징 버킷에서 문제가 발생하는 경우 다음 문제 중 하나가 원인일 수 있습니다.
권한 오류
추천 솔루션:
기존 버킷을 사용하려면 Vertex AI를 사용하도록 인증된 주 구성원(사용자 또는 서비스 계정)에 버킷에 대한 Storage Admin 액세스 권한이 있는지 확인하고 서비스 계정에 권한을 부여합니다.
또는 에이전트를 배포할 때 새 버킷을 지정하면 됩니다. 이렇게 하면 SDK에서 필요한 권한으로 버킷을 만듭니다.
문제가 여전히 해결되지 않으면 버그 신고를 제출합니다.
Cloud Storage 버킷 하위 디렉터리가 생성되지 않음
문제:
다음과 유사한 오류 메시지가 표시됩니다.
NotFound: 404 Can not copy from \"gs://[LOCATION]-*/agent_engine/agent_engine.pkl\" to \"gs://*/code.pkl\", check if the source object and target bucket exist.
시스템이 존재하지 않는 폴더에 복사하려고 시도하면 404 오류가 발생합니다.
가능한 원인:
1.49.0 버전 이전의 google-cloud-aiplatform에서 발생하는 문자열 보간 유형 문제가 원인일 수 있습니다. 이 문제는 이후 버전에서 수정되었습니다. 사용 중인 google-cloud-aiplatform 버전을 확인하려면 터미널에서 다음 명령어를 실행합니다.
pip show google-cloud-aiplatform추천 솔루션:
터미널에서 다음 명령어를 실행하여 패키지를 업데이트합니다.
pip install google-cloud-aiplatform --upgrade터미널에서 다음 명령어를 실행하여 1.49.0 이상 버전의 google-cloud-aiplatform을 사용하고 있는지 확인합니다.
pip show google-cloud-aiplatform노트북 인스턴스(예: Jupyter, Colab 또는 Workbench)를 사용하는 경우 업데이트된 패키지를 사용하려면 먼저 런타임을 다시 시작해야 할 수 있습니다.
VPC-SC 위반 오류
VPC-SC에 문제가 있는 경우 다음 문제 중 하나가 원인일 수 있습니다.
권한 오류
문제:
다음과 유사한 오류 메시지가 표시됩니다.
Reasoning Engine instance REASONING_ENGINE_ID failed to start and cannot serve traffic.
또는
Request is prohibited by organization's policy.
가능한 원인:
VPC-SC 경계에 필요한 인그레스 규칙이 누락되어 발생했을 수 있습니다.
추천 솔루션:
VPC-SC 환경에서 Vertex AI Agent Engine을 사용하는 경우 경계에서 인그레스 규칙을 만들어 Reasoning Engine 서비스 에이전트(service-PROJECT_NUMBER@gcp-sa-aiplatform-re.)에서 storage.googleapis.com 서비스 및 artifactregistry.googleapis.com 서비스로의 인그레스를 허용해야 합니다.
커스텀 서비스 계정 오류
서비스 계정에 문제가 있는 경우 다음 문제 중 하나가 원인일 수 있습니다.
서비스 계정 역할
문제:
다음과 유사한 오류 메시지가 표시됩니다.
You do not have permission to act as service_account.
가능한 원인:
배포에 사용되는 커스텀 서비스 계정에 iam.serviceAccounts.actAs 권한이 없을 수 있습니다. 커스텀 서비스 계정이 여러 개인 멀티 에이전트 시스템에서는 하나의 에이전트 작성자 또는 배포자가 일부 서비스 계정의 역할을 할 수 있습니다. 잘못된 서비스 계정을 사용하는 경우 이 오류는 예상되는 동작입니다.
또한 커스텀 서비스 계정이 에이전트를 배포하는 프로젝트와 다른 프로젝트에 있고 서비스 계정 프로젝트에서 iam.disableCrossProjectServiceAccountUsage 조직 정책이 시행되는 경우 이 오류가 발생할 수 있습니다.
이 시나리오에 필요한 구성의 전체 목록은 프로젝트 간 커스텀 서비스 계정을 참조하세요.
추천 솔루션:
의도한 서비스 계정을 사용하고 있는지 확인합니다. 이 서비스 계정에 서비스 계정 사용자(roles/iam.serviceAccountUser) 역할이 있는지 확인합니다. 그렇지 않으면 관리자에게 이 서비스 계정에 대한 역할을 부여해 달라고 요청하세요.
프로젝트 간 시나리오인 경우 서비스 계정 프로젝트에 iam.disableCrossProjectServiceAccountUsage 조직 정책이 적용되어 있는지 확인합니다.
이 경우 관리자에게 정책을 중지해 달라고 요청하세요.
메타데이터 서버를 사용할 수 없음
문제:
다음과 유사한 오류 메시지가 표시됩니다.
ServiceUnavailable: 503 Getting metadata from plugin failed with error
또는
Compute Engine Metadata server unavailable due to : Could not fetch URI /computeMetadata/v1/instance/service-accounts/default/token
가능한 원인:
커스텀 서비스 계정과 에이전트가 서로 다른 프로젝트에 있고 AI Platform Reasoning Engine 서비스 에이전트에 커스텀 서비스 계정에 대한 iam.serviceAccounts.getAccessToken 권한이 없는 경우 이러한 문제가 발생할 수 있습니다.
이 시나리오에 필요한 구성의 전체 목록은 프로젝트 간 커스텀 서비스 계정을 참조하세요.
추천 솔루션:
관리자에게 에이전트 프로젝트의 AI Platform Reasoning Engine 서비스 에이전트에 커스텀 서비스 계정에 대한 서비스 계정 토큰 생성자(roles/iam.serviceAccountTokenCreator) 역할을 부여해 달라고 요청합니다.
AI Platform Reasoning Engine 서비스 에이전트는 에이전트를 배포하는 데 사용하는 프로젝트와 동일한 프로젝트에 있어야 합니다. 역할 부여의 IAM 바인딩은 커스텀 서비스 계정이 있는 프로젝트에 있어야 합니다.
지원 리소스
여전히 문제가 해결되지 않으면 지원 가이드를 참조하여 도움을 받으세요.