Installer un environnement de développement local (stack RAG)

Ce tutoriel vous fait monter, de zéro, un environnement de dev pour une application web accompagnée d'un cœur RAG (recherche sémantique par vecteurs). À la fin, vous aurez indexé un petit corpus et obtenu une réponse à une recherche. On avance par petites étapes, chacune vérifiable.

Public : vous savez ouvrir un terminal et lancer quelques commandes. Aucune connaissance préalable du RAG n'est requise.

Ce que vous allez construire

Trois briques qui coopèrent, comme en production :

L'index et les vecteurs sont des artefacts dérivés : on ne les versionne pas, on les régénère avec une commande d'ingestion.

Pourquoi un environnement Linux (même sous Windows)

Le cœur RAG charge une extension SQLite au moment de l'exécution PHP. Ce chargement d'extension est fiable sous Linux et fragile en Windows natif. Pour éviter un environnement de dev qui diverge de la production, on travaille dans un Linux : soit une machine/VM Linux, soit un sous-système Linux sous Windows. Toute la suite se déroule dans un terminal Linux.

Étape 1 — Préparer le système

Dans votre terminal Linux, mettez le système à jour :

sudo apt update && sudo apt upgrade -y

Sous Windows, installez au préalable le sous-système Linux via votre méthode habituelle, puis ouvrez son terminal.

Étape 2 — Installer PHP et les extensions SQLite

Visez une version de PHP alignée sur celle de votre production. Installez PHP et les extensions nécessaires (dont SQLite), plus les outils de base :

sudo apt install -y php-cli php-sqlite3 php-mbstring php-xml \
  php-curl php-intl php-zip unzip git

Si votre distribution ne propose pas la version PHP cible, ajoutez un dépôt PHP tiers reconnu avant d'installer, en précisant explicitement la version voulue.

Vérifiez que les extensions SQLite indispensables au RAG sont bien chargées :

php -m | grep -E 'pdo_sqlite|sqlite3'
php --version

Vous devez voir pdo_sqlite et sqlite3 listés. Installez enfin le gestionnaire de dépendances PHP (Composer) :

sudo apt install -y composer

Étape 3 — Installer l'extension vectorielle SQLite

La recherche kNN (plus proches voisins) exige une extension vectorielle chargeable dans SQLite. Elle ne s'installe pas via le gestionnaire de paquets : on récupère la release « loadable » correspondant à votre OS/architecture, puis on dépose la bibliothèque partagée à un emplacement stable.

sudo mkdir -p <REPERTOIRE_EXTENSIONS>
cd /tmp
# récupérer l'archive « loadable » adaptée à votre OS/arch depuis le dépôt officiel de l'extension
tar xzf <ARCHIVE_TELECHARGEE>.tar.gz
sudo cp <FICHIER_.so> <REPERTOIRE_EXTENSIONS>/

Retenez le chemin complet de cette bibliothèque : vous le pointerez dans la configuration (Étape 6). Sa validité réelle sera confirmée à l'ingestion (Étape 7).

Point clé : la recherche kNN exige l'extension chargée dans PHP. Il n'y a pas de repli hors extension.

Étape 4 — Lancer le microservice d'embeddings

Le microservice reçoit du texte et renvoie des vecteurs. Le plus simple est de le lancer via conteneur.

docker compose up -d embeddings
curl http://127.0.0.1:<PORT_EMBEDDINGS>/health

Une réponse type {"status":"ok", ...} indique que le service est prêt.

Premier démarrage lent : le service télécharge un modèle (plusieurs centaines de Mo à ~1 Go). Montez un volume de cache pour ne pas re-télécharger à chaque redémarrage.

Alternative sans conteneur : créer un environnement virtuel Python, installer les dépendances, puis lancer le serviceur.

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn app:app --host 127.0.0.1 --port <PORT_EMBEDDINGS>

Dans tous les cas, le service écoute en local uniquement — jamais exposé publiquement.

Étape 5 — Orchestrer en « une commande » (optionnel mais recommandé)

Un fichier compose.yaml à la racine de l'app permet de lever le microservice d'un coup, avec cache de modèle persistant et sonde de santé :

services:
  embeddings:
    image: <IMAGE_MICROSERVICE_EMBEDDINGS>
    ports:
      - "127.0.0.1:<PORT_EMBEDDINGS>:<PORT_EMBEDDINGS>"
    volumes:
      - hf-cache:<CHEMIN_CACHE_MODELE>   # persiste le modèle entre deux démarrages
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://127.0.0.1:<PORT_EMBEDDINGS>/health"]
      interval: 10s
      timeout: 3s
      retries: 5

volumes:
  hf-cache:

docker compose up -d

Le service est prêt quand la sonde /health passe au vert.

Étape 6 — Configurer l'application

Installez les dépendances et créez votre fichier d'environnement local :

cd <REPERTOIRE_APP>
composer install
cp .env .env.local

Renseignez les variables RAG dans .env.local (mêmes clés qu'en production) :

RAG_EMBEDDING_URL=http://127.0.0.1:<PORT_EMBEDDINGS>
RAG_DB_PATH=%kernel.project_dir%/var/rag/index.sqlite
RAG_SQLITE_VEC_PATH=<CHEMIN_EXTENSION_VECTORIELLE>

Les réglages plus fins (modèle, dimension, taille des chunks, k de récupération, racine du corpus) vivent dans la configuration du bundle RAG. Aucune clé de fournisseur LLM n'est nécessaire en local pour la partie récupération seule.

Fournir un corpus

Le RAG a besoin de documents à indexer. Placez un dépôt/dossier de documentation à l'emplacement attendu comme racine du corpus :

git clone <URL_CORPUS_DOC> docs/

Étape 7 — Amorcer l'index et faire une première recherche

Microservice up (/health OK), lancez le diagnostic, l'ingestion, puis une recherche :

php bin/console app:rag:stats                # diagnostic (index + microservice)
php bin/console app:rag:ingest               # construit l'index vectoriel
php bin/console app:rag:search "votre requête"   # vérifie la recherche kNN

Si la recherche renvoie des résultats pertinents, votre stack fonctionne. L'index vit dans var/rag/ (non versionné). Pour repartir de zéro :

rm -rf var/rag/* && php bin/console app:rag:ingest --full

Étape 8 — Lancer l'application

symfony serve -d          # ou : php -S 127.0.0.1:<PORT_APP> -t public/

Ouvrez l'app sur http://127.0.0.1:<PORT_APP>. Une page d'administration RAG affiche l'état du système ; en cas de microservice indisponible, l'app reste debout en mode dégradé (bannière « index indisponible »).

Base de données : pour la recherche RAG en ligne de commande, aucune base applicative n'est requise. Elle ne devient nécessaire que si vous voulez tester l'UI authentifiée (création d'un admin de dev, migrations). C'est une étape facultative pour ce tutoriel.

Récapitulatif « machine neuve »

# une fois : Linux + PHP (Étapes 1-2), extension vectorielle (Étape 3)
docker compose up -d                       # microservice (Étapes 4-5)
cd <REPERTOIRE_APP> && composer install
cp .env .env.local                         # + variables RAG (Étape 6)
git clone <URL_CORPUS_DOC> docs/
php bin/console app:rag:ingest             # amorçage (Étape 7)
symfony serve -d                           # go (Étape 8)

Dépannage