Google Vertex AI 연결

Google Vertex AI를 생각할 때, 구글의 Gemini AI 모델을 위한 “비즈니스 클래스 라운지”라고 떠올리면 됩니다. 같은 훌륭한 모델이지만, 안정적인 요금, Google Cloud 계정을 통한 결제, 그리고 갑작스러운 속도 제한 서프라이즈가 없는 엔터프라이즈급 혜택이 딸려 오죠.

그냥 일반 API 키를 쓰면 안 되나요?

다른 AI 제공업체를 써봤다면, 정적인 API 키를 복사해서 설정 파일에 붙여넣는 방식에 익숙할 겁니다. Vertex는 그렇게 작동하지 않아요. 절대 바뀌지 않는 키 대신, Vertex는 수명이 짧은 OAuth2 토큰을 사용합니다. 마치 약 1시간 후에 만료되는 탑승권 같은 거죠.

좋은 소식? Hermes Agent가 토큰 발급과 갱신을 자동으로 처리해 줍니다. 여러분은 토큰을 직접 만질 일이 전혀 없어요. 이것이 바로 임시 토큰을 커스텀 제공업체의 api_key 필드에 그냥 붙여넣을 수 없는 이유이기도 합니다. 대화 중간에 토큰이 만료되어 세션이 끊겨버리거든요.

준비사항 (사전 요구사항)

• Vertex AI API가 활성화되고 결제가 연결된 Google Cloud 프로젝트
• 다음 자격 증명 유형 중 하나:
  • 서비스 계정 JSON 키 파일 (서버 환경에 권장)
  • gcloud auth application-default login을 통한 ADC(애플리케이션 기본 자격 증명) (로컬 개발에 적합)

이게 전부입니다. Hermes는 Vertex를 처음 선택할 때 google-auth를 자동으로 설치할 거예요.

빠른 시작: 두 가지 옵션

옵션 A — 서비스 계정 JSON (서버/게이트웨이용)

~/.hermes/.env 파일에 한 줄만 추가하면 됩니다:

echo "VERTEX_CREDENTIALS_PATH=/path/to/service-account.json" >> ~/.hermes/.env

옵션 B — ADC (로컬 개발용)

터미널에서 다음을 실행하세요:

gcloud auth application-default login

그런 다음 Vertex를 제공업체로 선택합니다:

hermes model

“More providers…” → “Google Vertex AI”를 선택하고 → GCP 프로젝트 ID를 입력하거나 (비워두면 자격 증명에 있는 값을 사용) → 리전을 선택하고 (기본값: global) → Gemini 모델을 고르세요.

마지막으로, 대화를 시작합니다:

hermes chat

설정 파일 위치 (간단 정리)

Hermes는 민감도에 따라 Vertex 설정을 두 개의 파일로 나눠 관리합니다.

~/.hermes/.env — 비밀 포인터 (자격 증명 경로)를 보관합니다:

# 다음 중 하나를 사용하세요 (이 순서대로 확인됨); 둘 다 생략하면 ADC를 사용:
VERTEX_CREDENTIALS_PATH=/path/to/service-account.json
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

~/.hermes/config.yaml — 비밀이 아닌 라우팅 설정 (프로젝트 ID 및 리전)을 보관합니다:

model:
  default: google/gemini-...

요약 및 실용적인 팁

Vertex AI는 Gemini 모델과 함께 엔터프라이즈급 안정성을 제공하며, Hermes가 까다로운 OAuth2 토큰 갱신을 자동으로 처리해 줍니다. 한 번만 자격 증명을 지정해 주면 끝입니다.

프로 팁: 서버나 게이트웨이에서 Hermes를 실행 중이라면, 항상 서비스 계정 JSON 방식(옵션 A)을 사용하세요. ADC보다 더 안전하고 예측 가능합니다. 그리고 문제가 생기면, google-auth의 지연 설치가 실패한 경우 hermes setup을 실행하여 관리형 설치를 복구할 수 있습니다. 즐거운 빌드 되세요!