Cấu trúc đối tượng Anthropic Vertex AI

LibreChat hỗ trợ chạy các mô hình Anthropic Claude thông qua Google Cloud Vertex AI. Điều này cho phép bạn sử dụng các mô hình Claude với cơ sở hạ tầng, hệ thống thanh toán và thông tin xác thực Google Cloud hiện có của mình.

Để thiết lập nhanh bằng cách sử dụng các biến môi trường, hãy xem hướng dẫn cấu hình Anthropic

Lợi ích

• Thanh toán hợp nhất: Sử dụng tài khoản thanh toán Google Cloud hiện có của bạn
• Các tính năng doanh nghiệp: Truy cập các tính năng bảo mật và tuân thủ dành cho doanh nghiệp của Google Cloud
• Tuân thủ theo khu vực: Triển khai tại các khu vực cụ thể để đáp ứng các yêu cầu về lưu trú dữ liệu
• Cơ sở hạ tầng hiện có: Tận dụng các tài khoản dịch vụ GCP và chính sách IAM hiện tại của bạn

Điều kiện tiên quyết

Trước khi cấu hình Anthropic Vertex AI, hãy đảm bảo bạn đã:

1. Google Cloud Project với Vertex AI API đã được bật
2. Service Account với vai trò Vertex AI User (roles/aiplatform.user)
3. Các Claude models đã được kích hoạt trong Vertex AI Model Garden của bạn
4. Service Account Key (tệp JSON) đã tải xuống và có thể truy cập được bởi LibreChat

Cấu hình ví dụ

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

Lưu ý: Endpoint Anthropic hỗ trợ tất cả Shared Endpoint Settings, bao gồm streamRate, titleModel, titleMethod, titlePrompt, titlePromptTemplate và titleEndpoint.

vertex

Đối tượng vertex chứa tất cả các tùy chọn cấu hình dành riêng cho Vertex AI.

region

Khóa:

Mặc định: us-east5

Các khu vực khả dụng:

• global (được khuyến nghị cho hầu hết các trường hợp sử dụng)
• us-east5
• us-central1
• europe-west1
• europe-west4
• asia-southeast1

Mẹo: Khu vực global được khuyến nghị vì nó cung cấp khả năng định tuyến tự động đến khu vực khả dụng gần nhất. Chỉ sử dụng các khu vực cụ thể nếu bạn có yêu cầu về lưu trữ dữ liệu.

Ví dụ:

region: "global"

projectId

Khóa:

Mặc định: Tự động phát hiện từ tệp khóa dịch vụ

Ví dụ:

projectId: "${GOOGLE_PROJECT_ID}"

serviceKeyFile

Khóa:

Mặc định: api/data/auth.json (hoặc biến môi trường GOOGLE_SERVICE_KEY_FILE)

Ví dụ:

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

models

Trường models xác định các model Claude khả dụng và ánh xạ các tên thân thiện với người dùng tới các ID triển khai Vertex AI. Điều này hoạt động tương tự như ánh xạ model Azure OpenAI.

Các tùy chọn định dạng

Bạn có thể cấu hình các model theo ba cách:

Lựa chọn 1: Mảng đơn giản

Sử dụng trực tiếp các ID mô hình Vertex AI thực tế. Chúng sẽ được hiển thị nguyên trạng trong giao diện người dùng:

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

Tùy chọn 2: Đối tượng với tên tùy chỉnh (Khuyên dùng)

Ánh xạ các tên thân thiện với người dùng sang tên triển khai 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

Lựa chọn 3: Định dạng hỗn hợp với mặc định

Đặt tên triển khai mặc định và sử dụng các giá trị boolean cho các model kế thừa tên đó:

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

Các thuộc tính của đối tượng Model

Ví dụ:

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

Giải pháp thay thế cho biến môi trường

Đối với các thiết lập đơn giản hơn, bạn có thể cấu hình Vertex AI bằng cách sử dụng các biến môi trường thay vì YAML:

# 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

Lưu ý: Khi sử dụng các biến môi trường, tính năng ánh xạ mô hình (model mapping) sẽ không khả dụng. Tất cả các mô hình Claude đã biết sẽ được tự động bao gồm.

Các ví dụ hoàn chỉnh

Thiết lập cơ bản

Cấu hình tối thiểu sử dụng các giá trị mặc định (Vertex AI được kích hoạt khi có phần vertex):

endpoints:
  anthropic:
    vertex:
      region: us-east5

Điều này sử dụng:

• Khu vực: us-east5
• Service key: api/data/auth.json (hoặc biến môi trường GOOGLE_SERVICE_KEY_FILE)
• Project ID: Tự động phát hiện từ khóa dịch vụ (service key)
• Các model: Tất cả các model Claude đã biết

Thiết lập môi trường Production với Model Mapping

Cấu hình đầy đủ với tên và tiêu đề mô hình tùy chỉnh:

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

Thiết lập đa vùng (Multi-Region)

Bạn chỉ có thể cấu hình một khu vực cho mỗi lần triển khai. Đối với các nhu cầu đa khu vực, hãy cân nhắc sử dụng các instance LibreChat riêng biệt hoặc các endpoint tùy chỉnh.

Khắc phục sự cố

Các lỗi thường gặp

"Không thể tải thông tin xác thực mặc định"

• Đảm bảo tệp khóa tài khoản dịch vụ tồn tại tại đường dẫn đã chỉ định
• Kiểm tra quyền truy cập tệp (phải có thể đọc được bởi tiến trình LibreChat)
• Xác minh tệp JSON là hợp lệ và không bị hỏng

"Permission denied" hoặc "403 Forbidden"

• Xác minh tài khoản dịch vụ đã có vai trò Vertex AI User
• Đảm bảo các mô hình Claude đã được kích hoạt trong Vertex AI Model Garden của bạn
• Kiểm tra xem tài khoản dịch vụ có thuộc đúng dự án hay không

"Model not found"

• Kiểm tra xem ID mô hình trong deploymentName có chính xác không
• Xác minh rằng model có sẵn trong khu vực bạn đã chọn
• Đảm bảo rằng mô hình đã được bật trong Vertex AI Model Garden của bạn

Các vấn đề về khu vực

"Invalid region" hoặc "Region not supported"

• Sử dụng một trong các khu vực được hỗ trợ được liệt kê ở trên
• Hãy thử sử dụng vùng global để được định tuyến tự động
• Kiểm tra tài liệu của Google Cloud để biết danh sách mới nhất về các khu vực có hỗ trợ Claude.

"Model not available in region"

• Không phải tất cả các model Claude đều khả dụng ở mọi khu vực
• Hãy thử chuyển sang vùng global để tự động định tuyến đến một vùng khả dụng
• Kiểm tra Vertex AI Model Garden để xem những model nào khả dụng trong khu vực của bạn
• Hãy cân nhắc sử dụng một khu vực khác có sẵn nhiều mô hình hơn (ví dụ: us-east5)

Các vấn đề về độ trễ

• Nếu bạn đang gặp phải độ trễ cao, hãy thử sử dụng một khu vực gần hơn về mặt địa lý với người dùng của bạn.
• Vùng global tự động định tuyến đến vùng khả dụng gần nhất
• Đối với các khối lượng công việc trong môi trường production có yêu cầu nghiêm ngặt về độ trễ, hãy thử nghiệm các khu vực khác nhau và chọn khu vực có hiệu suất tốt nhất cho trường hợp sử dụng của bạn.

Xác minh thiết lập

1. Đảm bảo khóa tài khoản dịch vụ của bạn hợp lệ:

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

2. Kiểm tra quyền truy cập Vertex AI:

   gcloud ai models list --region=us-east5

3. Xác minh quyền truy cập mô hình 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"}]}'

Ghi chú

• Vertex AI và API Anthropic trực tiếp loại trừ lẫn nhau. Khi phần cấu hình vertex xuất hiện, biến môi trường ANTHROPIC_API_KEY sẽ bị bỏ qua.
• Tính năng tìm kiếm web được hỗ trợ đầy đủ với Vertex AI.
• Prompt caching được hỗ trợ thông qua tính năng lọc tiêu đề tự động để tương thích với Vertex AI.
• Function calling và việc sử dụng tool hoạt động tương tự như với Anthropic API trực tiếp.