El cómo estructuramos un mensaje determina como de eficientemente podemos procesar las requests. Con una buena estructura puedes hacer debug de los fallos, incluir metadatos para routing y tracking, y mantenernos dentro de los límites de nuestro tier de Service Bus.
Message anatomy
Un message de Service Bus se compone de:
- body: lleva el payload. primary data que quieres transmitir
- app properties: custom key-value metadata. util para enrutar, filtrar y trackear
- system properties: propiedades añadidas por Service Bus o el SDK. Ejemplo
message_id
Serializar prompts y model params
Podemos estructurar el body de un mensaje como JSON payload con todos los campos que necesita el consumer
El campo
message_idse usa para identificar mensajes dentro de Service Bus. Si se activa duplicate detection en la queue, se usa este ID para descargar duplicados. Generar siempre un ID único por mensaje para evitar problemas de duplicación
# Code fragment - focus on creating a message with a JSON payload
import json
import uuid
from azure.servicebus import ServiceBusMessage
request_payload = {
"prompt": "Extract the contract parties and effective date from this document.",
"model": "gpt-4o",
"temperature": 0.1,
"max_tokens": 2000,
"document_id": "doc-2025-0142"
}
message = ServiceBusMessage(
body=json.dumps(request_payload),
content_type="application/json",
message_id=str(uuid.uuid4()),
correlation_id="req-abc-12345",
application_properties={
"model_name": "gpt-4o",
"priority": "standard",
"document_type": "contract"
}
)
Track requests w. correlation IDs
El correlation_id ofrece end-to-end request tracking a lo largo de la pipe. Debemos generar un ID único para cada request, ya que el mismo ID sigue al request desde el producer que lo encola, al consumer que lo procesa y al results store.
Al hacer debug de una inferencia fallida, puedes buscar los logs, colas y result stores por el correlation_id y ver el full lifecycle de la request.
# Code fragment - focus on propagating trace context in application properties
from opentelemetry import trace
current_span = trace.get_current_span()
span_context = current_span.get_span_context()
message = ServiceBusMessage(
body=json.dumps(request_payload),
correlation_id=correlation_id,
application_properties={
"traceparent": f"00-{format(span_context.trace_id, '032x')}-{format(span_context.span_id, '016x')}-01",
"model_name": "gpt-4o"
}
)
Handle large payloads with the claim-check pattern
Service Bus Standard tier soporta solo mensajes de 256 KB - el premium soporta hasta 100 MB.
El claim-check pattern permite separar el payload del mensaje. El producer encola un payload demasiado grande a Azure Blob Storage (u otro storage persistente) y envía al Service Bus un mensaje que contiene solo la blob URI como referencia.
De este modo el body se mantiene pequeño y solo mandamos la URL junto a los metadatos que necesitemos. El processor obtiene la el payload del storage usando la misma URI, y opcionalmente, borra el blob.
Esto también reduce los costes del broker throughput ya que hace las transferencias realmente pequeñas, y se puede usar en el Standard tier
# Code fragment - focus on the claim-check pattern for large payloads
import json
from azure.storage.blob import BlobServiceClient
from azure.servicebus import ServiceBusMessage
# Producer: upload the large payload to Blob Storage
blob_service = BlobServiceClient(
account_url="https://<storage-account>.blob.core.windows.net",
credential=credential
)
container_client = blob_service.get_container_client("documents")
blob_client = container_client.get_blob_client("doc-2025-0142.pdf")
blob_client.upload_blob(large_document_bytes)
# Send a claim-check message with the blob URI
claim_check = {
"blob_uri": f"https://<storage-account>.blob.core.windows.net/documents/doc-2025-0142.pdf",
"document_id": "doc-2025-0142",
"model": "gpt-4o",
"operation": "extract"
}
message = ServiceBusMessage(
body=json.dumps(claim_check),
content_type="application/json",
correlation_id="req-abc-12345",
application_properties={"pattern": "claim-check"}
)
Message TTL
La propiedad time_to_live define el tiempo de expiracion de un mensaje.
Cuando los mensajes expiran se pueden enrutar a la dead-letter queue paras ver los mensajes que no se procesaron a tiempo
# Code fragment - focus on setting time-to-live
from datetime import timedelta
from azure.servicebus import ServiceBusMessage
# Real-time classification: expire after five minutes
urgent_message = ServiceBusMessage(
body=json.dumps(request_payload),
time_to_live=timedelta(minutes=5)
)
# Batch processing: expire after 24 hours
batch_message = ServiceBusMessage(
body=json.dumps(batch_payload),
time_to_live=timedelta(hours=24)
)
Para batch processing donde la latencia no importa tanto es importante poner un TTL grande u omitirlo y usar el default de la queue
Batch messages for throughput
Cuando necesitamos enviar varias requests de a una usamos ServiceBusMessageBatch para agrupar mensajes en una única operación. Batchear reduce el numero de network round trips entre la app y el Service Bus broker.
El SDK administra el batch size automáticamente, asegurando que el total batch no se pasa del maximum size para tu tier.
El
add_message()lanzaMessageSizeExceededErrorcuando el mensaje se pasaría del batch size limit.
# Code fragment - focus on batch message sending
from azure.servicebus import ServiceBusClient, ServiceBusMessage
from azure.servicebus.exceptions import MessageSizeExceededError
import json
with client.get_queue_sender("inference-requests") as sender:
batch = sender.create_message_batch()
for request in pending_requests:
message = ServiceBusMessage(
body=json.dumps(request),
content_type="application/json"
)
try:
batch.add_message(message)
except MessageSizeExceededError:
# Batch is full, send the current batch and start a new one
sender.send_messages(batch)
batch = sender.create_message_batch()
batch.add_message(message)
# Send any remaining messages in the last batch
if len(batch) > 0:
sender.send_messages(batch)