turbovec est un index vectoriel en cours de processus open source écrit en Rust avec des liaisons Python. Il implémente l'approche TurboQuant de Google Research pour compresser les vecteurs denses sans phase distincte de formation du livre de codes, puis recherche les codes compressés avec les noyaux SIMD spécifiques à l'architecture. Son attrait pratique réside dans une combinaison d'ingestion en ligne, de stockage 2 bits ou 4 bits, de persistance, d'identifiants externes stables, de prise en charge de la suppression, de recherche filtrée par liste d'autorisation et d'adaptateurs pour les frameworks RAG courants.
Il est important de le classer correctement. turbovec est une bibliothèque d'index, pas une base de données vectorielles hébergée ou un service de récupération complet. Il ne fournit pas à lui seul la réplication distribuée, le partitionnement multi-nœuds, les sauvegardes, l'authentification, l'administration des locataires, les APIs réseau, la recherche lexicale hybride, l'observabilité ou un plan de contrôle. Les équipes gagnent en contrôle local et en efficacité de mémoire en échange de la possession des préoccupations environnantes.
Comment fonctionne la compression TurboQuant
L’idée sous-jacente est qu’une rotation orthogonale aléatoire fait que les coordonnées des vecteurs unitaires de grande dimension suivent une distribution prévisible. turbovec sépare d'abord la norme de chaque vecteur de sa direction. Il applique une rotation aléatoire partagée, puis quantifie les coordonnées pivotées à l'aide de compartiments Lloyd–Max précalculés. Deux bits fournissent quatre valeurs par coordonnée ; quatre bits en fournissent seize. Les codes sont remplis de bits et une correction par vecteur supprime le rétrécissement systématique du produit interne introduit par la quantification.
Le projet ajoute l'étalonnage TQ+ : lors du premier ajout, il estime un décalage et une échelle pour chaque coordonnée à l'aide de quantiles empiriques, puis gèle ces valeurs pour des ingérations ultérieures. Ce n’est pas la même chose qu’une formation conventionnelle à la quantification de produits, mais le premier lot influence l’étalonnage. Un premier ajout minuscule ou non représentatif peut donc être une mauvaise initialisation de la production. Ensemencer l'index avec un échantillon représentatif et tester la dérive de distribution.
| Scène | Stocké ou calculé | Conséquence opérationnelle |
|---|---|---|
| Normaliser | Direction de l'unité plus norme d'origine | Préserve la magnitude tout en quantifiant la structure angulaire |
| Rotation aléatoire | Transformation orthogonale partagée | Rend les distributions de coordonnées prévisibles sur des données d'entrée arbitraires |
| TQ+ étalonnage | Décalage et échelle par coordonnées appris lors du premier ajout | Améliore le comportement fini/de faible dimension ; nécessite une initialisation représentative |
| Lloyd–Max quantification | Codes de coordonnées 2 bits ou 4 bits | Réduction importante de la mémoire avec perte de rappel dépendante de l'ensemble de données |
| Correction de longueur | Un scalaire par vecteur | Corrige les estimations du produit interne biaisées à la baisse |
| SIMD recherche | Requête pivotée et notation de table de recherche sur des codes compressés | Évite la décompression complète ; les performances dépendent de l'architecture du processeur |
Mathématiques de mémoire sans raccourci marketing
Un vecteur float32 de 1 536 dimensions utilise 6 144 octets pour les coordonnées brutes. Ses codes de coordonnées nécessitent 384 octets à 2 bits ou 768 octets à 4 bits avant les métadonnées. Il s’agit d’une réduction théorique de 16× ou 8× pour la charge utile coordonnée. Le titre du référentiel indique qu'un corpus float32 de 10 millions de documents occupant environ 31 Go peut contenir environ 4 Go ; cet exemple reflète une dimension et une représentation particulières et ne doit pas être généralisé à tous les corpus.
La planification de la capacité doit ajouter des ID externes, des valeurs de correction/norme par vecteur, des données d'étalonnage, l'alignement, la surcharge de l'allocateur, les emplacements supprimés, les métadonnées d'application, les tampons de requête et le magasin de documents d'origine. Les intégrations représentent rarement la totalité de la facture de mémoire RAG. Mesurez la taille de l’ensemble résident après avoir chargé l’index persistant réel et répondu aux requêtes simultanées.
Ce que API prend en charge
importer numpy en tant que np
à partir de turbovec importer IdMapIndex
index = IdMapIndex(dim=1536, bit_width=4)
index.add_with_ids(vectors.astype(np.float32), ids.astype(np.uint64))
scores, result_ids = index.search(query.astype(np.float32), k=10)
index.remove(document_id)
index.write("corpus.tvim")
restauré = IdMapIndex.load("corpus.tvim")Le Python API rejette délibérément les vecteurs non-float32 au lieu de les convertir silencieusement. Les ID stables sont importants car les emplacements internes peuvent changer après les suppressions et la maintenance. La persistance rend le redémarrage local pratique, mais les applications nécessitent toujours une publication atomique, des sommes de contrôle, une politique de sauvegarde/version et des tests de compatibilité entre les mises à niveau de bibliothèque.
La récupération filtrée est un différenciateur significatif
Pour une récupération multi-tenant, par fenêtre temporelle ou basée sur les autorisations, l'application peut d'abord produire un ensemble d'ID autorisés à partir de SQL, BM25, d'un service ACL ou d'un autre système, puis demander à turbovec de classer uniquement ces candidats. Le filtrage s'effectue à l'intérieur du chemin SIMD avec une granularité de bloc de 32 vecteurs. Les blocs vides peuvent être ignorés et les emplacements non autorisés sont rejetés avant l'insertion du tas, de sorte que les filtres sélectifs peuvent éviter une grande partie du travail de notation dense.
C'est mieux que de récupérer un top-k global et de rejeter les résultats non autorisés, qui peuvent renvoyer trop peu de documents valides et risquer de divulguer des informations de classement. Il incombe toujours à l'appelant de construire correctement la liste d'autorisation, de la lier au locataire authentifié et de tester les ensembles vides, minuscules, énormes et évoluant rapidement. N'utilisez jamais le filtrage des métadonnées comme seul contrôle d'autorisation lors de la récupération du document final.
Comment lire les benchmarks publiés
| Réclamation | Limite de test publiée | Ce qui reste à prouver |
|---|---|---|
| Rappel compétitif avec FAISS PQ | 100 000 vecteurs, k = 64 ; OpenAI cote 1536/3072 et GloVe cote 200 ; débit binaire adapté | Votre modèle d'intégration, distribution du corpus, k, étiquettes de métrique et de pertinence |
| 10 à 19 % plus rapide sur ARM | Apple M3 Max contre FAISS IndexPQFastScan dans les configurations de référentiel | Autres puces Apple, filtres de concurrence, d'état thermique et de production |
| Vitesse x86 compétitive | Xeon Platine 8481C ; gains signalés pour 4 bits, pertes modestes dans certains cas 2 bits | Votre génération de CPU, chemin AVX, cœurs, NUMA et lot de requêtes |
| Pas de formation/reconstruction | Quantificateur à distribution connue avec calibrage TQ+ en premier ajout et ajouts en ligne | Impact d’un premier lot non représentatif ou d’un changement de distribution important |
| La recherche filtrée évite la récupération excessive | Liste d'autorisation gérée dans le scoring de bloc et l'insertion de tas | Coût SQL/ACL de bout en bout et filtres non sélectifs dans le pire des cas |
La référence de comparaison est FAISS IndicePQ/IndexPQFastScan, pas tous les types d'index FAISS. La recherche exacte plate, HNSW, IVF-PQ, les index GPU et les bases de données gérées résolvent différents points sur la courbe de rappel, de latence, de mémoire et d'opérations. Reproduisez d'abord les références du référentiel, puis remplacez vos données et votre cible d'acceptation un facteur à la fois.
Un protocole d’évaluation RAG utile
- Geler les intégrations. Utilisez le modèle exact, la normalisation, la dimension et la convention de distance prévus pour la production.
- Créez une vérité terrain. Calculez les meilleurs voisins exacts avec une implémentation plate fiable et gérez séparément les jugements de pertinence des tâches.
- Testez les deux largeurs de bits. Comparez 2 bits et 4 bits avec float32 ou une recherche exacte, pas seulement les uns contre les autres.
- Stratifiez les requêtes. Incluez les cas courants, rares, multilingues, courts, longs, dupliqués et hors domaine.
- Ingestion d’exercice. Initialisez avec un lot représentatif, ajoutez des distributions ultérieures, supprimez des identifiants, conservez, rechargez et vérifiez le comportement déterministe.
- Filtres de référence. Mesurez l'absence de filtre et les listes autorisées à une couverture de 0 %, 0,1 %, 1 %, 10 %, 50 % et 100 %, y compris les dispositions de blocs contradictoires.
- Test de charge. Enregistrez la latence p50/p95/p99, le débit, l'utilisation du processeur, la mémoire résidente et le comportement de la queue en simultanéité réelle.
- Évaluez la réponse. Mesurez le rappel de récupération, la qualité du reclassement, l’exactitude des citations et le succès de la réponse finale. Les voisins approximatifs plus rapides n'ont de valeur que si le résultat de l'application survit.
Métriques de décision
| Métrique | Définition | Rapports suggérés |
|---|---|---|
| Rappel@k | Voisins top-k exacts récupérés par recherche approximative | Par tranche d'ensemble de données, largeur de bits et sélectivité du filtre |
| Rappel de tâche | Requêtes dont les pièces justificatives requises sont récupérées | Plus significatif que le seul chevauchement vecteur-voisin |
| Mémoire par vecteur | Traiter RSS delta / vecteurs consultables chargés | Inclure les identifiants, les emplacements supprimés et la surcharge des métadonnées |
| Latence de queue | Temps de requête de bout en bout p95/p99 | Avec une concurrence réaliste et un mélange de listes autorisées |
| Coût de mise à jour | Temps et mémoire maximale pour les ajouts, suppressions, sauvegardes et rechargements | Inclut le calibrage du premier ajout et la récupération après incident |
| Coût par requête acceptée | Infrastructure plus opérations d'ingénierie / résultats corrects des tâches | Comparez avec FAISS et les alternatives gérées |
Intégrations de framework
Le référentiel documente les adaptateurs pour LangChain, LlamaIndex, Haystack et Agno qui remplacent leurs magasins de référence en mémoire tout en conservant les interfaces familières. Cela peut accélérer une preuve de concept, mais « drop-in » fait référence à une surface logicielle publique – et non à une notation, un filtrage, une suppression, une persistance, un thread ou une sémantique d'échec identiques. Exécutez les tests de récupération de chaque framework et épinglez les versions compatibles avant le déploiement.
Alternatives
| Options | Préférez-le quand | Compromis |
|---|---|---|
| turbovec | La recherche locale en cours de processus, la compression extrême, les ajouts en ligne et le filtrage des listes d'autorisation s'adaptent à la charge de travail. | Vous possédez les contrôles de service, de réplication et opérationnels |
| FAISS | Vous avez besoin de choix d'indexation mature exact, FIV, PQ, HNSW ou GPU | La configuration et la formation peuvent être plus complexes ; la mémoire varie selon l'index |
| hnswlib | Un rappel élevé et une recherche de graphiques à faible latence sont plus importants qu'un stockage compact | La surcharge du graphique peut consommer beaucoup plus de mémoire |
| Qdrant, Weaviate ou Milvus | Un service réseau, des filtres de métadonnées, une réplication et des opérations sont requis | Plus d'infrastructure et de mémoire qu'une petite bibliothèque intégrée |
| Base de données vectorielles gérée | L'équipe souhaite une mise à l'échelle, des sauvegardes, une authentification et une assistance hébergées | Coût récurrent, résidence des données et dépendance aux fournisseurs |
| PostgreSQL avec pgvector | Les vecteurs doivent rester proches des données relationnelles et des opérations existantes | Peut ne pas correspondre à un index compressé spécialisé à grande échelle |
Limites et risques de production
- Une compression approximative peut modifier l'ordre du voisin le plus proche, en particulier en cas de largeur de bit agressive ou de faible dimension.
- Les noyaux spécifiques au processeur signifient que les résultats des tests ne doivent pas être transférés entre le matériel ARM, AVX2 et AVX-512.
- L'étalonnage du premier ajout, la modification des modèles d'intégration et la dérive du corpus nécessitent des tests de migration explicites.
- Le déploiement local maintient les vecteurs sous votre contrôle mais n'ajoute pas automatiquement le cryptage, le contrôle d'accès ou les sauvegardes sécurisées.
- Un crash en cours de processus affecte l'application hôte à moins que les limites du service et la stratégie de récupération ne soient délibérément conçues.
- Le projet évolue ; épingler les versions, inspecter les journaux de modifications/les conseils de sécurité et valider la compatibilité des index persistants.
Questions fréquemment posées
turbovec est-il une base de données vectorielle ?
Non, il s’agit d’une bibliothèque d’index vectoriels. Les applications doivent fournir des opérations de stockage de documents, de mise en réseau, d’autorisation, de réplication, de surveillance et de cycle de vie selon les besoins.
Cela nécessite-t-il une étape de formation hors ligne ?
Il évite la formation conventionnelle sur les livres de codes et prend en charge les ajouts en ligne. TQ+ calibre les valeurs par coordonnées lors du premier ajout, de sorte que le lot d'initialisation mérite toujours du soin.
Dois-je choisir 2 bits ou 4 bits ?
Utilisez 2 bits lorsque la mémoire est la contrainte contraignante et que votre rappel de tâche mesuré reste acceptable. Quatre bits achètent généralement plus de fidélité pour environ deux fois le stockage du code de coordonnées. Comparez les deux.
La recherche filtrée renforce-t-elle la sécurité des locataires ?
Il peut efficacement restreindre le classement à une liste verte. L'application doit créer la liste correcte et revérifier l'autorisation avant de renvoyer le contenu source.
Ses revendications de vitesse FAISS sont-elles universelles ?
Les résultats publiés couvrent le matériel nommé, les ensembles de données, les dimensions, les largeurs de bits et les configurations FAISS PQ/FastScan. Les résultats x86 2 bits incluent les cas où FAISS est plus rapide.
Peut-il être doté d'un espace d'air ?
L'index s'exécute localement et ne nécessite pas de service géré. Une pile RAG complète et isolée nécessite également des intégrations locales, des documents, la provenance du package/modèle et des mises à jour contrôlées.
Sources primaires
- turbovec référentiel officiel et documentation de référence
- Référence turbovec API
- Scripts et résultats de référence reproductibles
- TurboQuant document de recherche
- RaBitQ article cité pour la correction de longueur
- FAISS FastScan référence technique
- Forfait turbovec Python
- turbovec Rust caisse
Dernière révision le 25 juillet 2026. Les déclarations de performances s'appliquent à la configuration publiée du référentiel, sauf indication contraire. Reproduisez sur votre corpus, en intégrant le modèle, le matériel et la distribution des filtres avant adoption.
