Richiedere previsioni con i modelli Claude

Puoi utilizzare l'SDK di Anthropic o i comandi curl per inviare richieste all'endpoint Vertex AI utilizzando i seguenti nomi di modelli:

  • Per Claude Opus 4, utilizza claude-opus-4@20250514
  • Per Claude Sonnet 4, utilizza claude-sonnet-4@20250514
  • Per Claude 3.7 Sonnet, utilizza claude-3-7-sonnet@20250219
  • Per Claude 3.5 Sonnet v2, utilizza claude-3-5-sonnet-v2@20241022
  • Per Claude 3.5 Haiku, utilizza claude-3-5-haiku@20241022
  • Per Claude 3.5 Sonnet, utilizza claude-3-5-sonnet@20240620
  • Per Claude 3 Opus, utilizza claude-3-opus@20240229
  • Per Claude 3 Haiku, utilizza claude-3-haiku@20240307

Le versioni del modello Anthropic Claude devono essere utilizzate con un suffisso che inizia con un simbolo @ (ad esempio claude-3-7-sonnet@20250219 o claude-3-5-haiku@20241022) per garantire un comportamento coerente.

Prima di iniziare

Per utilizzare i modelli Anthropic Claude con Vertex AI, devi eseguire i seguenti passaggi. Per utilizzare Vertex AI, devi abilitare l'API Vertex AI (aiplatform.googleapis.com). Se hai già un progetto esistente con l'API Vertex AI abilitata, puoi utilizzare questo progetto anziché crearne uno nuovo.

Assicurati di disporre delle autorizzazioni necessarie per attivare e utilizzare i modelli partner. Per maggiori informazioni, vedi Concedere le autorizzazioni richieste.

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the Vertex AI API.

    Enable the API

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

    Go to project selector

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Enable the Vertex AI API.

    Enable the API

  8. Vai a una delle seguenti schede del modello Model Garden, poi fai clic su Attiva:
  9. Anthropic consiglia di attivare il logging di 30 giorni dell'attività di prompt e completamento per registrare eventuali utilizzi impropri del modello. Per abilitare il logging, vedi [Registrare richieste e risposte][logging].
  10. Utilizzare l'SDK Anthropic

    Puoi effettuare richieste API ai modelli Anthropic Claude utilizzando l'SDK Anthropic Claude. Per saperne di più, consulta le seguenti risorse:

    Effettuare una chiamata di streaming a un modello Claude utilizzando l'SDK Anthropic Vertex

    Il seguente esempio di codice utilizza l'SDK Anthropic Vertex per eseguire una chiamata di streaming a un modello Claude.

    Python

    Per scoprire come installare o aggiornare l'SDK Vertex AI Python, consulta Installare l'SDK Vertex AI Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python.

    L'esempio seguente utilizza endpoint regionali. Per utilizzare l'endpoint globale, vedi Specificare l'endpoint globale.
    # TODO(developer): Vertex AI SDK - uncomment below & run
    # pip3 install --upgrade --user google-cloud-aiplatform
    # gcloud auth application-default login
    # pip3 install -U 'anthropic[vertex]'
    
    # TODO(developer): Update and un-comment below line
    # PROJECT_ID = "your-project-id"
    
    from anthropic import AnthropicVertex
    
    client = AnthropicVertex(project_id=PROJECT_ID, region="us-east5")
    result = []
    
    with client.messages.stream(
        model="claude-3-5-sonnet-v2@20241022",
        max_tokens=1024,
        messages=[
            {
                "role": "user",
                "content": "Send me a recipe for banana bread.",
            }
        ],
    ) as stream:
        for text in stream.text_stream:
            print(text, end="", flush=True)
            result.append(text)
    
    # Example response:
    # Here's a simple recipe for delicious banana bread:
    # Ingredients:
    # - 2-3 ripe bananas, mashed
    # - 1/3 cup melted butter
    # ...
    # ...
    # 8. Bake for 50-60 minutes, or until a toothpick inserted into the center comes out clean.
    # 9. Let cool in the pan for a few minutes, then remove and cool completely on a wire rack.
    

    Fai una chiamata unaria a un modello Claude utilizzando l'SDK Anthropic Vertex

    Il seguente esempio di codice utilizza l'SDK Anthropic Vertex per eseguire una chiamata unaria a un modello Claude.

    Python

    Per scoprire come installare o aggiornare l'SDK Vertex AI Python, consulta Installare l'SDK Vertex AI Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python.

    L'esempio seguente utilizza endpoint regionali. Per utilizzare l'endpoint globale, vedi Specificare l'endpoint globale.
    # TODO(developer): Vertex AI SDK - uncomment below & run
    # pip3 install --upgrade --user google-cloud-aiplatform
    # gcloud auth application-default login
    # pip3 install -U 'anthropic[vertex]'
    
    # TODO(developer): Update and un-comment below line
    # PROJECT_ID = "your-project-id"
    
    from anthropic import AnthropicVertex
    
    client = AnthropicVertex(project_id=PROJECT_ID, region="us-east5")
    message = client.messages.create(
        model="claude-3-5-sonnet-v2@20241022",
        max_tokens=1024,
        messages=[
            {
                "role": "user",
                "content": "Send me a recipe for banana bread.",
            }
        ],
    )
    print(message.model_dump_json(indent=2))
    # Example response:
    # {
    #   "id": "msg_vrtx_0162rhgehxa9rvJM5BSVLZ9j",
    #   "content": [
    #     {
    #       "text": "Here's a simple recipe for delicious banana bread:\n\nIngredients:\n- 2-3 ripe bananas...
    #   ...
    

    Utilizzare un comando curl

    Puoi utilizzare un comando curl per inviare una richiesta all'endpoint Vertex AI. Il comando curl specifica il modello Claude supportato che vuoi utilizzare.

    Le versioni del modello Anthropic Claude devono essere utilizzate con un suffisso che inizia con un simbolo @ (ad esempio claude-3-7-sonnet@20250219 o claude-3-5-haiku@20241022) per garantire un comportamento coerente.

    L'argomento seguente mostra come creare un comando curl e include un comando curl di esempio.

    REST

    Per testare un prompt di testo utilizzando l'API Vertex AI, invia una richiesta POST all'endpoint del modello del publisher.

    L'esempio seguente utilizza endpoint regionali. Per utilizzare l'endpoint globale, vedi Specificare l'endpoint globale.

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

    • LOCATION: una regione che supporta i modelli Anthropic Claude. Per utilizzare l'endpoint globale, consulta Specificare l'endpoint globale.
    • MODEL: il nome del modello che vuoi utilizzare.
    • ROLE: Il ruolo associato a un messaggio. Puoi specificare un user o un assistant. Il primo messaggio deve utilizzare il ruolo user. I modelli Claude operano con turni alternati user e assistant. Se il messaggio finale utilizza il ruolo assistant, il contenuto della risposta continua immediatamente dal contenuto di quel messaggio. Puoi utilizzare questo prompt per vincolare una parte della risposta del modello.
    • STREAM: un valore booleano che specifica se la risposta viene trasmessa in streaming o meno. Trasmetti in streaming la risposta per ridurre la percezione della latenza di utilizzo finale. Imposta su true per trasmettere in streaming la risposta e false per restituire la risposta tutta in una volta.
    • CONTENT: i contenuti, ad esempio il testo, del messaggio user o assistant.
    • MAX_TOKENS: il numero massimo di token che possono essere generati nella risposta. Un token equivale a circa 3,5 caratteri. 100 token corrispondono a circa 60-80 parole.

      Specifica un valore più basso per risposte più brevi e un valore più alto per risposte potenzialmente più lunghe.

    • TOP_P (facoltativo): Top-P cambia il modo in cui il modello seleziona i token per l'output. I token vengono selezionati dal più probabile al meno probabile finché la somma delle loro probabilità non corrisponde al valore di Top-P. Ad esempio, se i token A, B e C hanno una probabilità di 0,3, 0,2 e 0,1 e il valore di top-P è 0.5, il modello seleziona A o B come token successivo utilizzando la temperatura ed esclude C come candidato.

      Specifica un valore più basso per risposte meno casuali e un valore più alto per risposte più casuali.

    • TOP_K(Facoltativo): Top-K cambia il modo in cui il modello seleziona i token per l'output. Un top-K pari a 1 indica che il token successivo selezionato è il più probabile tra tutti i token nel vocabolario del modello (chiamato anche decodifica greedy). Un top-K pari a 3 indica, invece, che il token successivo viene selezionato tra i tre token più probabili (utilizzando la temperatura).

      Per ogni fase di selezione dei token, vengono campionati i token Top-K con le probabilità più alte. Quindi i token vengono ulteriormente filtrati in base a top-P e il token finale viene selezionato utilizzando il campionamento con temperatura.

      Specifica un valore più basso per risposte meno casuali e un valore più alto per risposte più casuali.

    • TYPE: per Claude 3.7 Sonnet e i modelli Claude successivi, per attivare la modalità di pensiero esteso, specifica enable.
    • BUDGET_TOKENS: se attivi il pensiero esteso, devi specificare il numero di token che il modello può utilizzare per il suo ragionamento interno come parte dell'output. Budget più ampi possono consentire un'analisi più approfondita per problemi complessi e migliorare la qualità delle risposte. Devi specificare un valore maggiore o uguale a 1024 ma inferiore a MAX_TOKENS.

    Metodo HTTP e URL:

    POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:streamRawPredict

    Corpo JSON della richiesta:

    {
      "anthropic_version": "vertex-2023-10-16",
      "messages": [
       {
        "role": "ROLE",
        "content": "CONTENT"
       }],
      "max_tokens": MAX_TOKENS,
      "stream": STREAM,
      "thinking": {
        "type": "TYPE",
        "budget_tokens": BUDGET_TOKENS
      }
    }
    

    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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:streamRawPredict"

    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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:streamRawPredict" | Select-Object -Expand Content

    Dovresti ricevere una risposta JSON simile alla seguente.

    Comando curl di esempio

    MODEL_ID="MODEL"
    LOCATION="us-central1"
    PROJECT_ID="PROJECT_ID"
    
    curl \
    -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/anthropic/models/${MODEL_ID}:streamRawPredict -d \
    '{
      "anthropic_version": "vertex-2023-10-16",
      "messages": [{
        "role": "user",
        "content": "Hello!"
      }],
      "max_tokens": 50,
      "stream": true}'
    

    Utilizzo degli strumenti (chiamata di funzione)

    I modelli Anthropic Claude supportano strumenti e chiamate di funzione per migliorare le funzionalità di un modello. Per saperne di più, consulta la panoramica sull'utilizzo degli strumenti nella documentazione di Anthropic.

    Gli esempi riportati di seguito mostrano come utilizzare gli strumenti utilizzando un SDK o il comando curl. Gli esempi cercano ristoranti aperti nelle vicinanze di San Francisco.

    Python

    Per scoprire come installare o aggiornare l'SDK Vertex AI Python, consulta Installare l'SDK Vertex AI Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python.

    L'esempio seguente utilizza endpoint regionali. Per utilizzare l'endpoint globale, vedi Specificare l'endpoint globale.
    # TODO(developer): Vertex AI SDK - uncomment below & run
    # pip3 install --upgrade --user google-cloud-aiplatform
    # gcloud auth application-default login
    # pip3 install -U 'anthropic[vertex]'
    from anthropic import AnthropicVertex
    
    # TODO(developer): Update and un-comment below line
    # PROJECT_ID = "your-project-id"
    
    client = AnthropicVertex(project_id=PROJECT_ID, region="us-east5")
    message = client.messages.create(
        model="claude-3-5-sonnet-v2@20241022",
        max_tokens=1024,
        tools=[
            {
                "name": "text_search_places_api",
                "description": "returns information about a set of places based on a string",
                "input_schema": {
                    "type": "object",
                    "properties": {
                        "textQuery": {
                            "type": "string",
                            "description": "The text string on which to search",
                        },
                        "priceLevels": {
                            "type": "array",
                            "description": "Price levels to query places, value can be one of [PRICE_LEVEL_INEXPENSIVE, PRICE_LEVEL_MODERATE, PRICE_LEVEL_EXPENSIVE, PRICE_LEVEL_VERY_EXPENSIVE]",
                        },
                        "openNow": {
                            "type": "boolean",
                            "description": "whether those places are open for business.",
                        },
                    },
                    "required": ["textQuery"],
                },
            }
        ],
        messages=[
            {
                "role": "user",
                "content": "What are some affordable and good Italian restaurants open now in San Francisco??",
            }
        ],
    )
    print(message.model_dump_json(indent=2))
    # Example response:
    # {
    #   "id": "msg_vrtx_018pk1ykbbxAYhyWUdP1bJoQ",
    #   "content": [
    #     {
    #       "text": "To answer your question about affordable and good Italian restaurants
    #       that are currently open in San Francisco....
    # ...
    

    REST

    L'esempio seguente utilizza endpoint regionali. Per utilizzare l'endpoint globale, vedi Specificare l'endpoint globale.

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

    • LOCATION: una regione che supporta i modelli Anthropic Claude. Per utilizzare l'endpoint globale, consulta Specificare l'endpoint globale.
    • MODEL: il nome del modello da utilizzare.
    • ROLE: Il ruolo associato a un messaggio. Puoi specificare un user o un assistant. Il primo messaggio deve utilizzare il ruolo user. I modelli Claude operano con turni alternati user e assistant. Se il messaggio finale utilizza il ruolo assistant, il contenuto della risposta continua immediatamente dal contenuto di quel messaggio. Puoi utilizzare questo prompt per vincolare una parte della risposta del modello.
    • STREAM: un valore booleano che specifica se la risposta viene trasmessa in streaming o meno. Trasmetti in streaming la risposta per ridurre la percezione della latenza di utilizzo finale. Imposta su true per trasmettere in streaming la risposta e su false per restituire la risposta tutta in una volta.
    • CONTENT: i contenuti, ad esempio il testo, del messaggio user o assistant.
    • MAX_TOKENS: Numero massimo di token che possono essere generati nella risposta. Un token equivale a circa 3,5 caratteri. 100 token corrispondono a circa 60-80 parole.

      Specifica un valore più basso per risposte più brevi e un valore più alto per risposte potenzialmente più lunghe.

    Metodo HTTP e URL:

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

    Corpo JSON della richiesta:

    
    {
      "anthropic_version": "vertex-2023-10-16",
      "max_tokens": MAX_TOKENS,
      "stream": STREAM,
      "tools": [
        {
          "name": "text_search_places_api",
          "description": "Returns information about a set of places based on a string",
          "input_schema": {
            "type": "object",
            "properties": {
              "textQuery": {
                "type": "string",
                "description": "The text string on which to search"
              },
              "priceLevels": {
                "type": "array",
                "description": "Price levels to query places, value can be one of [PRICE_LEVEL_INEXPENSIVE, PRICE_LEVEL_MODERATE, PRICE_LEVEL_EXPENSIVE, PRICE_LEVEL_VERY_EXPENSIVE]",
              },
              "openNow": {
                "type": "boolean",
                "description": "Describes whether a place is open for business at
                the time of the query."
              },
            },
            "required": ["textQuery"]
          }
        }
      ],
      "messages": [
        {
          "role": "user",
          "content": "What are some affordable and good Italian restaurants that are open now in San Francisco??"
        }
      ]
    }
    

    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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict" | Select-Object -Expand Content

    Dovresti ricevere una risposta JSON simile alla seguente.

    Utilizzare Vertex AI Studio

    Per alcuni modelli Anthropic Claude, puoi utilizzare Vertex AI Studio per prototipare e testare rapidamente i modelli di AI generativa nella console Google Cloud . Ad esempio, puoi utilizzare Vertex AI Studio per confrontare le risposte del modello Claude con altri modelli supportati come Google Gemini.

    Per ulteriori informazioni, consulta Guida rapida: invia prompt di testo a Gemini utilizzando Vertex AI Studio.

    Quote e disponibilità per regione di Anthropic Claude

    I modelli Claude hanno quote regionali e, per i modelli che supportano un endpoint globale, una quota globale. La quota è specificata in query al minuto (QPM) e token al minuto (TPM). Il TPM include sia i token di input che di output.

    Per mantenere le prestazioni complessive del servizio e un utilizzo accettabile, le quote massime possono variare in base all'account e, in alcuni casi, l'accesso potrebbe essere limitato. Visualizza le quote del tuo progetto nella pagina Quote e limiti di sistema della console Google Cloud . Devi anche disporre delle seguenti quote:

    • online_prediction_requests_per_base_model e global_online_prediction_requests_per_base_model definiscono la quota di QPM.

    • Per TPM, esistono tre valori di quota che si applicano a modelli particolari:

      • Per i modelli che conteggiano insieme i token di input e output, online_prediction_tokens_per_minute_per_base_model e global_online_prediction_tokens_per_minute_per_base_model definiscono la quota TPM del modello.
      • Per i modelli che conteggiano separatamente i token di input e output, online_prediction_input_tokens_per_minute_per_base_model e global_online_prediction_input_tokens_per_minute_per_base_model definiscono la quota TPM di input e online_prediction_output_tokens_per_minute_per_base_model e global_online_prediction_output_tokens_per_minute_per_base_model definiscono la quota TPM di output.

      Per vedere quali modelli conteggiano i token di input e output separatamente, consulta Quote per modello e regione.

    Token di input

    Il seguente elenco definisce i token di input che possono essere conteggiati ai fini della quota di TPM di input. I token di input conteggiati da ciascun modello possono variare. Per vedere quali token di input vengono conteggiati da un modello, consulta Quote per modello e regione.

    • I token di input includono tutti i token di input, inclusi i token di lettura e scrittura della cache.
    • Token di input non memorizzati nella cache include solo i token di input che non sono stati letti da una cache (token di lettura della cache).
    • Token di scrittura della cache include i token utilizzati per creare o aggiornare una cache.

    Quote per modello e regione

    La tabella seguente mostra le quote predefinite e la lunghezza del contesto supportata per ogni modello in ogni regione.

    Modello Regione Quote Lunghezza del contesto
    Claude Opus 4
    us-east5 200.000
    global endpoint 200.000
    Claude Sonnet 4
    us-east5 200.000
    europe-west1 200.000
    asia-east1 200.000
    global endpoint 200.000
    Claude 3.7 Sonnet
    us-east5 200.000
    europe-west1 200.000
    global endpoint 200.000
    Claude 3.5 Sonnet v2
    us-east5
    • QPM: 90
    • TPM: 540.000 (input e output)
    200.000
    europe-west1
    • QPM: 55
    • TPM: 330.000 (input e output)
    200.000
    global endpoint
    • QPM: 25
    • TPM: 140.000 (input e output)
    200.000
    Claude 3.5 Haiku
    us-east5
    • QPM: 80
    • TPM: 350.000 (input e output)
    200.000
    Claude 3.5 Sonnet
    us-east5
    • QPM: 80
    • TPM: 350.000 (input e output)
    200.000
    europe-west1
    • QPM: 130
    • TPM: 600.000 (input e output)
    200.000
    asia-southeast1
    • QPM: 35
    • TPM: 150.000 (input e output)
    200.000
    Claude 3 Opus
    us-east5
    • QPM: 20
    • TPM: 105.000 (input e output)
    200.000
    Claude 3 Haiku
    us-east5
    • QPM: 245
    • TPM: 600.000 (input e output)
    200.000
    europe-west1
    • QPM: 75
    • TPM: 181.000 (input e output)
    200.000
    asia-southeast1
    • QPM: 70
    • TPM: 174.000 (input e output)
    200.000

    Se vuoi aumentare una delle quote per l'AI generativa su Vertex AI, puoi utilizzare la Google Cloud console per richiedere un aumento di quota. Per scoprire di più sulle quote, consulta Utilizzo delle quote.