Apéndices A-D
Apéndice A · Plantillas del acceso
Las tres plantillas que el libro usa como entregables. Son puntos de partida: cada cláusula debe nacer de un caso propio, como defiende el capítulo tres.
A.1 Contrato de recuperación (plantilla de dos páginas)
- Alcance. Dominios atendidos y excluidos; regla de frontera (negocio = filtro, datos = colección); qué se hace ante consulta cruzada.
- Entrega. Unidad entregada (píldora con pedigri); k de entrega por tipo de consulta; presupuesto de contexto por tipo; garantía de integridad (ninguna píldora ni tabla descapitada).
- Vigencia. Solo contenido vigente por defecto; lo derogado consultable como historia etiquetada; compromiso de frescura del estado.
- Permisos. Quién puede ver qué; regla de oro: lo no permitido no alcanza el contexto, no se degrada ni se anuncia.
- Trazabilidad. Toda afirmación con cita remontable a fuente, apartado y fecha; paquete de trazabilidad entregado con cada respuesta.
- Calidad. Objetivos por tipo de consulta sobre el dataset de referencia (recall@k contractual, MRR de cabeza, nDCG de conjunto); quién firma las verdades.
- Vacío. Política del vacío: clasificación filtro/corpus, escalera de relajación con confesión, declaración honesta con coordenadas, prohibición del falso positivo.
- Cada cláusula lleva su caso fundacional, su fecha y su historia de revisión.
A.2 Esquema de facetas (plantilla por dominio)
Para cada faceta: nombre, tipo (crítica o descriptiva), vocabulario cerrado con sus valores, política del nulo (excluido / incluido / prohibido), decisión de acceso que habilita y consultas que la exigen. Campos críticos sin excepción: dominio, vigencia, estado editorial, permiso. Procedimiento de migración de valores: retirar-sustituir, nunca renombrar en sitio.
A.3 Ficha de evaluación de consultas (por entrada del dataset)
- Consulta tal cual llegó (con errata y jerga si la hubo).
- Tipo: fáctica / navegacional / sintética / procedimental.
- Dominio y filtros de contexto esperados.
- Verdad de referencia: píldoras o documentos que deberían salir; cuál basta; cuál es la respuesta exacta si la hay.
- Firma del negocio y fecha; herida de origen (si entró por un fallo de producción, cuál).
Apéndice B · Guía de métricas
Las tres métricas del capítulo dieciocho, sin fórmulas impenetrables.
Recall@k — la métrica del olvido. De todo lo que debería haber salido dentro del tope, cuánto salió. Se lee como un porcentaje de cobertura; es la métrica contractual porque mide el fallo más grave: la evidencia que existía y no llegó. Objetivo orientativo para dominios de respuesta única (fácticas): ≥ 0,9 en k = 10. Su punto ciego: no mira puestos —medido con un tope mayor del que ve el usuario, un recall perfecto con la verdad en el puesto 25 es una experiencia nefasta.
MRR — la métrica de la cabeza. Media del inverso del puesto del primer acierto: primero = 1, quinto = 0,2, ausente = 0. Mide lo que vive el usuario —nadie mira el puesto nueve—. Objetivo orientativo para navegacionales: ≥ 0,8. Su punto ciego: solo mira el primer acierto; en consultas sintéticas con varias evidencias necesarias, engaña.
nDCG — la métrica del conjunto. Ganancia acumulada con descuento por posición: premia que lo mejor esté arriba y castiga el orden mediocre. Es la honesta para sintéticas y para evaluar la diversidad del capítulo catorce. Su punto ciego: exige graduar la relevancia de cada referencia (qué es imprescindible, qué secundario), que es trabajo del negocio.
Cómo no engañarse. Objetivos por tipo de consulta, nunca globales; ningún cambio sin antes-después; el dataset crece por heridas; y la advertencia de fondo: estas métricas miden la recuperación, no la respuesta redactada.
Apéndice C · Revisión de tecnología
Sin código, con criterio: qué preguntarle a cualquier motor antes de elegirlo. Los nombres concretos envejecen; las preguntas, no.
Filtrado. ¿Aplica filtros pre o post por defecto, y se puede elegir? ¿Cómo se comporta el índice de vecindad con filtros selectivos —degrada, fuerza recorrido exacto, o usa índices parciales por faceta? ¿Devuelve menos de k sin avisar cuando el filtro aprieta? En el despacho, esta batería descartó más candidatos que cualquier benchmark.
Híbrido. ¿Soporta búsqueda dispersa nativa (BM25 y familia) además de la densa? ¿Qué fusión ofrece —RRF o equivalente— y permite sustituirla? ¿Pueden ajustarse los anchos de cada canal por consulta? Si un motor solo hace denso, el híbrido se monta fuera; posible, pero más piezas.
Topes y umbrales. ¿Score expuesto por resultado (necesario para umbrales)? ¿k ajustable por consulta? ¿Over-fetch práctico —pedir 100 para entregar 10— sin penalización de tarifa?
Rerank. ¿Reranker integrado o vía servicio? ¿Qué modelos cruzados ofrece y con qué coste de latencia? La regla: el rerank se dimensiona desde el contrato (cap. 15), no desde la carta de productos.
Operación. ¿Versionado de colecciones (necesario para la idempotencia del corpus y las migraciones de embeddings)? ¿Payload filtrable con esquema libre? ¿Coste por consulta predecible? ¿Exportación completa —vectores y payload— sin fricción? El día que toque cambiar de motor, la exportación es la diferencia entre una migración y una recaída.
Mención expresa. El sistema real de la serie corre sobre Qdrant por estas preguntas, no por el folleto: filtrado pre con estrategias declaradas, híbrido nativo, payload sin ataduras. Los alternativos serios (Weaviate, pgvector, Elasticsearch/OpenSearch) pasan la misma batería con distintas respuestas; el apéndice no elige por el lector —le enseña a preguntar.
Apéndice D · La brújula imprimible
La brújula de 7 pasos del acceso, en una página, para clavar en la pared.
| Paso | Capítulos | Criterio de salida |
|---|---|---|
| 1. Entender la pregunta | 1–3 | El contrato de recuperación, escrito y firmado |
| 2. Trazar el mapa de facetas | 4–6 | Un esquema de payload versionado; cero nulos en campos críticos |
| 3. Filtrar el espacio | 7–10 | Duras en pre, blandas en post; gobernanza en el 100 % de las búsquedas; vacío diseñado |
| 4. Recuperar | 11–14 | Híbrido con fusión declarada; k, umbral y presupuesto como política; cero fotocopias en el top |
| 5. Reranquear y ensamblar | 15–17 | Ancho de tamiz calibrado; juez solo donde el error cobra; contexto compuesto, citado e íntegro |
| 6. Medir | 18–19 | Dataset de consultas firmado; recall@k contractual; suite de regresión bloqueando en cada cambio |
| 7. Observar y cerrar el ciclo | 20–21 | Diario completo; cinco señales en rutina semanal; cada consulta sin respuesta es una tarea de corpus |
La regla de oro, en una línea: que la respuesta diga la verdad del corpus —solo lo elegible, solo lo vigente, solo lo permitido— y que cada afirmación se pueda comprobar hasta el documento real que la sostiene.