turbovec es un índice vectorial en proceso de código abierto escrito en Rust con enlaces Python. Implementa el enfoque TurboQuant de Google Research para comprimir vectores densos sin una fase separada de entrenamiento del libro de códigos, luego busca los códigos empaquetados con núcleos SIMD específicos de la arquitectura. Su atractivo práctico es una combinación de ingesta en línea, almacenamiento de 2 o 4 bits, persistencia, ID externas estables, soporte de eliminación, búsqueda filtrada por listas permitidas y adaptadores para marcos RAG comunes.
Es importante clasificarlo correctamente. turbovec es una biblioteca de índices, no una base de datos vectorial alojada ni un servicio de recuperación completo. Por sí solo no proporciona replicación distribuida, fragmentación de múltiples nodos, copias de seguridad, autenticación, administración de inquilinos, APIs de red, búsqueda léxica híbrida, observabilidad o un plano de control. Los equipos obtienen control local y eficiencia de la memoria a cambio de apropiarse de las preocupaciones circundantes.
Cómo funciona la compresión TurboQuant
La idea subyacente es que una rotación ortogonal aleatoria hace que las coordenadas de vectores unitarios de alta dimensión sigan una distribución predecible. turbovec primero separa la norma de cada vector de su dirección. Aplica una rotación aleatoria compartida y luego cuantifica las coordenadas rotadas utilizando depósitos Lloyd–Max precalculados. Dos bits proporcionan cuatro valores por coordenada; cuatro bits proporcionan dieciséis. Los códigos están empaquetados en bits y una corrección por vector elimina la contracción sistemática del producto interno introducida por la cuantificación.
El proyecto agrega calibración TQ+: en la primera adición, estima un desplazamiento y una escala para cada coordenada utilizando cuantiles empíricos y luego congela esos valores para ingestas posteriores. Esto no es lo mismo que la capacitación convencional en cuantificación de productos, pero el primer lote influye en la calibración. Por lo tanto, una primera adición pequeña o poco representativa puede ser una inicialización de producción deficiente. Siembre el índice con una muestra representativa y pruebe la deriva de la distribución.
| etapa | Almacenado o calculado | Consecuencia operativa |
|---|---|---|
| normalizar | Dirección de la unidad más norma original | Preserva la magnitud mientras cuantifica la estructura angular. |
| Rotación aleatoria | Transformación ortogonal compartida | Hace que las distribuciones de coordenadas sean predecibles en datos de entrada arbitrarios. |
| TQ+ calibración | Cambio por coordenadas y escala aprendidos en la primera adición | Mejora el comportamiento finito/de baja dimensión; requiere inicialización representativa |
| Lloyd–Max cuantificación | Códigos de coordenadas de 2 o 4 bits | Gran reducción de memoria con pérdida de recuperación dependiente del conjunto de datos |
| Corrección de longitud | Un escalar por vector | Corrige estimaciones del producto interno sesgadas a la baja. |
| SIMD búsqueda | Consulta rotada y puntuación de tabla de búsqueda sobre códigos empaquetados | Evita la descompresión total; El rendimiento depende de la arquitectura de la CPU. |
Matemáticas de la memoria sin el atajo del marketing
Un vector float32 de 1.536 dimensiones utiliza 6.144 bytes para coordenadas sin formato. Sus códigos de coordenadas requieren 384 bytes a 2 bits o 768 bytes a 4 bits antes de los metadatos. Esa es una reducción teórica de 16 × u 8 × para la carga útil de coordenadas. El titular del repositorio dice que un corpus float32 de 10 millones de documentos que ocupa unos 31 GB puede caber en unos 4 GB; ese ejemplo refleja una dimensión y representación particular y no debe generalizarse a todos los corpus.
La planificación de la capacidad debe agregar identificaciones externas, valores de corrección/norma por vector, datos de calibración, alineación, gastos generales del asignador, ranuras eliminadas, metadatos de la aplicación, búferes de consulta y el almacén de documentos original. Las incrustaciones rara vez representan toda la factura de la memoria RAG. Mida el tamaño del conjunto residente después de cargar el índice persistente real y atender consultas simultáneas.
Qué admite API
importar numpy como np
desde turbovec importar IdMapIndex
índice = IdMapIndex(dim=1536, ancho_bit=4)
index.add_with_ids(vectores.astype(np.float32), ids.astype(np.uint64))
puntuaciones, result_ids = index.search(query.astype(np.float32), k=10)
index.remove(document_id)
index.write("corpus.tvim")
restaurado = IdMapIndex.load("corpus.tvim")El Python API rechaza deliberadamente vectores que no son float32 en lugar de convertirlos silenciosamente. Las identificaciones estables son importantes porque las ranuras internas pueden cambiar después de las eliminaciones y el mantenimiento. La persistencia hace que el reinicio local sea práctico, pero las aplicaciones aún necesitan publicación atómica, sumas de verificación, políticas de copia de seguridad/versión y pruebas de compatibilidad entre las actualizaciones de la biblioteca.
La recuperación filtrada es un diferenciador significativo
Para la recuperación multiinquilino, ventana de tiempo o con reconocimiento de permisos, la aplicación puede primero generar un conjunto de ID permitido desde SQL, BM25, un servicio ACL u otro sistema, luego pedirle a turbovec que clasifique solo a esos candidatos. El filtrado se produce dentro de la ruta SIMD con una granularidad de bloque de 32 vectores. Los bloques vacíos se pueden omitir y las ranuras no permitidas se rechazan antes de la inserción del montón, por lo que los filtros selectivos pueden evitar gran parte del trabajo de puntuación densa.
Esto es mejor que recuperar un top-k global y descartar resultados no autorizados, lo que puede devolver muy pocos documentos válidos y filtrar información de clasificación. Sigue siendo responsabilidad de la persona que llama construir la lista de permitidos correctamente, vincularla al inquilino autenticado y probar conjuntos vacíos, pequeños, enormes y que cambian rápidamente. Nunca utilice el filtrado de metadatos como única verificación de autorización en la recuperación del documento final.
Cómo leer los puntos de referencia publicados
| Reclamar | Límite de prueba publicado | Lo que queda sin demostrar |
|---|---|---|
| Retirada competitiva con FAISS PQ | 100.000 vectores, k=64; OpenAI dimensiones 1536/3072 y GloVe dimensión 200; tasa de bits coincidente | Su modelo de incrustación, distribución de corpus, k, métricas y etiquetas de relevancia |
| Entre un 10% y un 19% más rápido en ARM | Apple M3 Max contra FAISS IndexPQFastScan en configuraciones de repositorio | Otros chips de Apple, filtros de concurrencia, estado térmico y producción |
| Velocidad x86 competitiva | Xeon Platino 8481C; ganancias reportadas para 4 bits, pérdidas modestas en algunos casos de 2 bits | Su generación de CPU, ruta AVX, núcleos, NUMA y lote de consultas |
| Sin entrenamiento/reconstrucción | Cuantizador de distribución conocida con calibración de primera adición TQ+ y adiciones en línea | Impacto de un primer lote no representativo o un gran turno de distribución |
| La búsqueda filtrada evita la búsqueda excesiva | Lista de permitidos manejada dentro de la puntuación de bloques y la inserción del montón | Costo SQL/ACL de extremo a extremo y filtros no selectivos en el peor de los casos |
La línea base de comparación es FAISS ÍndicePQ/IndexPQFastScan, no todos los tipos de índice FAISS. La búsqueda exacta plana, HNSW, IVF-PQ, índices GPU y bases de datos administradas resuelven diferentes puntos en la curva de recuperación, latencia, memoria y operaciones. Primero reproduzca los puntos de referencia del repositorio, luego sustituya sus datos y el objetivo de aceptación un factor a la vez.
Un protocolo de evaluación RAG útil
- Congelar incrustaciones. Utilice el modelo exacto, la normalización, la dimensión y la convención de distancia planificadas para la producción.
- Crear verdad sobre el terreno. Calcule los vecinos top-k exactos con una implementación plana confiable y mantenga por separado los juicios de relevancia de las tareas.
- Pruebe ambos anchos de broca. Compare 2 bits y 4 bits con float32 o búsqueda exacta, no solo entre sí.
- Estratificar consultas. Incluya casos comunes, raros, multilingües, cortos, largos, duplicados y fuera de dominio.
- Ingesta de ejercicio. Inicialice con un lote representativo, agregue distribuciones posteriores, elimine ID, persista, vuelva a cargar y verifique el comportamiento determinista.
- Filtros de referencia. Mida sin filtro y listas permitidas con una cobertura del 0%, 0,1%, 1%, 10%, 50% y 100%, incluidos los diseños de bloques adversarios.
- Prueba de carga. Registre la latencia, el rendimiento, la utilización de la CPU, la memoria residente y el comportamiento de cola de p50/p95/p99 con simultaneidad real.
- Evalúa la respuesta. Mida el recuerdo de la recuperación, la calidad del reclasificador, la corrección de las citas y el éxito de la respuesta final. Los vecinos aproximados más rápidos son valiosos sólo si el resultado de la aplicación sobrevive.
Métricas de decisión
| Métrica | Definición | Informes sugeridos |
|---|---|---|
| recordar@k | Vecinos top-k exactos recuperados mediante búsqueda aproximada | Por segmento del conjunto de datos, ancho de bits y selectividad del filtro |
| recuperación de tareas | Consultas cuyo justificante requerido se recupera | Más significativo que la superposición de vector-vecino por sí sola |
| Memoria por vector | Procesar RSS delta / vectores de búsqueda cargados | Incluir ID, espacios eliminados y sobrecarga de metadatos |
| Latencia de cola | p95/p99 tiempo de consulta de un extremo a otro | Con simultaneidad realista y combinación de listas permitidas |
| Costo de actualización | Tiempo y memoria máxima para agregar, eliminar, guardar y recargar | Incluir calibración de primera adición y recuperación de fallas |
| Costo por consulta aceptada | Infraestructura más operaciones de ingeniería/resultados correctos de las tareas | Comparar con FAISS y alternativas administradas |
Integraciones de marco
El repositorio documenta adaptadores para LangChain, LlamaIndex, Haystack y Agno que reemplazan sus almacenes de referencia en memoria manteniendo interfaces familiares. Esto puede hacer que una prueba de concepto sea rápida, pero "incorporación" se refiere a una superficie de software pública, no a una puntuación, filtrado, eliminación, persistencia, subprocesamiento o semántica de falla idéntica. Ejecute las pruebas de recuperación de cada marco y fije las versiones compatibles antes de implementarlo.
Alternativas
| Opción | Prefiero cuando | Compensación |
|---|---|---|
| turbovec | La búsqueda local en proceso, la compresión extrema, la adición en línea y el filtrado de listas permitidas se adaptan a la carga de trabajo | Usted posee controles operativos, de replicación y de servicio |
| FAISS | Necesita opciones maduras de indexación exacta, FIV, PQ, HNSW o GPU | La configuración y la formación pueden ser más complicadas; la memoria varía según el índice |
| hnswlib | La búsqueda de gráficos de alta recuperación y baja latencia importa más que el almacenamiento compacto | La sobrecarga de gráficos puede consumir mucha más memoria |
| Qdrant, Weaviate o Milvus | Se requieren servicio de red, filtros de metadatos, replicación y operaciones. | Más infraestructura y memoria que una pequeña biblioteca integrada |
| Base de datos vectorial gestionada | El equipo quiere ampliación alojada, copias de seguridad, autenticación y soporte | Costo recurrente, residencia de datos y dependencia de proveedores |
| PostgreSQL con pgvector | Los vectores deben permanecer cerca de los datos relacionales y las operaciones existentes. | Puede no coincidir con un índice comprimido especializado a gran escala |
Límites y riesgos de producción.
- La compresión aproximada puede cambiar el orden del vecino más cercano, especialmente con un ancho de broca agresivo o dimensiones bajas.
- Los núcleos específicos de la CPU significan que los resultados de las pruebas comparativas no deben transferirse entre el hardware ARM, AVX2 y AVX-512.
- La calibración de primer agregado, el cambio de modelos de incrustación y la deriva del corpus necesitan pruebas de migración explícitas.
- La implementación local mantiene los vectores bajo su control, pero no agrega automáticamente cifrado, control de acceso ni copias de seguridad seguras.
- Una falla en el proceso afecta la aplicación host a menos que el límite del servicio y la estrategia de recuperación se diseñen deliberadamente.
- El proyecto está evolucionando; lanzamientos de pines, inspeccionar registros de cambios/orientaciones de seguridad y validar la compatibilidad del índice persistente.
Preguntas frecuentes
¿Es turbovec una base de datos vectorial?
No. Es una biblioteca de índices vectoriales. Las aplicaciones deben proporcionar operaciones de almacenamiento de documentos, redes, autorización, replicación, monitoreo y ciclo de vida según sea necesario.
¿Requiere un paso de formación fuera de línea?
Evita la capacitación en libros de códigos convencionales y admite anuncios en línea. TQ+ calibra los valores por coordenada durante la primera adición, por lo que el lote de inicialización aún merece atención.
¿Debo elegir 2 bits o 4 bits?
Utilice 2 bits cuando la memoria sea la limitación vinculante y la recuperación de la tarea medida siga siendo aceptable. Los cuatro bits generalmente compran más fidelidad con aproximadamente el doble del almacenamiento del código de coordenadas. Compara ambos.
¿La búsqueda filtrada aplica la seguridad de los inquilinos?
Puede restringir eficientemente la clasificación a una lista de permitidos. La aplicación debe crear la lista correcta y volver a verificar la autorización antes de devolver el contenido fuente.
¿Son universales sus FAISS afirmaciones de velocidad?
No. Los resultados publicados cubren hardware con nombre, conjuntos de datos, dimensiones, anchos de bits y configuraciones FAISS PQ/FastScan. Los resultados de x86 de 2 bits incluyen casos en los que FAISS es más rápido.
¿Puede tener espacio de aire?
El índice se ejecuta localmente y no requiere un servicio administrado. Una pila RAG completa con espacio de aire también necesita incrustaciones locales, documentos, procedencia del paquete/modelo y actualizaciones controladas.
fuentes primarias
- turbovec repositorio oficial y documentación de referencia
- turbovec API referencia
- Scripts y resultados de referencia reproducibles
- TurboQuant trabajo de investigación
- RaBitQ artículo citado para corrección de extensión
- FAISS FastScan referencia técnica
- turbovec Python paquete
- turbovec Rust caja
Revisado por última vez el 25 de julio de 2026. Las declaraciones de rendimiento se limitan a la configuración publicada del repositorio, a menos que se indique lo contrario. Reproduzca en su corpus, incruste el modelo, el hardware y la distribución de filtros antes de la adopción.
