← Documentation API Reference

Guide Administrateur AISIA

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

---

Table des matières

1. Premier accès : Bootstrap Admin 2. Interface d'administration 3. Gestion des clés API 4. Gestion des utilisateurs 5. Groupes et permissions 6. Règles IA / Guardrails 7. Maintenance planifiée 8. Self-Audit et Self-Repair 9. Auto-Test par LLM 10. Billing et monitoring 11. Gestion des modèles locaux 12. Synchronisation des modèles 13. Base de connaissances 14. RGPD et conformité

---

1. Premier accès : Bootstrap Admin

Lors du premier déploiement, un mécanisme de bootstrap permet de créer le premier compte administrateur. La procédure détaillée est fournie dans la documentation d'installation interne (non publique pour raisons de sécurité).

Contactez l'équipe technique pour obtenir les instructions : admin@aisia.fr

Points importants

L'endpoint accepte secret_key ou app_secret_key dans le body (rétro-compatibilité).
Le token expire après le nombre d'heures configuré (défaut : 72h, variable AUTH_TOKEN_EXPIRE_HOURS).
En production, la clé est lue depuis le Docker secret /run/secrets/auth_secret_key.
Ce mécanisme doit être utilisé uniquement pour le premier accès. Créez ensuite un vrai

compte admin via l'interface ou les endpoints OIDC.

---

2. Interface d'administration

L'interface web d'administration est accessible à l'adresse :

https://aisia.fr/admin

Elle comporte les onglets suivants :

Onglet	Description	Endpoint API
Clés API	Configuration des clés providers	`GET/PUT /admin/api-keys/`
Utilisateurs	Gestion des comptes	`GET/PUT /admin/users/`
Groupes	Gestion des groupes et permissions	`GET/POST/PUT/DELETE /admin/groups/`
Règles IA	Guardrails et filtres	`GET/PUT /admin/ai-rules`
Maintenance	17 tâches planifiées	`GET/POST /admin/maintenance/`
Bot	Statut du bot d'interaction	`GET/POST /admin/bot/`
Modèles locaux	Gestion des 83 modèles locaux (52 activés)	`GET/PUT /admin/local-models`
Billing	Suivi des coûts API	`GET /admin/billing`
Knowledge	Base de connaissances RAG	`GET/POST /admin/knowledge`
Self-Audit	Diagnostic automatique	`GET /admin/self-audit`
Datasets	Gestion des datasets HuggingFace	`GET/POST /admin/datasets`
Investisseurs	Page investisseurs	`GET /admin/investors`

Toutes les 33 routes admin sont protégées par Depends(get_admin_user). Un token JWT avec role=admin est requis pour chaque appel.

Authentification des requêtes API

# Inclure le token dans le header Authorization
curl -H "Authorization: Bearer VOTRE_TOKEN_JWT" \
  https://aisia.fr/admin/self-audit

---

3. Gestion des clés API

AISIA utilise un système de résolution de clés API à trois niveaux de priorité :

1. Cache DB admin : clés définies via l'interface d'administration (priorité maximale) 2. Variable d'environnement : OPENAI_API_KEY, ANTHROPIC_API_KEY, etc. 3. Docker Swarm secret : fichiers /run/secrets/

Configurer une clé via l'API

# Mettre à jour la clé d'un provider
curl -X PUT https://aisia.fr/admin/api-keys/{provider_id} \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "sk-xxx..."}'

Providers supportés (52 au total, dont 5 spécialisés)

Les clés sont configurées dans providers.yaml via le champ env_api_key qui indique la variable d'environnement ou le Docker secret correspondant.

Détection des placeholders

AISIA détecte et ignore automatiquement les clés commençant par : placeholder, changez, change-me, xxx, your-, sk-xxx.

---

4. Gestion des utilisateurs

Lister les utilisateurs

GET /admin/users/

Retourne la liste de tous les utilisateurs enregistrés avec : id, email, display_name, role (user/admin), active, auth_provider.

Modifier le rôle d'un utilisateur

PUT /admin/users/{user_id}/role
Body: {"role": "admin"}  # ou "user"

Activer/désactiver un compte

PUT /admin/users/{user_id}/active
Body: {"active": false}

Un utilisateur désactivé ne peut plus se connecter. Son token JWT existant continuera de fonctionner jusqu'à expiration (le JWT est stateless).

Permissions par provider

Chaque utilisateur peut avoir des permissions individuelles limitant l'accès à certains providers :

# Consulter les permissions
GET /admin/users/{user_id}/permissions

Définir les permissions
PUT /admin/users/{user_id}/permissions
Body: [
  {"provider_id": "openai", "enabled": true},
  {"provider_id": "anthropic", "enabled": false}
]

---

5. Groupes et permissions

Les groupes permettent de gérer les permissions de manière collective.

Opérations CRUD sur les groupes

# Lister les groupes
GET /admin/groups/

Créer un groupe
POST /admin/groups/
Body: {"name": "Équipe Data Science", "description": "Accès modèles spécialisés"}

Modifier un groupe
PUT /admin/groups/{group_id}
Body: {"name": "Nouveau nom", "description": "Nouvelle description"}

Supprimer un groupe
DELETE /admin/groups/{group_id}

Gestion des membres

# Lister les membres
GET /admin/groups/{group_id}/members

Définir les membres (remplacement complet)
PUT /admin/groups/{group_id}/members
Body: {"user_ids": ["user-uuid-1", "user-uuid-2"]}

Retirer un membre
DELETE /admin/groups/{group_id}/members/{user_id}

Permissions des groupes

Les permissions s'appliquent par type de ressource et niveau d'accès.

Types de ressources disponibles : llm, routing, model, token, api_key, storage, download, upload, admin, maintenance, provider, integration, group, user, learning, bot, chat, settings, monitoring, cluster.

Niveaux de permission : read, write, execute, manage, admin, owner, full.

# Consulter les permissions du groupe
GET /admin/groups/{group_id}/permissions

Définir les permissions
PUT /admin/groups/{group_id}/permissions
Body: [
  {"resource_type": "llm", "resource_id": "*", "permission": "execute"},
  {"resource_type": "admin", "resource_id": "*", "permission": "read"}
]

---

6. Règles IA / Guardrails

Les guardrails permettent de configurer des règles de sécurité applicables à toutes les requêtes LLM. Elles sont stockées dans la table aisia_ai_rules (MariaDB) avec cache Redis (TTL 300s) et cache mémoire (TTL 30s).

Règles disponibles

Clé	Description	Défaut
`system_prompt_global`	Prompt système injecté avant chaque requête	`""` (désactivé)
`max_tokens_per_request`	Limite tokens par requête (0 = illimité)	`0`
`forbidden_keywords`	Mots-clés interdits dans les messages (liste JSON)	`[]`
`forbidden_topics`	Sujets interdits	`[]`
`output_filter_keywords`	Mots-clés bloqués dans les réponses	`[]`
`rate_limit_requests_per_hour`	Limite par utilisateur par heure (0 = illimité)	`0`
`rate_limit_requests_per_day`	Limite par utilisateur par jour	`0`
`allow_local_models_for_users`	Modèles locaux pour non-admins	`true`
`allow_cloud_providers_for_users`	Providers cloud pour non-admins	`true`
`refusal_message`	Message affiché lors d'un blocage	`"Cette demande ne peut pas être traitée par AISIA."`
`log_refused_requests`	Journaliser les requêtes refusées	`true`

Lire et modifier les règles

# Lire les règles actuelles
GET /admin/ai-rules

Mettre à jour les règles
PUT /admin/ai-rules
Body: {
  "forbidden_keywords": ["violence", "armes"],
  "rate_limit_requests_per_hour": 100,
  "system_prompt_global": "Tu es un assistant professionnel AISIA."
}

Fonctionnement du rate limiting

Le rate limiting utilise des compteurs Redis avec des buckets horaires et journaliers. Les clés Redis suivent le format :

aisia:rl:hour:{user_id}:{bucket} (TTL 3600s)
aisia:rl:day:{user_id}:{bucket} (TTL 86400s)

---

7. Maintenance planifiée

Le MaintenanceScheduler centralise 17 tâches de maintenance, remplaçant les anciens cron jobs distribués sur les workers du cluster.

Consulter le statut

GET /admin/maintenance/status

Lancer une tâche manuellement

POST /admin/maintenance/tasks/{task_id}/run

Activer/désactiver une tâche

PUT /admin/maintenance/tasks/{task_id}/enabled
Body: {"enabled": true}

Liste des 17 tâches

ID	Catégorie	Auto	Intervalle	Description
`cluster-runtime-reconcile`	cluster	oui	15min	Réconciliation Docker workers
`cluster-root-usage-audit`	audit	oui	1h	Audit occupation disque workers
`cluster-logging-audit`	audit	oui	30min	Audit uniformité syslog
`manager-syslog-share-audit`	audit	oui	15min	Audit partage syslog manager
`syslog-health-summary`	analysis	oui	15min	Résumé santé syslog
`cluster-package-uniformity-audit`	audit	oui	6h	Homogénéité paquets
`cluster-worker-baseline-audit`	audit	oui	6h	Baseline système workers
`cluster-docker-prune`	maintenance	non	24h	Purge Docker (destructif)
`cluster-image-refresh`	maintenance	non	24h	Refresh images Docker (destructif)
`integrations-health-check`	intégrations	oui	1h	Health check intégrations
`integrations-update-review`	intégrations	oui	24h	Revue versions API
`sia-state-backup`	backup	oui	24h	Backup MariaDB + Qdrant
`redis-backup`	backup	oui	6h	BGSAVE Redis
`rgpd-data-purge`	rgpd	oui	24h	Purge données expirées (destructif)
`self-audit`	audit	oui	1h	Auto-diagnostic AISIA
`model-sync`	audit	non	24h	Synchronisation modèles LLM

Coordination multi-replicas

Quand Redis est disponible, le scheduler utilise un mécanisme de leader election (clé aisia:maintenance:leader avec TTL) pour garantir qu'une seule replica exécute les tâches planifiées. En l'absence de Redis, le fallback local s'active.

---

8. Self-Audit et Self-Repair

Self-Audit

GET /admin/self-audit

Exécute un diagnostic complet automatique :

Services Docker en cours d'exécution
Endpoints API (health, providers, models)
Tables de base de données
Modèles Ollama disponibles
Connectivité Redis et Qdrant
Produit un rapport JSON avec score global

Self-Repair

POST /admin/self-repair

Exécute des actions correctives automatiques basées sur le dernier rapport self-audit :

Recrée les tables manquantes
Redémarre les connexions Redis/Qdrant
Recharge les modèles locaux

---

9. Auto-Test par LLM

POST /admin/auto-test

AISIA utilise ses propres LLM pour tester l'intégralité de la plateforme :

1. Pages web : teste les 17 pages (/, /chat, /about, /contact, /investors, etc.) 2. Endpoints admin : teste 12 endpoints admin avec token 3. Chat : 10 questions dans différents domaines (math, coding, général, traduction, science, créatif) 4. Cycle auth : register, login, profile, login-history, OIDC Google 5. Intégrité données : providers (>50), modèles locaux (>40), OpenAPI (>60 paths), health

Le rapport final inclut :

Score global (pourcentage de checks réussis)
Points forts et faiblesses
Recommandations d'amélioration
Temps d'exécution total

---

10. Billing et monitoring

Statistiques billing

GET /admin/billing

Retourne les statistiques de la journée :

Nombre d'appels aujourd'hui
Tokens consommés
Coût estimé en USD

Coûts par utilisateur / par provider

GET /admin/billing/users
GET /admin/billing/providers

Estimation des coûts

AISIA estime les coûts en USD par million de tokens (approximation 30% input / 70% output) :

Provider	Input / 1M tokens	Output / 1M tokens
OpenAI	$0.15	$0.60
Anthropic	$0.25	$1.25
Gemini	$0.00	$0.00 (free tier)
Groq	$0.00	$0.00 (free tier)
Cerebras	$0.00	$0.00 (free tier)
DeepSeek	$0.07	$0.28
Mistral	$0.10	$0.30

Les données sont stockées dans Redis avec une rétention de 90 jours, par clés :

aisia:billing:daily:{date}
aisia:billing:user:{user_id}:{date}
aisia:billing:provider:{provider_id}:{date}

---

11. Gestion des modèles locaux

Lister les modèles

GET /admin/local-models

Retourne les 83 modèles locaux (52 activés) configurés dans local_models.yaml avec leur statut (actif/inactif, runtime, endpoint, priorité).

Activer/désactiver un modèle

PUT /admin/local-models/{model_id}/enabled
Body: {"enabled": false}

Les surcharges sont persistées dans la table aisia_local_model_overrides (MariaDB) et cachées dans Redis pour accès rapide.

Hot-reload

POST /admin/autonomy/reload

Recharge à chaud tous les modèles locaux sans redémarrer le service :

Invalide le cache providers
Ferme les adaptateurs existants
Relit local_models.yaml
Initialise les nouveaux adaptateurs
Timeout global de 30 secondes

---

12. Synchronisation des modèles

POST /admin/models/sync

Déclenche manuellement la synchronisation des modèles :

Interroge chaque provider cloud via leur API /v1/models
Interroge Ollama via /api/tags pour les modèles locaux
Met à jour providers.yaml et local_models.yaml

Le bot ModelSync exécute automatiquement cette synchronisation toutes les 24 heures.

---

13. Base de connaissances

Statistiques

GET /admin/knowledge

Retourne les statistiques des collections Qdrant (nombre de points, vecteurs).

Ingérer un document

POST /admin/knowledge/ingest
Body: {"text": "Contenu à indexer...", "source": "documentation"}

Ou depuis une URL
POST /admin/knowledge/ingest
Body: {"url": "https://exemple.com/doc.html"}

Le texte est : 1. Nettoyé (suppression HTML, normalisation espaces) 2. Découpé en chunks de 500 caractères avec chevauchement de 50 caractères 3. Encodé avec le modèle all-MiniLM-L6-v2 (384 dimensions, cosine) 4. Stocké dans la collection Qdrant mtp_knowledge

Vider la base

POST /admin/knowledge/clear

---

14. RGPD et conformité

Paramètres RGPD

Variable	Défaut	Description
`RGPD_USER_RETENTION_DAYS`	1095 (3 ans)	Durée de rétention des comptes
`RGPD_AUDIT_RETENTION_DAYS`	365 (1 an)	Durée de rétention des logs audit
`RGPD_DPO_EMAIL`	contact@aisia.fr	Email du DPO

Purge automatique

La tâche rgpd-data-purge s'exécute quotidiennement et supprime :

Les comptes inactifs depuis plus de RGPD_USER_RETENTION_DAYS jours
Les entrées audit_log plus anciennes que RGPD_AUDIT_RETENTION_DAYS jours
Conforme à l'article 5(1)(e) du RGPD (limitation de la conservation)

Droits des utilisateurs

Droit à la portabilité (art. 20) : GET /auth/me/export
Droit à l'effacement (art. 17) : DELETE /auth/me
Gestion du consentement : GET/PUT /auth/me/consents
Historique des connexions : GET /auth/me/login-history

Protection des logs

Les chemins /auth/* sont automatiquement filtrés des logs d'accès HTTP pour éviter la journalisation de données personnelles (emails, tokens) dans les logs serveur.

---

Document AISIA v4.21.0