에이전트 배포 문제 해결

이 문서에서는 Agent Runtime에 에이전트를 배포할 때 발생할 수 있는 오류를 해결하는 방법을 설명합니다. 여기에는 직렬화 실패, 권한 오류, VPC-SC 경계 위반 등 다양한 일반적인 문제가 포함됩니다.

참고: 에이전트 오류 로그를 검색하고 필터링하려면 로그 탐색기를 사용하고 RESOURCE TYPE을 'Vertex AI Reasoning Engine'으로 선택한 후 해당하는 RESOURCE CONTAINER 값 (즉, 프로젝트 번호)과 REASONING ENGINE ID 값을 선택하세요.

사전 빌드된 템플릿 오류

배포 중에 LangchainAgent 템플릿에 문제가 발생하면 이 섹션의 문제 중 하나 때문일 수 있습니다.

내부 서버 오류

문제:

다음과 유사한 오류 메시지가 표시됩니다.

InternalServerError: 500 Revision YYY is not ready and cannot serve traffic.

안타깝게도 이 오류는 런타임 시 컨테이너와 관련된 모든 문제에 대한 포괄적인 오류이며 발생할 수 있는 여러 오류 중 하나가 원인일 수 있습니다.

가능한 원인

  • LangchainAgent의 더티 상태 이는 에이전트를 배포하기 전에 LangchainAgent에서 .set_up()이 호출된 경우에 발생할 수 있습니다.
  • 일관되지 않은 패키지 버전 이는 개발 환경에 설치된 패키지가 Agent Runtime의 원격 환경에 설치된 패키지와 다르면 발생할 수 있습니다.

추천 해결 방법

  • 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 YYY is not ready and cannot serve traffic.

가능한 원인:

이는 에이전트를 배포할 때 sys_version=이 개발 환경과 다르면 발생할 수 있습니다.

추천 솔루션:

에이전트를 배포한 후 입력 인수에서 sys_version=을 삭제하는 것이 좋습니다. 문제가 여전히 해결되지 않으면 버그 신고를 제출합니다.

Cloud Storage 버킷 오류

배포 시 에이전트를 수집하고 업로드하는 데 사용되는 Cloud Storage 스테이징 버킷에서 문제가 발생하는 경우 다음 문제 중 하나가 원인일 수 있습니다.

권한 오류

추천 솔루션:

기존 버킷을 사용하려면 에이전트 플랫폼을 사용하도록 인증된 주 구성원 (사용자 또는 서비스 계정)에 버킷에 대한 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 환경에서 Agent Platform을 사용하는 경우 경계에서 인그레스 규칙을 만들어 Reasoning Engine 서비스 에이전트 (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com)에서 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 바인딩은 커스텀 서비스 계정이 있는 프로젝트에 있어야 합니다.

리소스 소진 또는 비율 제한 오류 (오류 429)

문제:

Error 429 또는 RESOURCE_EXHAUSTED 상태로 배포가 실패합니다.

가능한 원인:

프로젝트가 API 비율 제한 또는 동시 요청 할당량을 초과했습니다.

추천 솔루션:

  • 배포 스크립트에서 지수 백오프 및 재시도 전략을 구현합니다.
  • Google Cloud 할당량 페이지에서 'Agent Platform API'의 한도에 대한 현재 사용량을 확인합니다.
  • 동시 배포 빈도를 줄입니다.

일시적으로 용량 한도에 도달한 리전

문제:

429, RESOURCE_EXHAUSTED 상태와 함께 리전의 총 허용 메모리 또는 CPU 양이 일시적으로 한도에 도달했다는 메시지가 표시되며 배포가 실패합니다.

가능한 원인:

리전의 에이전트 배포는 Agent Runtime이 사용자를 대신하여 관리하고 해당 리전의 모든 고객이 공유하는 서비스 제공 용량 풀을 사용합니다. 풀이 소진되면 용량이 확보될 때까지 해당 리전의 새 배포가 실패합니다.

이 한도는 프로젝트 할당량에 포함되지 않습니다.Google Cloud 할당량 페이지에 표시되지 않으며 할당량 상향 조정을 요청해도 늘릴 수 없습니다.

추천 솔루션:

  • 지원되는 다른 리전에 배포합니다. 배포를 차단 해제하는 가장 빠른 방법입니다.
  • 나중에 다시 시도하세요. 용량이 가득 찬 지역은 일시적인 문제이며 일반적으로 자동으로 해결됩니다.
  • 에이전트의 메모리 또는 CPU를 더 적게 요청합니다. 더 작은 배포는 남은 용량 내에 맞을 수 있습니다.
  • 리전의 배포가 이러한 방식으로 계속 실패하면 지원팀에 문의하세요. 한도를 늘릴 수는 없지만 신고를 통해 필요한 곳에 용량을 할당할 수 있습니다.

적용되지 않는 해결 방법:

  • 기존 에이전트를 삭제해도 이 한도의 용량이 확보되지 않습니다. 용량은 프로젝트에서만 사용하는 것이 아니기 때문입니다.
  • 한도가 프로젝트 할당량이 아니므로 할당량 상향을 요청해도 아무런 효과가 없습니다.

최대 인스턴스가 리전 한도를 초과함

문제:

429, RESOURCE_EXHAUSTED 상태와 spec.deployment_spec.max_instances가 리전의 resource_limits에서 요청된 CPU 또는 메모리에 지원되는 최대 인스턴스 수를 초과한다는 메시지와 함께 배포가 실패합니다.

가능한 원인:

에이전트를 배포하면 Agent Runtime이 spec.deployment_spec.resource_limits에서 인스턴스당 cpu 및 memory로 spec.deployment_spec.max_instances를 곱하고 이 단일 에이전트의 최대 할당이 기본 제공 프로젝트의 지역 한도 내에 맞는지 확인합니다. max_instances을 지정하지 않으면 Agent Runtime이 기본값(예: 200)을 적용하며, 이 값은 제한이 낮은 리전에서 구성된 인스턴스별 cpu 또는 memory와 곱해질 때 지원되는 최대 인스턴스를 초과할 수 있습니다.

추천 솔루션:

  • spec.deployment_spec.max_instances을 오류 메시지에 표시된 최댓값 이하로 설정합니다.
  • spec.deployment_spec.resource_limits에서 인스턴스별 cpu 또는 memory 값을 줄입니다.
  • 제한이 더 높은 지원되는 다른 리전에 에이전트를 배포합니다.

적용되지 않는 해결 방법:

  • 이 한도는 프로젝트가 아닌 Google 관리 서비스 프로젝트에 적용되므로 프로젝트의 Google Cloud 할당량 페이지에서 할당량 증가를 요청해도 효과가 없습니다.
  • 프로젝트에서 다른 에이전트를 삭제하거나 max_instances 또는 resource_limits를 변경하지 않고 다시 시도해도 이 오류가 해결되지 않습니다. 검사에서는 단일 배포의 최대 할당량을 정적 한도와 비교하여 평가하기 때문입니다.

Secret Manager 액세스 오류

문제:

400, INVALID_ARGUMENT 상태(REASONING_ENGINE_SECRET_ACCESS_DENIED)와 다음과 유사한 메시지가 표시되면서 배포가 실패합니다.

The Reasoning Engine could not access `projects/PROJECT_NUMBER/secrets/SECRET_ID/versions/VERSION_ID` referenced by `spec.deployment_spec.secret_env` (reason: FAILURE_REASON).

가능한 원인:

  • NOT_FOUND: secret_env에 지정된 보안 비밀 ID 또는 버전 ID가 배포된 에이전트와 동일한 프로젝트의 Secret Manager에 없거나 오타가 포함되어 있습니다.
  • DESTROYED 또는 DISABLED: Secret Manager에서 참조된 보안 비밀 버전이 폐기됨 또는 사용 중지 상태입니다.
  • PERMISSION_DENIED: 에이전트에서 사용하는 서비스 계정에 참조된 보안 비밀에 대한 Secret Manager 보안 비밀 접근자 역할(roles/secretmanager.secretAccessor)이 없습니다.

추천 솔루션:

  • NOT_FOUND, DESTROYED 또는 DISABLED의 경우:
    1. 에이전트를 배포하는 프로젝트의 Secret Manager 페이지에서 secret_env에 참조된 각 SECRET_ID 및 VERSION_ID가 존재하고 사용 설정됨 상태인지 확인합니다.
    2. 참조된 버전을 사용 중지하거나 폐기한 경우 유효한 버전을 사용 설정하거나 secret_env를 업데이트하여 사용 설정된 버전을 참조하세요.
  • PERMISSION_DENIED의 경우: 보안 비밀을 가져오는 서비스 계정에 보안 비밀(또는 보안 비밀이 포함된 프로젝트)에 대한 Secret Manager 보안 비밀 접근자 역할 (roles/secretmanager.secretAccessor)을 부여합니다.
    • 기본 서비스 계정: AI Platform Reasoning Engine 서비스 에이전트(service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com)에 역할을 부여합니다.
    • 커스텀 서비스 계정: 에이전트에서 구성된 커스텀 서비스 계정에 역할을 부여합니다.

지원 리소스

여전히 문제가 해결되지 않으면 지원 가이드를 참조하여 도움을 받으세요.