El procesamiento por lotes es un enfoque poderoso para manejar grandes volúmenes de solicitudes de manera eficiente. En lugar de procesar solicitudes una a la vez con respuestas inmediatas, el procesamiento por lotes le permite enviar múltiples solicitudes juntas para su procesamiento asíncrono. Este patrón es particularmente útil cuando:

• Necesita procesar grandes volúmenes de datos
• No se requieren respuestas inmediatas
• Desea optimizar la eficiencia de costos
• Está ejecutando evaluaciones o análisis a gran escala

La API de Lotes de Mensajes es la primera implementación de Anthropic de este patrón.

API de Lotes de Mensajes

La API de Lotes de Mensajes es una forma poderosa y rentable de procesar de manera asíncrona grandes volúmenes de solicitudes de Mensajes. Este enfoque es adecuado para tareas que no requieren respuestas inmediatas, con la mayoría de los lotes terminando en menos de 1 hora mientras se reducen los costos en un 50% y se aumenta el rendimiento.

Puede explorar la referencia de la API directamente, además de esta guía.

Cómo funciona la API de Lotes de Mensajes

Cuando envía una solicitud a la API de Lotes de Mensajes:

1. El sistema crea un nuevo Lote de Mensajes con las solicitudes de Mensajes proporcionadas.
2. El lote se procesa de manera asíncrona, con cada solicitud manejada de forma independiente.
3. Puede sondear el estado del lote y recuperar los resultados cuando el procesamiento haya terminado para todas las solicitudes.

Esto es especialmente útil para operaciones masivas que no requieren resultados inmediatos, como:

• Evaluaciones a gran escala: Procese miles de casos de prueba de manera eficiente.
• Moderación de contenido: Analice grandes volúmenes de contenido generado por usuarios de manera asíncrona.
• Análisis de datos: Genere información o resúmenes para grandes conjuntos de datos.
• Generación masiva de contenido: Cree grandes cantidades de texto para diversos propósitos (p. ej., descripciones de productos, resúmenes de artículos).

Limitaciones de los lotes

• Un Lote de Mensajes está limitado a 100,000 solicitudes de Mensajes o 256 MB de tamaño, lo que se alcance primero.
• El sistema procesa cada lote lo más rápido posible, con la mayoría de los lotes completándose en 1 hora. Podrá acceder a los resultados del lote cuando todos los mensajes se hayan completado o después de 24 horas, lo que ocurra primero. Los lotes expirarán si el procesamiento no se completa dentro de las 24 horas.
• Los resultados del lote están disponibles durante 29 días después de su creación. Después de eso, aún puede ver el Lote, pero sus resultados ya no estarán disponibles para descargar.
• Los lotes están limitados a un Espacio de trabajo. Puede ver todos los lotes (y sus resultados) que se crearon dentro del Espacio de trabajo al que pertenece su clave de API.
• Los límites de velocidad se aplican tanto a las solicitudes HTTP de la API de Lotes como al número de solicitudes dentro de un lote que esperan ser procesadas. Consulte Límites de velocidad de la API de Lotes de Mensajes. Además, el procesamiento puede ralentizarse según la demanda actual y el volumen de sus solicitudes. En ese caso, es posible que vea más solicitudes que expiran después de 24 horas.
• Debido al alto rendimiento y al procesamiento concurrente, los lotes pueden superar ligeramente el límite de gasto configurado de su Espacio de trabajo.

Modelos compatibles

Todos los modelos activos son compatibles con la API de Lotes de Mensajes.

Qué se puede procesar en lotes

Cualquier solicitud que pueda realizar a la API de Mensajes puede incluirse en un lote. Esto incluye:

• Visión
• Uso de herramientas
• Mensajes del sistema
• Conversaciones de múltiples turnos
• Cualquier función beta

Dado que cada solicitud en el lote se procesa de forma independiente, puede mezclar diferentes tipos de solicitudes dentro de un solo lote.

Precios

La API de Lotes ofrece ahorros de costos significativos. Todo el uso se cobra al 50% de los precios estándar de la API.

Cómo usar la API de Lotes de Mensajes

Prepare y cree su lote

Un Lote de Mensajes está compuesto por una lista de solicitudes para crear un Mensaje. La forma de una solicitud individual comprende:

• Un custom_id único para identificar la solicitud de Mensajes
• Un objeto params con los parámetros estándar de la API de Mensajes

Puede crear un lote pasando esta lista al parámetro requests:

curl https://api.anthropic.com/v1/messages/batches \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "requests": [
        {
            "custom_id": "my-first-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hello, world"}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hi again, friend"}
                ]
            }
        }
    ]
}'

En este ejemplo, dos solicitudes separadas se agrupan en un lote para su procesamiento asíncrono. Cada solicitud tiene un custom_id único y contiene los parámetros estándar que usaría para una llamada a la API de Mensajes.

Cuando se crea un lote por primera vez, la respuesta tendrá un estado de procesamiento de in_progress.

{
  "id": "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
  "type": "message_batch",
  "processing_status": "in_progress",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2024-09-24T18:37:24.100435Z",
  "expires_at": "2024-09-25T18:37:24.100435Z",
  "cancel_initiated_at": null,
  "results_url": null
}

Seguimiento de su lote

El campo processing_status del Lote de Mensajes indica la etapa de procesamiento en la que se encuentra el lote. Comienza como in_progress, luego se actualiza a ended una vez que todas las solicitudes en el lote han terminado de procesarse y los resultados están listos. Puede monitorear el estado de su lote visitando la Consola, o usando el endpoint de recuperación.

Sondeo para la finalización del Lote de Mensajes

Para sondear un Lote de Mensajes, necesitará su id, que se proporciona en la respuesta al crear un lote o al listar lotes. Puede implementar un bucle de sondeo que verifique el estado del lote periódicamente hasta que el procesamiento haya terminado:

import anthropic
import time

client = anthropic.Anthropic()

message_batch = None
while True:
    message_batch = client.messages.batches.retrieve(MESSAGE_BATCH_ID)
    if message_batch.processing_status == "ended":
        break

    print(f"Batch {MESSAGE_BATCH_ID} is still processing...")
    time.sleep(60)
print(message_batch)

Listado de todos los Lotes de Mensajes

Puede listar todos los Lotes de Mensajes en su Espacio de trabajo usando el endpoint de lista. La API admite paginación, obteniendo automáticamente páginas adicionales según sea necesario:

import anthropic

client = anthropic.Anthropic()

# Obtiene automáticamente más páginas según sea necesario.
for message_batch in client.messages.batches.list(limit=20):
    print(message_batch)

Recuperación de resultados del lote

Una vez que el procesamiento del lote ha terminado, cada solicitud de Mensajes en el lote tendrá un resultado. Hay 4 tipos de resultados:

Verá un resumen de sus resultados con el request_counts del lote, que muestra cuántas solicitudes alcanzaron cada uno de estos cuatro estados.

Los resultados del lote están disponibles para descargar en la propiedad results_url del Lote de Mensajes, y si el permiso de la organización lo permite, en la Consola. Debido al tamaño potencialmente grande de los resultados, se recomienda transmitir los resultados en lugar de descargarlos todos a la vez.

#!/bin/sh
curl "https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  | grep -o '"results_url":[[:space:]]*"[^"]*"' \
  | cut -d'"' -f4 \
  | while read -r url; do
    curl -s "$url" \
      --header "anthropic-version: 2023-06-01" \
      --header "x-api-key: $ANTHROPIC_API_KEY" \
      | sed 's/}{/}\n{/g' \
      | while IFS= read -r line
    do
      result_type=$(echo "$line" | sed -n 's/.*"result":[[:space:]]*{[[:space:]]*"type":[[:space:]]*"\([^"]*\)".*/\1/p')
      custom_id=$(echo "$line" | sed -n 's/.*"custom_id":[[:space:]]*"\([^"]*\)".*/\1/p')
      error_type=$(echo "$line" | sed -n 's/.*"error":[[:space:]]*{[[:space:]]*"type":[[:space:]]*"\([^"]*\)".*/\1/p')

      case "$result_type" in
        "succeeded")
          echo "Success! $custom_id"
          ;;
        "errored")
          if [ "$error_type" = "invalid_request" ]; then
            # Request body must be fixed before re-sending request
            echo "Validation error: $custom_id"
          else
            # Request can be retried directly
            echo "Server error: $custom_id"
          fi
          ;;
        "expired")
          echo "Expired: $line"
          ;;
      esac
    done
  done

Los resultados estarán en formato .jsonl, donde cada línea es un objeto JSON válido que representa el resultado de una sola solicitud en el Lote de Mensajes. Para cada resultado transmitido, puede hacer algo diferente dependiendo de su custom_id y tipo de resultado. Aquí hay un conjunto de resultados de ejemplo:

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-4-6","content":[{"type":"text","text":"Hello again! It's nice to see you. How can I assist you today? Is there anything specific you'd like to chat about or any questions you have?"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":11,"output_tokens":36}}}}
{"custom_id":"my-first-request","result":{"type":"succeeded","message":{"id":"msg_01FqfsLoHwgeFbguDgpz48m7","type":"message","role":"assistant","model":"claude-opus-4-6","content":[{"type":"text","text":"Hello! How can I assist you today? Feel free to ask me any questions or let me know if there's anything you'd like to chat about."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":34}}}}

Si su resultado tiene un error, su result.error se establecerá en la forma de error estándar.

Cancelación de un Lote de Mensajes

Puede cancelar un Lote de Mensajes que se está procesando actualmente usando el endpoint de cancelación. Inmediatamente después de la cancelación, el processing_status de un lote será canceling. Puede usar la misma técnica de sondeo descrita anteriormente para esperar hasta que la cancelación se finalice. Los lotes cancelados terminan con un estado de ended y pueden contener resultados parciales para las solicitudes que se procesaron antes de la cancelación.

import anthropic

client = anthropic.Anthropic()

message_batch = client.messages.batches.cancel(
    MESSAGE_BATCH_ID,
)
print(message_batch)

La respuesta mostrará el lote en un estado canceling:

{
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message_batch",
  "processing_status": "canceling",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2024-09-24T18:37:24.100435Z",
  "expires_at": "2024-09-25T18:37:24.100435Z",
  "cancel_initiated_at": "2024-09-24T18:39:03.114875Z",
  "results_url": null
}

Uso del almacenamiento en caché de prompts con Message Batches

La API de Message Batches admite el almacenamiento en caché de prompts, lo que le permite reducir potencialmente los costos y el tiempo de procesamiento para las solicitudes por lotes. Los descuentos de precios del almacenamiento en caché de prompts y de Message Batches pueden acumularse, proporcionando un ahorro de costos aún mayor cuando ambas funciones se usan juntas. Sin embargo, dado que las solicitudes por lotes se procesan de forma asíncrona y concurrente, los aciertos de caché se proporcionan en la medida de lo posible. Los usuarios generalmente experimentan tasas de aciertos de caché que van del 30% al 98%, dependiendo de sus patrones de tráfico.

Para maximizar la probabilidad de aciertos de caché en sus solicitudes por lotes:

1. Incluya bloques cache_control idénticos en cada solicitud de Message dentro de su lote
2. Mantenga un flujo constante de solicitudes para evitar que las entradas de caché expiren después de su vida útil de 5 minutos
3. Estructure sus solicitudes para compartir la mayor cantidad posible de contenido en caché

Ejemplo de implementación del almacenamiento en caché de prompts en un lote:

curl https://api.anthropic.com/v1/messages/batches \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "requests": [
        {
            "custom_id": "my-first-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 1024,
                "system": [
                    {
                        "type": "text",
                        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
                    },
                    {
                        "type": "text",
                        "text": "<the entire contents of Pride and Prejudice>",
                        "cache_control": {"type": "ephemeral"}
                    }
                ],
                "messages": [
                    {"role": "user", "content": "Analyze the major themes in Pride and Prejudice."}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 1024,
                "system": [
                    {
                        "type": "text",
                        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
                    },
                    {
                        "type": "text",
                        "text": "<the entire contents of Pride and Prejudice>",
                        "cache_control": {"type": "ephemeral"}
                    }
                ],
                "messages": [
                    {"role": "user", "content": "Write a summary of Pride and Prejudice."}
                ]
            }
        }
    ]
}'

En este ejemplo, ambas solicitudes en el lote incluyen mensajes de sistema idénticos y el texto completo de Orgullo y prejuicio marcado con cache_control para aumentar la probabilidad de aciertos de caché.

Mejores prácticas para un procesamiento por lotes efectivo

Para aprovechar al máximo la API de Batches:

• Supervise el estado del procesamiento por lotes regularmente e implemente la lógica de reintento adecuada para las solicitudes fallidas.
• Use valores custom_id significativos para emparejar fácilmente los resultados con las solicitudes, ya que el orden no está garantizado.
• Considere dividir conjuntos de datos muy grandes en múltiples lotes para una mejor manejabilidad.
• Realice una prueba con una sola forma de solicitud con la API de Messages para evitar errores de validación.

Solución de problemas comunes

Si experimenta un comportamiento inesperado:

• Verifique que el tamaño total de la solicitud por lotes no supere los 256 MB. Si el tamaño de la solicitud es demasiado grande, puede obtener un error 413 request_too_large.
• Compruebe que está usando modelos compatibles para todas las solicitudes en el lote.
• Asegúrese de que cada solicitud en el lote tenga un custom_id único.
• Asegúrese de que hayan pasado menos de 29 días desde la hora created_at del lote (no la hora ended_at del procesamiento). Si han pasado más de 29 días, los resultados ya no serán visibles.
• Confirme que el lote no haya sido cancelado.

Tenga en cuenta que el fallo de una solicitud en un lote no afecta el procesamiento de otras solicitudes.

Almacenamiento y privacidad de lotes

• Aislamiento del espacio de trabajo: Los lotes están aislados dentro del Workspace en el que se crean. Solo pueden ser accedidos por claves API asociadas con ese Workspace, o usuarios con permiso para ver los lotes del Workspace en la Consola.

• Disponibilidad de resultados: Los resultados de los lotes están disponibles durante 29 días después de que se crea el lote, lo que permite tiempo suficiente para la recuperación y el procesamiento.

Retención de datos

El procesamiento por lotes almacena los datos de solicitud y respuesta durante hasta 29 días después de la creación del lote. Puede eliminar un lote de mensajes en cualquier momento después del procesamiento usando el endpoint DELETE /v1/messages/batches/{batch_id}. El procesamiento asíncrono requiere almacenamiento del lado del servidor tanto de las entradas como de las salidas hasta que se complete el lote y se recuperen los resultados.

Para la elegibilidad de ZDR en todas las funciones, consulte API y retención de datos.

Preguntas frecuentes