Define objetivos de frescura, propagación de versiones, flujos de trabajo de reindexación, visibilidad de eliminación y evidencia de reconciliación para un índice RAG derivado de documentos fuente cambiantes.
Estado del paquete: contexto de referencia listo para revisión humana. El contrato y los escenarios de prueba están completos, pero no se afirma que una implementación adoptante los haya superado.
Decisión
Modelar la indexación como una proyección versionada, no como un trabajo de copia. Cada fragmento apunta a una versión fuente inmutable; los alias activos cambian solo después de la validación, y las eliminaciones o revocaciones de acceso tienen un objetivo de visibilidad más estricto que las actualizaciones ordinarias.
Alcance
- Descubrimiento de fuente, identidad de cambio, perfil de fragmentación, embedding, construcción de índice, cambio de alias, eliminación, revocación de acceso, reconciliación y reversión.
- Rutas de reconstrucción incremental y completa.
- Métricas de frescura desde la observación de la fuente hasta la visibilidad en búsqueda.
Fuera de este bloque
- Copia de seguridad del sistema fuente o aprobación editorial de la verdad del documento.
- Invalidación de caché de respuestas más allá del registro de versiones fuente para una política de caché separada.
Contrato
- Cada fragmento indexado registra ID de fuente, versión de fuente, resumen de contenido, perfil de fragmento, perfil de embedding, tiempo observado y versión de política de visibilidad.
- El procesamiento repetido de la misma versión fuente es idempotente.
- Una generación de índice activa se vuelve visible solo después de pasar conteo, muestreo, autorización y pruebas básicas de recuperación.
- La eliminación y revocación de acceso crean lápidas duraderas que suprimen fragmentos coincidentes en generaciones activas y en reconstrucción.
- Una reconstrucción completa puede ejecutarse junto al índice activo y cambia mediante un alias reversible o versión de enrutamiento.
- Los SLOs de frescura se miden por separado para creaciones, actualizaciones, eliminaciones y cambios de autorización.
Guía de implementación
- Usar un libro mayor de cambios con desplazamientos fuente monótonicos o eventos duraderos por versión fuente.
- Propagar lápidas antes del trabajo costoso de embedding.
- Reconciliar inventario de fuente, libro mayor, conteos de objetos/fragmentos y muestras del índice activo.
- Mantener la generación aceptada previa durante una ventana de reversión configurada.
Manejo de fallos y salvaguardas
- Si falla el embedding, reintentar la versión inmutable y mantener activa la versión fuente previa cuando la política lo permita.
- Si los datos de autorización están obsoletos, suprimir la fuente afectada en lugar de exponerla bajo una política antigua.
- Si falla la validación, no cambiar el alias activo; conservar evidencia y reparar la generación candidata.
Verificación y operaciones
- Medir el retraso de observación a búsqueda por clase de cambio, antigüedad del retraso, versiones fallidas, documentos activos obsoletos, propagación de lápidas, deltas de reconciliación y tiempo de reversión de alias.
- Alertar sobre incumplimientos de SLO de autorización/eliminación con mayor agresividad que el retraso de actualización de contenido.
- Ejecutar sondas programadas de recuperación para fixtures recién actualizados y revocados.
Los ejemplos con apariencia ejecutable en este paquete son fixtures y contratos de aceptación. Ejecute
python tools/validate.py desde la raíz de la colección para verificar la estructura y metadatos del paquete; luego
implemente y ejecute los escenarios en el repositorio objetivo.
Suposiciones de adopción
- Los nombres y valores numéricos en
example.yamlson un perfil de adopción, no valores predeterminados universales. - El equipo adoptante debe mapear actores, clases de datos, vocabulario de errores y propiedad a su sistema.
Referencias
- No se requiere fuente normativa externa; este paquete define una decisión de proyecto.