05 Cerrar el ciclo

Material del facilitador para 05 Cerrar el ciclo.

Duración

~25 minutos en total.

• 5 min — crear y promover los tres registros derivados de producción.
• 5 min — lanzar experimentos emparejados con policy-v1 y policy-v2.
• 5 min — comparar la corrección y calibrar business-policy-adherence.
• 5 min — habilitar la regla protegida de observaciones y reproducir cuatro tipos de métricas.
• 5 min — inspeccionar las pruebas y debatir la reversión, el coste y el siguiente ciclo de feedback.

Los dos experimentos y los evaluators asíncronos pueden durar más que estos bloques. Inicia pronto las ejecuciones, aprovecha la espera para el guion conceptual y ensaya la latencia del proveedor el día anterior.

Preflight del instructor

Ejecuta desde la raíz del laboratorio estas comprobaciones que no modifican datos y verifica antes de la sesión que existe la configuración seleccionada:

cd ClickHouse_Demos/workshops/agent_arena
.venv/bin/python -m scripts.promote_to_golden --help
.venv/bin/python -m scripts.provision_online_evaluators --help
.venv/bin/python -m eval.harness --help
.venv/bin/python -m scripts.verify_online_scores --help

Después confirma que:

• el Módulo 03 tiene una única raíz autoritativa chat_turn con sql-execution-success=true y el Boolean user-thumbs=false;
• la tarea del Módulo 04, creada solo mediante la interfaz en production-investigation-<session>, está completada, su SQL corregido se ejecutó, el ID de traza real está disponible de forma privada y el ID de la tarea de anotación se registró cuando Langfuse lo expone;
• reviewed.json se creará a partir de esa revisión auténtica y no es el fixture sintético versionado;
• WINNER_MODEL, WINNER_PROMPT y WINNER_CONFIG_ID describen al mismo ganador del grupo;
• la conexión LLM de Langfuse agent-arena-openrouter puede acceder al modelo juez configurado y tiene credenciales válidas;
• la salida categórica estructurada del juez acepta exactamente PASS, FAIL y NOT_APPLICABLE, además del razonamiento; y
• el dispatcher del evaluator está operativo y el grupo puede recibir puntuaciones asíncronas.

En cada ensayo, crea un sufijo único y mantén unido el par de referencia/candidato:

export LOOP_RUN_SUFFIX="$(date +%Y%m%d-%H%M%S)"
export BASELINE_RUN_ID="online-loop-baseline-${LOOP_RUN_SUFFIX}"
export CANDIDATE_RUN_ID="online-loop-candidate-${LOOP_RUN_SUFFIX}"

No reutilices los ID de ejecución de otra sesión. El harness añade la versión de política y la configuración; un ID base único impide que los participantes comparen pruebas no relacionadas o sobrescritas parcialmente.

Límite de la anotación manual

La anotación humana del Módulo 04 no se automatiza deliberadamente. Los scripts de runtime no crean la cola, rellenan juicios humanos, introducen la salida corregida, aprueban el elemento ni completan la tarea. Un fixture sintético versionado sirve para un ensayo del instructor cuando no existe una revisión real, pero conserva source=synthetic-reviewed-fixture y no demuestra que se haya completado un ciclo de anotación humana.

Para el itinerario del participante, usa el archivo reviewed.json auténtico e ignorado. La redacción original es una pregunta real procedente del feedback de un usuario. Las otras dos entradas exactas son paráfrasis escritas por el revisor a partir del incidente revisado:

How many active customers do we have?
What is our active customer count right now?
How many customers qualify as active under our business definition?

Las tres conservan la misma traza de origen real y la misma procedencia de anotación. Dilo en voz alta para que nadie confunda un incidente de producción con tres trazas de feedback independientes.

Fiabilidad y procedencia de la promoción

Antes de que el grupo ejecute la promoción, inspecciona reviewed.json sin proyectarlo. Debe contener el SQL corregido exacto de solo lectura, la procedencia de producción exigida y tres ID seguros y únicos. La promoción valida primero todo el lote local; después realiza una lectura autenticada de los metadatos antes de ejecutar en ClickHouse o actualizar elementos del dataset. Se cierra ante un fallo si no puede leer los metadatos y rechaza un ID que colisione con otra procedencia de producción auténtica.

Una promoción auténtica idéntica es idempotente. Un fixture sintético requiere el indicador explícito --synthetic-fixture; no se puede proporcionar como ruta directa ni combinar con reviewed.json. Nunca lo ejecutes después de una promoción real. Si se informa de una colisión, conserva ambos orígenes, investiga el elemento existente del dataset y elige un nuevo ID auditado solo cuando los elementos representen casos revisados realmente distintos.

Regla de experimentos frente a regla de observaciones

Mantén visibles en una diapositiva o pizarra estos dos contextos:

El aprovisionador instala un evaluator general basado en un catálogo, no uno limitado al recuento de clientes. Su catálogo policy-v2 cubre clientes activos, ingresos, conversión de vista a compra y margen bruto; las preguntas no relacionadas deben ser NOT_APPLICABLE.

La fase --business-policy-experiments debe informar online rule enabled=False. Comprueba también la interfaz de reglas de Langfuse como segunda protección. El comando posterior de activación demuestra que existe al menos una puntuación business-policy-adherence limitada al dataset, pero no sustituye la revisión completa de calibración del instructor.

Puertas de calibración

Compara referencia y candidato con los mismos ID de elementos, modelo y prompt. El repositorio contiene 20 preguntas YAML, pero q019 y q020 son ejemplos few-shot reservados, por lo que un proyecto limpio comienza con 18 elementos de experimento y alcanza 21 después de las tres promociones. El proyecto compartido reutilizado que se verificó tenía 22 elementos solo porque quedaba un elemento aprobado antiguo y no relacionado; su nueva ejecución emparejada pasó de 16/22 a 19/22. Tómalo como prueba de verificación condicionada, no como el recuento exigido a los participantes ni como promesa de que los proveedores estocásticos repetirán exactamente todos los agregados.

No habilites la regla a menos que se superen todas las puertas:

• los tres casos prod-active-* pasan de FAIL e incorrectos con policy-v1 a PASS y correctos con policy-v2;
• los casos de ingresos (q005) y conversión (q018) del candidato son PASS;
• un recuento sencillo (q001) es NOT_APPLICABLE;
• se compara por elemento la correctness de todos los elementos preexistentes y no hay ninguna regresión de 1→0;
• la corrección agregada no empeora; y
• todos los elementos de experimento tienen correctness, agent-arena-llm-judge y la puntuación exacta business-policy-adherence con una salida estructurada válida.

Un juez que etiqueta todos los recuentos como PASS no ha superado la calibración, aunque el candidato parezca bueno. Usa la prueba NOT_APPLICABLE para mostrar que determinar la aplicabilidad de una política es una verdadera etapa de clasificación.

Puntuación asíncrona y diagnóstico de puntuaciones ausentes

La evaluación de experimentos y observaciones es asíncrona. El harness espera las puntuaciones requeridas de los experimentos, mientras que scripts.verify_online_scores consulta las puntuaciones de trazas en vivo durante 180 segundos de forma predeterminada. No actualices sin descanso, recrees reglas ni habilites antes de tiempo solo porque haya una puntuación pendiente.

Si no aparecen las puntuaciones:

1. Confirma el nombre exacto esperado. Los experimentos usan business-policy-adherence; las observaciones del servicio usan agent-arena-business-policy-online.
2. Confirma que el dispatcher o worker de ejecución del evaluator está operativo.
3. Comprueba la conexión agent-arena-openrouter y la disponibilidad del modelo juez. Un retraso del proveedor, un límite de solicitudes o una restricción de enrutamiento puede dejar la evaluación pendiente o fallida aunque la respuesta del agente haya funcionado.
4. Confirma que la regla de experimento apunta al dataset arena-golden y que la regla de observación apunta a observaciones raíz chat_turn. El mapeo debe exponer $.question y $.sql.
5. Inspecciona la salida estructurada. Una categoría ausente, ajena a los tres valores permitidos o sin razonamiento supone un fallo de calibración.
6. Si el aprovisionamiento informa de un nombre de regla ambiguo, detente y resuelve en Langfuse los nombres exactos duplicados antes de reintentarlo; no adivines qué duplicado se actualizó.

Conserva las trazas fallidas y las pruebas del evaluator. No conviertas una interrupción del proveedor en un PASS inventado ni omitas la puerta de puntuaciones ausentes.

Guía para la reproducción

Después de habilitar la regla, reinicia explícitamente el servicio con policy-v2 y usa las cuatro preguntas exactas del participante:

How many active customers do we have?
What was revenue in the last 30 days?
What is our view-to-purchase conversion rate for the last 7 days?
How many products are there?

Exige que todas las trazas superen la comprobación operativa. Clientes activos, ingresos y conversión deben tener agent-arena-business-policy-online=PASS; el recuento de productos debe ser NOT_APPLICABLE.

La solicitud de conversión tiene un límite estocástico verificado. Permite como máximo un reintento con la misma configuración, conserva los ID de traza y los resultados de ambos intentos, y detente si ninguno lo supera. Un fallo repetido es una nueva prueba de producción que investigar, no un motivo para repetir hasta que aparezca en verde.

Muestreo, coste y fiabilidad

Las reglas del taller usan un muestreo de 1 para que cada traza válida produzca pruebas visibles. En un volumen de producción, un juez LLM en cada solicitud añade coste del proveedor, consume el límite de solicitudes y puede producir puntuaciones después de la respuesta al usuario. Elige el muestreo según el tráfico, el riesgo de incidentes, el coste y la latencia del evaluator, y la cobertura necesaria. Mantén amplias las comprobaciones operativas deterministas; reserva los juicios semánticos caros para el tráfico y las métricas en los que compensen su coste.

El evaluator sirve para monitorizar, no para autorizar solicitudes. Un juez con retraso no debe bloquear silenciosamente la respuesta del servicio. Envía las puntuaciones ausentes, la deriva de categorías y los desacuerdos entre señales a alertas operativas o a una cola de revisión, de acuerdo con los objetivos de nivel de servicio del sistema.

Reversión y restablecimiento

Si el juez de observaciones produce aprobaciones o fallos falsos, una salida mal formada o un coste o latencia inaceptables después de habilitarlo:

1. Abre Evaluations en Langfuse, busca la regla exacta de observación agent-arena-business-policy-online y cámbiala a disabled.
2. Confirma que las nuevas observaciones chat_turn ya no reciben la puntuación de esa regla online.
3. Mantén activos policy-v2, sql-execution-success y 👍/👎 salvo que sus propias pruebas indiquen lo contrario; desactivar un juez defectuoso no debe reintroducir la política obsoleta conocida.
4. Añade las trazas afectadas a una cola de anotación humana con sufijo, mejora el catálogo o prompt del evaluator y los datos dorados, y repite la calibración con experimentos emparejados antes de volver a habilitarla.

Para detener los servicios locales sin eliminar las pruebas remotas:

scripts/arena.sh stop

scripts/arena.sh down también elimina la base de datos del taller en ClickHouse y el usuario de solo lectura, pero no borra datasets, ejecuciones de experimentos, colas de anotación ni puntuaciones de Langfuse. No lo uses para revertir un evaluator.

Guion: el ciclo sigue abierto

• El evaluator original aprobó porque su contrato era únicamente «el SQL se ejecutó». El 👎 del usuario reveló un fallo de valor ajeno a ese contrato.
• La revisión humana convirtió una señal incierta en un diagnóstico y una corrección probados.
• La procedencia de producción hizo auditable el incidente al incorporarlo al conjunto dorado; las paráfrasis ampliaron la cobertura lingüística sin inventar más trazas de usuarios.
• Los experimentos emparejados aislaron el cambio de política de cualquier cambio de modelo o prompt y probaron el juez general antes de producción.
• Un PASS online no vuelve obsoleto el feedback del usuario. Un futuro agent-arena-business-policy-online=PASS junto con user-thumbs=false es exactamente el tipo de discrepancia que debe reiniciar la investigación.

Puerta de finalización

No cierres el módulo hasta que el grupo pueda mostrar los seis artefactos:

1. la traza de producción con aprobación operativa y señal negativa del usuario;
2. la anotación humana completada y el SQL corregido y verificado;
3. tres elementos dorados con procedencia de producción auténtica;
4. pruebas de referencia y candidato sobre el mismo dataset sin regresiones de corrección en los elementos existentes;
5. pruebas de experimento calibradas para FAIL, PASS y NOT_APPLICABLE; y
6. puntuaciones en vivo habilitadas para clientes activos, ingresos, conversión y un recuento sencillo, mientras 👍/👎 sigue disponible para el próximo ciclo.