Modo rápido com modelos Anthropic Claude

O modo rápido acelera a geração de tokens de saída para modelos Anthropic Claude compatíveis na Gemini Enterprise Agent Platform. Ele usa uma configuração de exibição de alta velocidade que preserva os recursos de inteligência e segurança do modelo de base. Para ativar o modo rápido em solicitações de previsão on-line, defina "speed": "fast" no corpo da solicitação.

Use o modo rápido para cargas de trabalho interativas e sensíveis à latência, em que esperar pela geração de tokens interrompe o fluxo do desenvolvedor ou do usuário:

  • Programação agêntica interativa: faça iterações em tarefas de programação, refatoração e depuração em várias etapas com agentes human-in-the-loop sem alternar o contexto.
  • Planejamento em tempo real: colete o contexto operacional ou do repositório e gere planos de execução de forma interativa.
  • Resposta a incidentes: faça a triagem de alertas de produção e sintetize as etapas de correção quando o tempo de resposta da inferência for crítico.

Modelos compatíveis e política de ciclo de vida

O modo rápido é oferecido na versão mais recente de uma família de modelos Claude compatível e durante uma janela de transição de 30 dias na versão que será desativada. A Agent Platform é compatível com o modo rápido para os seguintes modelos:

Quando uma nova versão de uma família de modelos compatível é lançada, o modo rápido na versão anterior dessa família é desativado 30 dias após o lançamento da nova versão. Depois que o período de desativação de 30 dias terminar, as solicitações para a versão anterior do modelo que incluírem "speed": "fast" vão retornar um erro HTTP 400 (INVALID_ARGUMENT). As solicitações de velocidade padrão para essa versão do modelo continuam funcionando normalmente. Para continuar usando o modo rápido, atualize suas solicitações para segmentar a versão mais recente do modelo ou remova "speed": "fast" do corpo da solicitação.

Locais suportados

O modo rápido está disponível nos seguintes IDs de local da API para modelos compatíveis:

  • Global (Claude Fable 5.2 da Anthropic no Google Cloud): global
  • Multirregião dos Estados Unidos (Claude Fable 5.2 da Anthropic no Google Cloud): us
  • Multirregião da Europa (Claude Fable 5.2 da Anthropic no Google Cloud): eu

Os endpoints regionais diretos não são compatíveis publicamente com o modo rápido. O envio de uma solicitação com "speed": "fast" para um local em que o modo rápido não está disponível retorna um erro HTTP 400 (FAILED_PRECONDITION).

Antes de começar

Antes de enviar solicitações do modo rápido, conclua as etapas de configuração a seguir. O modo rápido usa a mesma configuração de projeto e ativação do Model Garden que as solicitações padrão do Claude. Para mais detalhes sobre a configuração do modelo de parceiro, consulte Antes de começar.

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

  4. Verify that billing is enabled for your Google Cloud project.

  5. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  6. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  7. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

  8. Verify that billing is enabled for your Google Cloud project.

  9. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    10.
  10. Acesse um dos seguintes cards de modelo do Model Garden, clique em Ativar e preencha os termos específicos do modelo ou os requisitos de compartilhamento de dados:

Funções exigidas

Para receber as permissões necessárias para enviar solicitações de previsão do modo rápido para modelos do Claude, peça ao administrador para conceder a você os seguintes papéis do IAM no seu projeto do Google Cloud :

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Enviar uma solicitação de modo rápido

Para usar o modo rápido, envie uma solicitação ao endpoint do modelo de publicação padrão (por exemplo, claude-fable-5-2) e defina "speed": "fast" no corpo da solicitação de nível superior. Nenhum cabeçalho anthropic-beta é necessário, e não há um card de modelo separado para ativar no Model Garden.

REST

O exemplo a seguir envia uma solicitação de previsão para claude-fable-5-2 no endpoint global com "speed": "fast" ativado.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto do Google Cloud (por exemplo, my-agent-project).
  • MODEL: um modelo Claude compatível com o modo rápido, como claude-fable-5-2 (padrão: claude-fable-5-2). Sempre especifique o ID do modelo base no URL do endpoint.

Este exemplo usa o endpoint global. Para usar um endpoint multirregional compatível, consulte Especificar o endpoint multirregional.

Método HTTP e URL: 

POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/anthropic/models/MODEL:rawPredict

Corpo JSON da solicitação:

{
  "anthropic_version": "vertex-2023-10-16",
  "speed": "fast",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Analyze the root cause of an HTTP 502 spike on an upstream GKE ingress controller and list three immediate mitigation steps."
    }
  ]
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/anthropic/models/MODEL:rawPredict"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/anthropic/models/MODEL:rawPredict" | Select-Object -Expand Content

A resposta é um objeto JSON semelhante ao seguinte. Quando a solicitação é atendida no modo rápido, o objeto usage inclui "speed": "fast".

Python

Usando o SDK Vertex Anthropic (anthropic[vertex]), transmita extra_body={"speed": "fast"} ao chamar client.messages.create():

from anthropic import AnthropicVertex
from anthropic.types import Message


def generate_with_fast_mode(
    project_id: str = "PROJECT_ID",
) -> Message:
    client = AnthropicVertex(
        project_id=project_id,
        region="global",
    )

    message = client.messages.create(
        model="claude-fable-5-2",
        max_tokens=1024,
        extra_body={"speed": "fast"},
        messages=[
            {
                "role": "user",
                "content": (
                    "Analyze the root cause of an HTTP 502 spike on an upstream "
                    "GKE ingress controller and list three immediate mitigation "
                    "steps."
                ),
            }
        ],
    )
    print(message.model_dump_json(indent=2))
    return message

Verificar qual velocidade foi usada

Para verificar se uma solicitação foi atendida no modo rápido, inspecione o campo usage.speed na resposta:

  • Modo rápido: usage.speed está presente e definido como "fast" (em respostas unárias ou nos eventos message_start ou message_delta para respostas de streaming).
  • Velocidade padrão: quando você envia uma solicitação padrão ("speed": "standard" ou speed omitido), usage.speed é "standard" ou omitido.

Cotas, monitoramento e controle de acesso

O modo rápido usa capacidade dedicada e limitação de taxa isoladas do tráfego de velocidade padrão, além de herdar a configuração de acesso do projeto para o modelo de base.

Cotas

Em endpoints globais e multirregionais, as solicitações do modo rápido consomem um bucket dedicado de cota de linhagem compartilhada, separado da cota do modelo de velocidade padrão. O tráfego do modo rápido não é deduzido da sua cota padrão de anthropic-claude-fable, e o tráfego de velocidade padrão não é deduzido da sua cota do modo rápido.

Para conferir ou solicitar um aumento de cota do modo rápido na página Cotas e limites do sistema no console doGoogle Cloud , filtre por base_model:

  • anthropic-claude-fable-fast (aplica-se a endpoints globais e multirregionais)

Opções de consumo e capacidade de processamento provisionada

O modo rápido não é compatível com a capacidade de processamento provisionada:

  • Somente PayGo: as solicitações do modo rápido sempre usam o pay-as-you-go, mesmo que seu projeto tenha um pedido de Capacidade de Processamento Provisionada ativo para o modelo de base. O tráfego do modo rápido nunca consome nem transborda de um pedido de capacidade de processamento provisionada.
  • Os cabeçalhos da solicitação dedicated são limitados: não inclua o cabeçalho HTTP X-Vertex-AI-LLM-Request-Type: dedicated (ou metadados gRPC) em solicitações de modo rápido. O modo rápido não tem cota de capacidade de processamento provisionada, e as solicitações de dedicated não podem ser transferidas para o pagamento por uso. Como resultado, as solicitações do modo rápido com X-Vertex-AI-LLM-Request-Type: dedicated retornam um erro HTTP 429 (RESOURCE_EXHAUSTED). Omita o cabeçalho ou defina X-Vertex-AI-LLM-Request-Type: shared.

Monitorar métricas do modo rápido

No Cloud Monitoring, o modo rápido informa o tráfego model_user_id="claude-fable-5-2-fast" em vez do ID do modelo base (claude-fable-5-2). Filtre por model_user_id="claude-fable-5-2-fast" no Metrics Explorer para monitorar as contagens de solicitações, o uso de tokens e a latência do modo rápido separadamente do tráfego de velocidade padrão.

Controle de acesso e política da organização

O modo rápido usa os mesmos papéis necessários e o mesmo estado de ativação do Model Garden que o modelo base. Se uma solicitação retornar 403 PERMISSION_DENIED, verifique se o principal tem o papel de usuário da Agent Platform (roles/aiplatform.user) e se o modelo de base está ativado no Model Garden.

Se a organização aplicar a restrição de política da organização constraints/vertexai.allowedModels, o modo rápido será regido pelo valor :predict do modelo base (por exemplo, publishers/anthropic/models/claude-fable-5-2:predict):

  • Permitir publishers/anthropic/models/claude-fable-5-2:predict permite solicitações de velocidade padrão e de modo rápido para claude-fable-5-2.
  • Negar publishers/anthropic/models/claude-fable-5-2:predict bloqueia solicitações de velocidade padrão e de modo rápido.

Para mais informações sobre políticas da organização, consulte Controlar o acesso aos modelos do Model Garden.

Preços

O modo rápido sempre usa o faturamento de pay-as-you-go e tem preços separados das solicitações de velocidade padrão:

  • Tokens: o preço é duas vezes as taxas de token de velocidade padrão em todos os tipos de token (entrada, saída, gravação em cache de 5 minutos e 1 hora e tokens de ocorrência em cache).
  • Pesquisa na Web: as chamadas de ferramenta de pesquisa na Web são cobradas de acordo com a taxa padrão (1x).

O uso é cobrado de acordo com a SKU do modelo base Google Cloud com um rótulo de modo rápido. Para conferir as taxas de token regionais e globais, consulte a página de preços da Agent Platform.

Limitações e tratamento de erros

Lembre-se das seguintes limitações ao usar o modo rápido:

  • Sem capacidade de processamento provisionada: o modo rápido não é compatível com a capacidade de processamento provisionada e sempre usa o pagamento por uso. O envio de uma solicitação de modo rápido com o cabeçalho X-Vertex-AI-LLM-Request-Type: dedicated retorna um erro HTTP 429 (RESOURCE_EXHAUSTED).
  • Sem predições em lote: o modo rápido foi projetado para inferência interativa em tempo real e não é compatível com predições em lote.
  • Isolamento do cache de comandos: os caches de comandos não são compartilhados entre solicitações de velocidade padrão e de modo rápido. Uma entrada de cache gravada na velocidade padrão não produzirá uma ocorrência em cache no modo rápido. Da mesma forma, uma entrada de cache de modo rápido não produzirá uma ocorrência em cache na velocidade padrão.
  • Sem downgrade silencioso: se uma solicitação com "speed": "fast" não puder ser atendida no modo rápido, a Plataforma de Agentes vai retornar um erro em vez de voltar para a velocidade padrão.

A tabela a seguir resume os erros retornados para solicitações de modo rápido inválidas ou não compatíveis:

Status e código HTTP Mensagem de erro Causa e correção
400 INVALID_ARGUMENT Fast mode (speed: fast) is not supported for this model. O modelo de destino não oferece o modo rápido ou esse modo foi desativado 30 dias após o lançamento de uma versão mais recente do modelo. Segmente um modelo compatível ou remova "speed": "fast".
400 INVALID_ARGUMENT Invalid value for speed; expected "standard" or "fast". O campo speed contém um valor não aceito ou não é uma string. Especifique "fast" ou "standard".
400 INVALID_ARGUMENT Invalid request body: duplicate keys or malformed JSON. O corpo da solicitação JSON contém chaves duplicadas (como chaves "speed" duplicadas) ou sintaxe JSON incorreta. Envie um JSON válido com uma única chave "speed".
400 INVALID_ARGUMENT Fast mode is not supported for batch prediction. A solicitação foi enviada para um job de predição em lote com "speed": "fast". Remova "speed": "fast" para cargas de trabalho em lote.
400 FAILED_PRECONDITION Fast mode is not available in this location. O modo rápido não está implantado na região solicitada. Encaminhe a solicitação para um dos locais com suporte.
404 NOT_FOUND Publisher Model ... was not found O URL da solicitação segmentou o rótulo da métrica de monitoramento (claude-fable-5-2-fast) em vez de um ID de modelo que pode ser chamado. Segmente o ID do modelo base (claude-fable-5-2) e transmita "speed": "fast" no corpo da solicitação.
429 RESOURCE_EXHAUSTED Too many requests. Exceeded the provisioned throughput A solicitação incluiu "speed": "fast" e o cabeçalho X-Vertex-AI-LLM-Request-Type: dedicated. O modo rápido não é compatível com a capacidade de processamento provisionada e sempre usa o pagamento por uso. Remova X-Vertex-AI-LLM-Request-Type: dedicated (ou defina como shared).
429 RESOURCE_EXHAUSTED Cota excedida para anthropic-claude-fable-fast Seu projeto excedeu a cota de QPM, TPM de entrada ou TPM de saída do modo rápido nesse local. Tente novamente com a espera exponencial ou solicite um aumento de cota para anthropic-claude-fable-fast.

Tratar erros do modo rápido

Como a Plataforma de Agentes não faz downgrade silencioso das solicitações do modo rápido, seu aplicativo decide o que acontece quando o modo rápido não está disponível. Por exemplo, o modo rápido é desativado 30 dias após o lançamento da próxima versão, ou um local pode não oferecer o modo rápido. Os exemplos de Python a seguir correspondem às mensagens de erro específicas do modo rápido para que erros HTTP 400 não relacionados ainda apareçam.

Voltar para a velocidade padrão

Para cargas de trabalho que toleram latência mais alta, capture os erros de disponibilidade do modo rápido e tente novamente a solicitação na velocidade padrão:

import anthropic
from anthropic import AnthropicVertex
from anthropic.types import Message

# Errors that mean fast mode isn't available for this model or location.
_FAST_MODE_UNAVAILABLE = (
    "Fast mode (speed: fast) is not supported for this model.",
    "Fast mode is not available in this location.",
)


def generate_with_standard_fallback(
    project_id: str = "PROJECT_ID",
    region: str = "LOCATION",
    model: str = "claude-fable-5-2",
) -> Message:
    client = AnthropicVertex(project_id=project_id, region=region)
    messages = [{"role": "user", "content": "PROMPT"}]
    try:
        return client.messages.create(
            model=model,
            max_tokens=1024,
            messages=messages,
            extra_body={"speed": "fast"},
        )
    except anthropic.BadRequestError as e:
        if not any(msg in str(e) for msg in _FAST_MODE_UNAVAILABLE):
            raise
        # Fast mode isn't available: retry at standard speed.
        return client.messages.create(
            model=model,
            max_tokens=1024,
            messages=messages,
        )

Substitua:

  • PROJECT_ID: o ID do projeto do Google Cloud , como my-agent-project.
  • LOCATION: um local compatível, como global (padrão: global).
  • PROMPT: o texto do comando a ser enviado ao modelo.

Ir para a próxima versão do modelo

Para manter o modo rápido após a desativação na versão do modelo, tente novamente a solicitação com o modo rápido na próxima versão:

import anthropic
from anthropic import AnthropicVertex
from anthropic.types import Message

_FAST_MODE_NOT_SUPPORTED = (
    "Fast mode (speed: fast) is not supported for this model."
)


def generate_with_next_version(
    project_id: str = "PROJECT_ID",
    region: str = "LOCATION",
    model: str = "CURRENT_MODEL",
    next_model: str = "NEXT_MODEL",
) -> Message:
    client = AnthropicVertex(project_id=project_id, region=region)
    messages = [{"role": "user", "content": "PROMPT"}]
    try:
        return client.messages.create(
            model=model,
            max_tokens=1024,
            messages=messages,
            extra_body={"speed": "fast"},
        )
    except anthropic.BadRequestError as e:
        if _FAST_MODE_NOT_SUPPORTED not in str(e):
            raise
        # Fast mode is retired on this version: use the next version.
        return client.messages.create(
            model=next_model,
            max_tokens=1024,
            messages=messages,
            extra_body={"speed": "fast"},
        )

Substitua:

  • PROJECT_ID: o ID do projeto do Google Cloud , como my-agent-project.
  • LOCATION: um local compatível, como global (padrão: global).
  • CURRENT_MODEL e NEXT_MODEL: a versão do modelo que você usa (como claude-fable-5-2) e a próxima versão na mesma família de modelos.
  • PROMPT: o texto do comando a ser enviado ao modelo.

O padrão de próxima versão lida apenas com o erro de desativação do modelo. Se o local não oferecer o modo rápido, a próxima versão não vai resolver o erro. Encaminhe a solicitação para um local compatível.

A seguir