Posts Tagged - durablefunctions

Design reliable workflow steps (Durable Functions)

Durable orchestration preserva el workflow progress, pero la persistencia por si sola no hace que las operaciones externas sean seguras. Los model endpoints pueden hacer throttle de requests, los storage writes pueden sufrir timeouts y un host se pueden reiniciar.

Classify failures before retrying

Los retries ayudan con los fallos que sean efimeros. Consumen recursos por lo que no se reintentar de manera indiscriminada. Clasificar los fallos ayuda a poder resolverlos:

  • Transient failure Aplicar una bounded retry policy
  • Permanent failure Validar early y enrutar el item a un terminal outcome
  • Auth failure Revisar
  • Timeout Compensar el tiempo, escalar o preservar para auditar
  • Business-rule failure Una confidence score baja o un approval rechazado podemos enrutarlo a una workflow branch explicita

Las activity functions deberian raise failures que el orchestrator necesita tratar como errores técnicos. Pueden devolver outputs estructurados para distinguir casos que no se puedan cumplir de consumir retry attempts.

Apply bounded activity retries

Durable Functions pueden hacer schedule de una actividad con una retry policy. El durable runtime graba cada intento y espera entre intentos el solo. Ponemos un maximum attempt count para que un fallo persistente eventualmente llegue al orchestrator.

en python usamos la RetryOptions API

# Code fragment - focus on a bounded activity retry
import azure.durable_functions as df

retry_options = df.RetryOptions(
    first_retry_interval_in_milliseconds=5_000,
    max_number_of_attempts=3,
)

result = yield context.call_activity_with_retry(
    "process_document",
    retry_options,
    {
        "operation_id": operation_id,
        "document_id": document["document_id"],
        "blob_url": document["blob_url"],
    },
)

NO debemos hacer nest de muchos retry layers no controladas. Calcular el maximo numero de retry attempts y tiempo combinado y configurar ambas capas de manera intencional

Enforce durable timeouts

Una retry policy limita los intentos, mientras que un timeout limita cuanto tiempo espera el workflow por un outcome. Durable timers permiten a un orchestrator expresar una deadline sin mantener recursos activos.

Un timer que gane a task_any() no cancela automaticamente una activity que ya ha comenzado. La activity puede todavia finalizar y producir external side effects. Usamos operation record o cancellation flag que el activity comprueba cuando es necesario, haciendo un eventual write idempotente. Diseñamos el workflow para ignorar un late result tras una terminal deadline.

Timeout scopes:

  • Client request timeout Bound one HTTP o SDK call dentro de una activity
  • Activity retry window Bound de attempts y delays para un durable step
  • Workflow step timeout Race durable task against durable timer
  • End-to-end deadline Stop or compensates workflow when the business process exceeds its allowed duration

Make activity side effects idempotent

IMPORTANTE

Durable Functions proveen de at-least-once activity execution. Una activity puede completar un external write y entonces ejecutarse de nuevo si el host falla antes de que el runtime grabe sus resultados.

La idempotencia asegura que repetir las mismas operaciones produce el mismo resultado, en vez de crear duplicados

Derivar una stable operation ID de orchestration input, o crear una con context.new_uuid() y lo pasamos a la activity. Usamos ese ID como database key, blob name, o cualquier otra key.

NUNCA crear operation ID con uuid.uuid4() ya que esto causaria que cada reintento parezca que es trabajo nuevo, cuando en realidad estaríamos creando duplicados

/IMPORTANTE

usamos operation ID como blob name y creamos el resultado solo cuando no exista

# Code fragment - focus on an idempotent result write
import json
from azure.core.exceptions import ResourceExistsError


def persist_result(request: dict) -> dict:
    blob_name = f"results/{request['operation_id']}.json"
    blob_client = results_container.get_blob_client(blob_name)
    payload = json.dumps(request["result"])

    try:
        blob_client.upload_blob(payload, overwrite=False)
        write_status = "Created"
    except ResourceExistsError:
        write_status = "AlreadyExists"

    return {
        "operation_id": request["operation_id"],
        "result_url": blob_client.url,
        "write_status": write_status,
    }

Compoensate completed side effects

Distributed workflows por lo general no pueden hacer rollback de varios servicios como si fuera una transacción. Tenemos que compensar manualmente cualqueir side effect.
Ejemplo: una activity podria marcar como invalid un rejected claim summary, moverlo a un quarantine container, o esconderlo de downstream consumers.

La compensación debe ser idempotente.

schedule compensation when document processing exhausts its retries. La exception se vuelve a relanzar tras compensar para que el orchestrator mantenga un failed terminal status

# Code fragment - focus on compensation after a failed durable step
try:
    result = yield context.call_activity_with_retry(
        "process_document",
        retry_options,
        process_request,
    )
except Exception:
    yield context.call_activity(
        "compensate_document",
        {
            "operation_id": process_request["operation_id"],
            "reason": "ProcessingFailed",
        },
    )
    raise

Expose terminal status and diagnostics

Cada workflow branch deberia llegar a un status como Completed, Rejected, TimedOut, Compensated o Failed.

Incluir IDs para poder trackear requests.

No hacer logging de document contents, prompts, model credentials o tokens.

Read More

Azure Durable Functions

Las Azure Durable Functions permiten que un AI workflow sobreviva a reinicios del host y a long delays. Graban cada operación y permiten hacer un replay para reconstruir el estado local que teníamos antes del reinicio.

Durable workflows

Un durable workflow combina una client function, una orchestrator function y una o más activity functions.

Cuando un cliente comienza una orchestration, el Durable Task runtime graba el input y cada durable action en la orchestration history. El runtime chequea el progreso cuando el orchestrator asigna trabajo o recibe un resultado. Si el host se restartea, el runtime hace replay del history a través del orchestrator hasta que llega a la ultima accion no terminada.

Este modelo hace restore de local variables y workflow position sin que tengas que escribir ningún checkpoint.

Client Function

Una Client function comienza la orquestación, hace query del status, lo temrmina, o envía un evento externo.

Un cliente triggeado por HTTP, normalmente, devuelve una status URL que el caller usa para hacer track de long-running workflows

Orchestrator Function

Una Orchestrator function define la workflow sequence, branching rules, parallel tasks, durable waits y result aggregation.

El orchestrator pone en cola el durable work, en vez de hacer ese trabajo por si mismo

Activity Function

Una Activity function hace una unidad de trabajo no determinista como leer un blob, llamar un model endpoint, enviar una notificacion o hacer update de una BBDD

Son las que pueden ejecutar trabajo no-determinista como language libraries o Azure SDK Clients

Entity Function

Una Entity function administra una pieza de durable state state a través de operaciones explicitas.

Las Entities pueden ayudar a coordinar ese shared state. No son obligatorias. con un orchestrator y activity functions puede ser suficiente.

Keep orchestrator logic deterministic

Un orchestrator puede hacer replay muchas veces durante una workflow instance. Un codigo determinista produce la misma secuencia de durable actions con el mismo orchestration history, para que el runtime pueda hacer match de las acciones que se ha hecho replay para completar el trabajo.

Si hay trabajo no determinista puede causar que el workflow falle o se comporte de manera no predecible.

Puedes usar de manera segura calculos locales, loops sobre stable inputs y resultados devueltos por durable tasks. Usa orchestration context APIs cuando una decision requiere del current time o un identificador unico.

Ejemplos

  • context.current_utc_datetime devuelve un replay-safe time.
  • context.new_uuid() crea un ID determinista para el orchestration history

Evita las siguientes operaciones en orchestrator functions:

  • Direct HTTP, DDBB, file system o Azure SDK calls
  • Model inference o embedding requests
  • Random-number generators y nondeterministic UUID APIs
  • Language-native current time como datetime.now()
  • Block waits como time.sleep()
  • Threads, multiprocessing y async ops que el Durable Task runtime no schedulea
  • Environment-dependent decisions que pueden cambiar entre replays

ejemplo que usa orchestration-safe time para calcular una review deadline. En el replay context.current_utc_datetime devuelve el mismo valor

# Code fragment - focus on deterministic orchestration time
from datetime import timedelta
import azure.durable_functions as df


def orchestrator(
    context: df.DurableOrchestrationContext,
):
    review_deadline = context.current_utc_datetime + timedelta(hours=24)
    review_timer = context.create_timer(review_deadline)

    yield review_timer
    return {"status": "ReviewTimedOut"}

Move model calls e input/output a activities

Activity functions no hacen replay bajo el orchestrator deterministic execution rules. Pueden llamar Azure Services, usar SDK clients, generar random values y ejecutar otras operaciones externas.

Las activities son la unidad que las Durable Functions distribuyen across workers disponibles y se reintentan segun la orchestration policy.

La separación importa para AI workloads ya que las respuestas de los modelos son no deterministas y las llamadas a servicios pueden ser lentas o tener fallos transientes. El orchestrator pasa una request estable a una activity y hace record solo del activity result.

el orchestrator hace schedule de una actividad con una compact blob reference. La activity entonces lee el documento y llama al model client configurado

# Code fragment - focus on orchestration and activity boundaries
import azure.durable_functions as df

app = df.DFApp()


@app.orchestration_trigger(context_name="context")
def document_orchestrator(
    context: df.DurableOrchestrationContext,
):
    document = context.get_input()
    result = yield context.call_activity("analyze_document", document)
    return result


@app.activity_trigger(input_name="document")
def analyze_document(document: dict) -> dict:
    document_text = read_blob_text(document["blob_url"])
    model_result = call_classification_model(document_text)
    return {
        "document_id": document["document_id"],
        "category": model_result["category"],
        "confidence": model_result["confidence"],
    }

Llamar read_blob_text() o call_classification_model() desde el orchestrator violawria la regla de ejecucion determinista. Mantener esas operaciones en analyze_document mantiene efectos externos fuera del replaying orchestrator code y permite aplicar una retry policy especifica al external work.
Activity functions tienen at-least-once execution semantics, por lo que sus efectos deben ser idempotentes.

Control data in orchestration history

Durable Functions serializan orchestration inputs, activity inputs / outputs y otros workflow state en el durable store configurado. Payloads grandes incrementar el coste de las operaciones, replay time, memory use. Evitar pasar documentos completos, imagenes, prompts, embeddings, etc, a través de una orchestration.

Para nuevas Durtable Function Apps, se recomienda Durable Task Scheduler como el managed storage provider.

Guarda datos grandes en un servicio apropiado como Durable Task Scheduler o Azure Blob Storage. Pasa una referencia y los metadatos minimos necesarios para workflow decisiones como document ID, blob URL, content type, confidence score, etc. Una activity puede leer el source content y escribir un resultado detallado, mientras que el orchestrator recibe solo el status y los campos requeridos para su next branch.

Considerar el impacto de seguridad de la durable data. No poner secretos en orchestration inputs u outputs. Usa managed identities para credenciales.

Account for replay in telemetry

El replay puede ejecutar un orchestrator’s logging más de una vez. Los mensajes duplicados pueden llevar a confusión. Usar replay-safe logging support.

# Code fragment - focus on replay-aware orchestrator logging
import logging

if not context.is_replaying:
    logging.info(
        "Scheduling document analysis for orchestration %s",
        context.instance_id,
    )

Read More

Process independent work with fan-out/fan-in (Durable Functions)

El Durable Functions fan-out/fan-in pattern se usa para operaciones independientes que no tienen por que ejecutarse secuencialmente.

Fan-out/fan-in permite hacer schedule de esas operaciones de manera simultánea, esperar a que el grupo acabe y combinar los resultados.

Este patrón puede reducir batch latency mientras que mantiene la coordinacion y los checkpoints en el durable runtime.

Identify independent work

Fan-out/fan-in funciona mejor cuando cada work item se puede completar sin cambiar los inputs ed otro item (es completamente independiente).

Algunos ejemplos son extraer texto de varios documentos, clasificar imágenes, generar embeddings para chunks separados.

La fase fan-out distribuye estas tasks a lo largo de activity executions, mientras que la fase fan-in le da al orchestrator un result set completo para la siguiente decisión.

Schedule tasks before awaiting results

El python durable functions SDK representa activity calls como durable tasks. Para fan-out, el orchestrator crea una task para cada referencia work-item y guarda las tasks en una lista. Entonces entrega context.task_all(tasks para hacer wait de cada scheduled activity y recibir los resultados.

schedule una activity por document reference. Cada activity puede leer su source blob, llamar al AI model requerido y escribir un output detallado al storage. El orchestrator recibe compact fields que puede agregar sin poner large model responses en orchestration history

# Code fragment - focus on fan-out/fan-in coordination
import azure.durable_functions as df


def orchestrator(
    context: df.DurableOrchestrationContext,
):
    batch = context.get_input()
    tasks = []

    for document in batch["documents"]:
        tasks.append(
            context.call_activity(
                "process_document",
                {
                    "batch_id": batch["batch_id"],
                    "document_id": document["document_id"],
                    "blob_url": document["blob_url"],
                },
            )
        )

    results = yield context.task_all(tasks)

    return {
        "batch_id": batch["batch_id"],
        "processed": len(results),
        "requires_review": [
            item["document_id"]
            for item in results
            if item["confidence"] < 0.80
        ],
    }

El orden de las listas devueltas hace match con la task list, aun cuando las activities acaban en un orden distinto.
Una activity fallida causa que la task_all operation haga raise de un task failure al orchestrator. El orchestrator puede hace catch de ese error y puede elegir si falla el batch entero, compensa el trabajo completado o lo marca para investigación

Design compact fan-in results

fan-in se ejecuta dentro de una orchestrator instance, por lo que la agregación se debe mantener determinista y lightweight. Puedes contar status, seleccionar documentos por debajo de un confidence threshold o construir un summary compacto para activity outputs.

Las expensive transformations y external writes pertenecen a otra acticity

Una document-processing activity podria devolver los siguientes campos:

  • Document ID: correlacionar resultado con original work item
  • Status: success/validation failure
  • Confidence: soporta deterministic routing a un approval step
  • Result URL: apunta al full output almacenado en Blob Storage o BBDD
  • Operation ID: para idempotent updates y trazas

No devuelvas extracted text, full model prompts, large arrays of embeddings. Estos valores expanden la orchestration history y las Durable Functions los tienen que cargar durante el replay. Escribe estos resultados desde la activity a un external store y devuelve una referencia.

Si la agregacion en si misma requiere mucha CPU, memoria, IO ops - haz schedule de una AggregateResults activity tras task_all. El orchestrator puede pasar compact result references a esa activity y esperar un final summary. Este diseño preserva un small orchestration history mientras permite la agregacion del trabajo par usar normal function execution.

Bound parallel work

Un batch con miles de documentos puede hacer schedule de un gran numero de activities de a una. El durable runtime puede grabar esas tasks, pero el historial resultado y fan-in work puede volverse muy caro.
Asi mismo, un burst de trabajo puede exceder los rate limits de los modelos.

Puedes dividir inputs grandes en bounded batches y procesar los batches de uno en uno. Cada batch ejecuta sus items en paralelo, pero el workflow espera antes de asignar el siguiente grupo.

# Code fragment - focus on bounded fan-out
batch_size = 20
all_results = []

for start in range(0, len(documents), batch_size):
    current_batch = documents[start : start + batch_size]
    tasks = [
        context.call_activity("process_document", document)
        for document in current_batch
    ]
    batch_results = yield context.task_all(tasks)
    all_results.extend(batch_results)

Los Bounded Batches limitan el trabajo asignado pero no ofrecen un limite preciso de requests-por-segundo.

Scale aggregation with sub-orchestration

Un orchestrator ejecuta el fan-in step en un worker a la vez. Un solo flat fan-in puede convertirse en un cuello de botella cuando tiene que cargar y agregar muchos resultados. Sub-orchestrations te permiten crear una jerarquia en la cual child orchestration procesan particiones separadas y un padre combina sus summaries.

Por ejemplo un parent orchestration divide un claim archive grande por policy o mes.
Cada child orchestration hace fan out de su propio document activities y devuelve counts + result locations.
El parent entonces agregar esos summaries en vez de cada document result individual.

Este approach reduce la cantidad de estado manejada por una orquestacion y da a cada particion su estado independiente.

La sub-orquestacion junta coordinacion y history records, por lo que no son necesarios para small batches. Comienza con un fan-out/fan-in pattern, mide la ejecucion y el replay behavior, e introduce partitioning cuando el batch size o el coste de agregacion justifique la estructura añadida.

Read More

Coordinate human approval with external events (Durable Functions)

Algunos workflwos requieren de input por parte de una persona u otro sistema cuando el proceso automatizado termina. Las Durable Functions pueden suspender una orchestration mientras espera por un external event, y entonces recomenzar desde su durable state cuando ese event llega.

La orchestration suspendida no mantiene un worker ni una invocacion de funcion activa. Esto se recomienda para approval windows de horas a dias.

Model an approval as an external event

Un external event es un one-way message, con nombre, enviado a una instancia especifica de orquestacion. El orchestrator crea una durable task con wait_for_external_event() y cede esa task cuando necesita del event data.

Las Durable Functions extensions persisten un evento que llega al orchestrator antes de que este comience la espera, para que el workflow pueda consumir ese buffered event más tarde.

Para un document-processing workflow, una activity primero crea un approval record y notifica al adjuster asignado. El orchestrator entonces espera a un evento ApprovalResponse que contiene la decision y la identidad del reviewer.

Diseña el event contract alrededor de workflow decisions, en vez de una user-interface action. Un approval payload compacto puede contener:

  • Decision Un valor fijo como Approved o Rejected
  • Reviewer ID para auditar y correlacionar
  • Document ID el work item que el reviewer ha evaluado
  • Approval version Un valor que ayuda al workflow a rechazar una respuesta para una review request viaje
  • Comment reference URL para cargar detalles, almacenado fuera del flujo

Combina un external event con un durable timer

Un approval process necesita una deadline para que un workflow no espere de manera infinita.
Usa context.create_timer() con context.current_utc_datetime. NO USAR time.sleep() u otras APIs bloqueantes. Un durable timer graba el deadline en la orchestration history y no requiere que el worker se mantenga activo mientras no hay trabajo.

Patrón human interaction - es una carrera entre el event task contra el timer task con context.task_any(). Si el evento gana, el orchestrator lee el event result y cancela el timer. Si el timer gana, el orchestrator sigue el timeout path.

ejemplo que implementa approval, rejection y timeout outcomes. Usa un input estable y orchestration-safe time para el replay

# Code fragment - focus on the event-and-timer race
from datetime import timedelta
import azure.durable_functions as df


def orchestrator(
    context: df.DurableOrchestrationContext,
):
    review_request = context.get_input()

    yield context.call_activity("notify_approver", review_request)

    approval_task = context.wait_for_external_event("ApprovalResponse")
    deadline = context.current_utc_datetime + timedelta(hours=24)
    timeout_task = context.create_timer(deadline)

    winner = yield context.task_any([approval_task, timeout_task])

    if winner == approval_task:
        if not timeout_task.is_completed:
            timeout_task.cancel()

        response = approval_task.result
        if response["decision"] == "Approved":
            return {"status": "Approved"}

        return {"status": "Rejected"}

    return {"status": "TimedOut"}

Una external event task no requiere cancelación después de que el timer gane. Si el workflow puede recibir otro evento con el mismo nombre despues, definimos si la app ignora ese evento tardia, lo graba para auditarlo, o lo enruta hacia orta orchestration instance nueva.

Send an event to the correct instance

Una client function usa las Durable Functions orchestration client binding para enviar un evento. El cliente debe conocer el orchestration instance ID o usar el mismo event name que el orchestrator espera. Los event names deberian ser estables.

fragmento que muestra Durable Function call tras un OK de app-specific auth y validacion. El endpoint devuelve 202 ya que el event delivery retoma la orchestration de manera asincrona

# Code fragment - focus on raising an external event
import json
import azure.functions as func
import azure.durable_functions as df

app = df.DFApp(http_auth_level=func.AuthLevel.FUNCTION)


@app.route(route="approvals/{instance_id}", methods=["POST"])
@app.durable_client_input(client_name="client")
async def submit_approval(
    req: func.HttpRequest,
    client: df.DurableOrchestrationClient,
) -> func.HttpResponse:
    instance_id = req.route_params["instance_id"]
    response = req.get_json()

    reviewer = authorize_reviewer(req)
    validated_event = validate_approval_response(response, reviewer)

    await client.raise_event(
        instance_id,
        "ApprovalResponse",
        validated_event,
    )

    return func.HttpResponse(
        json.dumps({"status": "Accepted"}),
        status_code=202,
        mimetype="application/json",
    )

Handle duplicate and out-of-order responses

Diferentes servicios pueden mandar la misma decision mas de una vez. External events tienen at-least-once delivery guarantee, por lo que restarts, escalado o fallos pueden producir deliveries duplicadas. Sigue siendo nuestra responsabilidad garantizar idempotencia ya que un evento duplicado no debería crear un segundo approval record o repetir una operación downstream.

Podemos incluir un ID estable para approvals y que una actividad de manera atómica compruebe este ID para reportar si la operación ya existe.

Respuestas out-of-order requieren de una policy explicita. Evitar usar solo el orden de llegada cuando hay múltiples sistemas que pueden mandar eventos.

Choose a timeout outcome

Un timeout es un outcome pero no necesariamente un fallo técnico. El orchestrator debe elegir un terminal path y hacer schedule de cualquier update requerida, a través de activities.

Read More