Introduction
Weaviate est une base de données vectorielle open-source conçue pour la recherche sémantique et les applications d'IA. En 2026, son adoption pour les systèmes RAG et la recherche hybride exige une maîtrise des déploiements production. Ce tutoriel vous guide pas à pas pour configurer un cluster scalable, gérer les modules et optimiser les performances. Vous apprendrez à éviter les pièges courants tout en construisant une solution robuste et maintenable.
Prérequis
- Docker et Docker Compose v2.20+
- Python 3.11+ avec connaissance de Pydantic
- Compte OpenAI ou clé API pour les embeddings
- Notions avancées de vector embeddings et de schémas JSON
Configuration Docker Compose
version: '3.8'
services:
weaviate:
image: semitechnologies/weaviate:1.26.0
ports:
- "8080:8080"
- "50051:50051"
environment:
QUERY_DEFAULTS_LIMIT: 25
AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
ENABLE_MODULES: 'text2vec-openai,generative-openai,qna-openai'
CLUSTER_HOSTNAME: 'node1'
volumes:
- weaviate_data:/var/lib/weaviate
volumes:
weaviate_data:Ce fichier définit un déploiement Weaviate avec les modules OpenAI activés. Les variables d'environnement activent l'authentification et la persistance. Adaptez le hostname pour un cluster multi-nœuds.
Lancement du conteneur
docker compose up -d
sleep 10
curl http://localhost:8080/v1/metaLance le conteneur en arrière-plan et vérifie que l'API Weaviate répond. Le sleep permet d'attendre le démarrage complet du service.
Client Python et connexion
import weaviate
from weaviate.classes.init import Auth
client = weaviate.connect_to_local(
host="localhost",
port=8080,
grpc_port=50051,
)
print(client.is_ready())
client.close()Connexion via le client officiel Python avec support gRPC. Toujours vérifier is_ready() avant toute opération et fermer la connexion proprement.
Création du schéma Article
from weaviate.classes.config import Configure, Property, DataType
client.collections.create(
name="Article",
vectorizer_config=Configure.Vectorizer.text2vec_openai(
model="text-embedding-3-small"
),
properties=[
Property(name="title", data_type=DataType.TEXT),
Property(name="content", data_type=DataType.TEXT),
Property(name="url", data_type=DataType.TEXT, skip_vectorization=True)
]
)Crée une collection avec vectorisation automatique via OpenAI. Le champ url est exclu de la vectorisation pour optimiser les coûts.
Ingestion de données
import json
with client.batch.dynamic() as batch:
for item in json.load(open("articles.json")):
batch.add_object(
collection="Article",
properties=item,
)
print("Ingestion terminée")Utilise le batch dynamique pour ingérer efficacement de gros volumes. Évitez les appels individuels en production.
Requête hybride avancée
from weaviate.classes.query import HybridFusion
response = client.collections.get("Article").query.hybrid(
query="intelligence artificielle",
alpha=0.75,
fusion_type=HybridFusion.RELATIVE_SCORE,
limit=10,
return_properties=["title", "url"]
)
for obj in response.objects:
print(obj.properties)Requête hybride combinant recherche vectorielle et BM25. Le paramètre alpha contrôle l'équilibre entre les deux approches.
Bonnes pratiques
- Toujours activer la persistance et configurer des sauvegardes régulières
- Utiliser des modèles d'embeddings cohérents entre ingestion et recherche
- Monitorer la mémoire et le CPU via les métriques Prometheus
- Limiter la taille des objets et utiliser des références pour les relations
- Versionner les schémas et tester les migrations en environnement de staging
Erreurs courantes à éviter
- Oublier d'activer les modules nécessaires dans docker-compose
- Ingérer sans batching sur des datasets volumineux
- Utiliser des requêtes vectorielles sans indexation préalable
- Négliger la configuration des timeouts gRPC en production
Pour aller plus loin
Explorez les modules de replication et les filtres géospatiaux. Découvrez nos formations Learni sur les bases vectorielles.