Aller au contenu

Démarrage (Local & Pilote)

Objectif du guide

Ce guide vous permet de déployer un POC SalamBot fonctionnel en moins de 30 minutes. À la fin, vous aurez :

  • Une stack SalamBot complète (Webchat + Gateway + Orchestrateur + NLU + RAG + LLM)
  • Un tenant configuré (acme) avec locale fr-MA
  • Une base de connaissance initialisée avec des FAQ de démonstration
  • Un test réussi via Webchat avec message Darija/Arabizi

Prérequis

Versions minimales requises :

  • Docker : 20.10+
  • Docker Compose : 2.0+
  • Git : 2.30+
  • Make (optionnel, pour raccourcis)

Systèmes supportés : macOS, Linux, Windows WSL2

Cloner le projet & structure

# Cloner le dépôt
git clone https://github.com/salambot/salambot.git
cd salambot

Structure des dossiers principaux :

salambot/
├── docker-compose.yml          # Stack complète
├── config/
│   ├── tenants/                # Configurations par tenant
│   └── models/                 # Modèles NLU/LLM
├── data/
│   ├── knowledge-base/         # FAQ et documents
│   └── logs/                   # Logs applicatifs
├── scripts/
│   └── seed-kb.sh             # Script d'initialisation KB
└── webchat/                    # Interface utilisateur

Configuration rapide du tenant

Créez le fichier de configuration pour le tenant acme :

# config/tenants/acme.yml
tenant: acme
locale: fr-MA
region: ma-central

# Canaux activés
channels:
  webchat:
    enabled: true
    theme: salambot-default

# Modèles par défaut
models:
  nlu: salambot-nlu-v2
  llm: auto
  embedding: multilingual-e5-base

# Sécurité
security:
  pii_masking: true
  data_retention_days: 90

Variables d'environnement :

# Créer le fichier .env
cat > .env << EOF
TENANT=acme
LOCALE=fr-MA
LLM_API_KEY=YOUR_API_KEY
LLM_BASE_URL=http://localhost:8000
MODEL=llama3-8b
# OPENAI_API_KEY=YOUR_OPENAI_KEY  # Option pour OpenAI
LOG_LEVEL=info
ENV=development
EOF

WARNING : Remplacez YOUR_API_KEY par votre clé LLM réelle (ou configurez OPENAI_API_KEY pour OpenAI).

Démarrage de la stack

# Démarrer tous les services
docker compose up -d

# Vérifier que tous les conteneurs sont actifs
docker compose ps

Services démarrés :

  • Gateway : localhost:8080 (API principale)
  • Webchat : localhost:3000 (Interface utilisateur)
  • Orchestrateur : localhost:8081 (Coordination des flux)
  • NLU : localhost:8082 (Compréhension du langage)
  • RAG : localhost:8083 (Recherche documentaire)
  • Observabilité : localhost:3001 (Métriques et traces)

Remarque : les ports exacts peuvent varier ; se référer au docker-compose.yml fourni.

Workflow de déploiement

Le diagramme suivant illustre les étapes automatisées du déploiement :

flowchart TD
    START[🚀 docker compose up -d] --> PULL[📥 Pull des images Docker]
    PULL --> NETWORK[🌐 Création réseau salambot]
    NETWORK --> VOLUMES[💾 Création volumes persistants]

    VOLUMES --> GATEWAY_START[⚡ Démarrage Gateway:8080]
    VOLUMES --> ORCH_START[⚡ Démarrage Orchestrateur:8081]
    VOLUMES --> NLU_START[⚡ Démarrage NLU:8082]
    VOLUMES --> RAG_START[⚡ Démarrage RAG:8083]
    VOLUMES --> OBS_START[⚡ Démarrage Observabilité:3001]

    GATEWAY_START --> GATEWAY_HEALTH{Gateway healthy?}
    ORCH_START --> ORCH_HEALTH{Orchestrateur healthy?}
    NLU_START --> NLU_HEALTH{NLU healthy?}
    RAG_START --> RAG_HEALTH{RAG healthy?}
    OBS_START --> OBS_HEALTH{Observabilité healthy?}

    GATEWAY_HEALTH -->|✅ Oui| GATEWAY_READY[Gateway prêt]
    GATEWAY_HEALTH -->|❌ Non| GATEWAY_RETRY[Retry 30s]
    GATEWAY_RETRY --> GATEWAY_HEALTH

    ORCH_HEALTH -->|✅ Oui| ORCH_READY[Orchestrateur prêt]
    ORCH_HEALTH -->|❌ Non| ORCH_RETRY[Retry 30s]
    ORCH_RETRY --> ORCH_HEALTH

    NLU_HEALTH -->|✅ Oui| NLU_READY[NLU prêt]
    NLU_HEALTH -->|❌ Non| NLU_RETRY[Retry 30s]
    NLU_RETRY --> NLU_HEALTH

    RAG_HEALTH -->|✅ Oui| RAG_READY[RAG prêt]
    RAG_HEALTH -->|❌ Non| RAG_RETRY[Retry 30s]
    RAG_RETRY --> RAG_HEALTH

    OBS_HEALTH -->|✅ Oui| OBS_READY[Observabilité prête]
    OBS_HEALTH -->|❌ Non| OBS_RETRY[Retry 30s]
    OBS_RETRY --> OBS_HEALTH

    GATEWAY_READY --> SERVICES_CHECK{Tous services OK?}
    ORCH_READY --> SERVICES_CHECK
    NLU_READY --> SERVICES_CHECK
    RAG_READY --> SERVICES_CHECK
    OBS_READY --> SERVICES_CHECK

    SERVICES_CHECK -->|✅ Oui| WEBCHAT_START[🌐 Démarrage Webchat:3000]
    SERVICES_CHECK -->|❌ Non| WAIT_SERVICES[⏱️ Attendre services]
    WAIT_SERVICES --> SERVICES_CHECK

    WEBCHAT_START --> WEBCHAT_HEALTH{Webchat healthy?}
    WEBCHAT_HEALTH -->|✅ Oui| READY[🎉 Stack prête pour tests]
    WEBCHAT_HEALTH -->|❌ Non| WEBCHAT_RETRY[Retry 15s]
    WEBCHAT_RETRY --> WEBCHAT_HEALTH

    READY --> SEED_KB[📚 Optionnel: seed-kb.sh]
    SEED_KB --> TEST[🧪 Tests via Webchat]

    style START fill:#4caf50
    style READY fill:#4caf50
    style TEST fill:#2196f3
    style GATEWAY_RETRY fill:#ff9800
    style ORCH_RETRY fill:#ff9800
    style NLU_RETRY fill:#ff9800
    style RAG_RETRY fill:#ff9800
    style OBS_RETRY fill:#ff9800
    style WEBCHAT_RETRY fill:#ff9800

Initialisation de la base de connaissance

# Charger les FAQ de démonstration
./scripts/seed-kb.sh --tenant=acme --locale=fr-MA

# Vérifier l'indexation
curl -X GET "http://localhost:8083/health" | jq '.knowledge_base.documents'

Fichiers FAQ inclus :

  • data/knowledge-base/acme/faq-services-publics.md
  • data/knowledge-base/acme/faq-procedures-administratives.md
  • data/knowledge-base/acme/faq-darija-expressions.md

Test rapide via Webchat

  1. Ouvrir l'interface : http://localhost:3000

  2. Message de test (Darija/Arabizi) :

kifach ndir demande carte identité?
  1. Réponse attendue :
Pour faire une demande de carte d'identité, vous devez :
1. Vous rendre à la commune avec les documents requis
2. Remplir le formulaire de demande
3. Payer les frais administratifs selon la commune
...

Exemple d'envelope JSON (schema_version=1.0) :

NOTE : language accepte les valeurs officielles SalamBot : fr, ar, en, darija_arabizi, darija_arabic (cf. Concepts/composants).

{
  "schema_version": "1.0",
  "tenant": "acme",
  "channel": "webchat",
  "message_id": "tst_001",
  "correlation_id": "corr_tst_001",
  "timestamp": "2025-08-14T10:00:00Z",
  "locale": "fr-MA",
  "data": {
    "user_text": "kifach ndir demande carte identité?",
    "language": "darija_arabizi"
  }
}

Flux de traitement

sequenceDiagram
    participant U as User
    participant W as Webchat
    participant G as Gateway
    participant O as Orchestrateur
    participant N as NLU
    participant R as RAG
    participant L as LLM

    U->>W: "kifach ndir demande carte identité?"
    W->>G: POST /chat (envelope v1.0)
    G->>O: Route vers tenant acme
    O->>N: Analyse intention + entités
    N-->>O: Intent: demande_procedure
    O->>R: Recherche documents pertinents
    R-->>O: FAQ carte identité
    O->>L: Génération réponse contextualisée
    L-->>O: Réponse structurée
    O-->>G: Envelope de réponse
    G-->>W: JSON response
    W-->>U: Affichage réponse

Observabilité minimale

Métriques p95 de référence :

  • Ingestion : ≤ 150ms
  • NLU : ≤ 200ms
  • Retrieval (RAG) : ≤ 500ms
  • TTFB LLM : ≤ 600ms
  • End-to-end : ≤ 2500ms

Accès aux métriques :

# Logs en temps réel
docker compose logs -f gateway orchestrateur

# Dashboard Observabilité
xdg-open http://localhost:3001  # Linux
# macOS: open http://localhost:3001
# Windows (PowerShell): start http://localhost:3001

# Métriques Prometheus
curl http://localhost:9090/metrics | grep salambot_latency_p95

TIP : Consultez Observabilité pour l'observabilité avancée.

Sécurité & PII

Rappels de base :

  • ✅ Clés API : Stockées dans .env, jamais committées
  • ✅ Masquage PII : Activé par défaut (pii_masking: true)
  • ✅ Données de démo : Aucune donnée personnelle réelle
  • ✅ Chiffrement : Réseau Docker isolé en local ; TLS 1.3 recommandé/enforcé en production
  • ✅ Rétention : 90 jours par défaut, configurable par tenant

Vérification du masquage PII :

# Test avec numéro de téléphone
curl -X POST http://localhost:8080/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Mon numéro est 0612345678"}'

# Réponse attendue : numéro masqué dans les logs

Nettoyage/Shutdown

# Arrêt propre des services
docker compose down

# Suppression complète (conteneurs + volumes + réseaux)
docker compose down -v --remove-orphans

# Nettoyage des images (optionnel)
docker system prune -f

Dépannage

Ports occupés

Erreur : port 3000 already in use

Solution :

# Identifier le processus
lsof -i :3000
# Tuer le processus ou changer le port dans docker-compose.yml

Mémoire insuffisante

Erreur : OOMKilled dans les logs

Solution :

# Augmenter la mémoire Docker (8GB minimum recommandé)
# Ou réduire les modèles dans config/tenants/acme.yml

Erreurs de modèles

Erreur : Model not found: <model_name>

Solution :

# Vérifier la configuration LLM générique
echo $LLM_API_KEY
echo $LLM_BASE_URL
echo $MODEL

# (Option) si vous utilisez OpenAI
echo $OPENAI_API_KEY
  • Assurez-vous que models.llm dans config/tenants/acme.yml correspond à $MODEL.
  • Vérifiez que la passerelle pointe vers LLM_BASE_URL (ex: vLLM/Ollama en local).

Base de connaissance vide

Erreur : No documents found for tenant acme

Solution :

# Re-exécuter l'indexation
./scripts/seed-kb.sh --tenant=acme --force

Logs d'erreur

Problème : Services qui ne démarrent pas

Solution :

# Logs détaillés par service
docker compose logs gateway
docker compose logs orchestrateur
# Redémarrage sélectif
docker compose restart gateway

Étapes suivantes

Documentation clé :

Prochaines actions suggérées :

  1. Personnaliser votre tenant (logo, couleurs, FAQ spécifiques)
  2. Intégrer d'autres canaux (WhatsApp, Telegram)
  3. Configurer l'observabilité en production
  4. Déployer sur votre infrastructure (Kubernetes, cloud)

NOTE : Ce guide couvre un déploiement de développement. Pour la production, consultez Observabilité et Flux & Séquences.