← Documentation API Reference

Architecture Cluster AISIA

Version : 4.15.0 Société : AISIA — Structure juridique en cours de création URL publique : https://aisia.fr/

---

Table des matières

1. Vue d'ensemble du cluster 2. Noeuds du cluster 3. Topologie réseau 4. Stack AISIA (services applicatifs) 5. Stack Core (services fondamentaux) 6. MariaDB 7. Redis 8. Qdrant 9. Prometheus et Grafana 10. Traefik (reverse proxy) 11. Placement et contraintes 12. Connectivité SSH

---

1. Vue d'ensemble du cluster

Le cluster AISIA est un ensemble de 21 noeuds physiques organisés en Docker Swarm, hébergeant l'intégralité de la plateforme AISIA en production.

Caractéristiques globales

AspectValeur
Noeuds totaux21
Raspberry Pi 412
Serveur toolsbox1
NVIDIA Jetson Xavier AGX1
Ring-mining1
Autres noeuds6 (NAS, manager, etc.)
OrchestrateurDocker Swarm
Registre privé192.168.1.1:5002
Stockage partagéNAS /mnt/docker/AISIA
URL publiquehttps://aisia.fr/

Architecture logique

                    Internet
                       │
                    Traefik
                       │
                ┌──────┴──────┐
                │  aisia_api  │ (14 replicas ARM64)
                │  (FastAPI)  │
                └──────┬──────┘
                       │
    ┌──────────┬───────┼───────┬──────────┐
    │          │       │       │          │
 MariaDB    Redis   Qdrant  Ollama    Jetson
 (Galera)  (+replica)        (3x RPi)  (GPU)

---

2. Noeuds du cluster

Manager

NoeudIPRôleSpecs
freebox-swarm192.168.1.1Manager Swarm + RegistryARM64, NAS
Le manager est le point d'entrée du Swarm. Il héberge :

Workers Raspberry Pi

NoeudIPLabelsUsage
raspberrypi01192.168.1.xworker, ollamaAPI + Ollama
raspberrypi02192.168.1.xworker, ollamaAPI + Ollama
raspberrypi03192.168.1.xworker, ollamaAPI + Ollama
raspberrypi04-12192.168.1.xworkerAPI replicas
Chaque Raspberry Pi 4 dispose de :

Toolsbox

NoeudIPRôleSpecs
toolsbox192.168.1.240Builds, bot, tâches lourdes8 vCPU, ~12 Go RAM
Toolsbox est le noeud de travail préféré pour : Règle : toujours préférer toolsbox pour les builds Docker. Ne jamais builder sur le manager sauf urgence.

NVIDIA Jetson Xavier AGX

NoeudIPRôleSpecs
nvidia192.168.1.200GPU inférence512-core Volta, 32 Go RAM, CUDA
Le Jetson est dédié à l'inférence GPU pour les modèles 7B-8B. Il héberge le service aisia_gpu avec 6 modèles pré-chargés.

Ring-mining

NoeudIPRôle
ring-mining-1192.168.1.xService ring
Héberge le service aisia_ring.

---

3. Topologie réseau

Réseaux Docker Swarm

RéseauTypeUsage
ingressOverlay (Swarm défaut)Load balancing des services publiés
aisia_backendOverlayCommunication inter-services AISIA
aisia-core_backendOverlayCommunication services core (DB, Redis, Qdrant)

Réseau physique

Internet ←→ Box Free (NAT/Port forwarding)
                │
                ├── 192.168.1.1   (manager/freebox-swarm)
                ├── 192.168.1.2-13 (RPi workers)
                ├── 192.168.1.200  (Jetson/nvidia)
                ├── 192.168.1.240  (toolsbox)
                └── 192.168.1.x    (NAS, ring-mining, etc.)

DNS et accès public

URLDestinationMéthode
https://aisia.fr/Traefik → aisia_apiDNS + Traefik
https://aisia.fr/chatTraefik → aisia_apiFile provider
L'accès public unique passe par https://aisia.fr/. Les anciennes routes lambda.freeboxos.fr ont été supprimées.

Résolution DNS interne (Swarm)

Les services Swarm sont résolus par leur nom de service :

---

4. Stack AISIA (services applicatifs)

Fichier : deploy/stack-poc-global-reuse.yml

Service : aisia_api

AttributValeur
Image192.168.1.1:5002/aisia:v4.15.0
ArchitectureARM64
Replicas14
Port8000 (interne), exposé via Traefik
Health checkGET /health
Placementaisia.role == worker
L'API FastAPI est le coeur de la plateforme. Avec 14 replicas, elle fournit une haute disponibilité et un load balancing natif via Swarm.

Service : aisia_bot

AttributValeur
Imageaisia:v4.15.0-amd64
ArchitectureAMD64
Replicas1
Placementtoolsbox
Le bot d'interaction autonome qui :

Service : aisia_ollama

AttributValeur
ImageOllama officielle ARM64
Replicas3
Port11434
Placementaisia.ollama == true
Volume/mnt/docker/AISIA/ollama/models
Runtime d'inférence locale pour les modèles Llama, CodeLlama, Mistral, etc.

Service : aisia_gpu

AttributValeur
Replicas1
Placementaisia.gpu == true (Jetson)
Inférence GPU pour les modèles 7B-8B.

Service : aisia_ring

AttributValeur
Replicas1
Placementring-mining-1
---

5. Stack Core (services fondamentaux)

Fichier : deploy/stack-core.yml

Services

ServiceImageReplicasPortVolume
mariadbMariaDB officielle1 (ou 3 Galera)3306NAS /mnt/docker/AISIA/mariadb
redisRedis officielle1 + replica6379NAS /mnt/docker/AISIA/redis
qdrantQdrant officielle16333, 6334NAS /mnt/docker/AISIA/qdrant
prometheusPrometheus officielle19090NAS /mnt/docker/AISIA/prometheus
grafanaGrafana officielle13000NAS /mnt/docker/AISIA/grafana
---

6. MariaDB

Configuration

ParamètreValeur
Base de donnéesaisia
Utilisateuraisia
Secret mot de passeaisia_db_password (Docker secret)
Port3306
MoteurInnoDB
Charsetutf8mb4

Tables

Le préfixe de toutes les tables est aisia_ :

TableDescription
aisia_usersComptes utilisateurs
aisia_api_keysClés API gérées par l'admin
aisia_conversationsHistorique des conversations
aisia_messagesMessages des conversations
aisia_ai_rulesRègles guardrails IA
aisia_local_model_overridesSurcharges modèles locaux
aisia_user_profilesProfils étendus utilisateurs
aisia_login_historyHistorique des connexions
aisia_groupsGroupes d'utilisateurs
aisia_group_membersMembres des groupes
aisia_group_permissionsPermissions des groupes
aisia_user_consentsConsentements RGPD
aisia_maintenance_tasksÉtats des tâches maintenance

Galera Cluster (optionnel)

Pour la haute disponibilité, MariaDB peut être déployé en cluster Galera sur 3 noeuds NAS :

Migrations

Toutes les tables utilisent des DDL idempotents : 

CREATE TABLE IF NOT EXISTS aisia_xxx (...) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Les migrations sont exécutées automatiquement au démarrage de l'API.

Connexion

AISIA utilise aiomysql pour les connexions asynchrones : 

pool = await aiomysql.create_pool(
    host=settings.database_host,
    port=settings.database_port,
    db=settings.database_name,
    user=settings.database_user,
    password=settings.database_password,
    minsize=1,
    maxsize=10,
)

Un jitter de 0-15 secondes est ajouté au démarrage pour éviter la surcharge quand les 14 replicas démarrent simultanément.

---

7. Redis

Rôle

Redis est utilisé comme :

Architecture

ComposantPortDescription
Redis primaire6379Lecture/écriture
Redis replica6379Lecture seule (haute disponibilité)

Clés principales

PatternUsageTTL
aisia:conv:*Cache conversations3600s (1h)
bandit:*État bandit router86400s (24h)
cb:*État circuit breakers3600s (1h)
aisia:billing:*Compteurs billing90 jours
aisia:bot:statusStatut du botvariable
aisia:maintenance:*Coordination maintenancevariable
aisia:learning:*Statut apprentissagevariable
aisia:ai_rulesCache guardrails300s
aisia:rl:*Rate limiting3600s/86400s
oidc:state:*CSRF states OIDC600s

Résilience

Si Redis est indisponible :

---

8. Qdrant

Rôle

Qdrant est la base de données vectorielle utilisée pour :

Collections

CollectionDescriptionUsage
ai_responsesRésultats bruts des appels providersHistorique
router_embeddingsDécisions de routingAnalyse
eval_corpusDatasets d'évaluationBenchmark
mtp_knowledgeBase de connaissances distilléeRAG
mtp_training_pairsPaires d'entraînementLearning loop

Encodeur

AttributValeur
Modèleall-MiniLM-L6-v2
Dimensions384
DistanceCosinus
Backend prioritairesentence-transformers
Backend fallbackfastembed (ONNX)

Ports

PortUsage
6333HTTP REST API
6334gRPC API
---

9. Prometheus et Grafana

Prometheus

AttributValeur
Port9090
Rétention15 jours (défaut)
Scrape interval15 secondes
Fichier configdeploy/prometheus.yml
Prometheus collecte les 14 métriques exposées par AISIA sur /metrics plus les métriques système des noeuds du cluster.

Configuration scrape

scrape_configs:
  - job_name: 'aisia-api'
    dns_sd_configs:
      - names: ['tasks.aisia_api']
        type: 'A'
        port: 8000
    metrics_path: '/metrics'

Alertes

Le fichier deploy/alerts.yml définit les règles d'alerte Prometheus.

Grafana

AttributValeur
Port3000
DatasourcePrometheus
Dashboards11 pré-configurés
Répertoire configsdeploy/grafana/
---

10. Traefik (reverse proxy)

Mode

Traefik est configuré en mode file provider (pas de découverte dynamique Docker).

Configuration

FichierDescription
deploy/traefik.ymlConfiguration principale
deploy/traefik-dynamic.ymlConfiguration dynamique (routes, middlewares)

Régénération après déploiement

Après chaque déploiement de aisia_api, les IPs des containers peuvent changer. Le script de mise à jour régénère le fichier services.yml : 

bash deploy/update-traefik-backend.sh

Routes

RouteServiceTLS
https://aisia.fr/*aisia_apiOui (Let's Encrypt)
---

11. Placement et contraintes

Labels Docker

LabelNoeudsUsage
aisia.role=managerfreebox-swarmServices manager
aisia.role=workerRPi01-12API replicas
aisia.role=toolsboxtoolsboxBot, builds
aisia.role=gpunvidiaInférence GPU
aisia.ollama=trueRPi01-03Replicas Ollama
aisia.gpu=truenvidiaService GPU
aisia.nas=trueNoeuds NASMariaDB Galera

Commandes de labeling

# Appliquer un label
docker node update --label-add aisia.role=worker raspberrypi01



Vérifier les labels

docker node inspect raspberrypi01 --format '{{json .Spec.Labels}}'



Lister tous les noeuds avec labels

docker node ls -q | xargs docker node inspect \
  --format '{{.Description.Hostname}} {{json .Spec.Labels}}'

Contraintes de placement dans les stacks

# API sur les workers
deploy:
  placement:
    constraints:
      - node.labels.aisia.role == worker



Bot sur toolsbox

deploy:
  placement:
    constraints:
      - node.labels.aisia.role == toolsbox



GPU sur Jetson

deploy:
  placement:
    constraints:
      - node.labels.aisia.gpu == true

---

12. Connectivité SSH

Règle de connectivité (permanente)

#### Sur le LAN (192.168.1.0/24) 

# Manager direct
ssh slambert@192.168.1.1



Toolsbox direct

ssh slambert@192.168.1.240



Jetson/NVIDIA direct

ssh slambert@192.168.1.200

#### Hors LAN (défaut -- fonctionne toujours) 

# Manager (point d'entrée)
ssh slambert@lambda.freeboxos.fr



Jump vers toolsbox

ssh -J slambert@lambda.freeboxos.fr slambert@192.168.1.240



Jump vers Jetson

ssh -J slambert@lambda.freeboxos.fr slambert@192.168.1.200



Jump vers un worker RPi

ssh -J slambert@lambda.freeboxos.fr slambert@192.168.1.x

Règle pour les tâches CPU/IO intensives

Toujours préférer toolsbox (192.168.1.240) pour :

Toolsbox dispose de 8 vCPU et ~12 Go de RAM, avec le NAS monté sur /mnt/docker. Ne jamais utiliser le manager pour les builds sauf en cas d'urgence.

---

Document AISIA v4.21.0