LibreChat is joining ClickHouse to power the open-source Agentic Data Stack 🎉 Learn more
LibreChat

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

键：

KeyTypeDescriptionExample
regionString部署您的 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

键：

KeyTypeDescriptionExample
projectIdStringGoogle Cloud 项目 ID。支持环境变量引用。Optional. If not specified, auto-detected from the service account key file.

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

示例：

projectId: "${GOOGLE_PROJECT_ID}"

serviceKeyFile

键：

KeyTypeDescriptionExample
serviceKeyFileStringGoogle 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"

将用户友好的名称映射到 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

模型对象属性

KeyTypeDescriptionExample
deploymentNameString用于 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 部分的存在启用 Vertex AI）：

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 角色
  • 确保 Claude 模型已在您的 Vertex AI Model Garden 中启用
  • 检查服务账号是否属于正确的项目

"未找到模型"

  • 检查 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 时相同。

这篇指南怎么样？

在 GitHub 上编辑