Solicitar predicciones con modelos Claude

Puedes usar el SDK de Anthropic o comandos curl para enviar solicitudes al endpoint de Vertex AI con los siguientes nombres de modelo:

  • En el caso de Claude Opus 4.1, usa claude-opus-4-1@20250805
  • En el caso de Claude Opus 4, usa claude-opus-4@20250514
  • En el caso de Claude Sonnet 4, usa claude-sonnet-4@20250514
  • En el caso de Claude 3.7 Sonnet, usa claude-3-7-sonnet@20250219
  • Para Claude 3.5 Sonnet v2, usa claude-3-5-sonnet-v2@20241022
  • En el caso de Claude 3.5 Haiku, usa claude-3-5-haiku@20241022
  • En el caso de Claude 3.5 Sonnet, usa claude-3-5-sonnet@20240620
  • En el caso de Claude 3 Opus, usa claude-3-opus@20240229.
  • En Claude 3 Haiku, usa claude-3-haiku@20240307

Las versiones del modelo Claude de Anthropic deben usarse con un sufijo que empiece por el símbolo @ (como claude-3-7-sonnet@20250219 o claude-3-5-haiku@20241022) para garantizar un comportamiento coherente.

Antes de empezar

Para usar los modelos Claude de Anthropic con Vertex AI, debes seguir estos pasos. La API de Vertex AI (aiplatform.googleapis.com) debe estar habilitada para usar Vertex AI. Si ya tienes un proyecto con la API Vertex AI habilitada, puedes usarlo en lugar de crear uno nuevo.

Comprueba que tienes los permisos necesarios para habilitar y usar modelos de partner. Para obtener más información, consulta Conceder los permisos necesarios.

  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.

    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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

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

  4. Enable the Vertex AI API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  5. 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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

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

  7. Enable the Vertex AI API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  8. Ve a una de las siguientes tarjetas de modelo de Model Garden y haz clic en Habilitar:
  9. Anthropic recomienda que habilites el registro de 30 días de tu actividad de peticiones y respuestas para registrar cualquier uso inadecuado del modelo. Para habilitar el registro, consulta Registrar solicitudes y respuestas.

    Usar el SDK de Anthropic

    Puedes hacer solicitudes a la API de los modelos Claude de Anthropic mediante el SDK de Claude de Anthropic. Para obtener más información, consulta los siguientes artículos:

    Hacer una llamada de streaming a un modelo de Claude con el SDK de Anthropic Vertex

    En el siguiente ejemplo de código se usa el SDK de Anthropic Vertex para hacer una llamada de streaming a un modelo de Claude.

    Python

    Para saber cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la API Python.

    En el siguiente ejemplo se usan puntos finales regionales. Para usar el endpoint global, consulta Especificar el 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.
    

    Hacer una llamada unaria a un modelo Claude con el SDK de Anthropic Vertex

    En el siguiente ejemplo de código se usa el SDK de Anthropic Vertex para hacer una llamada unaria a un modelo de Claude.

    Python

    Para saber cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la API Python.

    En el siguiente ejemplo se usan puntos finales regionales. Para usar el endpoint global, consulta Especificar el 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 un comando curl

    Puedes usar un comando curl para enviar una solicitud al endpoint de Vertex AI. El comando curl especifica qué modelo de Claude admitido quieres usar.

    Las versiones del modelo Claude de Anthropic deben usarse con un sufijo que empiece por el símbolo @ (como claude-3-7-sonnet@20250219 o claude-3-5-haiku@20241022) para garantizar un comportamiento coherente.

    En el siguiente tema se explica cómo crear un comando curl y se incluye un comando curl de ejemplo.

    REST

    Para probar una petición de texto con la API de Vertex AI, envía una solicitud POST al endpoint del modelo de editor.

    En el siguiente ejemplo se usan puntos finales regionales. Para usar el endpoint global, consulta Especificar el endpoint global.

    Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

    • LOCATION: Una región que admita los modelos Claude de Anthropic. Para usar el endpoint global, consulta Especificar el endpoint global.
    • MODEL: el nombre del modelo que quieras usar.
    • ROLE: el rol asociado a un mensaje. Puedes especificar un user o un assistant. El primer mensaje debe usar el rol user. Los modelos de Claude funcionan con turnos alternos de user y assistant. Si el mensaje final usa el rol assistant, el contenido de la respuesta continúa inmediatamente a partir del contenido de ese mensaje. Puedes usarlo para restringir parte de la respuesta del modelo.
    • STREAM: valor booleano que especifica si la respuesta se transmite o no. Transmite tu respuesta para reducir la percepción de latencia del usuario final. Defínelo como true para transmitir la respuesta y false para devolver la respuesta de una vez.
    • CONTENT: el contenido, como el texto, del mensaje user o assistant.
    • MAX_TOKENS: Número máximo de tokens que se pueden generar en la respuesta. Un token tiene aproximadamente 3,5 caracteres. 100 tokens corresponden aproximadamente a entre 60 y 80 palabras.

      Especifica un valor inferior para las respuestas más cortas y un valor superior para las respuestas que puedan ser más largas.

    • TOP_P (Opcional): Top-P cambia la forma en que el modelo selecciona los tokens de salida. Los tokens se seleccionan de más probable a menos probable hasta que la suma de sus probabilidades sea igual al valor de top-P. Por ejemplo, si los tokens A, B y C tienen una probabilidad de 0,3, 0,2 y 0,1, y el valor de top_p es 0.5, el modelo seleccionará A o B como el siguiente token usando la temperatura y excluirá C como candidato.

      Especifica un valor más bajo para obtener respuestas menos aleatorias y un valor más alto para obtener respuestas más aleatorias.

    • TOP_K(Opcional): Top-K cambia la forma en que el modelo selecciona los tokens de salida. Un valor de K superior de 1 significa que el siguiente token seleccionado es el más probable de todos los tokens del vocabulario del modelo (también llamado decodificación voraz), mientras que un valor de K superior de 3 significa que el siguiente token se selecciona de entre los tres tokens más probables mediante la temperatura.

      En cada paso de selección de tokens, se muestrean los K tokens principales con las probabilidades más altas. Después, los tokens se filtran en función de la probabilidad P máxima y el token final se selecciona mediante un muestreo de temperatura.

      Especifica un valor más bajo para obtener respuestas menos aleatorias y un valor más alto para obtener respuestas más aleatorias.

    • TYPE: En el caso de Claude 3.7 Sonnet y modelos de Claude posteriores, para habilitar el modo de reflexión ampliado, especifica enabled.
    • BUDGET_TOKENS: Si habilitas el pensamiento ampliado, debes especificar el número de tokens que puede usar el modelo para su razonamiento interno como parte de la salida. Los presupuestos más elevados pueden permitir un análisis más exhaustivo de los problemas complejos y mejorar la calidad de las respuestas. Debe especificar un valor igual o superior a 1024 pero inferior a MAX_TOKENS.

    Método HTTP y URL:

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

    Cuerpo JSON de la solicitud:

    {
      "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 tu solicitud, elige una de estas opciones:

    curl

    Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

    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

    Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

    $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

    Deberías recibir una respuesta JSON similar a la siguiente.

    Comando curl de ejemplo

    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 herramientas (llamadas de funciones)

    Los modelos Claude de Anthropic admiten herramientas y llamadas a funciones para mejorar las capacidades de un modelo. Para obtener más información, consulta la descripción general del uso de herramientas en la documentación de Anthropic.

    En los siguientes ejemplos se muestra cómo usar herramientas mediante un SDK o un comando curl. Las muestras buscan restaurantes cercanos en San Francisco que estén abiertos.

    Python

    Para saber cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la API Python.

    En el siguiente ejemplo se usan puntos finales regionales. Para usar el endpoint global, consulta Especificar el 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

    En el siguiente ejemplo se usan puntos finales regionales. Para usar el endpoint global, consulta Especificar el endpoint global.

    Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

    • LOCATION: Una región que admita los modelos Claude de Anthropic. Para usar el endpoint global, consulta Especificar el endpoint global.
    • MODEL: el nombre del modelo que se va a usar.
    • ROLE: el rol asociado a un mensaje. Puedes especificar un user o un assistant. El primer mensaje debe usar el rol user. Los modelos de Claude funcionan con turnos alternos de user y assistant. Si el mensaje final usa el rol assistant, el contenido de la respuesta continúa inmediatamente a partir del contenido de ese mensaje. Puedes usarlo para restringir parte de la respuesta del modelo.
    • STREAM: valor booleano que especifica si la respuesta se transmite o no. Transmite tu respuesta para reducir la percepción de latencia del usuario final. Defínelo como true para transmitir la respuesta y false para devolver la respuesta de una vez.
    • CONTENT: el contenido, como el texto, del mensaje user o assistant.
    • MAX_TOKENS: Número máximo de tokens que se pueden generar en la respuesta. Un token tiene aproximadamente 3,5 caracteres. 100 tokens corresponden aproximadamente a entre 60 y 80 palabras.

      Especifica un valor inferior para las respuestas más cortas y un valor superior para las respuestas que puedan ser más largas.

    Método HTTP y URL:

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

    Cuerpo JSON de la solicitud:

    
    {
      "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 tu solicitud, elige una de estas opciones:

    curl

    Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

    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

    Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

    $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

    Deberías recibir una respuesta JSON similar a la siguiente.

    Usar Vertex AI Studio

    En algunos de los modelos Claude de Anthropic, puedes usar Vertex AI Studio para crear prototipos y probar modelos de IA generativa rápidamente en la Google Cloud consola. Por ejemplo, puedes usar Vertex AI Studio para comparar las respuestas del modelo Claude con las de otros modelos compatibles, como Google Gemini.

    Para obtener más información, consulta la guía de inicio rápido para enviar peticiones de texto a Gemini mediante Vertex AI Studio.

    Cuotas y disponibilidad por regiones de Anthropic Claude

    Los modelos de Claude tienen cuotas regionales y, en el caso de los modelos que admiten un punto final global, una cuota global. La cuota se especifica en consultas por minuto (CPM) y tokens por minuto (TPM). TPM incluye tokens de entrada y de salida.

    Para mantener el rendimiento general del servicio y un uso aceptable, las cuotas máximas pueden variar según la cuenta y, en algunos casos, el acceso puede estar restringido. Consulta las cuotas de tu proyecto en la página Cuotas y límites del sistema de la consola de Google Cloud . También debe tener disponibles las siguientes cuotas:

    • online_prediction_requests_per_base_model y global_online_prediction_requests_per_base_model definen tu cuota de QPM.

    • En el caso de TPM, hay tres valores de cuota que se aplican a modelos concretos:

      • En los modelos que cuentan los tokens de entrada y salida juntos, online_prediction_tokens_per_minute_per_base_model y global_online_prediction_tokens_per_minute_per_base_model definen la cuota de TPM del modelo.
      • En los modelos que cuentan los tokens de entrada y salida por separado, online_prediction_input_tokens_per_minute_per_base_model y global_online_prediction_input_tokens_per_minute_per_base_model definen la cuota de TPM de entrada, mientras que online_prediction_output_tokens_per_minute_per_base_model y global_online_prediction_output_tokens_per_minute_per_base_model definen la cuota de TPM de salida.

      Para ver qué modelos cuentan los tokens de entrada y de salida por separado, consulta Cuotas por modelo y región.

    Tokens de entrada

    En la siguiente lista se definen los tokens de entrada que se pueden tener en cuenta para tu cuota de TPM de entrada. Los tokens de entrada que cuenta cada modelo pueden variar. Para ver qué tokens de entrada cuenta un modelo, consulta Cuotas por modelo y región.

    • Tokens de entrada: incluye todos los tokens de entrada, incluidos los tokens de lectura y escritura de caché.
    • Tokens de entrada sin almacenar en caché incluye solo los tokens de entrada que no se han leído de una caché (tokens de lectura de caché).
    • Tokens de escritura de caché: incluye los tokens que se han usado para crear o actualizar una caché.

    Cuotas por modelo y región

    En la siguiente tabla se muestran las cuotas predeterminadas y la longitud de contexto admitida para cada modelo en cada región.

    Modelo Región Cuotas Longitud del contexto
    Claude Opus 4.1
    us-east5 200.000
    global endpoint 200.000
    Claude Opus 4
    us-east5 200.000
    global endpoint 200.000
    Claude Sonnet 4
    us-east5 1.000.000
    europe-west1 1.000.000
    asia-east1 1.000.000
    global endpoint 1.000.000
    Claude 3.7 Sonnet
    us-east5
    • QPM: 55
    • TPM: 500.000 (entrada y salida sin caché)
    200.000
    europe-west1
    • QPM: 40
    • TPM: 300.000 (entrada y salida sin caché)
    200.000
    global endpoint
    • QPM: 35
    • TPM: 300.000 (entrada y salida sin caché)
    200.000
    Claude 3.5 Sonnet v2
    us-east5
    • QPM: 90
    • TPM: 540.000 (entrada y salida)
    200.000
    europe-west1
    • QPM: 55
    • TPM: 330.000 (entrada y salida)
    200.000
    global endpoint
    • QPM: 25
    • TPM: 140.000 (entrada y salida)
    200.000
    Claude 3.5 Haiku
    us-east5
    • QPM: 80
    • TPM: 350.000 (entrada y salida)
    200.000
    europe-west1
    • QPM: 90
    • TPM: 400.000 (entrada y salida)
    200.000
    Claude 3.5 Sonnet
    us-east5
    • QPM: 80
    • TPM: 350.000 (entrada y salida)
    200.000
    europe-west1
    • QPM: 130
    • TPM: 600.000 (entrada y salida)
    200.000
    asia-southeast1
    • QPM: 35
    • TPM: 150.000 (entrada y salida)
    200.000
    Claude 3 Opus
    us-east5
    • QPM: 20
    • TPM: 105.000 (entrada y salida)
    200.000
    Claude 3 Haiku
    us-east5
    • QPM: 245
    • TPM: 600.000 (entrada y salida)
    200.000
    europe-west1
    • QPM: 75
    • TPM: 181.000 (entrada y salida)
    200.000
    asia-southeast1
    • QPM: 70
    • TPM: 174.000 (entrada y salida)
    200.000

    Si quieres aumentar alguna de tus cuotas de IA generativa en Vertex AI, puedes solicitarlo a través de la Google Cloud consola. Para obtener más información sobre las cuotas, consulta el artículo Trabajar con cuotas.