트러블슈팅

데이터 스토어 생성·색인·검색 단계에서 자주 마주치는 IAM 권한·API·할당량 오류와 해결 절차

데이터 스토어와 App 을 만들고 운영할 때 발생하는 대표 오류와 진단·해결 방법을 정리합니다. 이 챕터의 내용은 실제 PoC / 운영 현장에서 확인된 사례를 바탕으로 합니다.

다음 절은 모두 실제 발생 사례 기반 이며, GCP 콘솔 메뉴와 API 응답 메시지는 시점에 따라 바뀔 수 있습니다. 공식 문서와 함께 참고하세요.

목차

  1. 개요 — 오류 분류
  2. Discovery Engine 서비스 계정 IAM 권한 누락
  3. Vertex AI Gemini 429 RESOURCE_EXHAUSTED
  4. 데이터 스토어 색인 실패 — 파일 형식·크기
  5. Layout Parser 옵션 선택
  6. GE 대화 시 InvocationMethodNotFoundError (streaming_agent_run_with_events)
  7. Agent Engine deploy 시 staging 버킷 cross-project 권한
  8. 확인용 체크리스트

1. 개요 — 오류 분류

대부분의 실패는 다음 3개 카테고리 중 하나입니다.

카테고리 대표 증상 우선 점검 위치
IAM 권한 콘솔에서 “Access denied” / API 403 / Agent Studio 가 데이터 스토어를 못 본다 서비스 계정 역할, 사용자 권한
API / 할당량 429 RESOURCE_EXHAUSTED / 503 모델 quota, 지역 할당량
데이터 형식 / 파싱 색인은 끝났지만 검색 결과가 비어 있다 / Layout Parser 결과가 깨진다 원본 파일 포맷, parser 선택, OCR

2. Discovery Engine 서비스 계정 IAM 권한 누락

2.1 증상

  • Agent Studio 에서 데이터 스토어를 만들거나 검색 미리보기를 실행할 때 “Permission denied” / “Failed to access data source” 류 오류
  • GCS 가 데이터 소스인데 Agent Studio 가 객체를 읽지 못함
  • API 직접 호출 시 403

2.2 원인

Discovery Engine API 를 enable 하면 GCP 가 자동으로 서비스 에이전트(Google-managed service account) 를 만들고 기본 역할만 부여합니다. 데이터 스토어가 GCS / Vertex AI 등 다른 GCP 리소스를 함께 사용할 때는 추가 역할이 필요 한데, 콘솔이 이를 명시적으로 알려주지 않아 사용자가 인지하지 못한 채 실패합니다.

기본 부여:

  • roles/discoveryengine.serviceAgent — API 자체 동작용 (자동 부여)

자주 누락: | 역할 | 언제 필요 | |—|—| | roles/discoveryengine.admin | 콘솔 / API 로 데이터 스토어·앱 관리 | | roles/aiplatform.user | Vertex AI 모델 호출 (Search 가 내부적으로 Gemini 호출) | | roles/storage.objectViewer | GCS 버킷의 객체 읽기 (GCS 데이터 스토어 필수) | | roles/bigquery.dataViewer | BigQuery 데이터 스토어 | | roles/bigquery.jobUser | 동일 |

2.3 진단 (read-only)

서비스 에이전트 이메일을 먼저 알아냅니다. 프로젝트 번호 기반입니다.

# PowerShell
$proj = "<YOUR_PROJECT_ID>"
$pn = gcloud projects describe $proj --format="value(projectNumber)"
$sa = "service-${pn}@gcp-sa-discoveryengine.iam.gserviceaccount.com"

# 현재 부여된 역할 조회
gcloud projects get-iam-policy $proj `
  --flatten="bindings[].members" `
  --format="table(bindings.role)" `
  --filter="bindings.members:$sa"

# Bash
proj="<YOUR_PROJECT_ID>"
pn=$(gcloud projects describe $proj --format="value(projectNumber)")
sa="service-${pn}@gcp-sa-discoveryengine.iam.gserviceaccount.com"

gcloud projects get-iam-policy $proj \
  --flatten="bindings[].members" \
  --format="table(bindings.role)" \
  --filter="bindings.members:$sa"

기대 출력에 다음 4개가 모두 보여야 정상입니다 (GCS 데이터 스토어 기준):

ROLE
roles/discoveryengine.serviceAgent
roles/discoveryengine.admin
roles/aiplatform.user
roles/storage.objectViewer

2.4 조치 — 누락 역할 추가

⚠️ IAM 변경은 프로젝트 차원의 영향이라 운영팀과 합의 후 진행합니다. 변경 사항은 워크로그 / 이슈에 반드시 기록하세요.

$proj = "<YOUR_PROJECT_ID>"
$sa   = "service-<PROJECT_NUMBER>@gcp-sa-discoveryengine.iam.gserviceaccount.com"
$roles = @(
  "roles/discoveryengine.admin",
  "roles/aiplatform.user",
  "roles/storage.objectViewer"
)
foreach ($r in $roles) {
  gcloud projects add-iam-policy-binding $proj `
    --member="serviceAccount:$sa" `
    --role=$r --condition=None
}

proj="<YOUR_PROJECT_ID>"
sa="service-<PROJECT_NUMBER>@gcp-sa-discoveryengine.iam.gserviceaccount.com"
for r in roles/discoveryengine.admin roles/aiplatform.user roles/storage.objectViewer; do
  gcloud projects add-iam-policy-binding "$proj" \
    --member="serviceAccount:$sa" --role="$r" --condition=None
done

2.5 검증

위 진단 명령을 다시 실행해 4개 역할이 모두 표시되는지 확인합니다. Agent Studio 에서 데이터 스토어 생성 / 검색 미리보기를 재시도하면 오류가 해소됩니다.

2.6 실제 사례 (2026-05-09)

ctu-gcp-dsa1-unit-sub 프로젝트 (projectNumber=902315899917) 에서 Agent Studio 가 GCS 데이터 스토어를 인식 못 함. 진단 결과 서비스 계정 service-902315899917@gcp-sa-discoveryengine.iam.gserviceaccount.com 에 discoveryengine.serviceAgent 만 있고 위 3개 역할이 모두 누락. 3개 모두 부여 후 정상 동작 확인.

3. Vertex AI Gemini 429 RESOURCE_EXHAUSTED

3.1 증상

데이터 스토어가 정상인데 Search / Assistant 응답이 간헐적으로 비거나 500 으로 끊김. 백엔드 로그에 429 RESOURCE_EXHAUSTED.

3.2 원인

Gemini Enterprise 의 검색·요약은 내부적으로 Vertex AI Gemini 모델을 호출합니다. 모델별 / 지역별 quota 가 사용자 계정 단위로 제한되며, 단일 사용자가 Burst 요청을 보내면 같은 프로젝트 안에서도 빠르게 한도에 부딪힙니다.

3.3 조치 단계

  1. 현재 사용 quota 조회 
    gcloud alpha services quota list \
  --service=aiplatform.googleapis.com \
  --consumer=projects/<PROJECT_ID>
  2. 단기 완화 — 클라이언트에 지수 backoff (0.5s → 1s → 2s → 4s) + 동시 요청수 제한
  3. 장기 해결 — 콘솔의 [IAM & Admin] → [Quotas] 에서 해당 모델·지역 quota 증액 요청 (Google 영업 / TAM 채널)
  4. 지역 분산 — us-central1 외 asia-northeast3 등 추가 지역으로 트래픽 분산

3.4 예방

  • 데이터 스토어 색인 단계 와 Search 호출 은 서로 다른 quota 를 씁니다. 색인이 많은 시점과 사용자 트래픽 피크가 겹치지 않게 스케줄링.
  • 외부 호출 단에 캐시 (예: identical query → 60초 캐시) 적용으로 quota 소비 절감.

4. 데이터 스토어 색인 실패 — 파일 형식·크기

4.1 자주 보는 실패

증상 원인 해결
색인 0건 / 일부만 성공 GCS prefix 잘못 지정 gs://bucket/path/ 끝에 / 확인
PDF 가 텍스트 추출 안 됨 스캔본 / 이미지 PDF OCR 옵션 활성화
HWP / 비표준 포맷 지원 안 됨 PDF 변환 후 재색인
단일 파일 50MB 초과 크기 제한 분할 또는 압축
색인 표가 깨짐 Default parser 로 표 인식 한계 Layout Parser 옵션

4.2 색인 상태 조회

PROJECT_ID="<YOUR_PROJECT_ID>"
DS_ID="<YOUR_DATA_STORE_ID>"
curl -s -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://discoveryengine.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/collections/default_collection/dataStores/${DS_ID}/documents" \
  | jq '.documents | length'

5. Layout Parser 옵션 선택

데이터 스토어 생성 시 Document parsing 옵션 3개 중 어느 것을 선택할지 자주 헷갈리는 부분입니다.

옵션 적합한 문서 메모
Default 본문 위주의 일반 문서 (md, txt, 일반 PDF) 가장 빠름. 표 / 다단 레이아웃 약함
Layout parser 표·헤더·다단 레이아웃이 많은 PDF (재무보고서, 카탈로그, 매뉴얼) 색인 시간 길지만 표 구조 보존
OCR 스캔본, 이미지 임베디드 PDF, 사진 OCR 추가 비용·시간 발생

한 번 정한 후에는 변경하려면 데이터 스토어를 다시 만들어야 합니다. 샘플 10~20 건으로 미리 비교 테스트 후 결정하기를 권장합니다.

6. GE 대화 시 InvocationMethodNotFoundError (streaming_agent_run_with_events)

6.1 증상

Gemini Enterprise App 에 Agent Engine 에이전트를 등록하고 대화를 시도하면 다음 에러:

Agent failed with error: Reasoning Engine Execution Service stream failed with
status code FAILED_PRECONDITION: Reasoning Engine Execution failed.
Error Details: (코드: 500)

Reasoning Engine 로그 (resource.type="aiplatform.googleapis.com/ReasoningEngine") 에는 stack trace 와 함께:

app.api.factory.utils.InvocationMethodNotFoundError:
User-specified method `streaming_agent_run_with_events` not found.
Available methods are: ['stream_query', 'async_stream_query'].

6.2 원인

GE 가 ADK 에이전트를 호출할 때 사용하는 메서드는 streaming_agent_run_with_events 인데, 이건 비교적 최신 (google-adk 1.10 ~ 1.20+) AdkApp 으로 wrap 했을 때만 자동 노출됩니다.

Agent Studio 의 자동 “Deploy” 버튼이 만든 reasoning engine 은 (2026-05 기준) 구 SDK 로 컨테이너를 빌드해서 이 메서드를 노출하지 못함. 사용자가 같은 에이전트를 다시 만들고 deploy 해도 SDK 캐시가 그대로라 같은 에러가 반복됩니다.

6.3 진단

# 1) Reasoning Engine 의 노출 메서드 확인
ENGINE_ID="<YOUR_REASONING_ENGINE_ID>"
PROJECT="<YOUR_PROJECT>"
curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://us-west1-aiplatform.googleapis.com/v1/projects/${PROJECT}/locations/us-west1/reasoningEngines/${ENGINE_ID}" \
  | python -c "import sys, json; d=json.load(sys.stdin); [print(m.get('name')) for m in d.get('spec',{}).get('classMethods', d.get('classMethods', []))]"

기대: streaming_agent_run_with_events 가 포함돼야 함. 없으면 구 SDK.

6.4 해결 — Manual deploy 로 전환

Agent Engine 을 수동으로 deploy 하면서 requirements 에 google-adk>=1.19 를 명시적으로 pin. 자세한 절차는 → Agent Platform → Manual deploy 챕터 참고.

핵심 코드:

from vertexai import agent_engines
from vertexai.preview.reasoning_engines import AdkApp

app = AdkApp(agent=root_agent, enable_tracing=True)

remote = agent_engines.create(
    app,
    display_name="...",
    requirements=[
        "google-adk>=1.19",
        "google-cloud-aiplatform[adk,agent_engines]",
    ],
)

배포 후 위 6.3 의 curl 로 메서드 13개가 노출되는지 확인 (streaming_agent_run_with_events 포함).

7. Agent Engine deploy 시 staging 버킷 cross-project 권한

7.1 증상

Manual deploy 실행 중 LRO 진행 후 실패:

google.api_core.exceptions.InternalServerError: 500
Service account service-<PROJECT_NUMBER>@gcp-sa-aiplatform.iam.gserviceaccount.com
doesn't have sufficient permission "storage.objects.get"
to read gs://<staging-bucket>/agent_engine/agent_engine.pkl.

7.2 원인

vertexai.init(staging_bucket=...) 에 지정한 GCS 버킷이 deploy 대상 프로젝트와 다른 프로젝트 소유일 때 발생. Vertex AI Agent Engine 서비스 계정 (gcp-sa-aiplatform) 은 자기 프로젝트 안의 버킷은 자동 접근 가능하지만 외부 프로젝트의 버킷 은 명시 권한 필요.

대표 시나리오: 데이터 스토어는 sub 프로젝트에 있고, GCS staging 버킷은 organization 공용 버킷이거나 메인 프로젝트 소유.

7.3 조치

gcloud storage (Windows / cross-platform):

SA="service-<PROJECT_NUMBER>@gcp-sa-aiplatform.iam.gserviceaccount.com"
gcloud storage buckets add-iam-policy-binding gs://<staging-bucket> \
  --member="serviceAccount:${SA}" \
  --role="roles/storage.objectAdmin"

roles/storage.objectAdmin 이 필요한 이유: deploy 시 pkl/tar 를 쓰고 (objectCreator) 다시 읽고 (objectViewer) 후에 정리 (objectAdmin 이 종합 권한). objectViewer 만 주면 다음 단계에서 또 막힙니다.

7.4 검증

gcloud storage buckets get-iam-policy gs://<staging-bucket> \
  --format="value(bindings.members,bindings.role)" \
  | grep gcp-sa-aiplatform

7.5 실제 사례 (2026-05-11)

gs://mzs-car-sales (메인 프로젝트 ctu-gcp-dsa1-unit 소유) 를 sub 프로젝트 ctu-gcp-dsa1-unit-sub 의 Agent Engine deploy 용 staging 으로 사용 → service-902315899917@gcp-sa-aiplatform.iam.gserviceaccount.com 권한 부재로 LRO 500 실패. storage.objectAdmin 부여 후 정상 deploy 완료 (reasoning engine 6931893047546347520).

💡 예방: 권한 복잡도가 부담스러우면 deploy 대상 프로젝트 안에 staging 버킷을 따로 만드는 게 가장 간단합니다 (예: gs://<project-id>-agent-engine-staging).

8. 확인용 체크리스트

새 데이터 스토어가 의도대로 동작하지 않을 때 위에서 아래로 점검:

  • 사용자 본인의 GCP 역할에 roles/discoveryengine.editor 이상 있는가
  • Discovery Engine 서비스 계정 에 위 2.2 의 4개 역할이 모두 있는가
  • 데이터 소스가 GCS 면 roles/storage.objectViewer, BigQuery 면 bigquery.dataViewer + jobUser 가 있는가
  • 데이터 스토어와 App 이 같은 location 인가 (global vs us 등)
  • 색인이 “Active” 상태인가 (수 분~수 시간 소요)
  • Search 미리보기에서 결과가 나오는가 (앱 단 통합 전)
  • Vertex AI quota 가 충분한가 (429 RESOURCE_EXHAUSTED 발생 여부)
  • 콘솔 [Audit Logs] 에서 거부된 API 호출이 있는가
Next: Part 4.
Agent platform
Previous: Setup › Chapter 9.
사용자/그룹 권한 부여