Executando Claude no Google Cloud Vertex AI: Quotas e Contas de Serviço

O Google Cloud Vertex AI coloca o Claude por trás do seu projeto GCP existente: uma conta de serviço autentica as chamadas, a quota do projeto limita o tráfego que você pode enviar e um endpoint regional decide onde a inferência realmente é executada.

Resumo

O Vertex AI autentica de forma diferente da API direta da Anthropic e do Amazon Bedrock - não há chave de API alguma, apenas as Credenciais Padrão de Aplicação do Google resolvidas através de uma conta de serviço.

Três coisas precisam existir antes que uma chamada seja bem-sucedida: uma conta de serviço com a função IAM correta, a API Vertex AI habilitada com quota suficiente no projeto e uma escolha deliberada de região em vez de um padrão assumido.

A falta de qualquer um desses três produz um erro de permissão ou quota que se parece com um bug no SDK, mas é realmente uma lacuna de provisionamento, a mesma forma de falha de uma conta Bedrock não provisionada.

Esta página cobre a configuração da conta de serviço, solicitação e monitoramento de quota, e a escolha entre uma região específica e o roteamento global do Vertex AI, em seguida, mostra o formato de solicitação que o código da aplicação realmente usa.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

from anthropic import AnthropicVertex
 
client = AnthropicVertex(project_id="my-gcp-project", region="us-east5")
 
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Summarize this ticket in one sentence."}],
)
print(response.content[0].text)

Quando usar isso:

Sua organização já executa cargas de trabalho de produção no Google Cloud e deseja que o uso do Claude flua através do IAM e faturamento existentes.
Você precisa que o tráfego do Claude permaneça dentro de um limite de rede e conformidade gerenciado pelo GCP.
Você deseja que os gastos do Claude contem contra um desconto de uso comprometido existente do Google Cloud.
Você está integrando o Claude a um serviço que já autentica outras APIs do GCP via conta de serviço.

Exemplo de Trabalho

import os
from anthropic import AnthropicVertex
import anthropic
 
# project_id and region are both required - there is no default project or region.
client = AnthropicVertex(
    project_id=os.environ["GCP_PROJECT_ID"],
    region=os.environ.get("GCP_REGION", "us-east5"),
)
 
 
def summarize_ticket(ticket_text: str) -> str:
    """Call Claude on Vertex AI and return a one-sentence summary.
 
    Assumes Application Default Credentials resolve to a service account
    with the Vertex AI User role, and that the project has quota for
    claude-sonnet-5 in the target region.
    """
    try:
        response = client.messages.create(
            model="claude-sonnet-5",
            max_tokens=200,
            messages=[
                {
                    "role": "user",
                    "content": f"Summarize this support ticket in one sentence:\n\n{ticket_text}",
                }
            ],
        )
        return response.content[0].text
    except anthropic.PermissionDeniedError:
        raise RuntimeError(
            "Service account lacks the Vertex AI User role, or the Vertex AI "
            "API is not enabled on this project."
        )
    except anthropic.RateLimitError:
        raise RuntimeError(
            "Project quota exceeded for this model and region - request a "
            "quota increase in the Google Cloud console."
        )
 
 
if __name__ == "__main__":
    ticket = "Customer reports login page returns a 500 error after the latest deploy."
    print(summarize_ticket(ticket))

O que isso demonstra:

AnthropicVertex aceita project_id e region como argumentos de construtor obrigatórios - nenhum tem um padrão, ao contrário do cliente da API direta que não tem argumentos.
A autenticação é inteiramente via Credenciais Padrão de Aplicação - não há chave de API da Anthropic em nenhum lugar neste código.
Capturar PermissionDeniedError e RateLimitError separadamente transforma as duas falhas mais comuns de primeira implantação (função IAM ausente, quota esgotada) em uma mensagem acionável.

Mergulho Profundo

Como Funciona

Toda solicitação do Vertex AI autentica como uma conta de serviço através da cadeia de Credenciais Padrão de Aplicação do Google - localmente isso se resolve através de gcloud auth application-default login, e em produção se resolve através da conta de serviço anexada ao ambiente de computação (uma instância GCE, um serviço Cloud Run ou uma vinculação de identidade de carga de trabalho GKE).
A conta de serviço precisa da função IAM Vertex AI User (ou uma função personalizada equivalente com as permissões correspondentes) vinculada no nível do projeto ou recurso antes que qualquer chamada seja bem-sucedida.
Habilitar a API Vertex AI no projeto é uma etapa separada do vínculo IAM - uma conta de serviço com a função correta ainda falha se a API em si nunca foi habilitada para esse projeto.
Quota é rastreada por projeto, por modelo e por região - um projeto com quota generosa em us-east5 pode não ter nenhuma em europe-west1 até que um aumento separado seja solicitado lá.
A seleção de região determina onde a inferência realmente é executada: uma região específica fixa o processamento nesse local, um valor multirregional abrange uma geografia e "global" permite que a Anthropic roteie para a região com capacidade.

Configuração da Conta de Serviço

# Create a service account dedicated to Claude API calls.
gcloud iam service-accounts create claude-api-caller \
  --display-name="Claude API caller"
 
# Grant the Vertex AI User role, scoped to the project.
gcloud projects add-iam-policy-binding my-gcp-project \
  --member="serviceAccount:claude-api-caller@my-gcp-project.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"
 
# Enable the Vertex AI API if it isn't already.
gcloud services enable aiplatform.googleapis.com --project=my-gcp-project

Criar uma conta de serviço dedicada para tráfego do Claude, em vez de reutilizar uma conta de propósito geral ampla, mantém a auditoria IAM simples e limita o raio de explosão se as credenciais forem comprometidas.
roles/aiplatform.user é a função predefinida padrão para invocar modelos do Vertex AI; uma função personalizada mais restrita vale a pena construir assim que suas necessidades de permissão forem bem compreendidas.
Habilitar a API é idempotente - executá-la novamente em um projeto já habilitado não faz nada, portanto, é seguro incluí-la em scripts de configuração.

Escolhas de Região e Endpoint

Valor da Região	Comportamento	Melhor ajuste
Região específica (ex: `us-east5`)	Inferência fixada nesse local exato.	Requisitos de residência de dados ou latência que exigem um local fixo.
Multirregional (ex: `us`, `eu`)	Roteia dentro de uma geografia, não um único data center.	Cargas de trabalho sensíveis à latência com um requisito de residência amplo, mas limitado.
`"global"`	A Anthropic roteia para a melhor região disponível.	Escolha padrão quando não há restrição de residência - maximiza a disponibilidade durante limites de capacidade regionais.

Aumentos de quota são com escopo regional, portanto, mudar uma carga de trabalho de uma região específica para "global" (ou vice-versa) mais tarde pode exigir uma nova conversa sobre quota, não apenas uma alteração de código.
Uma carga de trabalho regulamentada que deve manter o processamento dentro de uma jurisdição nomeada deve fixar uma região específica em vez de usar "global", mesmo que "global" seja o padrão mais resiliente para todo o resto.

Notas Python

from anthropic import AnthropicVertex
 
# Streaming works identically to the direct API - only the client class differs.
client = AnthropicVertex(project_id="my-gcp-project", region="us-east5")
 
with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=512,
    messages=[{"role": "user", "content": "Draft a short release note."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

AnthropicVertex expõe os mesmos métodos messages.create e messages.stream que os clientes da API direta e Bedrock - o código escrito contra a API direta precisa apenas de uma alteração na construção do cliente para rodar no Vertex AI.
Instalar o SDK com o extra vertex (pip install "anthropic[vertex]") puxa as bibliotecas de autenticação do Google que o cliente precisa; o pacote anthropic simples sozinho não é suficiente.

Parâmetros e Valores de Retorno

Parâmetro	Tipo	Descrição
`project_id`	`str`	Argumento construtor obrigatório. O projeto GCP que detém a quota e o faturamento para essas chamadas.
`region`	`str`	Argumento construtor obrigatório. Uma região específica, um valor multirregional ou `"global"`.
`model`	`str`	Os IDs de modelo Claude de geração atual no Vertex AI não têm prefixo, correspondendo à string de modelo nua da API direta.

Armadilhas

Assumir que o padrão de cliente sem argumentos da API direta funciona aqui. AnthropicVertex() sem argumentos gera um erro imediatamente - tanto project_id quanto region são obrigatórios. Correção: sempre passe ambos explicitamente, geralmente obtidos da configuração do ambiente.
A conta de serviço tem a função IAM, mas a API Vertex AI nunca foi habilitada. O vínculo da função é bem-sucedido silenciosamente, mas as chamadas ainda falham. Correção: confirme se aiplatform.googleapis.com está habilitado no projeto, não apenas se a função IAM existe.
Solicitar quota na região errada. A quota é concedida por região, portanto, um aumento de quota aprovado para us-east5 não faz nada para um cliente configurado com region="europe-west1". Correção: corresponda exatamente a região da solicitação de quota com a região configurada do cliente.
Tratar "global" como sempre a escolha mais segura. Para uma carga de trabalho regulamentada com um requisito de residência de dados, "global" pode rotear a inferência para uma região fora da jurisdição necessária. Correção: fixe uma região específica sempre que a residência for um requisito rígido e use "global" apenas quando não houver tal restrição.
Esquecer o extra vertex ao instalar o SDK. Um simples pip install anthropic não inclui as dependências de autenticação do Google que AnthropicVertex precisa. Correção: instale com pip install "anthropic[vertex]".
Reutilizar uma conta de serviço ampla e pré-existente em vez de uma com escopo. Isso torna a auditoria IAM para tráfego específico do Claude muito mais difícil depois. Correção: crie uma conta de serviço dedicada para chamadas de API do Claude com apenas as funções necessárias.

Alternativas

Alternativa	Use Quando	Não Use Quando
API Direta da Anthropic	Você quer o caminho mais rápido para novos modelos e recursos, sem dependência do GCP.	Sua organização exige que o tráfego permaneça dentro da governança IAM e de rede gerenciada pelo GCP.
Amazon Bedrock	Sua organização está padronizada em AWS em vez de GCP.	Você não tem presença na AWS e estaria adicionando um novo fornecedor de nuvem apenas para isso.
Um gateway auto-hospedado na frente do Vertex AI	Você quer adicionar cache, limitação de taxa centralizada ou fallback para outro provedor sem tocar no código da aplicação.	Você tem uma única carga de trabalho simples onde a infraestrutura adicionada não vale o custo operacional.

FAQs

Preciso de uma chave de API da Anthropic para usar o Claude no Vertex AI?

Não. A autenticação é inteiramente através das Credenciais Padrão de Aplicação do Google, resolvidas para uma conta de serviço - não há chave de API separada emitida pela Anthropic envolvida.

Por que `AnthropicVertex()` gera um erro sem argumentos?

Tanto project_id quanto region são argumentos construtores obrigatórios sem padrões, ao contrário do cliente da API direta que pode ser construído sem argumentos lendo uma variável de ambiente.

Qual função IAM a conta de serviço precisa?

A função predefinida roles/aiplatform.user, ou uma função personalizada equivalente com permissões correspondentes
A própria API Vertex AI habilitada no projeto, que é uma etapa separada do vínculo IAM

Como a quota é escopada no Vertex AI?

Por projeto, por modelo e por região. Um aumento de quota aprovado para uma região não se aplica a uma região diferente configurada no cliente.

Qual é a diferença entre uma região específica, um valor multirregional e "global"?

Uma região específica fixa a inferência em um local; um valor multirregional roteia dentro de uma geografia; "global" permite que a Anthropic roteie para a região com capacidade, que é o padrão mais resiliente na ausência de um requisito de residência.

Uma carga de trabalho regulamentada deve usar `region="global"`?

Geralmente não. Um requisito rígido de residência de dados exige a fixação de uma região específica, pois "global" pode rotear a inferência para fora de uma jurisdição necessária.

O mesmo código de aplicação pode rodar tanto contra a API direta quanto contra o Vertex AI?

Na maioria das vezes, sim. Ambos os clientes expõem os mesmos métodos messages.create e messages.stream - as diferenças são a construção do cliente (chave de API vs. projeto e região) e, para modelos mais antigos de snapshot datado, o formato do ID do modelo.

Os IDs de modelo Claude atuais precisam de um prefixo no Vertex AI?

Não, para modelos de geração atual, o ID corresponde à string de modelo nua da API direta. Modelos de snapshot datado usam um separador de versão @ em vez de um prefixo.

Qual extra de pacote preciso instalar para suporte ao Vertex AI?

pip install "anthropic[vertex]" - o pacote anthropic simples não inclui as dependências de autenticação do Google que AnthropicVertex requer.

O streaming funciona da mesma forma no Vertex AI que na API direta?

Sim. client.messages.stream(...) se comporta de forma idêntica, incluindo o iterador de conveniência text_stream.

Habilitar a API Vertex AI é o mesmo que conceder acesso IAM?

Não, são etapas separadas. Uma conta de serviço pode ter a função IAM correta enquanto a API em si ainda está desabilitada no projeto, e qualquer uma das lacunas sozinha faz com que as chamadas falhem.

Por que uma equipe escolheria o Vertex AI em vez da API direta, mesmo que exija mais configuração?

Para manter o tráfego do Claude dentro da governança IAM e de rede existente do GCP, e para que os gastos contem contra um acordo de faturamento ou desconto existente do Google Cloud, em vez de um novo relacionamento com o fornecedor.

Relacionados

Escolhendo entre a API Direta, Bedrock e Vertex AI para Claude - decida se o Vertex AI é a plataforma certa antes de provisioná-lo.
Noções Básicas de Implantação Empresarial - a primeira chamada mínima em todas as três plataformas, incluindo Vertex AI.
Implantação do Claude no Amazon Bedrock: IAM, Provisionamento e Inferência entre Regiões - as etapas de provisionamento equivalentes na AWS.
Lista de Verificação de Residência de Dados e Fixação de Região para Cargas de Trabalho Regulamentadas - como a escolha da região no Vertex AI interage com os requisitos de conformidade.
Comparando Bedrock, Vertex AI e Acesso Direto à API Anthropic - trade-offs entre todas as três plataformas em uma tabela.

Versões da Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5 - e o SDK oficial anthropic para Python (última versão 0.x). Nomes de modelos, preços e versões de SDK mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.