Anthropic Vertex AI 对象结构

LibreChat 支持通过 Google Cloud Vertex AI 运行 Anthropic Claude 模型。这使您能够利用现有的 Google Cloud 基础设施、账单和凭据来使用 Claude 模型。

如需使用环境变量进行快速设置，请参阅 Anthropic 配置指南

优势

• 统一计费： 使用您现有的 Google Cloud 计费账户
• 企业级功能： 访问 Google Cloud 的企业级安全和合规功能
• 区域合规性： 在特定区域部署以满足数据驻留要求
• 现有基础设施： 利用您当前的 GCP 服务账号和 IAM 策略

先决条件

在配置 Anthropic Vertex AI 之前，请确保您已完成以下准备工作：

1. 已启用 Vertex AI API 的 Google Cloud Project
2. 服务账号，需具备 Vertex AI User 角色 (roles/aiplatform.user)
3. 在您的 Vertex AI Model Garden 中启用的 Claude models
4. 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 支持所有 Shared Endpoint Settings，包括 streamRate、titleModel、titleMethod、titlePrompt、titlePromptTemplate 和 titleEndpoint。

vertex

vertex 对象包含所有 Vertex AI 特定的配置选项。

region

密钥：

默认值： us-east5

可用区域：

• global（推荐用于大多数用例）
• us-east5
• us-central1
• europe-west1
• europe-west4
• asia-southeast1

提示： 建议使用 global 区域，因为它会自动路由到最近的可用区域。仅在有数据驻留要求时才使用特定区域。

示例：

region: "global"

projectId

密钥：

默认值： 从服务密钥文件中自动检测

示例：

projectId: "${GOOGLE_PROJECT_ID}"

serviceKeyFile

密钥：

默认值： 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

模型对象属性

示例：

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 环境变量)
• 项目 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 区域，它提供自动路由功能
• 请查看 Google Cloud 的文档 以获取 Claude 可用区域的最新列表。

“模型在当前地区不可用”

• 并非所有 Claude 模型在所有地区都可用
• 尝试切换到 global 区域，以便自动路由到可用区域
• 请查看 Vertex AI Model Garden 以了解您所在区域可用的模型。
• 考虑使用模型可用性更广的其他区域（例如 us-east5）。

延迟问题

• 如果您遇到高延迟，请尝试使用地理位置更靠近您用户的区域。
• global 区域会自动路由到最近的可用区域
• 对于有严格延迟要求的生产工作负载，请测试不同的区域并选择最适合您用例的区域以获得最佳性能。

验证设置

1. 确保您的服务账号密钥有效：

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

2. 测试 Vertex AI 访问：

   gcloud ai models list --region=us-east5

3. 验证 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 完全支持网络搜索功能。
• 通过自动标头过滤支持 Prompt caching，以实现与 Vertex AI 的兼容性。
• Function calling 和 tool use 的工作方式与直接使用 Anthropic API 时相同。