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

• Necesitas procesar grandes volúmenes de datos
• No se requieren respuestas inmediatas
• Quieres optimizar la eficiencia en costos
• Estás realizando evaluaciones o análisis a gran escala

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

​

API de Lotes de Mensajes

La API de Lotes de Mensajes es una forma poderosa y rentable de procesar asincrónicamente 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 reducen los costos en un 50% y aumentan el rendimiento.

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

​

Cómo funciona la API de Lotes de Mensajes

Cuando envías 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 forma asíncrona, con cada solicitud manejada independientemente.
3. Puedes consultar 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: Procesa miles de casos de prueba eficientemente.
• Moderación de contenido: Analiza grandes volúmenes de contenido generado por usuarios de forma asíncrona.
• Análisis de datos: Genera insights o resúmenes para grandes conjuntos de datos.
• Generación masiva de contenido: Crea grandes cantidades de texto para varios propósitos (por ejemplo, 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.
• Procesamos cada lote lo más rápido posible, con la mayoría de los lotes completándose dentro de 1 hora. Podrás 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 24 horas.
• Los resultados de los lotes están disponibles durante 29 días después de su creación. Después de eso, aún podrás ver el Lote, pero sus resultados ya no estarán disponibles para descargar.
• Los lotes están limitados a un Espacio de trabajo. Puedes ver todos los lotes —y sus resultados— que fueron creados dentro del Espacio de trabajo al que pertenece tu clave API.
• Los límites de tasa se aplican tanto a las solicitudes HTTP de la API de Lotes como al número de solicitudes dentro de un lote esperando ser procesadas. Ver límites de tasa de la API de Lotes de Mensajes. Además, podemos ralentizar el procesamiento según la demanda actual y tu volumen de solicitudes. En ese caso, podrías ver más solicitudes expirando después de 24 horas.
• Debido al alto rendimiento y procesamiento concurrente, los lotes pueden exceder ligeramente el límite de gasto configurado en tu Espacio de trabajo.

​

Modelos soportados

La API de Lotes de Mensajes actualmente soporta:

• Claude 3.5 Sonnet (claude-3-5-sonnet-20240620 y claude-3-5-sonnet-20241022)
• Claude 3.5 Haiku (claude-3-5-haiku-20241022)
• Claude 3 Haiku (claude-3-haiku-20240307)
• Claude 3 Opus (claude-3-opus-20240229)

​

Qué se puede procesar por lotes

Cualquier solicitud que puedas hacer 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 característica beta

Dado que cada solicitud en el lote se procesa independientemente, puedes mezclar diferentes tipos de solicitudes dentro de un solo lote.

​

Precios

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

​

Cómo usar la API de Lotes de Mensajes

​

Preparar y crear tu 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

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

En este ejemplo, dos solicitudes separadas se procesan por lotes juntas para procesamiento asíncrono. Cada solicitud tiene un custom_id único y contiene los parámetros estándar que usarías 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 tu 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. Puedes monitorear el estado de tu lote visitando la Consola, o usando el endpoint de recuperación:

Puedes consultar este endpoint para saber cuándo ha terminado el procesamiento.

​

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ás un resumen de tus resultados con los 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 tanto en la Consola como en la results_url del Lote de Mensajes. Debido al tamaño potencialmente grande de los resultados, se recomienda transmitir los resultados en lugar de descargarlos todos a la vez.

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, puedes hacer algo diferente dependiendo de su custom_id y tipo de resultado. Aquí hay un ejemplo de conjunto de resultados:

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-3-5-sonnet-20241022","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-3-5-sonnet-20241022","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 tu resultado tiene un error, su result.error se establecerá en nuestra forma de error estándar.

​

Uso del caché de prompts con Lotes de Mensajes

La API de Lotes de Mensajes admite el caché de prompts, lo que permite potencialmente reducir los costos y el tiempo de procesamiento para las solicitudes por lotes. Los descuentos de precios del caché de prompts y los Lotes de Mensajes pueden acumularse, proporcionando aún mayores ahorros en costos cuando ambas características 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 según el mejor esfuerzo. Los usuarios típicamente 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 tus solicitudes por lotes:

1. Incluye bloques cache_control idénticos en cada solicitud de Mensaje dentro de tu lote
2. Mantén un flujo constante de solicitudes para evitar que las entradas de caché expiren después de su vida útil de 5 minutos
3. Estructura tus solicitudes para compartir tanto contenido en caché como sea posible

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

En este ejemplo, ambas solicitudes en el lote incluyen mensajes del 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 el procesamiento por lotes efectivo

Para aprovechar al máximo la API de Lotes:

• Monitorea el estado de procesamiento del lote regularmente e implementa lógica de reintento apropiada para las solicitudes fallidas.
• Usa valores custom_id significativos para hacer coincidir fácilmente los resultados con las solicitudes, ya que el orden no está garantizado.
• Considera dividir conjuntos de datos muy grandes en múltiples lotes para una mejor gestión.
• Prueba una sola forma de solicitud con la API de Mensajes para evitar errores de validación.

​

Solución de problemas comunes

Si experimentas un comportamiento inesperado:

• Verifica que el tamaño total de la solicitud del lote no exceda los 256 MB. Si el tamaño de la solicitud es demasiado grande, puedes obtener un error 413 request_too_large.
• Comprueba que estés usando modelos soportados para todas las solicitudes en el lote.
• Asegúrate de que cada solicitud en el lote tenga un custom_id único.
• Asegúrate de que han pasado menos de 29 días desde el tiempo created_at del lote (no el tiempo ended_at del procesamiento). Si han pasado más de 29 días, los resultados ya no serán visibles.
• Confirma que el lote no ha sido cancelado.

Ten 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 Espacio de trabajo en el que se crean. Solo pueden ser accedidos por claves API asociadas con ese Espacio de trabajo, o usuarios con permiso para ver lotes del Espacio de trabajo en la Consola.

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

​

Preguntas frecuentes

import anthropic

client = anthropic.Anthropic()

message_batch = client.beta.messages.batches.create(
    betas: ["max-tokens-3-5-sonnet-2024-07-15"],
    ...
)