Estrutura de Objeto do Anthropic Vertex AI

O LibreChat oferece suporte à execução de modelos Anthropic Claude por meio do Google Cloud Vertex AI. Isso permite que você utilize modelos Claude com sua infraestrutura, faturamento e credenciais existentes do Google Cloud.

Para uma configuração rápida usando variáveis de ambiente, consulte o guia de configuração da Anthropic

Benefícios

• Faturamento Unificado: Use sua conta de faturamento do Google Cloud existente
• Recursos Corporativos: Acesse os recursos de segurança e conformidade corporativa do Google Cloud
• Conformidade Regional: Implante em regiões específicas para atender aos requisitos de residência de dados
• Infraestrutura Existente: Aproveite suas contas de serviço e políticas de IAM do GCP atuais

Pré-requisitos

Antes de configurar o Anthropic Vertex AI, certifique-se de que você tenha:

1. Google Cloud Project com a Vertex AI API habilitada
2. Service Account com a função Vertex AI User (roles/aiplatform.user)
3. Modelos Claude habilitados no seu Vertex AI Model Garden
4. Service Account Key (arquivo JSON) baixada e acessível ao LibreChat

Exemplo de Configuração

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

Nota: O endpoint da Anthropic suporta todas as Shared Endpoint Settings, incluindo streamRate, titleModel, titleMethod, titlePrompt, titlePromptTemplate e titleEndpoint.

vertex

O objeto vertex contém todas as opções de configuração específicas do Vertex AI.

region

Chave:

Padrão: us-east5

Regiões Disponíveis:

• global (recomendado para a maioria dos casos de uso)
• us-east5
• us-central1
• europe-west1
• europe-west4
• asia-southeast1

Dica: A região global é recomendada, pois fornece roteamento automático para a região disponível mais próxima. Use regiões específicas apenas se você tiver requisitos de residência de dados.

Exemplo:

region: "global"

projectId

Chave:

Padrão: Detectado automaticamente a partir do arquivo de chave de serviço

Exemplo:

projectId: "${GOOGLE_PROJECT_ID}"

serviceKeyFile

Chave:

Padrão: api/data/auth.json (ou variável de ambiente GOOGLE_SERVICE_KEY_FILE)

Exemplo:

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

models

O campo models define os modelos Claude disponíveis e mapeia nomes amigáveis para IDs de implantação do Vertex AI. Isso funciona de forma semelhante ao mapeamento de modelos do Azure OpenAI.

Opções de Formato

Você pode configurar modelos de três maneiras:

Opção 1: Array Simples

Use os IDs de modelo reais do Vertex AI diretamente. Eles serão exibidos como estão na interface:

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

Opção 2: Objeto com Nomes Personalizados (Recomendado)

Mapeie nomes amigáveis para nomes de implantação do 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

Opção 3: Formato Misto com Padrão

Defina um nome de implantação padrão e use valores booleanos para modelos que o herdam:

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

Propriedades do Objeto Model

Exemplo:

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

Alternativa de Variável de Ambiente

Para configurações mais simples, você pode configurar o Vertex AI usando variáveis de ambiente em vez de 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

Nota: Ao usar variáveis de ambiente, o mapeamento de modelos não está disponível. Todos os modelos Claude conhecidos serão incluídos automaticamente.

Exemplos Completos

Configuração Básica

Configuração mínima usando os padrões (Vertex AI é habilitado pela presença da seção vertex):

endpoints:
  anthropic:
    vertex:
      region: us-east5

Isso utiliza:

• Região: us-east5
• Chave de serviço: api/data/auth.json (ou variável de ambiente GOOGLE_SERVICE_KEY_FILE)
• ID do Projeto: Detectado automaticamente a partir da chave de serviço
• Modelos: Todos os modelos Claude conhecidos

Configuração de Produção com Model Mapping

Configuração completa com nomes e títulos de modelos personalizados:

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

Configuração Multi-Região

Você só pode configurar uma região por implantação. Para necessidades de múltiplas regiões, considere usar instâncias separadas do LibreChat ou endpoints personalizados.

Solução de problemas

Erros Comuns

"Não foi possível carregar as credenciais padrão"

• Certifique-se de que o arquivo de chave da conta de serviço exista no caminho especificado
• Verifique as permissões de arquivo (devem ser legíveis pelo processo do LibreChat)
• Verifique se o arquivo JSON é válido e não está corrompido

"Permission denied" ou "403 Forbidden"

• Verifique se a conta de serviço possui a função Vertex AI User
• Certifique-se de que os modelos Claude estejam habilitados no seu Vertex AI Model Garden
• Verifique se a conta de serviço pertence ao projeto correto

"Modelo não encontrado"

• Verifique se o ID do modelo em deploymentName está correto
• Verifique se o modelo está disponível na região selecionada
• Certifique-se de que o modelo esteja habilitado no seu Vertex AI Model Garden

Problemas de Região

"Região inválida" ou "Região não suportada"

• Use uma das regiões suportadas listadas acima
• Tente usar a região global, que oferece roteamento automático
• Consulte a documentação do Google Cloud para obter a lista mais recente de regiões onde o Claude está disponível.

"Modelo não disponível na região"

• Nem todos os modelos Claude estão disponíveis em todas as regiões
• Tente mudar para a região global para roteamento automático para uma região disponível
• Verifique o Vertex AI Model Garden para ver quais modelos estão disponíveis em sua região
• Considere usar uma região diferente que tenha maior disponibilidade de modelos (por exemplo, us-east5)

Problemas de latência

• Se você estiver enfrentando alta latência, tente usar uma região geograficamente mais próxima aos seus usuários
• A região global roteia automaticamente para a região disponível mais próxima
• Para cargas de trabalho em produção com requisitos rigorosos de latência, teste diferentes regiões e escolha aquela com o melhor desempenho para o seu caso de uso.

Verificando a Configuração

1. Certifique-se de que a chave da sua conta de serviço seja válida:

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

2. Testar acesso ao Vertex AI:

   gcloud ai models list --region=us-east5

3. Verifique o acesso ao modelo 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"}]}'

Notas

• Vertex AI e a API direta da Anthropic são mutuamente exclusivos. Quando uma seção de configuração vertex está presente, a variável de ambiente ANTHROPIC_API_KEY é ignorada.
• A funcionalidade de pesquisa na web é totalmente suportada com Vertex AI.
• O prompt caching é suportado via filtragem automática de cabeçalhos para compatibilidade com o Vertex AI.
• Function calling e o uso de ferramentas funcionam da mesma forma que com a API direta da Anthropic.