Anthropic Vertex AI 객체 구조

LibreChat은 Google Cloud Vertex AI를 통해 Anthropic Claude 모델을 실행하는 것을 지원합니다. 이를 통해 기존 Google Cloud 인프라, 결제 및 자격 증명을 사용하여 Claude 모델을 사용할 수 있습니다.

환경 변수를 사용한 빠른 설정을 보려면, Anthropic 구성 가이드를 참조하세요

이점

통합 결제: 기존 Google Cloud 결제 계정을 사용하세요
Enterprise Features: Google Cloud의 엔터프라이즈 보안 및 규정 준수 기능에 액세스하세요
지역 규정 준수: 데이터 보존 요구 사항을 충족하기 위해 특정 지역에 배포
기존 인프라: 현재 사용 중인 GCP 서비스 계정 및 IAM 정책을 활용하세요

필수 조건

Anthropic Vertex AI를 구성하기 전에 다음 사항을 확인하세요:

Vertex AI API가 활성화된 Google Cloud Project
Vertex AI User 역할(roles/aiplatform.user)이 부여된 Service Account
Vertex AI Model Garden에서 활성화된 Claude models
Service Account Key (JSON 파일)가 다운로드되어 LibreChat에서 액세스할 수 있어야 합니다.

예시 구성

endpoints:
  anthropic:
    streamRate: 20
    titleModel: "claude-3.5-haiku"  # Use the visible model name (key from models config)

    vertex:
      region: "us-east5"
      # serviceKeyFile: "/path/to/service-account.json"  # Optional, defaults to api/data/auth.json
      # projectId: "${VERTEX_PROJECT_ID}"  # Optional, auto-detected from service key

      # Model mapping: visible name -> Vertex AI deployment name
      models:
        claude-opus-4.5:
          deploymentName: claude-opus-4-5@20251101
        claude-sonnet-4:
          deploymentName: claude-sonnet-4-20250514
        claude-3.7-sonnet:
          deploymentName: claude-3-7-sonnet-20250219
        claude-3.5-sonnet:
          deploymentName: claude-3-5-sonnet-v2@20241022
        claude-3.5-haiku:
          deploymentName: claude-3-5-haiku@20241022

참고: Anthropic endpoint는 streamRate, titleModel, titleMethod, titlePrompt, titlePromptTemplate, titleEndpoint를 포함한 모든 Shared Endpoint Settings을 지원합니다.

vertex

vertex 객체에는 모든 Vertex AI 관련 구성 옵션이 포함되어 있습니다.

region

키:

Key	Type	Description	Example
region	String	Vertex AI endpoint가 배포된 Google Cloud 리전입니다.	Must be a region where Claude models are available on Vertex AI.

기본값: us-east5

사용 가능한 리전:

global (대부분의 사용 사례에 권장됨)
us-east5
us-central1
europe-west1
europe-west4
asia-southeast1

팁: global 리전은 가장 가까운 사용 가능한 리전으로 자동 라우팅을 제공하므로 권장됩니다. 데이터 보존 요구 사항이 있는 경우에만 특정 리전을 사용하세요.

예시:

region: "global"

projectId

키:

Key	Type	Description	Example
projectId	String	Google Cloud 프로젝트 ID입니다. 환경 변수 참조를 지원합니다.	Optional. If not specified, auto-detected from the service account key file.

기본값: 서비스 키 파일에서 자동 감지됨

예시:

projectId: "${GOOGLE_PROJECT_ID}"

serviceKeyFile

키:

Key	Type	Description	Example
serviceKeyFile	String	Google Cloud 서비스 계정 키 JSON 파일의 경로입니다.	Can be absolute or relative to the LibreChat root directory.

기본값: api/data/auth.json (또는 GOOGLE_SERVICE_KEY_FILE 환경 변수)

예시:

serviceKeyFile: "/etc/secrets/gcp-service-account.json"

models

models 필드는 사용 가능한 Claude 모델을 정의하고 사용자 친화적인 이름을 Vertex AI 배포 ID에 매핑합니다. 이는 Azure OpenAI 모델 매핑과 유사하게 작동합니다.

형식 옵션

모델을 구성하는 방법은 세 가지가 있습니다:

옵션 1: 단순 배열

실제 Vertex AI 모델 ID를 직접 사용하세요. 이 ID들은 UI에 그대로 표시됩니다:

models:
  - "claude-sonnet-4-20250514"
  - "claude-3-7-sonnet-20250219"
  - "claude-3-5-haiku@20241022"

옵션 2: 사용자 지정 이름이 포함된 객체 (권장)

사용자 친화적인 이름을 Vertex AI 배포 이름에 매핑:

models:
  claude-opus-4.5:           # Visible in UI
    deploymentName: claude-opus-4-5@20251101  # Actual Vertex AI model ID
  claude-sonnet-4:
    deploymentName: claude-sonnet-4-20250514
  claude-3.5-haiku:
    deploymentName: claude-3-5-haiku@20241022

옵션 3: 기본값이 포함된 혼합 형식

기본 배포 이름을 설정하고 이를 상속받는 모델에는 불리언 값을 사용하세요:

deploymentName: claude-sonnet-4-20250514  # Default deployment
models:
  claude-sonnet-4: true  # Uses default deploymentName
  claude-3.5-haiku:
    deploymentName: claude-3-5-haiku@20241022  # Override for this model

Model Object Properties

Key	Type	Description	Example
deploymentName	String	API 호출에 사용되는 실제 Vertex AI 모델 ID입니다.	Required for each model unless using boolean `true` with a group-level default.

예시:

models:
  claude-sonnet-4:
    deploymentName: claude-sonnet-4-20250514

환경 변수 대안

더 간단한 설정을 원하신다면, YAML 대신 환경 변수를 사용하여 Vertex AI를 구성할 수 있습니다:

# Enable Vertex AI mode
ANTHROPIC_USE_VERTEX=true

# Vertex AI region (optional, defaults to us-east5)
ANTHROPIC_VERTEX_REGION=global

# Path to service account key (optional, defaults to api/data/auth.json)
GOOGLE_SERVICE_KEY_FILE=/path/to/service-account.json

참고: 환경 변수를 사용할 때는 모델 매핑을 사용할 수 없습니다. 알려진 모든 Claude 모델이 자동으로 포함됩니다.

전체 예시

기본 설정

기본값을 사용하는 최소 구성 (Vertex AI는 vertex 섹션이 존재하면 활성화됩니다):

endpoints:
  anthropic:
    vertex:
      region: us-east5

다음 항목을 사용합니다:

지역: us-east5
서비스 키: api/data/auth.json (또는 GOOGLE_SERVICE_KEY_FILE env var)
Project ID: 서비스 키에서 자동 감지됨
모델: 알려진 모든 Claude 모델

Model Mapping을 사용한 프로덕션 설정

사용자 지정 모델 이름과 제목을 포함한 전체 구성:

endpoints:
  anthropic:
    streamRate: 20
    titleModel: "haiku"
    titleMethod: "completion"

    vertex:
      region: "global"
      serviceKeyFile: "${GOOGLE_SERVICE_KEY_FILE}"

      models:
        opus:
          deploymentName: claude-opus-4-5@20251101
        sonnet:
          deploymentName: claude-sonnet-4-20250514
        haiku:
          deploymentName: claude-3-5-haiku@20241022

다중 리전 설정

배포당 하나의 리전만 구성할 수 있습니다. 다중 리전이 필요한 경우, 별도의 LibreChat 인스턴스나 사용자 지정 endpoint를 사용하는 것을 고려하세요.

문제 해결

일반적인 오류

"기본 자격 증명을 로드할 수 없습니다"

지정된 경로에 서비스 계정 키 파일이 있는지 확인하세요
파일 권한을 확인하세요 (LibreChat 프로세스에서 읽을 수 있어야 합니다)
JSON 파일이 유효하며 손상되지 않았는지 확인하세요

"Permission denied" 또는 "403 Forbidden"

서비스 계정에 Vertex AI User 역할이 있는지 확인하세요
Vertex AI Model Garden에서 Claude 모델이 활성화되어 있는지 확인하세요.
서비스 계정이 올바른 프로젝트에 속해 있는지 확인하세요

"모델을 찾을 수 없습니다"

deploymentName의 모델 ID가 올바른지 확인하세요
선택한 리전에서 해당 모델을 사용할 수 있는지 확인하세요
Vertex AI Model Garden에서 해당 모델이 활성화되어 있는지 확인하세요.

지역 문제

"Invalid region" 또는 "Region not supported"

위에 나열된 지원되는 리전 중 하나를 사용하세요
자동 라우팅을 제공하는 global 리전을 사용해 보세요.
Claude를 사용할 수 있는 최신 지역 목록은 Google Cloud의 문서를 확인하세요.

"해당 지역에서 사용할 수 없는 모델입니다"

모든 Claude 모델을 모든 지역에서 사용할 수 있는 것은 아닙니다.
사용 가능한 리전으로 자동 라우팅하려면 global 리전으로 전환해 보세요.
Vertex AI Model Garden을 확인하여 귀하의 지역에서 어떤 모델을 사용할 수 있는지 확인하세요.
더 넓은 모델 가용성을 가진 다른 리전(예: us-east5)을 사용하는 것을 고려해 보세요.

지연 시간 문제

높은 지연 시간이 발생한다면, 사용자들과 지리적으로 더 가까운 리전을 사용해 보세요.
global 리전은 가장 가까운 사용 가능한 리전으로 자동으로 라우팅합니다.
엄격한 지연 시간 요구 사항이 있는 프로덕션 워크로드의 경우, 여러 리전을 테스트하여 사용 사례에 가장 적합한 성능을 제공하는 리전을 선택하십시오.

설정 확인

서비스 계정 키가 유효한지 확인하세요:

gcloud auth activate-service-account --key-file=/path/to/key.json
gcloud auth list

Vertex AI 액세스 테스트:
```
gcloud ai models list --region=us-east5
```

Claude 모델 액세스 확인:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://us-east5-aiplatform.googleapis.com/v1/projects/YOUR_PROJECT/locations/us-east5/publishers/anthropic/models/claude-3-5-haiku@20241022:rawPredict" \
  -d '{"anthropic_version": "vertex-2023-10-16", "max_tokens": 100, "messages": [{"role": "user", "content": "Hello"}]}'

참고 사항

Vertex AI와 직접적인 Anthropic API는 상호 배타적입니다. vertex 구성 섹션이 존재하면 ANTHROPIC_API_KEY 환경 변수는 무시됩니다.
Vertex AI에서 웹 검색 기능이 완벽하게 지원됩니다.
Vertex AI 호환성을 위해 자동 헤더 필터링을 통해 Prompt caching이 지원됩니다.
Function calling 및 tool use는 직접적인 Anthropic API와 동일하게 작동합니다.