Modalità Veloce con i modelli Claude di Anthropic

La modalità veloce accelera la generazione di token di output per i modelli Anthropic Claude supportati su Gemini Enterprise Agent Platform. Utilizza una configurazione di distribuzione ad alta velocità che preserva le funzionalità di intelligence e sicurezza del modello di base. Puoi attivare la modalità rapida per le richieste di previsione online impostando "speed": "fast" nel corpo della richiesta.

Utilizza la modalità veloce per i workload interattivi sensibili alla latenza in cui l'attesa della generazione dei token interrompe il flusso dello sviluppatore o dell'utente:

  • Programmazione agentica interattiva: esegui iterazioni su attività di programmazione, rifattorizzazione e debug in più passaggi con agenti human-in-the-loop senza cambiare contesto.
  • Pianificazione in tempo reale: raccogli il contesto del repository o operativo e genera piani di esecuzione in modo interattivo.
  • Risposta agli incidenti: assegna la priorità agli avvisi di produzione e sintetizza i passaggi di correzione quando il tempo di risposta dell'inferenza è fondamentale.

Modelli supportati e policy del ciclo di vita

La modalità veloce è disponibile nell'ultima versione di una famiglia di modelli Claude supportata e durante una finestra di transizione di 30 giorni nella versione in fase di ritiro. Agent Platform supporta la modalità veloce per i seguenti modelli:

Quando viene lanciata una nuova versione di una famiglia di modelli supportati, la modalità rapida della versione precedente di quella famiglia viene ritirata 30 giorni dopo il lancio della nuova versione. Al termine del periodo di ritiro di 30 giorni, le richieste alla versione precedente del modello che includono "speed": "fast" restituiscono un errore HTTP 400 (INVALID_ARGUMENT). Le richieste a velocità standard a quella versione del modello continuano a funzionare normalmente. Per continuare a utilizzare la modalità veloce, aggiorna le tue richieste in modo che abbiano come target l'ultima versione del modello o rimuovi "speed": "fast" dal corpo della richiesta.

Località supportate

La modalità veloce è disponibile nei seguenti ID località dell'API per i modelli supportati:

  • Globale (Claude Fable 5.2 di Anthropic su Google Cloud): global
  • Multi-regione degli Stati Uniti (Claude Fable 5.2 di Anthropic su Google Cloud): us
  • Multi-regione Europa (Claude Fable 5.2 di Anthropic su Google Cloud): eu

Gli endpoint regionali diretti non sono supportati pubblicamente per la modalità rapida. L'invio di una richiesta con "speed": "fast" a una località in cui la modalità rapida non è disponibile restituisce un errore HTTP 400 (FAILED_PRECONDITION).

Prima di iniziare

Prima di inviare richieste in modalità rapida, completa i seguenti passaggi di configurazione. La modalità Fast utilizza la stessa configurazione del progetto e l'abilitazione di Model Garden delle richieste Claude standard. Per ulteriori dettagli sulla configurazione del modello partner, consulta Prima di iniziare.

  1. Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

  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. Vai a una delle seguenti schede dei modelli di Model Garden, fai clic su Abilita e completa i termini o i requisiti di condivisione dei dati specifici del modello:

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per inviare richieste di previsione in modalità rapida ai modelli Claude, chiedi all'amministratore di concederti i seguenti ruoli IAM nel tuo progetto Google Cloud :

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Invia una richiesta in modalità rapida

Per utilizzare la modalità veloce, invia una richiesta all'endpoint del modello di pubblicazione standard (ad esempio claude-fable-5-2) e imposta "speed": "fast" nel corpo della richiesta di primo livello. Non è richiesta l'intestazione anthropic-beta e non esiste una scheda del modello separata da attivare in Model Garden.

REST

L'esempio seguente invia una richiesta di previsione a claude-fable-5-2 sull'endpoint global con "speed": "fast" abilitato.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: il tuo ID progetto Google Cloud (ad esempio, my-agent-project).
  • MODEL: un modello Claude che supporta la modalità veloce, ad esempio claude-fable-5-2 (valore predefinito: claude-fable-5-2). Specifica sempre l'ID del modello di base nell'URL dell'endpoint.

Questo esempio utilizza l'endpoint global. Per utilizzare un endpoint multiregionale supportato, consulta Specifica l'endpoint multiregionale.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

{
  "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."
    }
  ]
}

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

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

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

$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

La risposta è un oggetto JSON simile al seguente. Quando la richiesta viene gestita in modalità rapida, l'oggetto usage include "speed": "fast".

Python

Utilizzando l'SDK Vertex Anthropic (anthropic[vertex]), passa extra_body={"speed": "fast"} quando chiami 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

Controlla quale velocità è stata utilizzata

Puoi verificare che una richiesta sia stata gestita in modalità rapida esaminando il campo usage.speed nella risposta:

  • Modalità rapida: usage.speed è presente e impostato su "fast" (nelle risposte unarie o negli eventi message_start o message_delta per le risposte in streaming).
  • Velocità standard: quando invii una richiesta standard ("speed": "standard" o speed omesso), usage.speed è "standard" o viene omesso.

Quote, monitoraggio e controllo dell'accesso

La modalità Veloce utilizza una capacità dedicata e limiti di frequenza isolati dal traffico a velocità standard, ereditando al contempo la configurazione di accesso del progetto per il modello di base.

Quote

Sugli endpoint globali e multiregionali, le richieste in modalità rapida consumano un bucket di quota di derivazione condivisa dedicato, separato dalla quota del modello a velocità standard. Il traffico in modalità rapida non viene detratto dalla quota standard di anthropic-claude-fable, mentre il traffico a velocità standard non viene detratto dalla quota in modalità rapida.

Per visualizzare o richiedere un aumento della quota per la modalità rapida nella pagina Quote e limiti di sistema della consoleGoogle Cloud , filtra per base_model:

  • anthropic-claude-fable-fast (si applica agli endpoint globali e multiregionali)

Opzioni di consumo e throughput riservato

La modalità veloce non supporta il throughput riservato:

  • Solo PayGo: le richieste in modalità veloce utilizzano sempre il pay-as-you-go, anche se il tuo progetto ha un ordine di Throughput riservato attivo per il modello di base. Il traffico in modalità veloce non consuma né si riversa da un ordine di throughput riservato.
  • Le intestazioni della richiesta dedicated sono limitate: non includere l'intestazione HTTP X-Vertex-AI-LLM-Request-Type: dedicated (o i metadati gRPC) nelle richieste in modalità rapida. La modalità veloce non ha una quota di throughput riservato e le richieste dedicated non possono passare al pagamento a consumo. Di conseguenza, le richieste in modalità veloce con X-Vertex-AI-LLM-Request-Type: dedicated restituiscono un errore HTTP 429 (RESOURCE_EXHAUSTED). Ometti l'intestazione o imposta X-Vertex-AI-LLM-Request-Type: shared.

Monitora le metriche della modalità veloce

In Cloud Monitoring, i report sul traffico in modalità veloce model_user_id="claude-fable-5-2-fast" anziché l'ID del modello di base (claude-fable-5-2). Filtra per model_user_id="claude-fable-5-2-fast" in Metrics Explorer per monitorare il numero di richieste, l'utilizzo dei token e la latenza per la modalità veloce separatamente dal traffico a velocità standard.

Controllo degli accessi e policy dell'organizzazione

La modalità veloce utilizza gli stessi ruoli richiesti e lo stesso stato di attivazione di Model Garden del modello di base. Se una richiesta restituisce 403 PERMISSION_DENIED, verifica che l'entità disponga del ruolo Agent Platform User (roles/aiplatform.user) e che il modello di base sia abilitato in Model Garden.

Se la tua organizzazione applica il vincolo della policy dell'organizzazione constraints/vertexai.allowedModels, la modalità rapida è regolata dal valore :predict del modello di base (ad esempio publishers/anthropic/models/claude-fable-5-2:predict):

  • Se consenti publishers/anthropic/models/claude-fable-5-2:predict, consenti le richieste sia in modalità standard sia in modalità rapida a claude-fable-5-2.
  • Se neghi l'accesso a publishers/anthropic/models/claude-fable-5-2:predict, blocchi le richieste sia in modalità standard che in modalità rapida.

Per saperne di più sulle policy dell'organizzazione, consulta Controlla l'accesso ai modelli di Model Garden.

Prezzi

La modalità veloce utilizza sempre la fatturazione pay-as-you-go e ha prezzi separati rispetto alle richieste a velocità standard:

  • Token: il prezzo è il doppio delle tariffe dei token a velocità standard per tutti i tipi di token (token di input, output, scrittura nella cache di 5 minuti e 1 ora e successo della cache).
  • Ricerca web: le chiamate allo strumento Ricerca web vengono fatturate alla tariffa standard (1x).

L'utilizzo viene fatturato in base allo SKU Google Cloud del modello di base con un'etichetta della modalità veloce. Per le tariffe dei token regionali e globali, consulta la pagina dei prezzi di Agent Platform.

Limitazioni e gestione degli errori

Tieni presente le seguenti limitazioni quando utilizzi la modalità rapida:

  • Nessun throughput riservato: la modalità veloce non supporta il throughput riservato e utilizza sempre il pagamento a consumo. L'invio di una richiesta in modalità veloce con l'intestazione X-Vertex-AI-LLM-Request-Type: dedicated restituisce un errore HTTP 429 (RESOURCE_EXHAUSTED).
  • Nessuna previsione in batch: la modalità veloce è progettata per l'inferenza interattiva in tempo reale e non è supportata con le previsioni in batch.
  • Isolamento della cache dei prompt: le cache dei prompt non sono condivise tra le richieste a velocità standard e in modalità veloce. Una voce della cache scritta a velocità standard non produrrà un successo della cache in modalità rapida. Analogamente, una voce della cache in modalità rapida non produrrà un successo della cache a velocità standard.
  • Nessun downgrade silenzioso: se una richiesta con "speed": "fast" non può essere gestita in modalità veloce, Agent Platform restituisce un errore anziché tornare alla velocità standard.

La tabella seguente riepiloga gli errori restituiti per le richieste in modalità rapida non valide o non supportate:

Stato e codice HTTP Messaggio di errore Causa e correzione
400 INVALID_ARGUMENT Fast mode (speed: fast) is not supported for this model. Il modello di destinazione non offre la modalità veloce o questa modalità è stata ritirata 30 giorni dopo il lancio di una versione più recente del modello. Scegli come target un modello supportato o rimuovi "speed": "fast".
400 INVALID_ARGUMENT Invalid value for speed; expected "standard" or "fast". Il campo speed contiene un valore non supportato o non è una stringa. Specifica "fast" o "standard".
400 INVALID_ARGUMENT Invalid request body: duplicate keys or malformed JSON. Il corpo della richiesta JSON contiene chiavi duplicate (ad esempio chiavi "speed" duplicate) o una sintassi JSON non corretta. Invia un JSON valido con una singola chiave "speed".
400 INVALID_ARGUMENT Fast mode is not supported for batch prediction. La richiesta è stata inviata a un job di previsione in batch con "speed": "fast". Rimuovi "speed": "fast" per i workload batch.
400 FAILED_PRECONDITION Fast mode is not available in this location. Il deployment della modalità rapida non è stato eseguito nella regione richiesta. Instrada la richiesta a una delle località supportate.
404 NOT_FOUND Publisher Model ... was not found L'URL della richiesta ha come target l'etichetta della metrica di monitoraggio (claude-fable-5-2-fast) anziché un ID modello richiamabile. Scegli come target l'ID del modello di base (claude-fable-5-2) e passa "speed": "fast" nel corpo della richiesta.
429 RESOURCE_EXHAUSTED Too many requests. Exceeded the provisioned throughput La richiesta includeva sia "speed": "fast" sia l'intestazione X-Vertex-AI-LLM-Request-Type: dedicated. La modalità veloce non supporta il throughput riservato e utilizza sempre il pagamento a consumo; rimuovi X-Vertex-AI-LLM-Request-Type: dedicated (o impostalo su shared).
429 RESOURCE_EXHAUSTED Quota superata per anthropic-claude-fable-fast Il tuo progetto ha superato la quota di QPM, TPM di input o TPM di output in modalità rapida in quella località. Riprova con il backoff esponenziale o richiedi un aumento della quota per anthropic-claude-fable-fast.

Gestisci gli errori della modalità rapida

Poiché Agent Platform non esegue il downgrade silenzioso delle richieste in modalità veloce, la tua applicazione decide cosa succede quando la modalità veloce non è disponibile. Ad esempio, la modalità rapida viene ritirata 30 giorni dopo il lancio della versione successiva oppure una località potrebbe non offrire la modalità rapida. I seguenti esempi di Python corrispondono ai messaggi di errore specifici della modalità rapida, pertanto vengono comunque visualizzati errori HTTP 400 non correlati.

Torna alla velocità standard

Per i workload che possono tollerare una latenza più elevata, intercetta gli errori di disponibilità della modalità veloce e riprova la richiesta alla velocità standard:

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,
        )

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto Google Cloud , ad esempio my-agent-project.
  • LOCATION: una località supportata, ad esempio global (valore predefinito: global).
  • PROMPT: il testo del prompt da inviare al modello.

Passa alla versione successiva del modello

Per mantenere la modalità veloce dopo il ritiro della versione del modello, riprova la richiesta con la modalità veloce nella versione successiva:

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"},
        )

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto Google Cloud , ad esempio my-agent-project.
  • LOCATION: una località supportata, ad esempio global (valore predefinito: global).
  • CURRENT_MODEL e NEXT_MODEL: la versione del modello che utilizzi (ad esempio claude-fable-5-2) e la versione successiva della stessa famiglia di modelli.
  • PROMPT: il testo del prompt da inviare al modello.

Il pattern della versione successiva gestisce solo l'errore di ritiro del modello. Se la località non offre la modalità rapida, la versione successiva non risolverà l'errore. Indirizza la richiesta a una località supportata.

Passaggi successivi