이 문서에서는 에이전트를 사용할 때 발생할 수 있는 오류를 해결하는 방법을 설명합니다.
작업 스키마가 비어 있음
에이전트가 .operation_schemas()
에서 빈 목록을 반환하는 경우 다음 문제 중 하나가 원인일 수 있습니다.
에이전트 생성 중에 스키마 생성 실패
문제:
에이전트를 배포하면 다음과 유사한 경고가 표시됩니다.
WARNING:vertexai.agent_engines:failed to generate schema: issubclass() arg 1 must be a class
가능한 원인:
1.49.0
보다 이전 버전의 google-cloud-aiplatform
에서 사전 빌드된 LangchainAgent
템플릿을 사용하여 에이전트를 배포하면 이 경고가 발생할 수 있습니다. 사용 중인 버전을 확인하려면 터미널에서 다음 명령어를 실행합니다.
pip show google-cloud-aiplatform
추천 솔루션:
터미널에서 다음 명령어를 실행하여 google-cloud-aiplatform
패키지를 업데이트합니다.
pip install google-cloud-aiplatform --upgrade
google-cloud-aiplatform
패키지를 업데이트한 후 다음 명령어를 실행하여 버전이 1.49.0
이상인지 확인합니다.
pip show google-cloud-aiplatform
노트북 인스턴스(예: Jupyter, Colab 또는 Workbench)를 사용하는 경우 런타임을 다시 시작하여 업데이트된 패키지를 사용해야 할 수 있습니다. google-cloud-aiplatform
버전이 1.49.0
이상인지 확인한 후 다시 에이전트를 배포해 보세요.
에이전트를 쿼리할 때 PermissionDenied
오류 발생
필요한 권한이 없으면 쿼리가 실패할 수 있습니다.
Vertex AI 확장 프로그램 권한
문제
다음과 유사한 PermissionDenied
오류가 표시될 수 있습니다.
Permission 'aiplatform.extensions.get' denied on resource
'//aiplatform.googleapis.com/projects/{PROJECT_ID}/locations/{LOCATION}/extensions/
{EXTENSION}' (or it may not exist). [reason: "IAM_PERMISSION_DENIED"
domain: "aiplatform.googleapis.com"
metadata {
key: "permission"
value: "aiplatform.extensions.get"
}
metadata {
key: "resource"
value: "projects/{PROJECT_ID}/locations/{LOCATION}/extensions/{EXTENSION}"
}
]
에이전트에게 Vertex AI 확장 프로그램 권한이 없습니다. Vertex AI Agent Engine에서 Vertex AI 확장 프로그램을 사용하려면 에이전트 ID 서비스 계정에 Vertex AI 사용자(roles/aiplatform.user
) 역할을 부여하세요.
자세한 내용은 에이전트의 ID 및 권한 설정을 참고하세요.
LLM 권한
문제:
다음과 유사한 PermissionDenied
오류가 표시될 수 있습니다.
PermissionDenied: 403 Permission 'aiplatform.endpoints.predict' denied on resource
'//aiplatform.googleapis.com/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/
google/models/{MODEL}' (or it may not exist). [reason: "IAM_PERMISSION_DENIED"
domain: "aiplatform.googleapis.com"
metadata {
key: "permission"
value: "aiplatform.endpoints.predict"
}
metadata {
key: "resource"
value: "projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL}"
}
]
가능한 원인:
에이전트 ID인 서비스 계정에 대규모 언어 모델 (LLM)을 쿼리할 적절한 권한이 없을 수 있습니다.
추천 솔루션:
서비스 계정에 오류 메시지에 나열된 적절한 Identity and Access Management(IAM) 권한이 있는지 확인합니다. 누락된 IAM 권한의 예시는 aiplatform.endpoints.predict
입니다. 자세한 내용은 에이전트의 ID 및 권한 설정을 참고하세요.
Reasoning Engine 실행 실패
에이전트를 쿼리할 때 '추론 엔진 실행 실패' 오류 메시지가 표시되는 경우 이 섹션에 설명된 문제 중 하나가 원인일 수 있습니다.
.query()
에 잘못된 입력값
문제:
다음과 유사한 FailedPrecondition
오류가 표시될 수 있습니다.
FailedPrecondition: 400 Reasoning Engine Execution failed. Error Details:
{"detail":"Invalid request: `{'query': ...}`"}
가능한 원인:
이 오류는 쿼리의 입력을 키워드 인수가 아닌 위치 인수로 지정할 때 발생합니다. 예를 들어 agent.query(input=query_str)
대신 agent.query(query_str)
를 호출합니다.
추천 솔루션:
배포된 Reasoning Engine의 인스턴스를 쿼리할 때는 모든 입력을 키워드 인수로 지정합니다.
Gemini 모델 할당량 소진
문제:
Gemini 호출에서 오류가 발생했음을 나타내는 다음과 유사한 오류가 표시될 수 있습니다.
FailedPrecondition: 400 Reasoning Engine Execution failed. Error Details:
{"detail":"...langchain_google_vertexai/chat_models.py...google.api_core.exceptions.ResourceExhausted: 429 Unable to submit request because the service is temporarily out of capacity. Try again later."}
또는 다른 오류 메시지가 표시됩니다.
FailedPrecondition: 400 Reasoning Engine Execution failed. Error Details:
{"detail":"...langchain_google_vertexai/chat_models.py...google.api_core.exceptions.InternalServerError: 500 Internal error occurred."}
가능한 원인:
최근에 요청을 너무 많이 보내 Gemini 모델 할당량을 모두 사용한 경우 이러한 문제가 발생할 수 있습니다.
추천 솔루션:
Gemini 모델 할당량 관리 프로세스에 따라 할당량을 늘립니다. 또는 테스트에 비율 제한을 적용하고 나중에 다시 시도해 보세요.
잘못된 Reasoning Engine ID
문제:
추론 엔진 실행이 실패했으며 세부정보가 Not Found
인 오류가 표시될 수 있습니다.
가능한 원인:
에이전트를 쿼리할 때 잘못된 추론 엔진 ID를 사용하면 이 오류가 발생할 수 있습니다.
추천 솔루션:
에이전트에 올바른 추론 엔진 ID를 사용하고 있는지 확인합니다.
지원 리소스
여전히 문제가 해결되지 않으면 지원 가이드를 참조하여 도움을 받으세요.