Skip to content
AI Agent Eval Harness

ADR-0025: Proveedor de reordenamiento gestionado y determinismo de evaluación

  • Estado: Accepted
  • Fecha: 2026-06-08
  • Responsables de la decisión: Waldemar Szemat

Contexto y planteamiento del problema

Section titled “Contexto y planteamiento del problema”

La canalización de recuperación híbrida (ADR-0022) termina reescalando el conjunto de candidatos fusionados con un reordenador cross-encoder. Ejecutar ese cross-encoder de forma local lo convierte en el único costo dominante de un turno: en el host de producción (Google Cloud Run, con una asignación pequeña de CPU y escalado a cero), la medición por nodo cableada por el stack de observabilidad (ADR-0006) registró el reordenador local como la abrumadora mayoría de la latencia de un turno en caliente, y mantiene un modelo grande residente en memoria. Un encuadre anterior había dejado fuera los reordenadores de pago por motivos de costo; una vez que el reordenador local se convirtió en el defecto de latencia principal, esa compensación dejó de sostenerse.

De ahí surgen dos preguntas. Primera, ¿qué reordenador preserva - o mejora - la calidad de recuperación mientras retira la inferencia local del turno? Segunda, ¿cómo se mantiene determinista la compuerta de evaluación (ADR-0003) una vez que un reordenador gestionado y respaldado por red se sitúa en la ruta de recuperación, sin llamar jamás a una API de pago dentro de la compuerta y detectando al mismo tiempo la deriva del modelo del proveedor?

Impulsores de la decisión

Section titled “Impulsores de la decisión”
  • Devolver el turno en caliente por debajo del presupuesto de latencia sin sacrificar la calidad de recuperación; el reordenamiento debe ser subsegundo y alojado.
  • Paridad de ranking multilingüe: el demo sirve en / es-419 / pt-BR, así que el reordenador debe clasificar bien los pares consulta-documento no en inglés.
  • $0 a escala de demo, sin sorpresas de cuota.
  • La compuerta de evaluación offline (ADR-0003) se mantiene determinista, offline y gratuita: ninguna llamada en vivo a una API de pago dentro de la compuerta.
  • Reversible y segura ante degradación, honrando el contrato de degradación elegante de la canalización híbrida (ADR-0022).

Opciones consideradas

Section titled “Opciones consideradas”
  • Un reordenador gestionado fuera de la caja (Voyage rerank-2.5), seleccionado por turno (elegida).
  • Mantener el cross-encoder local y aceptar la latencia dominante del turno en caliente.
  • Cuantizar / compilar a ONNX el modelo local para acelerar la inferencia en CPU.
  • Un proveedor gestionado distinto (por ejemplo Cohere o Jina) fuera de la caja.

Resultado de la decisión

Section titled “Resultado de la decisión”

Opción elegida: trasladar el reordenamiento a un reordenador gestionado fuera de la caja (Voyage rerank-2.5), resuelto por turno mediante un ajuste de proveedor con tres valores - automático (el predeterminado), gestionado y local.

  • Resolución del proveedor. El valor automático predeterminado se resuelve al reordenador gestionado cuando hay una clave de API de Voyage presente, y al cross-encoder local en caso contrario. El demo desplegado se resuelve a la ruta gestionada; una copia sin clave reordena localmente. Producción nunca carga el cross-encoder local, que es lo que retira el peso del modelo residente que el traslado existe para eliminar.
  • Por qué un modelo de calidad gestionado, y no el modelo local fuera de la caja. El proveedor gestionado no ofrece el cross-encoder local, ya que distribuye sus propios modelos; alojarlo implicaría un tercer proveedor. El modelo gestionado elegido es multilingüe, con una ventana de contexto larga y latencia alojada subsegundo, de modo que el cambio baja la latencia sin bajar la calidad.
  • Interfaz asíncrona. El reordenamiento es una interfaz asíncrona, así que un viaje de ida y vuelta alojado no bloquea el bucle de eventos; el adaptador gestionado reutiliza el patrón HTTP asíncrono de reintento acotado y sin reintento ante error de cliente ya establecido para el incrustador gestionado (ADR-0004), y el reordenador local se envuelve para presentar la misma superficie asíncrona. El resultado del ranking es idéntico en ambos; solo cambia la planificación.
  • Degradación. Un no-éxito gestionado o un fallo de transporte se eleva como un error de reordenamiento tipado, se captura en el límite de recuperación y se degrada al ranking solo-de-fusión - la misma ruta degradada que produce un fallo de carga local (ADR-0022). Un corte del reordenamiento nunca hace fallar el turno.
  • Costo. El reordenador gestionado se factura por token con una amplia franquicia gratuita; al volumen de reordenamiento por turno del demo, esto deja al demo cómodamente dentro de la franquicia gratuita ($0 a escala de demo), y más allá de ella el costo marginal por turno es una fracción de centavo, medido del lado del servidor en el libro de costos (ADR-0006).

Estrategia de determinismo de la evaluación

Section titled “Estrategia de determinismo de la evaluación”

La ruta de recuperación ahora contiene un reordenador respaldado por red. El determinismo en la compuerta se preserva por capas, no confiando en el proveedor:

  1. La compuerta offline no tiene store. La compuerta canónica de pull-request ejecuta un LLM de sustitución sin ningún almacén vectorial cableado, así que el nodo de recuperación ni siquiera está en el grafo y ningún reordenador - local o gestionado - se llama jamás dentro de la compuerta. El “gestionado-apagado” en la compuerta es estructural, no una bandera que pueda olvidarse.
  2. La evaluación con store fija el reordenador local. Cuando una corrida de evaluación sí cablea un store (corridas de calidad de recuperación e integración), construye el reordenador local para que el ranking puntuado sea determinista y offline. Ninguna corrida con compuerta emite jamás una llamada gestionada en vivo.
  3. Reproducción grabada y paridad en vivo no bloqueante (especificada, condicionada a clave). Para una puntuación de fidelidad de producción, una clave de evaluación aparte graba respuestas gestionadas reales en casetes que la evaluación con store reproduce de forma determinista, junto a una corrida programada de paridad en vivo no bloqueante que llama al servicio real para detectar temprano la deriva del modelo del proveedor. Las llamadas en vivo quedan fuera de toda corrida con compuerta. Esta capa se especifica aquí y se aprovisiona fuera de la máquina del desarrollador.

Confirmación

Section titled “Confirmación”
  • La compuerta offline se mantiene verde y libre de cualquier llamada al reordenador gestionado.
  • Las pruebas unitarias ejercitan ambos proveedores mediante un transporte HTTP simulado - incluidas las variantes del sobre de respuesta y la ruta de error tipado ante error de cliente - y la resolución de proveedor.
  • La verificación en vivo en el host de producción confirma que el turno en caliente cae por debajo del objetivo y que el componente de reordenamiento de la traza refleja la latencia fuera de la caja (ADR-0006).

Consecuencias

Section titled “Consecuencias”

Positivas

Section titled “Positivas”
  • El reordenamiento local dominante sale del turno; el turno en caliente cumple su objetivo de latencia con un ranking multilingüe igual o mejor.
  • Producción deja de cargar el peso del reordenador en memoria, lo que habilita un reajuste de memoria aparte.
  • La interfaz asíncrona desbloquea turnos concurrentes: la ruta de recuperación ya no bloquea el bucle de eventos durante la inferencia local.

Negativas

Section titled “Negativas”
  • Producción gana una dependencia de red del reordenador gestionado para la ruta de reordenamiento completa, mitigada por el contrato de degradación solo-de-fusión y la reversibilidad completa a la ruta local.
  • La capa de reproducción / paridad en vivo de fidelidad de producción necesita una clave de evaluación aparte, así que se ejecuta fuera de la máquina del desarrollador.

Neutrales

Section titled “Neutrales”
  • El ajuste de proveedor y el nombre del modelo gestionado se suman a la superficie de configuración.
  • El cross-encoder local sigue siendo el reordenador soportado offline y de evaluación; ya no se carga en producción, no se elimina.

Pros y contras de las opciones

Section titled “Pros y contras de las opciones”

Un reordenador gestionado fuera de la caja (elegida)

Section titled “Un reordenador gestionado fuera de la caja (elegida)”
  • Bueno, porque retira la inferencia local dominante del turno y devuelve el turno en caliente por debajo del presupuesto.
  • Bueno, porque el modelo elegido es multilingüe y alojado subsegundo, así que la latencia baja sin una compensación de calidad.
  • Bueno, porque se mantiene en $0 a escala de demo con la franquicia gratuita del proveedor.
  • Malo, porque introduce una dependencia de red en producción, aceptada porque la canalización se degrada a solo-de-fusión ante cualquier corte del reordenamiento.

Mantener el cross-encoder local

Section titled “Mantener el cross-encoder local”
  • Bueno, porque no tiene dependencia de red ni proveedor.
  • Malo, porque es la única latencia dominante de un turno en caliente y mantiene un modelo grande residente en memoria.

Cuantizar / compilar a ONNX el modelo local

Section titled “Cuantizar / compilar a ONNX el modelo local”
  • Bueno, porque mantiene el reordenamiento en la caja sin proveedor.
  • Malo, porque la inferencia en CPU de un cross-encoder grande se mantiene muy por encima del objetivo subsegundo incluso cuantizada, y añade una ruta de compilación en tiempo de build que mantener.

Un proveedor gestionado distinto

Section titled “Un proveedor gestionado distinto”
  • Bueno, porque es el mismo movimiento arquitectónico hacia un reordenador alojado.
  • Malo, porque no ofrece una ventaja decisiva de calidad o costo aquí y aun así introduce un segundo proveedor de reordenamiento.

Más información

Section titled “Más información”