SETTINGS · GOOGLE CLOUD

Google Cloud ADC와 Vertex AI

Google Cloud 프로젝트와 Vertex AI 권한, 로컬 Application Default Credentials, 9Miho 프로바이더 프로필을 순서대로 설정합니다.

언제 이 방식을 쓰나

9Miho 서버가 Google Cloud 프로젝트의 Vertex AI를 통해 Gemini나 Veo를 호출해야 한다면 Google **Application Default Credentials(ADC)**를 선택합니다. 9Miho의 Python 프로바이더는 Google 인증 라이브러리에 cloud-platform 범위의 자격 증명을 요청합니다. 선택한 프로필에 프로젝트를 입력했다면 그 값을 우선 사용하고, 비어 있으면 ADC가 알려 준 프로젝트를 사용합니다.

이 절차는 GCP ComfyUI/IAP 설치와 다릅니다. Vertex ADC는 Google이 호스팅하는 모델 API에 인증합니다. GCP ComfyUI는 사용자가 소유한 GPU VM을 만들거나 연결하며 GPU·디스크·스토리지·터널·모델 라이선스 비용 경계가 따로 있습니다. 그 경로는 ComfyUI와 GPU 설정을 참고하세요.

Google Cloud에서 먼저 준비할 것

다음 항목이 필요합니다.

결제가 연결된 Google Cloud 프로젝트
활성화된 Vertex AI API
Vertex AI 사용 권한. 일반적으로 Vertex AI User(roles/aiplatform.user)
아래 명령으로 API를 켤 경우 서비스 활성화 권한. 일반적으로 Service Usage Admin(roles/serviceusage.serviceUsageAdmin)
9Miho 서버와 같은 컴퓨터·운영체제 계정에 설치된 Google Cloud CLI

Google 공식 문서는 Vertex AI 시작 설정, 로컬 ADC 설정, 서비스 활성화에서 확인할 수 있습니다.

로컬 ADC 만들기

PROJECT_ID는 프로젝트 표시 이름이 아니라 정확한 프로젝트 ID로 바꿉니다.

gcloud --version
gcloud init
gcloud auth list
gcloud config set project PROJECT_ID

gcloud services enable aiplatform.googleapis.com --project=PROJECT_ID

gcloud auth application-default login
gcloud auth application-default set-quota-project PROJECT_ID

gcloud services list --enabled --filter="name:aiplatform.googleapis.com" --project=PROJECT_ID

gcloud auth application-default login은 클라이언트 라이브러리가 읽을 로컬 ADC를 만듭니다. 일반 gcloud 명령이 쓰는 로그인과 별개입니다. gcloud config set project도 CLI 기본 프로젝트를 바꿀 뿐 9Miho 프로필에 저장된 프로젝트를 대신하지 않습니다. quota project 설정에는 먼저 ADC가 있어야 하고, 그 프로젝트에 대한 serviceusage.services.use 권한이 필요합니다.

로컬 ADC 파일에는 갱신용 자격 증명이 들어 있습니다. 복사하거나 커밋하지 말고, 9Miho용 access token을 출력해 Canvas에 붙여넣지도 마세요. 9Miho는 서버 컴퓨터에서 Google 인증 라이브러리를 통해 ADC를 직접 읽습니다.

9Miho 프로필 설정

ADC를 만든 운영체제 계정으로 9Miho를 시작하거나 재시작합니다.
Settings → 프로바이더를 엽니다.
Google · Gemini / Veo를 선택합니다.
새 이름의 프로필을 만들거나 의도한 프로필을 고릅니다. API 키 방식도 계속 쓸 거라면 별도 ADC 프로필을 만드는 편이 안전합니다.
인증 방식을 Application Default Credentials로 바꿉니다.
GCP project ID를 입력합니다. 명시적으로 적어 두면 어느 프로젝트를 쓰고 비용이 어디에 귀속되는지 프로필에서 확인할 수 있습니다.
Vertex region을 입력합니다. 선택한 카탈로그 Variant가 요구하는 리전을 사용하세요. 프로필 기본값은 global이며 일부 모델 경로는 us-central1을 사용하거나 그곳으로 fallback합니다.
설정 저장을 누르고, 필요하면 기본 프로필로 설정을 누릅니다.
재확인을 눌러 감지된 인증 상태를 읽습니다.
호환되는 Google Variant를 선택하고 검증한 뒤 비용 승인 카드를 확인하고 실행합니다.

재확인은 프로바이더가 보고하는 인증 surface를 새로 읽습니다. 로그인 계정이나 로컬 ADC 자체를 바꿨다면 마지막 확인 전에 9Miho 서버를 재시작하세요. 실행 중인 adapter가 이전 자격 증명 객체를 계속 들고 있을 가능성을 없애는 가장 안전한 순서입니다.

ADC가 감지됐다는 표시는 서버가 로컬 자격 증명을 찾았다는 뜻입니다. Vertex AI API, 결제, IAM, 모델 접근 권한, 리전, quota, 실제 생성 성공까지 확인한 것은 아닙니다. 최종 확인은 호환 Variant의 실제 실행입니다.

서비스 계정 가장하기

로컬 컴퓨터에 서비스 계정 키 파일을 내려받고 싶지 않다면, Google이 지원하는 사용자 ADC 기반 서비스 계정 가장하기를 사용할 수 있습니다. 로그인한 사용자에게 대상 서비스 계정의 Service Account Token Creator(roles/iam.serviceAccountTokenCreator) 권한이 있어야 합니다. 가장되는 서비스 계정 자체에도 9Miho 프로필에서 선택한 프로젝트의 Vertex AI User(roles/aiplatform.user) 같은 실제 실행 권한이 필요합니다.

gcloud auth application-default login --impersonate-service-account SERVICE_ACCOUNT_EMAIL
gcloud auth application-default set-quota-project PROJECT_ID

9Miho 프로바이더는 이 방식이 지원되는 Python 기반입니다. 사용자 ADC나 가장하기로 충분하다면 서비스 계정 키 파일은 피하는 편이 좋습니다. 운영자가 의도적으로 GOOGLE_APPLICATION_CREDENTIALS를 쓸 경우, 이 환경 변수가 일반 ADC 파일보다 먼저 선택되어 오래된 인증 파일을 가리킬 수 있다는 점도 확인하세요.

문제 해결

증상	확인할 것
ADC가 계속 확인 중이거나 없음	서버 컴퓨터의 서버 계정으로 ADC를 만들었는지 확인하고, 서버를 재시작한 뒤 재확인합니다.
`403`	프로필 프로젝트의 결제와 Vertex AI API를 확인하고, 실제 호출 주체—가장하기를 썼다면 그 서비스 계정—에 `roles/aiplatform.user`가 있는지 봅니다. ADC quota project와 `serviceusage.services.use`는 quota 귀속 문제로 따로 확인합니다.
모델을 찾지 못하거나 `404`	선택한 Variant가 이 프로젝트·리전·계정에 제공되는지 확인합니다. 인증 성공과 모델 사용 권한은 별개입니다.
엉뚱한 프로젝트에 비용이 귀속됨	선택한 9Miho 프로필의 GCP project ID를 확인합니다. 이 값이 Vertex 리소스 경로와 리소스·과금 프로젝트를 정합니다. ADC quota project는 quota 귀속을 정할 뿐 프로필 프로젝트를 덮어쓰지 않으며, 현재 `gcloud` 기본 프로젝트도 덮어쓰지 않습니다.
다른 계정으로 보임	`GOOGLE_APPLICATION_CREDENTIALS`와 서버를 실행하는 운영체제 계정을 확인한 뒤 ADC를 의도적으로 다시 만듭니다.
API 키는 되는데 ADC는 안 됨	별도 실행 경로로 봅니다. API 키 방식은 Google API-key surface, ADC는 Vertex AI를 호출합니다.

ADC가 자격 증명을 찾는 순서와 오류 진단은 Google의 ADC 동작 방식과 ADC 문제 해결을 참고하세요.