Solicitar previsões com modelos de Claude

É possível usar o SDK da Anthropic ou comandos curl para enviar solicitações ao endpoint da Vertex AI usando os seguintes nomes de modelos:

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

As versões do modelo Anthropic Claude precisam ser usadas com um sufixo que comece com um símbolo @ (como claude-3-7-sonnet@20250219 ou claude-3-5-haiku@20241022) para garantir um comportamento consistente.

Antes de começar

Para usar os modelos do Anthropic Claude com a Vertex AI, siga as etapas abaixo. A API Vertex AI (aiplatform.googleapis.com) precisa estar ativada para usar a Vertex AI. Se você já tiver um projeto existente com a API do Vertex AI ativada, poderá usar esse projeto em vez de criar um novo.

Verifique se você tem as permissões necessárias para ativar e usar modelos do parceiro. Para mais informações, consulte Conceder as permissões necessárias.

  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. Acesse um dos seguintes cards de modelo do Model Garden e clique em Ativar:
  9. A Anthropic recomenda que você ative o registro em log de 30 dias da sua atividade de solicitação e conclusão para registrar qualquer uso indevido do modelo. Para ativar a geração de registros, consulte [Registrar solicitações e respostas][logging].
  10. Usar o SDK do Anthropic

    É possível fazer solicitações de API para os modelos do Anthropic Claude usando o SDK do Anthropic Claude (link em inglês). Para saber mais, consulte:

    Fazer uma chamada de streaming para um modelo Claude usando o SDK Vertex Anthropic

    O exemplo de código a seguir usa o SDK Vertex Anthropic para fazer uma chamada de streaming para um modelo do Claude.

    Python

    Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python.

    O exemplo a seguir usa endpoints regionais. Para usar o endpoint global, consulte Especificar o endpoint global.
    # 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.
    

    Fazer uma chamada unária para um modelo Claude usando o SDK Vertex Anthropic

    O exemplo de código a seguir usa o SDK Vertex Anthropic para realizar uma chamada unária para um modelo do Claude.

    Python

    Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python.

    O exemplo a seguir usa endpoints regionais. Para usar o endpoint global, consulte Especificar o endpoint global.
    # 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...
    #   ...
    

    Usar um comando curl

    É possível usar um comando curl para fazer uma solicitação ao endpoint da Vertex AI. O comando curl especifica qual modelo do Claude compatível você quer usar.

    As versões do modelo Anthropic Claude precisam ser usadas com um sufixo que comece com um símbolo @ (como claude-3-7-sonnet@20250219 ou claude-3-5-haiku@20241022) para garantir um comportamento consistente.

    O tópico a seguir mostra como criar um comando curl e inclui uma amostra do comando curl.

    REST

    Para testar um prompt de texto usando a API Vertex AI, envie uma solicitação POST para o endpoint do modelo do editor.

    O exemplo a seguir usa endpoints regionais. Para usar o endpoint global, consulte Especificar o endpoint global.

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

    • LOCATION: uma região compatível com modelos do Anthropic Claude. Para usar o endpoint global, consulte Especificar o endpoint global.
    • MODEL: o nome do modelo que você quer usar.
    • ROLE: o papel associado a uma mensagem. É possível especificar user ou assistant. A primeira mensagem precisa usar o papel user. Os modelos de Claude funcionam com voltas alternadas de user e assistant. Se a mensagem final usar o papel assistant, o conteúdo da resposta continuará imediatamente a partir do conteúdo dessa mensagem. É possível usar isso para restringir parte da resposta do modelo.
    • STREAM: um booleano que especifica se a resposta será transmitida ou não. Transmita sua resposta para reduzir a percepção de latência do uso final. Defina como true para transmitir a resposta e false para retornar a resposta de uma só vez.
    • CONTENT: o conteúdo, como texto, da mensagem user ou assistant.
    • MAX_TOKENS: número máximo de tokens que podem ser gerados na resposta. Um token tem aproximadamente 3,5 caracteres. 100 tokens correspondem a cerca de 60 a 80 palavras.

      Especifique um valor mais baixo para respostas mais curtas e um valor mais alto para respostas potencialmente mais longas.

    • TOP_P (opcional): o Top-P muda a forma como o modelo seleciona tokens para saída. Os tokens são selecionados do mais provável para o menos provável até que a soma das probabilidades seja igual ao valor do top-P. Por exemplo, se os tokens A, B e C tiverem uma probabilidade de 0,3, 0,2 e 0,1 e o valor de top-P for 0.5, o modelo selecionará A ou B como token seguinte usando temperatura e exclui C como candidato.

      Especifique um valor mais baixo para respostas menos aleatórias e um valor mais alto para respostas mais aleatórias.

    • TOP_K(opcional): o Top-P muda a forma como o modelo seleciona tokens para saída. Um top-K de 1 significa que o próximo token selecionado é o mais provável entre todos os tokens no vocabulário do modelo (também chamado de decodificação gananciosa), enquanto um top-K de 3 significa que o próximo token está selecionado entre os três tokens mais prováveis usando a temperatura.

      Para cada etapa da seleção de tokens, são amostrados os tokens top-K com as maiores probabilidades. Em seguida, os tokens são filtrados com base no valor de top-P com o token final selecionado por meio da amostragem de temperatura.

      Especifique um valor mais baixo para respostas menos aleatórias e um valor mais alto para respostas mais aleatórias.

    • TYPE: para o Claude 3.7 Sonnet e modelos do Claude mais recentes, especifique enable para ativar o modo de pensamento estendido.
    • BUDGET_TOKENS: se você ativar o pensamento estendido, especifique o número de tokens que o modelo pode usar para o raciocínio interno como parte da saída. Orçamentos maiores permitem análises mais completas para problemas complexos e melhoram a qualidade da resposta. É necessário especificar um valor maior ou igual a 1024, mas menor que MAX_TOKENS.

    Método HTTP e URL:

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

    Corpo JSON da solicitação:

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

    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 a seguir:

    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

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

    $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

    Você receberá uma resposta JSON semelhante a seguinte.

    Exemplo de comando curl

    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}'
    

    Uso de ferramentas (chamadas de função)

    Os modelos do Anthropic Claude oferecem suporte a ferramentas e chamadas de função para melhorar os recursos de um modelo. Para mais informações, consulte a Visão geral do uso da ferramenta na documentação do Anthropic.

    Os exemplos a seguir demonstram como usar ferramentas com um SDK ou o comando curl. Os exemplos pesquisam restaurantes por perto em São Francisco que estão abertos.

    Python

    Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python.

    O exemplo a seguir usa endpoints regionais. Para usar o endpoint global, consulte Especificar o endpoint global.
    # 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

    O exemplo a seguir usa endpoints regionais. Para usar o endpoint global, consulte Especificar o endpoint global.

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

    • LOCATION: uma região compatível com modelos do Anthropic Claude. Para usar o endpoint global, consulte Especificar o endpoint global.
    • MODEL: o nome do modelo a ser usado.
    • ROLE: o papel associado a uma mensagem. É possível especificar user ou assistant. A primeira mensagem precisa usar o papel user. Os modelos de Claude funcionam com voltas alternadas de user e assistant. Se a mensagem final usar o papel assistant, o conteúdo da resposta continuará imediatamente a partir do conteúdo dessa mensagem. É possível usar isso para restringir parte da resposta do modelo.
    • STREAM: um booleano que especifica se a resposta será transmitida ou não. Transmita sua resposta para reduzir a percepção de latência do uso final. Defina como true para transmitir a resposta e false para retornar a resposta de uma só vez.
    • CONTENT: o conteúdo, como texto, da mensagem user ou assistant.
    • MAX_TOKENS: número máximo de tokens que podem ser gerados na resposta. Um token tem aproximadamente 3,5 caracteres. 100 tokens correspondem a cerca de 60 a 80 palavras.

      Especifique um valor mais baixo para respostas mais curtas e um valor mais alto para respostas potencialmente mais longas.

    Método HTTP e URL:

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

    Corpo JSON da solicitação:

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

    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 a seguir:

    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

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

    $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

    Você receberá uma resposta JSON semelhante a seguinte.

    Usar o Vertex AI Studio

    Para alguns modelos do Anthropic Claude, é possível usar o Vertex AI Studio para criar protótipos e testar rapidamente modelos de IA generativa no console Google Cloud . Por exemplo, você pode usar o Vertex AI Studio para comparar as respostas do modelo Claude com outros modelos compatíveis, como o Gemini do Google.

    Para mais informações, consulte Guia de início rápido: envie comandos de texto para o Gemini usando o Vertex AI Studio.

    Cotas e disponibilidade regional do Anthropic Claude

    Os modelos do Claude têm cotas regionais e, para modelos que oferecem suporte a um endpoint global, uma cota global. A cota é especificada em consultas por minuto (QPM) e tokens por minuto (TPM). O TPM inclui tokens de entrada e saída.

    Para manter o desempenho geral do serviço e o uso aceitável, as cotas máximas podem variar de acordo com a conta e, em alguns casos, o acesso pode ser restrito. Consulte as cotas do seu projeto na página Cotas e limites do sistema no console do Google Cloud . Você também precisa ter as seguintes cotas disponíveis:

    • online_prediction_requests_per_base_model e global_online_prediction_requests_per_base_model definem sua cota de QPM.

    • Para o TPM, há três valores de cota que se aplicam a modelos específicos:

      • Para modelos que contam tokens de entrada e saída juntos, online_prediction_tokens_per_minute_per_base_model e global_online_prediction_tokens_per_minute_per_base_model definem a cota de TPM do modelo.
      • Para modelos que contam tokens de entrada e saída separadamente, online_prediction_input_tokens_per_minute_per_base_model e global_online_prediction_input_tokens_per_minute_per_base_model definem a cota de TPM de entrada, e online_prediction_output_tokens_per_minute_per_base_model e global_online_prediction_output_tokens_per_minute_per_base_model definem a cota de TPM de saída.

      Para saber quais modelos contam tokens de entrada e saída separadamente, consulte Cotas por modelo e região.

    Tokens de entrada

    A lista a seguir define os tokens de entrada que podem ser contabilizados na sua cota de TPM de entrada. Os tokens de entrada que cada modelo conta podem variar. Para saber quais tokens de entrada um modelo conta, consulte Cotas por modelo e região.

    • Os tokens de entrada incluem todos os tokens de entrada, incluindo tokens de leitura e gravação de cache.
    • Tokens de entrada não armazenados em cache inclui apenas os tokens de entrada que não foram lidos de um cache (tokens de leitura de cache).
    • Os tokens de gravação em cache incluem tokens usados para criar ou atualizar um cache.

    Cotas por modelo e região

    A tabela a seguir mostra as cotas padrão e o tamanho de contexto compatível para cada modelo em cada região.

    Modelo Região Cotas Tamanho do contexto
    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
    • QPM: 55
    • TPM: 500.000 (entrada e saída sem cache)
    200.000
    europe-west1
    • QPM: 40
    • TPM: 300.000 (entrada e saída sem cache)
    200.000
    global endpoint
    • QPM: 35
    • TPM: 300.000 (entrada e saída sem cache)
    200.000
    Claude 3.5 Sonnet v2
    us-east5
    • QPM: 90
    • TPM: 540.000 (entrada e saída)
    200.000
    europe-west1
    • QPM: 55
    • TPM: 330.000 (entrada e saída)
    200.000
    global endpoint
    • QPM: 25
    • TPM: 140.000 (entrada e saída)
    200.000
    Claude 3.5 Haiku
    us-east5
    • QPM: 80
    • TPM: 350.000 (entrada e saída)
    200.000
    Claude 3.5 Sonnet
    us-east5
    • QPM: 80
    • TPM: 350.000 (entrada e saída)
    200.000
    europe-west1
    • QPM: 130
    • TPM: 600.000 (entrada e saída)
    200.000
    asia-southeast1
    • QPM: 35
    • TPM: 150.000 (entrada e saída)
    200.000
    Claude 3 Opus
    us-east5
    • QPM: 20
    • TPM: 105.000 (entrada e saída)
    200.000
    Claude 3 Haiku
    us-east5
    • QPM: 245
    • TPM: 600.000 (entrada e saída)
    200.000
    europe-west1
    • QPM: 75
    • TPM: 181.000 (entrada e saída)
    200.000
    asia-southeast1
    • QPM: 70
    • TPM: 174.000 (entrada e saída)
    200.000

    Para aumentar alguma das suas cotas de IA generativa na Vertex AI, use o console Google Cloud para solicitar um aumento de cota. Para saber mais sobre cotas, consulte Trabalhar com cotas.