이 페이지의 일부 또는 모든 정보는 S3NS의 Cloud de Confiance에 적용되지 않을 수 있습니다. 자세한 내용은 Google Cloud와의 차이점을 참조하세요.

Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

에이전트 배포 문제 해결

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

참고: 에이전트 오류 로그를 검색하고 필터링하려면 로그 탐색기를 사용하고 RESOURCE TYPE을 'Vertex AI 추론 엔진'으로 선택한 후 해당하는 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 스테이징 버킷에서 문제가 발생하는 경우 다음 문제 중 하나가 원인일 수 있습니다.

권한 오류

추천 솔루션:

기존 버킷을 사용하려면 Agent Platform을 사용하도록 인증된 주 구성원 (사용자 또는 서비스 계정)에 버킷에 대한 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을 사용하는 경우 경계에서 인그레스 규칙을 만들어 추론 엔진 서비스 에이전트 (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.s3ns-system.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 비율 제한 또는 동시 요청 할당량을 초과했습니다.

추천 솔루션:

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

리전이 일시적으로 용량 한도에 도달했습니다

문제:

429, RESOURCE_EXHAUSTED 상태와 함께 배포가 실패하고 리전의 총 허용 메모리 또는 CPU 용량이 일시적으로 부족하다는 메시지가 표시됩니다.

가능한 원인:

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

이 한도는 프로젝트 할당량 중 하나가 아닙니다.Cloud de Confiance 할당량 페이지에 표시되지 않으며 할당량 상향 조정을 요청하여 상향 조정할 수 없습니다.

추천 솔루션:

지원되는 다른 리전에 배포합니다. 이는 배포를 차단 해제하는 가장 빠른 방법입니다.
나중에 다시 시도하세요. 리전 용량 부족은 일반적으로 저절로 해결되는 일시적인 문제입니다.
에이전트에 더 적은 양의 메모리 또는 CPU를 요청합니다. 더 작은 배포는 남은 용량에 맞을 수 있습니다.
리전의 배포가 계속 실패하면 지원팀에 문의하세요. 한도를 늘릴 수는 없지만, 보고서를 통해 필요한 곳에 용량을 할당할 수 있습니다.

적용되지 않는 솔루션:

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

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

문제:

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

가능한 원인:

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

추천 솔루션:

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

적용되지 않는 솔루션:

이 한도는 프로젝트가 아닌 Google 관리 서빙 프로젝트에 적용되므로 프로젝트의 Cloud de Confiance 할당량 페이지에서 할당량 증가를 요청해도 효과가 없습니다.
프로젝트에서 다른 에이전트를 삭제하거나 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 플랫폼 추론 엔진 서비스 에이전트(service-PROJECT_NUMBER@gcp-sa-aiplatform-re.s3ns-system.iam.gserviceaccount.com)에 역할을 부여합니다.
- 커스텀 서비스 계정: 에이전트에 구성된 커스텀 서비스 계정에 역할을 부여합니다.

컨테이너 이미지 빌드 제한 시간 초과

문제:

504, DEADLINE_EXCEEDED 상태(REASONING_ENGINE_BUILD_TIMEOUT)와 에이전트의 컨테이너 이미지가 제시간에 빌드되지 않았다는 메시지와 함께 배포가 실패합니다.

가능한 원인:

소스 파일에서 배포하면 Agent Runtime이 코드와 종속 항목을 설치하는 컨테이너 이미지를 빌드합니다. 허용된 시간이 경과했을 때 빌드가 아직 실행 중이면 배포가 실패합니다. 빌드는 일반적으로 설치하는 종속 항목으로 인해 너무 오래 걸립니다. 예를 들면 다음과 같습니다.

상담사가 사용하지 않는 패키지를 포함하여 requirements의 긴 패키지 목록
빌드 환경에 사전 빌드된 휠이 없는 패키지이며 빌드 중에 소스에서 컴파일됩니다.
고정되지 않거나 느슨하게 고정된 버전으로 인해 종속 항목 해결이 느려집니다.

추천 솔루션:

오류 메타데이터의 logs_url 필드에 연결된 빌드 로그를 확인하여 빌드가 중지되었을 때 실행 중인 단계를 확인합니다.
불필요한 종속 항목을 삭제하고 모든 필수 패키지의 버전을 고정합니다.
빌드 중에 아무것도 컴파일되지 않도록 사전 빌드된 휠을 게시하는 패키지와 버전에 우선순위를 지정합니다.
배포를 다시 시도합니다. 코드와 관련 없는 이유로 빌드가 평소보다 오래 실행될 수 있습니다.

컨테이너가 제때 시작되지 않음

문제:

504, DEADLINE_EXCEEDED 상태(REASONING_ENGINE_CONTAINER_START_TIMEOUT) 및 에이전트 컨테이너가 제때 제공을 시작하지 않았다는 메시지와 함께 배포가 실패합니다.

가능한 원인:

이미지가 빌드되면 Agent Runtime이 에이전트의 컨테이너를 시작하고 요청을 처리할 준비가 될 때까지 기다립니다. 허용된 시간이 만료되었을 때 컨테이너가 아직 시작 중이면 배포가 실패합니다. 일반적인 원인은 다음과 같습니다.

에이전트의 모듈을 가져올 때 대규모 모델이나 파일을 로드하는 등 가져오기 시 작업이 느립니다.
에이전트의 set_up() 메서드에서 느리거나 차단되는 작업(예: 연결할 수 없는 서비스를 기다리는 네트워크 호출)

추천 솔루션:

오류 메타데이터의 logs_url 필드에 연결된 컨테이너 로그를 확인하여 시작이 중단된 위치를 확인합니다.
비용이 많이 드는 초기화를 모듈 가져오기 시간에서 제외하고 set_up()의 단계 수를 빠르게 최소화합니다. 첫 번째 요청을 처리하는 데 필요하지 않은 작업은 연기합니다.
시작 중에 에이전트가 호출하는 모든 서비스가 에이전트에서 연결 가능한지 확인하고 이러한 호출에 제한 시간을 설정하여 시작을 무기한 차단할 수 없도록 합니다.
컨테이너 로그에 에이전트가 정상적으로 시작되었다고 표시되면 배포를 다시 시도합니다. 코드와 관련 없는 이유로 시작하는 데 평소보다 오래 걸릴 수 있습니다.

지원 리소스

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