에이전트를 사용하여 문제 해결

이 문서에서는 에이전트를 사용할 때 발생할 수 있는 오류를 해결하는 방법을 설명합니다.

작업 스키마가 비어 있음

에이전트가 .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를 사용하고 있는지 확인합니다.

지원 리소스

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