Weaviate self-hosted : RAG + GraphQL — tutoriel 2026

Introduction

Parmi les bases de données vectorielles open source qui ont émergé ces dernières années, Weaviate occupe une position singulière : là où Qdrant mise sur la performance brute en Rust et Chroma sur la simplicité d’intégration Python, Weaviate a fait le pari d’une architecture modules-first. Concrètement, cela signifie que la vectorisation, la génération de texte et l’extraction d’entités ne sont pas des étapes externes à gérer dans votre code applicatif — elles sont déléguées à des modules branchés directement dans le moteur. Weaviate appelle ça les vectorizer modules et les generative modules.

Le résultat pratique est frappant : vous importez un document texte brut, Weaviate génère lui-même l’embedding via le module text2vec-ollama, l’indexe dans son graphe HNSW, et vous pouvez immédiatement interroger la base en langage naturel via une requête GraphQL nearText. Pas une ligne de code d’embedding à écrire. Et si vous voulez passer à la Retrieval Augmented Generation (RAG) — c’est-à-dire demander à un LLM de répondre en s’appuyant sur les documents récupérés — il suffit d’activer le module generative-ollama et d’ajouter un paramètre generate à votre requête GraphQL.

Ce tutoriel vous guide pas à pas sur un serveur Linux standard (ou un VPS), entièrement en self-hosted, sans dépendance cloud, sans clé API payante. À la fin, vous aurez une instance Weaviate opérationnelle qui vectorise et répond à des questions sur vos documents locaux, avec une stratégie de backup sur stockage compatible S3.

Prérequis

• Docker Engine 24+ et Docker Compose v2 installés (docs.docker.com/engine/install)
• Ollama installé sur la machine hôte (ollama.com) avec au moins un modèle d’embedding (ollama pull nomic-embed-text) et un LLM (ollama pull llama3)
• 2 Go de RAM minimum disponibles pour Weaviate seul ; 6 Go recommandés si Ollama tourne sur le même serveur
• Un accès réseau au port 8080 de votre serveur (Weaviate API) et au port 11434 (Ollama)
• Niveau attendu : intermédiaire — vous savez lire un docker-compose.yml et faire une requête HTTP
• Temps estimé : 30 à 45 minutes selon votre connexion pour tirer les images Docker

Étape 1 — Weaviate : l’approche modules-first

Avant de lancer la moindre commande, il est utile de comprendre pourquoi l’architecture de Weaviate diffère des autres vector databases. Dans la plupart des systèmes — Qdrant, Chroma, pgvector — le workflow classique est le suivant : votre application calcule un embedding avec un modèle (via sentence-transformers, OpenAI, Cohere…), puis envoie ce vecteur à la base de données pour indexation ou recherche. La base est « vecteur-agnostique » : elle ne sait pas comment le vecteur a été produit, elle ne fait que le stocker et le comparer.

Weaviate prend une décision architecturale différente. La base de données embarque la notion de module : un composant qui s’attache à une class d’objets et qui intercepte les opérations d’import et de recherche pour gérer la vectorisation à votre place. Quand vous configurez une class avec "vectorizer": "text2vec-ollama", chaque document importé dans cette class est automatiquement envoyé au module, qui appelle Ollama, récupère le vecteur, et l’associe à l’objet. Vous n’avez jamais à manipuler un tableau de floats dans votre code.

Cette philosophie a un coût — la configuration est un peu plus verbeuse qu’avec Chroma — mais elle offre un avantage majeur en équipe : le schéma déclare explicitement quel modèle d’embedding est utilisé pour quelle collection. Si dans six mois vous changez de modèle, vous modifiez la définition de la class, pas votre code d’ingestion. Pour des équipes de développeurs juniors ou des PME qui n’ont pas de ML engineer dédié, c’est un gain de maintenabilité considérable.

Weaviate expose également une interface GraphQL native — pas un wrapper, une implémentation GraphQL réelle avec introspection, playground intégré, et toute la richesse des filtres composés. C’est l’une des rares vector databases à avoir fait ce choix, et nous verrons à l’étape 5 pourquoi c’est particulièrement accessible pour des développeurs habitués aux API modernes.

Étape 2 — Déployer Weaviate avec Docker Compose et le module text2vec-ollama

Weaviate se déploie via l’image officielle semitechnologies/weaviate disponible sur Docker Hub. La configuration des modules se fait entièrement via des variables d’environnement passées au conteneur — il n’y a pas de fichier de configuration séparé à gérer. Créez un répertoire de travail et placez-y le fichier suivant.

# docker-compose.yml
version: '3.8'
services:
  weaviate:
    image: semitechnologies/weaviate:1.25.0
    restart: unless-stopped
    ports:
      - "8080:8080"   # API REST + GraphQL
      - "50051:50051" # gRPC (optionnel, performances accrues)
    volumes:
      - weaviate_data:/var/lib/weaviate
    environment:
      # Modules actifs (séparés par virgule)
      ENABLE_MODULES: 'text2vec-ollama,generative-ollama'

      # URL d'Ollama — host.docker.internal si Ollama tourne sur l'hôte
      OLLAMA_APIENDPOINT: 'http://host.docker.internal:11434'

      # Authentification désactivée pour usage local
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'

      # Taille du cluster (standalone = 1 nœud)
      CLUSTER_HOSTNAME: 'node1'

      # Persistence activée
      PERSISTENCE_DATA_PATH: '/var/lib/weaviate'

      # Modules de backup S3 (activé ici pour l'étape 7)
      ENABLE_MODULES: 'text2vec-ollama,generative-ollama,backup-s3'
      BACKUP_S3_BUCKET: 'mon-bucket-weaviate'
      BACKUP_S3_ENDPOINT: 'https://s3.amazonaws.com' # ou votre endpoint MinIO

    # Sur Linux, host.docker.internal n'est pas résolu par défaut
    extra_hosts:
      - "host.docker.internal:host-gateway"

volumes:
  weaviate_data:

Notez un point important : la ligne ENABLE_MODULES apparaît deux fois dans le YAML ci-dessus à titre illustratif — dans votre fichier final, conservez uniquement la seconde valeur qui inclut les trois modules. La variable OLLAMA_APIENDPOINT pointe vers host.docker.internal, un alias spécial Docker qui résout vers l’adresse IP de la machine hôte ; le bloc extra_hosts est nécessaire sur Linux pour que cet alias fonctionne. Lancez le service avec docker compose up -d, puis vérifiez que Weaviate est prêt en interrogeant son endpoint de readiness.

# Vérifier que Weaviate répond
curl http://localhost:8080/v1/meta | python3 -m json.tool

# La réponse doit inclure :
# "modules": { "text2vec-ollama": {...}, "generative-ollama": {...} }
# "version": "1.25.0"

Si vous voyez la version et la liste des modules dans la réponse JSON, Weaviate est opérationnel et a chargé les modules correctement. Si le champ modules est vide ou ne contient pas text2vec-ollama, c’est que la variable d’environnement ENABLE_MODULES n’a pas été prise en compte — vérifiez qu’il n’y a pas de doublon dans votre fichier Compose et relancez avec docker compose down && docker compose up -d.

Étape 3 — Créer une class avec vectorizer automatique

Dans Weaviate, le schéma est organisé en classes (l’équivalent des collections dans d’autres vector databases). Chaque class définit ses propriétés, son vectorizer, et les paramètres du module. On crée la class via l’API REST POST /v1/schema. Ici, on va créer une class Document destinée à stocker des extraits textuels de documents OHADA ou d’articles techniques, avec vectorisation automatique via nomic-embed-text d’Ollama.

curl -X POST http://localhost:8080/v1/schema \
  -H 'Content-Type: application/json' \
  -d '{
    "class": "Document",
    "description": "Extraits de documents textuels (OHADA, tutoriels, manuels)",
    "vectorizer": "text2vec-ollama",
    "moduleConfig": {
      "text2vec-ollama": {
        "model": "nomic-embed-text",
        "apiEndpoint": "http://host.docker.internal:11434"
      },
      "generative-ollama": {
        "model": "llama3",
        "apiEndpoint": "http://host.docker.internal:11434"
      }
    },
    "properties": [
      {
        "name": "texte",
        "dataType": ["text"],
        "description": "Contenu textuel du document",
        "moduleConfig": {
          "text2vec-ollama": { "skip": false, "vectorizePropertyName": false }
        }
      },
      {
        "name": "source",
        "dataType": ["text"],
        "description": "Origine du document (nom de fichier, URL, référence)",
        "moduleConfig": {
          "text2vec-ollama": { "skip": true }
        }
      },
      {
        "name": "dateCreation",
        "dataType": ["date"],
        "description": "Date de création ou de mise à jour"
      }
    ]
  }'

Plusieurs détails méritent attention. La propriété texte a "skip": false — c’est elle qui sera vectorisée. La propriété source a "skip": true : son contenu n’entre pas dans le calcul de l’embedding, ce qui évite que le nom de fichier ne pollue la représentation sémantique du document. Le paramètre "vectorizePropertyName": false empêche Weaviate d’ajouter le nom de la propriété au texte vectorisé — comportement souhaitable dans la plupart des cas. Une fois la requête envoyée, la réponse HTTP 200 confirme la création de la class. Vous pouvez vérifier avec GET /v1/schema.

Étape 4 — Importer des documents et laisser Weaviate générer les embeddings

C’est ici que la philosophie modules-first de Weaviate prend tout son sens. Pour importer un document, vous envoyez simplement le texte brut via POST /v1/objects — pas de pré-calcul d’embedding, pas d’appel à un modèle externe depuis votre code. Weaviate intercepte l’import, envoie le champ texte au module text2vec-ollama, récupère le vecteur, et stocke le tout. Voici un exemple d’import de trois extraits représentatifs d’un corpus OHADA.

# Import d'un premier document
curl -X POST http://localhost:8080/v1/objects \
  -H 'Content-Type: application/json' \
  -d '{
    "class": "Document",
    "properties": {
      "texte": "L'Acte Uniforme relatif au droit commercial général définit le fonds de commerce comme l'ensemble des éléments corporels et incorporels affectés à l'exploitation d'une activité commerciale.",
      "source": "OHADA-AUDCG-Art1.pdf",
      "dateCreation": "2010-01-15T00:00:00Z"
    }
  }'

# Import en batch (plus efficace pour un grand corpus)
curl -X POST http://localhost:8080/v1/batch/objects \
  -H 'Content-Type: application/json' \
  -d '{
    "objects": [
      {
        "class": "Document",
        "properties": {
          "texte": "Le registre du commerce et du crédit mobilier (RCCM) est l'organisme chargé de l'immatriculation des commerçants et des sociétés commerciales dans l'espace OHADA.",
          "source": "OHADA-RCCM-Guide.pdf",
          "dateCreation": "2017-03-01T00:00:00Z"
        }
      },
      {
        "class": "Document",
        "properties": {
          "texte": "La Société à Responsabilité Limitée (SARL) dans l'espace OHADA peut être constituée par une ou plusieurs personnes. Le capital social minimum est fixé à un (1) franc CFA.",
          "source": "OHADA-AUSGIE-SARL.pdf",
          "dateCreation": "2014-09-22T00:00:00Z"
        }
      }
    ]
  }'

L’API batch (/v1/batch/objects) est fortement recommandée dès que vous avez plus d’une dizaine de documents à importer. Elle réduit le nombre d’aller-retours réseau et optimise le parallélisme côté module. Pour un corpus de plusieurs milliers de documents, vous pouvez envoyer des lots de 100 à 200 objets à la fois. La réponse de l’API batch retourne un tableau indiquant, pour chaque objet, si l’import a réussi ou échoué — vérifiez que tous les champs result.status valent "SUCCESS" avant de passer à la suite.

Étape 5 — Requête GraphQL nearText : la recherche sémantique en action

Weaviate expose son interface de recherche via un endpoint GraphQL unique : POST /v1/graphql. Le point fort est que vous pouvez tester vos requêtes directement dans l’interface graphique intégrée, accessible sur http://localhost:8080/v1/graphql via le GraphQL Playground. Aucun outil externe nécessaire. Pour une recherche sémantique, l’opérateur clé est nearText : vous lui passez un ou plusieurs concepts en langage naturel, et Weaviate vectorise ces concepts via le même module que celui de la class cible, puis cherche les objets les plus proches dans l’espace vectoriel.

{
  Get {
    Document(
      nearText: {
        concepts: ["création d'entreprise société responsabilité limitée"]
        certainty: 0.7
      }
      limit: 3
    ) {
      texte
      source
      _additional {
        certainty
        distance
        id
      }
    }
  }
}

Via cURL, la même requête s’envoie ainsi :

curl -X POST http://localhost:8080/v1/graphql \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "{ Get { Document( nearText: { concepts: [\"création d entreprise SARL\"] certainty: 0.7 } limit: 3 ) { texte source _additional { certainty id } } } }"
  }'

La réponse retourne les trois documents dont la représentation vectorielle est la plus proche du concept « création d’entreprise SARL ». Le champ _additional.certainty est un score de pertinence entre 0 et 1 — plus il est proche de 1, plus le document est sémantiquement proche de la requête. Vous pouvez ajuster le paramètre certainty dans le filtre pour n’obtenir que des résultats de haute confiance. Vous pouvez aussi combiner nearText avec des filtres where sur les propriétés scalaires — par exemple, ne retourner que des documents dont la source contient « OHADA » et dont la date est postérieure à 2010.

Étape 6 — Generative search avec generative-ollama : le RAG complet

La recherche sémantique nearText retourne des documents pertinents — c’est la phase de retrieval. La generation consiste à passer ces documents à un LLM pour qu’il rédige une réponse synthétique en s’appuyant dessus. Dans Weaviate, cette chaîne RAG est entièrement déclarative : vous ajoutez un paramètre generate à votre requête GraphQL existante, et le module generative-ollama s’occupe d’appeler Llama 3 (ou tout autre LLM Ollama) avec les documents récupérés comme contexte.

{
  Get {
    Document(
      nearText: {
        concepts: ["capital minimum pour créer une SARL en Afrique"]
        certainty: 0.65
      }
      limit: 5
    ) {
      texte
      source
      _additional {
        generate(
          singleResult: {
            prompt: "En te basant uniquement sur les extraits fournis, réponds en français à cette question : quel est le capital minimum pour créer une SARL dans l'espace OHADA ? Cite la source si disponible."
          }
        ) {
          singleResult
          error
        }
      }
    }
  }
}

Le paramètre singleResult demande à Weaviate de passer l’ensemble des 5 documents récupérés à Ollama en une seule génération, avec le prompt que vous définissez. Il existe aussi un mode groupedResult qui génère une réponse agrégée à partir de tous les documents. Le champ error dans _additional.generate est crucial : en cas d’échec d’Ollama (timeout, modèle non chargé, contexte trop long), il contiendra le message d’erreur sans faire planter toute la requête. Pensez à le vérifier systématiquement dans votre code applicatif avant d’afficher la réponse à l’utilisateur final.

Étape 7 — Backup vers stockage S3 (ou MinIO)

Weaviate propose un mécanisme de backup natif via l’API REST /v1/backups. Avec le module backup-s3 activé dans notre Compose (étape 2), vous pouvez déclencher un backup complet de toutes les classes vers un bucket S3 ou un serveur MinIO self-hosted. C’est la stratégie de sauvegarde recommandée en production, car elle est atomique et ne nécessite pas d’arrêter Weaviate.

# Créer un backup nommé "backup-2026-04-27" vers S3
curl -X POST http://localhost:8080/v1/backups/s3 \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "backup-2026-04-27",
    "include": ["Document"]
  }'

# Vérifier le statut du backup
curl http://localhost:8080/v1/backups/s3/backup-2026-04-27

# Restaurer depuis un backup
curl -X POST http://localhost:8080/v1/backups/s3/backup-2026-04-27/restore \
  -H 'Content-Type: application/json' \
  -d '{ "include": ["Document"] }'

La réponse à la requête de création retourne immédiatement un objet avec "status": "STARTED". Le backup s’exécute en arrière-plan — interrogez le endpoint de statut jusqu’à obtenir "status": "SUCCESS" avant de considérer la sauvegarde terminée. Pour un usage avec MinIO self-hosted, remplacez BACKUP_S3_ENDPOINT par l’URL de votre instance MinIO (ex: http://minio.local:9000) et ajoutez BACKUP_S3_USE_SSL: 'false' si MinIO tourne en HTTP. Pour automatiser, un simple cron qui appelle le endpoint de backup chaque nuit suffit pour la plupart des usages PME.

Erreurs fréquentes

Adaptation au contexte ouest-africain

RAG OHADA 100 % local avec Weaviate + Ollama

L’un des cas d’usage les plus pertinents pour Weaviate en Afrique de l’Ouest est la construction d’un assistant juridique RAG sur le corpus OHADA — les Actes Uniformes représentent plusieurs milliers de pages de texte structuré, et les entreprises locales (cabinets d’avocats, DRH, comptables) posent régulièrement des questions du type « quel est le délai légal pour contester une décision de l’assemblée générale ? » ou « quelles sont les obligations de publication du bilan pour une SA dans l’espace OHADA ? ».

La combinaison Weaviate + Ollama répond exactement à ce besoin : tout tourne en local, les documents ne quittent jamais le serveur (confidentialité préservée), et le coût marginal d’une requête est nul une fois le serveur déployé. Sur un VPS à 15-20 €/mois chez Hetzner ou OVH (4 vCPU, 8 Go RAM), vous pouvez faire tourner Weaviate avec le module text2vec-ollama (nomic-embed-text, très léger) et Llama 3 8B quantisé Q4 pour les réponses — configuration testée et viable pour une charge de quelques dizaines de requêtes par jour.

GraphQL Playground accessible aux développeurs débutants

Un atout souvent sous-estimé de Weaviate pour les équipes de développement en Afrique de l’Ouest est son interface GraphQL Playground intégrée, accessible directement sur http://votre-serveur:8080/v1/graphql. Les développeurs juniors qui n’ont jamais manipulé de vector database peuvent explorer le schéma, construire des requêtes avec l’autocomplétion, et voir les résultats immédiatement — sans installer un client spécialisé, sans configurer Postman, sans comprendre la structure des vecteurs. Cette accessibilité est particulièrement précieuse dans les contextes de formation (universités, centres de formation comme ITSkillsCenter) où le temps de prise en main doit être minimal.

Intégration avec ERPNext via l’API REST

ERPNext est l’ERP open source le plus déployé en Afrique de l’Ouest pour la gestion PME. Une intégration Weaviate ↔ ERPNext permet d’enrichir les recherches dans les modules Documentation, Support, ou HR : les tickets de support sont indexés dans Weaviate au fur et à mesure de leur création (via un hook Frappe côté ERPNext), et un widget de recherche sémantique permet aux agents de retrouver des tickets similaires ou des réponses passées. L’intégration se fait via l’API REST standard de Weaviate (POST /v1/batch/objects) appelée depuis un document hook Python dans ERPNext — pas besoin de bibliothèque cliente spécifique, un simple requests.post() suffit.

Pour les connexions à faible bande passante fréquentes en zone sahélienne, pensez à activer le mode gRPC de Weaviate (port 50051) pour les imports batch : les performances sont nettement supérieures grâce à la sérialisation Protocol Buffers, surtout pour des lots de 50+ documents. La bibliothèque cliente Python officielle (pip install weaviate-client) utilise gRPC par défaut depuis la v4.

Tutoriels frères

• Qdrant self-hosted : déployer et requêter une vector DB Rust ultra-rapide — même pipeline RAG, mais avec l’API REST/gRPC de Qdrant et une comparaison de performances
• Chroma self-hosted : RAG Python en 30 minutes avec LangChain — l’alternative la plus simple pour les projets Python purs, sans GraphQL ni modules
• pgvector : recherche sémantique dans PostgreSQL sans infrastructure dédiée — idéal si votre stack tourne déjà sur PostgreSQL et que vous ne voulez pas ajouter un nouveau service

Pour aller plus loin

• Retour au pilier : Vector DB self-hosted 2026 : Qdrant, Weaviate, Chroma, Milvus — comparatif complet des quatre solutions
• Documentation officielle : weaviate.io/developers/weaviate — référence complète des modules, de l’API GraphQL et des options de configuration
• Recettes officielles : weaviate.io/developers/weaviate/starter-guides — guides de démarrage rapide pour Python, TypeScript et Go
• Prochaine étape dans le cluster : Milvus self-hosted sur Kubernetes — quand votre corpus dépasse 10 M de vecteurs et nécessite une architecture distribuée

FAQ