Cambiar modelos de embedding RAG sin reindexar: cómo funciona rebasis

Mejorar el modelo de incrustación que está detrás de un sistema de generación ampliada mediante recuperación de información parece algo rutinario, hasta que el índice vectorial existente se interpone en el camino. Una herramienta de código abierto para Python llamada rebasis aborda exactamente ese problema. Entrena un pequeño adaptador que traduce los vectores de consulta desde un nuevo modelo de incrustación al espacio que el índice antiguo ya comprende. De este modo, se puede posponer una reindexación completa o llevarla a cabo de forma gradual y bajo supervisión.

La herramienta prueba varios tipos de mapeo (Procrustes ortogonal centrado, afín, redes de rango bajo y con pequeños residuos) bajo un mismo protocolo de evaluación compartido. No solo informa sobre la calidad del alineamiento, sino que también estima cuán mejor es realmente el nuevo modelo en el corpus en cuestión, y si el sistema adaptado supera a mantener el anterior. Los intervalos de confianza obtenidos mediante bootstrap emparejado, varias métricas de recuperación, las características únicas de la configuración de codificación, registros de auditoría reproducibles y una rutina de migración segura contra fallos convierten la actualización en una decisión medible en lugar de una apuesta al azar.

Los temas abordados son RAG, deriva de embeddings, bases de datos vectoriales, compatibilidad retroactiva, migración de modelos, evaluación de recuperación y búsqueda de vecino más cercano aproximada.

Por qué el modelo de embeddings queda bloqueado

Construir un sistema RAG implica comprometerse no solo con un modelo de lenguaje y una base de datos vectorial, sino también con el sistema de coordenadas del modelo de incrustación que estuviera en uso el día de la indexación. Los documentos, ya sean miles o millones, se dividen en fragmentos, se codifican y se guardan en un índice. Tarde o temprano aparece un modelo de incrustación más rápido, mejor o más adecuado, y ahí comienzan los problemas: un vector de consulta del nuevo modelo no significa nada para un índice creado con el antiguo.

El consejo habitual es “simplemente vuelve a indexar todo”. Técnicamente es correcto, pero a menudo es costoso. Una gran base de conocimiento personal, un conjunto de documentación interna, un código fuente o la memoria a largo plazo de un agente deben ser divididos nuevamente en fragmentos e incrustados de nuevo, lo cual requiere tiempo, recursos de cómputo, presupuesto para APIs y conlleva riesgos operativos. Por eso, muchos sistemas siguen utilizando un modelo obsoleto mucho después de que exista uno mejor.

rebasis fue creado para romper ese encasillamiento. Su objetivo declarado es permitir que un sistema RAG local cambie su modelo de embedding sin eliminar el índice de vectores que ya posee.

Transformar la consulta, no el índice

Los dos modelos de embedding no generan espacios comparables. Al codificar una oración con cada uno, la dimensionalidad puede diferir, pero las diferencias son más profundas: el significado de cada eje, el punto central del espacio, la escala utilizada y la forma en que se organizan los vecindarios semánticos pueden cambiar todos. Un vector de consulta del nuevo modelo, enviado directamente al índice antiguo, devuelve resultados en su mayor parte sin sentido. Algunas bases de datos de vectores rechazan la consulta por completo porque la dimensionalidad no coincide con la de la colección.

La respuesta de la herramienta es un pequeño adaptador aprendido. Toma un vector de consulta del nuevo modelo y lo mapea al espacio en el que habla el índice existente. Para aprender este mapeo, los mismos textos se codifican tanto con el modelo antiguo como con el nuevo, generando vectores emparejados. Si la relación entre los dos espacios es lo suficientemente aprendible, un nuevo vector de consulta puede convertirse en algo significativo para el índice antiguo.

Las ventajas prácticas son significativas: el nuevo modelo puede atender las consultas de inmediato, y los vectores de los documentos en el índice permanecen intactos. La integración en una aplicación se mantiene deliberadamente sencilla. Primero, la importación:

from rebasis import Bridge

Luego se carga el adaptador y se coloca en la ruta de la consulta:

bridge = Bridge.load("adapters/minilm-to-bge.rbs")query_vector = new_model.encode(["how do I deploy to production?"])
query_vector = bridge.to_index_space(query_vector)
results = collection.query(query_embeddings=query_vector, n_results=10)

Bridge es la capa delgada que se encuentra en la ruta de procesamiento principal de la aplicación RAG. Cuando se carga el adaptador, este valida las identidades del modelo, los perfiles de codificación, las dimensiones y la integridad del archivo del adaptador. Después de eso, cada consulta solo implica la operación matricial. El registro de actividades, la construcción de diccionarios y la validación repetida se omiten intencionadamente de esta ruta, ya que una pequeña comodidad no debería convertirse en un costo que se pague en cada solicitud. Tampoco se necesita GPU, porque a esta escala, transferir datos entre dispositivos suele costar más que la multiplicación.

La matemática detrás del adaptador predeterminado

Denomine al antiguo modelo de incrustación f_old y al nuevo f_new, y tome n documentos codificados por ambos. Esto genera dos matrices de datos, una en cada espacio. El objetivo es aprender una función que mapee el nuevo espacio al antiguo, y en su forma general, el objetivo de entrenamiento minimiza la distancia de norma de Frobenius entre los vectores nuevos mapeados y los antiguos.

El método por defecto es el Procrustes ortogonal centrado. Primero se restan las medias de las columnas de ambas matrices. Para espacios de dimensión igual, la restricción es que la transformación debe ser una matriz ortogonal similar a una rotación. Se realiza la descomposición en valores singulares del producto de las matrices centradas, y la mejor matriz ortogonal tiene una forma cerrada, construida a partir de los vectores singulares izquierdo y derecho multiplicados entre sí. Luego, una consulta se transforma centrándola en la media del nuevo espacio, rotándola y sumando nuevamente la media del espacio original. Este es el clásico problema de Procrustes, estudiado desde la década de 1960.

Dicha solución no implica optimización iterativa, por lo que no existe tasa de aprendizaje ni necesidad de elegir épocas. Los mismos datos de entrada siempre producen la misma transformación.

Los vectores se normalizan en longitud antes del ajuste y nuevamente después de aplicar el adaptador, por lo que la similitud coseno se reduce a un producto interno. El centrado es importante porque los espacios de incrustación son anisotrópicos y comparten un componente de media común. Eliminarlo evita que la transformación tenga que representar una traslación que una rotación simple no puede expresar. Si una pareja de modelos necesita más libertad que esa, se utilizan alternativas afines, de rango bajo o residuales.

Se deriva una propiedad de importancia operativa: el costo de entrenamiento depende de la cantidad de pares coincidentes, no del tamaño del corpus. Se puede ajustar un adaptador a partir de unos pocos miles de pares representativos, incluso cuando el índice contiene cientos de miles de registros. Una transformación de matriz completa tiene un costo del orden del producto de las dos dimensiones por consulta y requiere una memoria de parámetros del mismo orden. Una factorización de tipo rank-r reduce el costo de la consulta a aproximadamente r veces la suma de las dimensiones. Como ejemplo concreto, una matriz float32 de 768 por 768 ocupa unos 2,36 MB, lo cual es insignificante en comparación con el ahorro que se logra al no tener que reconstruir el índice.

Por qué un método de transformación no es suficiente

La relación entre dos espacios de incrustación suele ser similar a una rotación, pero no ocurre así para todas las parejas de modelos. Por lo tanto, rebasis no supone que un único algoritmo funcione en todos los casos. Parte de Orthogonal Procrustes, el método con solución analítica para alinear de la mejor manera dos conjuntos de puntos correspondientes. Sin embargo, los espacios reales pueden presentar desplazamientos medios, diferencias de escala por dimensión y componentes no lineales.

Con --method auto, la herramienta ajusta varios candidatos sobre la misma división de datos y con el mismo preprocesamiento, y luego los compara:

• Procrustes, en variantes centradas y clásicas.
• Un mapa lineal regularizado con crestas.
• Un mapa afín de rango bajo.
• Procrustes con escala por dimensión.
• Cuando está disponible PyTorch, una pequeña red MLP residual.

CSLS no se impone forzosamente en el mapeo; también compite como candidato. La razón es práctica: en espacios de alta dimensión puede aliviar el problema de la “centralidad” en los adaptadores débiles, pero puede perjudicar una alineación que ya era sólida. El objetivo no es tener una larga lista de nombres de algoritmos, sino un ganador seleccionado mediante mediciones en datos reservados. Cuando varios candidatos se encuentran dentro de la misma región de incertidumbre, la herramienta prefiere al que tiene menos parámetros y un costo menor.

Los datos de entrenamiento y evaluación permanecen estrictamente separados en todo momento, y eso no es solo una convención. La herramienta verifica la superposición en tiempo de ejecución. Calcular la puntuación de un adaptador con los ejemplos que aprendió daría un número impresionante que no demuestra nada.

Los modelos de incrustación asimétrica también reciben un tratamiento específico. Por ejemplo, en la familia E5, los prefijos query: y passage: significan que el mismo texto se codifica de manera diferente según su rol, y otros modelos utilizan instrucciones de consulta o de documento con el mismo propósito. Al adaptar el adaptador a pares codificados con documentos y aplicarlo a vectores codificados con consultas, se crea un caso típico de desajuste entre entrenamiento y uso en la práctica. Por esa razón, un perfil de codificación en rebasis incluye mucho más que el nombre del modelo: dimensionalidad, normalización, procesamiento de grupos, los prefijos de consulta y documento, y cualquier dimensión de tipo Matryoshka. Un adaptador creado bajo un perfil incorrecto es rechazado en el momento de la carga en lugar de generar resultados deficientes de forma silenciosa.

Cómo se relaciona esto con investigaciones anteriores

Hacer que los embeddings sean compatibles entre versiones es una cuestión antigua. El entrenamiento compatible hacia atrás restringe a un nuevo modelo durante su entrenamiento para que sus representaciones sigan siendo comparables con las antiguas. El entrenamiento compatible hacia adelante hace lo contrario: prepara información adicional mientras se entrena el modelo antiguo, de modo que las actualizaciones posteriores sean más sencillas. Ambos enfoques son adecuados para grandes sistemas de recuperación que controlan todo el ciclo de vida del modelo desde la fase de diseño.

rebasis aborda otra situación. El índice ya existe, los modelos antiguos y nuevos se entrenaron por separado, y nadie puede modificar ninguno de los procesos de entrenamiento. Eso lo convierte en una capa de compatibilidad post-hoc. Se basa en el método Orthogonal Procrustes, en transformaciones de rango bajo y en los trabajos más recientes de la línea Drift-Adapter; su propia contribución radica en la ingeniería: en integrar estas ideas en una herramienta local que además incluye funciones de medición, selección de adaptadores, teoría de decisiones, abstracciones sobre los almacenes, migración segura y un flujo de trabajo para auditorías reproducibles.

CSLS proviene de la literatura sobre alineación de embeddings interlingüísticos. Toma en cuenta la densidad del vecindario local de la consulta y del objetivo, y penaliza a los vectores “hub” que se convierten en el vecino más cercano de demasiadas consultas. En términos generales, asigna a una pareja una puntuación equivalente al doble de la similitud coseno menos un término de densidad para cada lado. Según los experimentos con corpus reales realizados por el propio proyecto, este método ayudó a las mapeaciones débiles y a veces perjudicó a las fuertes, por lo que se mide en lugar de aplicarse ciegamente.

Una herramienta que a veces te dice que no la uses

Al principio del proyecto, la pregunta “¿se puede construir un puente entre estos dos espacios?” resultó ser la incorrecta si se planteaba por sí sola. Hay tres preguntas que son más importantes:

1. ¿Es realmente mejor el nuevo modelo de embeddings con estos datos en particular?
2. ¿Cuánta de la calidad de un reindexamiento completo mantiene el adaptador?
3. ¿Es mejor utilizar el método de puente que simplemente seguir con el modelo actual?

Por eso probe, en lugar de fit, se presenta como la orden clave. Este método integra la toma de muestras, el embedding, la construcción de datos de referencia, la selección de candidatos, el cálculo de métricas y la decisión final en un único proceso de medición, sin escribir nunca en el índice existente.

Una medida central es el ARR, Retención de Recuperación Adaptada: la calidad de la búsqueda adaptada expresada como fracción de lo que ofrecería un reindexamiento completo con el nuevo modelo. Un alto valor de ARR por sí solo no es suficiente. Si el nuevo modelo apenas mejora al anterior, el adaptador tiene poco valor operativo. Si el nuevo modelo representa un gran avance pero el adaptador no puede transmitir esa ventaja, un reindexamiento completo podría ser la solución adecuada.

Por lo tanto, la decisión depende de una medida de punto de equilibrio:

bridge_advantage = ARR × upgrade_gain

Escribirlo de forma explícita hace que la lógica sea más clara. Sea Ra el valor de Recall@k para el sistema adaptado, Rn el mismo valor para un sistema completamente reindexado con el nuevo modelo, y Ro para el sistema antiguo actual. Entonces, ARR representa la ganancia del sistema adaptado en comparación con el antiguo, dividida entre la ganancia del reindexado completo en comparación con el antiguo; la ganancia por actualización es la relación entre Rn y Ro. Al multiplicarlos, los términos de Rn se cancelan, quedando Ra dividido entre Ro: es decir, la comparación directa entre el sistema adaptado y la alternativa real del usuario de no hacer nada.

Cada factor responde a una pregunta sencilla. ARR pregunta cuánto del reindexamiento ideal se mantuvo. El índice de mejora por actualización pregunta cuán mejor es el nuevo modelo. Su producto indica si el paso intermedio actual realmente impulsa el progreso. Un valor superior a 1 significa que el paso intermedio es mejor que seguir con el modelo actual; uno inferior a 1 indica lo contrario. Cuando una medición está muy cerca del umbral, la herramienta no puede ofrecer certeza. Etiqueta el resultado como marginal y recomienda un conjunto de muestras más grande.

Con un registro de consultas real además de IDs de documentos relevantes evaluados por humanos, probe puede medir la verdadera mejora del nuevo modelo en ese corpus. Sin dicho registro, los documentos reservados pueden usarse como consultas, y las consultas sintéticas basadas en palabras clave proporcionan una evaluación aproximada. Cada resultado indica su nivel de evidencia, por lo que la salida incluye tanto una puntuación como los fundamentos en los que se basó.

Un conjunto de mediciones, no un solo número

Recall@k es el eje principal de toma de decisiones, pero la calidad de la recuperación no se resume en una sola cifra. Una sola ejecución de probe genera varios indicadores complementarios:

• MRR@k muestra a qué altura aparece el primer resultado relevante.
• nDCG@k pondera tanto la relevancia como la posición en el ranking.
• Superposición Top-k revela qué parte del entorno de resultados del sistema original mantiene el conjunto de resultados adaptado.
• Correlación de Spearman indica cuán gravemente se degrada el orden interno de los resultados compartidos.
• Distancia de Kolmogorov-Smirnov mide cuánto se desvía la calibración de la distribución de las puntuaciones de similitud.
• Tail ARR determina la calidad de los clústeres más dispersos en relación con el promedio global, de modo que se detecta la deriva que afecta más gravemente a algunas regiones.

Estas diferencias son importantes. Dos sistemas pueden devolver los mismos documentos en orden diferente, algo que el recuerdo no puede detectar pero que sí lo hace el nDCG. De manera similar, el ranking puede parecer adecuado mientras la forma de la distribución de las puntuaciones cambia lo suficiente como para invalidar a un filtro con umbral estricto. Si los resultados de equilibrio basados en el recuerdo y en el nDCG difieren, rebasis informa sobre esa discrepancia y no sustituye silenciosamente una métrica por otra.

La incertidumbre debe formar parte del resultado

El ARR medido en una muestra es una estimación puntual, por lo que la herramienta asigna un intervalo de confianza del 95% basado en 2,000 remuestras bootstrap, siguiendo el método de Efron. En el nivel de evidencia T1, el ARR es una razón entre dos medias. Remuestrear de forma independiente el numerador y el denominador destruiría su dependencia estadística, por lo que un método de bootstrap de razón emparejada reutiliza los mismos índices de consulta para ambos. Los límites corresponden al 2.5% y al 97.5% de los percentiles de la distribución resultante.

El emparejamiento mantiene una correlación real: una consulta que resulta difícil para el adaptador suele serlo también para el oráculo. Cuando el intervalo abarca un umbral de decisión, el resultado no se considera definitivo. En lugar de confundir las decimales con certeza científica, la precisión de la medición pasa a formar parte de la decisión. La semilla, la estrategia de muestreo y la versión de la métrica se incluyen en el registro de auditoría, de modo que el intervalo puede reproducirse.

El proyecto indica que la medición determinó directamente su dirección. Según su informe publicado, comparó el modelo antiguo, un intercambio de modelos ingenuo, la recuperación adaptada y un reindexación completa en conjuntos de consultas idénticos, en 11 corpora, 398,010 documentos y 10,346 consultas reales de usuarios. Se utilizaron juicios humanos de relevancia, y los resultados principales se calificaron de forma independiente con ranx en lugar de basarse únicamente en el código métrico propio de la herramienta. Según esas cifras, un intercambio directo mantuvo aproximadamente el 12.5% de la calidad de una reindexación completa, mientras que el enfoque de conexión mantuvo alrededor del 71%, es decir, unas 6.4 veces más recuperación que el intercambio ingenuo.

El resultado más revelador es que el método de conexión no funcionó correctamente en todas las ocasiones. Realmente valió la pena únicamente en 12 de los 62 pares de modelos y corpus analizados. La regla de decisión apuntó en la dirección correcta en 61 de los 62 casos, incluyendo 32 de los 33 en corpus que no había visto antes de que se fijara la regla. Una herramienta gana confianza al indicar “reindexar aquí” o “no necesita esta actualización” cuando esa es la respuesta honesta, así como al decir “úsenme”.

El flujo de trabajo en línea de comandos de principio a fin

rebasis no es solo una función de biblioteca. Su línea de comandos convierte un cambio de modelo en un proceso manejable. Comienza con una verificación del entorno y de qué almacenes e incrustadores están disponibles:

# Inspect the environment and available store/embedder support
rebasis doctor

A continuación vienen las tres etapas del proceso real: primero medir y elegir una ruta, luego instalar el adaptador, y finalmente migrar el índice en lotes en segundo plano cuando esté listo.

# Measure first and choose the right path
rebasis probe --store chroma:///path/to/db#notes \
  --old sentence-transformers/all-MiniLM-L6-v2 \
  --new BAAI/bge-base-en-v1.5 \
  --queries queries.jsonl --sample 10000 --report report.html# Fit the appropriate adapter
rebasis fit --store chroma:///path/to/db#notes \
  --old sentence-transformers/all-MiniLM-L6-v2 \
  --new BAAI/bge-base-en-v1.5 \
  --method auto --pairs 4000 \
  --out adapters/minilm-to-bge.rbs# When ready, migrate the index in background batches
rebasis migrate --adapter adapters/minilm-to-bge.rbs \
  --store chroma:///path/to/db#notes --priority access --limit 5000

El adaptador .rbs resultante contiene más que solo pesos. Su manifiesto registra las identidades de los modelos antiguos y nuevos, las dimensiones del vector, la dirección y las huellas dactilares del perfil de codificación. Los tensores se almacenan en el formato safetensors, y también se incluyen los resultados de calibración y evaluación de las puntuaciones. Por lo tanto, un adaptador representa un registro portátil y verificable de qué modelos y condiciones lo generaron, y los hashes de los tensores pueden volverse a calcular para verificar su integridad.

La calibración de las puntuaciones merece especial atención. Una transformación puede conservar el ranking y, aun así, modificar las puntuaciones de similitud absoluta. Una aplicación con un umbral fijo, como similarity > 0.7, podría descartar silenciosamente algunos resultados. Para abordar esto, la herramienta utiliza un calibrador isotónico monotónico que ajusta las puntuaciones de vuelta hacia la escala tradicional sin alterar su orden, y además advierte a los sistemas que dependen de umbrales fijos.

Comportamiento de cálculo y memoria

Una herramienta que en teoría no necesita todo el corpus en memoria aún podría cargarlo por accidente. En rebasis, los iteradores de corpus transmiten los registros de forma continua, por lo que el consumo máximo de memoria durante la migración es aproximadamente igual al tamaño del lote multiplicado por la dimensión del vector. El tiempo de ejecución aumenta con la cantidad de registros, pero el corpus del usuario nunca se materializa en RAM. A medida que la memoria se acerca al límite establecido por --max-memory, el tamaño del lote puede disminuir y el trabajo con puntos de control puede pausarse en lugar de ser interrumpido.

La matriz de similitud utilizada para la búsqueda de valores de referencia, según el tamaño de la muestra, tampoco se construye en su totalidad. Las consultas se procesan en bloques. Cada bloque realiza una multiplicación matricial, extrae los resultados top-k y descarta la matriz de puntuaciones intermedia. Un ordenamiento completo costaría S log S por fila. Al utilizar argpartition, el costo esperado de selección por fila se mantiene lineal en S. En el caso de vectores float32 normalizados, la búsqueda por coseno se reduce a una sola multiplicación matricial, lo que permite controlar tanto el uso máximo de memoria como las diferencias entre plataformas relacionadas con el tipo de dato.

En este proyecto, la CPU es la referencia numérica y no una solución secundaria de último recurso. Una GPU puede acelerar en gran medida la generación de embeddings, pero la transferencia entre el dispositivo anfitrión y la GPU puede anular esa ventaja en el caso de una operación sencilla de adaptador para una sola consulta. Las pruebas de equivalencia entre dispositivos comparan las tolerancias de las puntuaciones, así como los conjuntos de vecinos recuperados, y, sobre todo, si datos idénticos conducen a la misma decisión final. Una diferencia numéricamente pequeña que haga que un ARR supere un umbral como 0.95 no se considera una variación de hardware aceptable; se trata de un defecto en el comportamiento del producto.

Migración que resiste las interrupciones

Al utilizar un puente, el índice no necesita cambiar de inmediato; el sistema puede seguir funcionando a través del adaptador todo el tiempo que se desee. Si el índice debe trasladarse de forma permanente, la función migrate mueve los registros al nuevo espacio por lotes, y en esta fase la seguridad de los datos tiene prioridad sobre la velocidad bruta.

Cada lote comienza con la lectura de los vectores actuales, los cuales se copian a un almacén de respaldo antes de cualquier sobrescritura. A continuación, se escriben los vectores transformados, y se lee de nuevo una muestra de los registros escritos para verificarlos. Al final, la herramienta no confía únicamente en su identificador de cliente actual; vuelve a abrir el almacén a través de una conexión nueva y realiza nuevas pruebas de verificación para garantizar la fiabilidad, de modo que el caché del lado del cliente no pueda ocultar lo que realmente llegó al almacenamiento persistente.

El motor de migración se basa en cuatro invariantes:

1. Debe existir un vector original de tipo float32 en el almacén de respaldo antes de que se modifique su registro.
2. Una muestra obtenida después de la escritura de cada lote marcado como completado debe poder leerse dentro de los límites permitidos de tolerancia.
3. Un trabajo finalizado debe seguir verificándose después de que el almacén se vuelva a abrir a través de una nueva conexión.

El retroceso debe restaurar los vectores originales sin cambiar la cantidad de registros ni los datos cargados.

El orden es la base del argumento de seguridad ante fallos. Si el proceso se detiene después de la escritura en copia de seguridad pero antes de la escritura en el almacenamiento principal, el resultado es una copia adicional inofensiva. Si se intercambian esos dos pasos, la misma interrupción podría destruir un vector original de forma permanente.

La cola de migración también funciona como punto de control, por lo que --resume continúa desde el último lote completado. La herramienta puede monitorear la presión de memoria y el estado de la batería, y un registro de accesos puede colocar primero los registros más solicitados. Si el resultado no es satisfactorio, rollback restaura los originales a partir de la copia de seguridad. Los contratos compartidos entre los servidores backend (Chroma, LanceDB, sqlite-vec, Qdrant, FAISS y uno en memoria) garantizan que estas operaciones tengan el mismo significado en todas partes.

Plugins para diferentes tecnologías

Local RAG no se basa en una única base de datos vectorial ni en un proveedor de embeddings, por lo que el almacenamiento y los embeddings se gestionan a través de registros basados en plugins. Las bases de datos soportadas son: Chroma, LanceDB, sqlite-vec, Qdrant y FAISS, además de un backend que funciona en memoria. Para generar embeddings se utilizan sentence-transformers, fastembed, Ollama, APIs compatibles con OpenAI, llama.cpp y vectores precalculados.

La instalación básica está diseñada para funcionar sin PyTorch. Las funciones principales probe, el ajuste de Procrustes y la lógica de toma de decisiones se ejecutan con NumPy, SciPy y scikit-learn, mientras que las dependencias pesadas o específicas de la plataforma solo se instalan si es necesario. Los paquetes de terceros pueden ofrecer un punto de entrada rebasis.stores o rebasis.embedders para integrarse sin modificar el proyecto.

Privacidad, registro de actividades y reproducibilidad

Por diseño, rebasis no envía datos locales a ningún lugar. No cuenta con telemetría de tipo “phone-home” ni con contador de uso, y el texto de los documentos ni los vectores llegan nunca a los registros. Dado que la información puede reconstruirse a partir de un embedding, los vectores se tratan con la misma sensibilidad que el texto plano. Existe soporte para OpenTelemetry como opción; está desactivado por defecto y solo exporta a la colección del propio usuario.

Cada decisión puede registrarse en un registro de auditoría de solo escritura para que sea reproducible. La entrada contiene las identidades del modelo, las huellas dactilares del perfil, el método de muestreo, la semilla, los umbrales, la versión de la métrica, la versión de rebasis y los detalles del entorno. Las entradas están vinculadas en una cadena de hash, lo que hace visible cualquier corrupción posterior o edición parcial. rebasis audit replay vuelve a ejecutar una medición anterior para determinar si la diferencia se debe a una regresión del software o a un cambio en el corpus.

Qué busca demostrar el empaquetado de código abierto

rebasis se publica bajo la licencia Apache 2.0, y su objetivo declarado es hacer que tanto sus afirmaciones como su código sean inspeccionables y legibles. En el repositorio encontrarás registros de decisiones arquitectónicas para las elecciones clave, además de escenarios ideales, mediciones en corpus reales, presupuestos de rendimiento, pruebas de contrato por backend, pruebas CLI que se ejecutan de principio a fin y documentación para los colaboradores. La estrategia de pruebas va más allá del camino óptimo para abarcar la consistencia numérica entre dispositivos, los límites de memoria, las propiedades de los adaptadores, los contratos de almacenamiento y la durabilidad de las migraciones y retrocesos.

La pipeline de CI está diseñada para Python 3.12 y 3.13 en Linux y macOS, dos sistemas cuyas semánticas de almacenamiento difieren. Las versiones mínimas de las dependencias soportadas tienen un proceso propio, y un trabajo separado verifica que elementos opcionales como PyTorch u OpenTelemetry no se incluyan en el paquete principal. La verificación de tipos se realiza con mypy --strict, la calidad del código es gestionada por Ruff, los límites entre capas por import-linter y los enlaces a la documentación por MkDocs en modo estricto. La idea detrás de todo esto es que la confianza en el código abierto depende menos de afirmaciones contundentes en los README que de demostrar qué pruebas y mediciones las respaldan.

Cambios en los modelos sin la opción todo o nada

El problema subyacente no es elegir una tecnología, sino el costo de cambiarla. A medida que los sistemas RAG crecen, sus índices se convierten en inversiones en infraestructura, y elegir un modelo de embedding se vuelve una decisión mucho más difícil de revertir de lo que debería ser. La idea detrás de rebasis es aflojar esa vinculación.

Cuando aparece un nuevo modelo, el primer paso debe ser medir si realmente es mejor con los propios datos. Si lo es, el siguiente paso es averiguar si existe un puente fiable que pueda conectarlo con el índice actual. Si el puente es lo suficientemente bueno, el nuevo modelo puede utilizarse de inmediato. Si se desea mantener una calidad óptima a largo plazo, la migración puede realizarse en lotes controlados, con verificaciones y garantías de reversión. Y si el puente no es suficiente, eso debe descubrirse antes de realizar un costoso experimento en producción, no durante él.

Ese es el espacio de decisiones que ofrece la herramienta: medir primero, crear un puente intermedio, y migrar de forma segura cuando sea necesario. Se trata de una herramienta abierta cuyo objetivo es fortalecer la infraestructura local RAG, hacer que la elección de modelos incrustados sea menos restrictiva y que las actualizaciones de modelos sean más transparentes, además de estar abierta para que los desarrolladores la examinen, la prueben con corpus reales y contribuyan a su desarrollo.