ADEN vs akko-rag — quand utiliser lequel¶

Revue founder 2026-04-26 a soulevé la question : « dans ADEN y'a une partie unstructured data PDF, c'est quoi la différence avec ce qui est dans RAG ? »

Les deux services répondent à des questions sur des documents, mais ils sont à des couches différentes de la stack et servent des publics différents. Cette page existe pour qu'un CISO/opérateur/ prospect lise un paragraphe et choisisse le bon outil.

En bref¶

Capacité	ADEN unstructured	akko-rag
Durée de vie du document	Une conversation	Collection persistante
Qui upload	L'utilisateur en plein chat	Un admin, à l'avance
Backend stockage	En mémoire / éphémère	PostgreSQL (schéma `akko_rag`) + pgvector + SeaweedFS originaux
Re-queryable	Non — disparaît avec la conversation	Oui — chaque consommateur peut re-querer
Connaissance partagée multi-utilisateur	Non	Oui (accès par collection via `allowed_roles`)
Surface API	Embarquée dans le flow `/query` d'ADEN	FastAPI standalone : `/collections`, `/upload`, `/query`
Page cockpit	Dans la page ADEN	Page RAG dédiée
Idéal pour	« Drop ce PDF, pose une question, passe à autre chose »	« Construire une base de connaissance corporate, partager avec l'équipe »

Quand utiliser ADEN unstructured¶

Un utilisateur a un seul PDF/CSV/DOCX devant lui, veut une réponse rapide et n'aura plus besoin de ce document.
Le document est sensible (NDA client, brouillon de proposition) et ne doit pas persister au-delà de la conversation.
La conversation a besoin à la fois de requêtes SQL structurées ET du contexte du document dans le même flow — ADEN orchestre Trino
le document ensemble.
Pas de surcoût admin — l'utilisateur drop simplement le fichier dans l'UI ADEN.

Session exemple :

Utilisateur : upload Q3-bank-loan-terms.pdf Utilisateur : « Compare ces conditions de prêt à notre table customers.contracts. Y a-t-il des covenants violés par les clients actuels ? » ADEN : (extrait les conditions du contexte PDF, lance le SQL sur Trino, joint le résultat, produit un dashboard)

Le PDF disparaît quand l'utilisateur ferme la conversation. Le log d'audit garde la question + le SQL mais pas le corps du PDF.

Quand utiliser akko-rag¶

L'équipe va poser plusieurs questions sur le même set de documents dans le temps (manuel produit, wiki interne, textes réglementaires).
Plusieurs utilisateurs / rôles doivent quérer la même collection — akko-rag applique allowed_roles par collection.
La collection mérite son propre cycle de vie (créer / uploader plusieurs docs / ré-indexer / supprimer via la page RAG du cockpit, cf PR #63).
Un consommateur non-AKKO (un notebook, un service externe) doit appeler la même API de retrieval — akko-rag est un FastAPI standalone qui expose /collections/{slug}/query avec similarité cosinus sur pgvector.

Session exemple :

Admin : crée une collection internal-policies, upload 30 PDF de politique RH. Admin : assigne allowed_roles: [hr, akko-admin]. Employé Bob (rôle hr) : demande à ADEN ou à n'importe quel outil RAG-aware « quelle est la politique de congé parental ? », le retrieval frappe internal-policies, la réponse cite le PDF. Employée Eve (rôle analyst) : même question, le retrieval trouve 0 résultats car Eve n'est pas dans allowed_roles. ADEN répond « aucun document pertinent dans les collections que vous pouvez lire ».

La collection persiste entre les sessions. D'autres consommateurs (un notebook, un bot Slack, un service externe) peuvent appeler la même API.

Implémentation sous le capot¶

                        ┌──────────────────────────────────┐
                        │  ADEN (NL → SQL → Dashboard)     │
                        │  docker/aden/                    │
                        │                                  │
   upload fichier ─────▶│  /query                          │
   (in-chat)            │     ├─ SQL Trino                 │
                        │     ├─ handler "unstructured"    │
                        │     │   └─ extraction texte      │
                        │     │      éphémère → contexte   │
                        │     └─ client akko-rag (option.) │──┐
                        │        pour collections persist. │  │
                        └──────────────────────────────────┘  │
                                                               │
                                                               ▼
                        ┌──────────────────────────────────┐
                        │  akko-rag (standalone)           │
                        │  docker/akko-rag/                │
                        │                                  │
   upload doc ─────────▶│  POST /collections/{slug}/documents
   (admin, à l'avance)  │       └─ pdf/csv/docx → chunks → embeddings
                        │           └─ pgvector + SeaweedFS │
                        │                                  │
   query ──────────────▶│  POST /collections/{slug}/query  │
                        │       └─ similarité vectorielle → top-k│
                        └──────────────────────────────────┘

ADEN unstructured¶

Code dans docker/aden/ à côté du pipeline SQL.
Les bytes du PDF/CSV/DOCX sont parsés en mémoire (pypdf, python-docx, pandas pour CSV) et le texte extrait devient partie de la fenêtre de contexte du LLM pour CETTE question.
Aucune table persistante ne garde le document. Le log d'audit garde le texte de la question + le SQL généré par ADEN, pas le corps du document.
Limite upload soft 50 MB (max_upload_bytes).

akko-rag¶

Service FastAPI standalone (docker/akko-rag/).
Schéma Postgres akko_rag avec tables collections, documents, chunks, query_log (voir postgres/init/11-akko-rag.sql).
Chaque upload chunke le document, embarque les chunks via l'embedder configuré (LiteLLM par défaut, Ollama on-prem en mode air-gapped), stocke les embeddings dans pgvector.
Originaux stockés dans le bucket SeaweedFS akko-rag/originals/.
/query fait similarité cosinus, retourne les top-k chunks avec metadata de citation (fichier, page).
Limite upload hard 50 MB (maxUploadBytes valeur chart).

Quand FUSIONNER les deux (et pourquoi on ne l'a pas fait)¶

Le founder a demandé s'il fallait merger. Le jugement actuel est non, garder séparés, mais faire en sorte que le handler unstructured d'ADEN appelle akko-rag sous le capot pour le chemin persistant.

Avantages de la séparation :

ADEN unstructured est l'UX juste pour « drop un fichier, pose une question, passe à autre chose ». Forcer chaque PDF déposé à passer par une étape « créer collection + nom + rôles + indexation » tuerait le flow conversationnel.
akko-rag a des consommateurs au-delà d'ADEN (notebooks, services externes, futur bot Slack/Teams). Il a besoin de sa propre API et cycle de vie.
Les deux services ont des modèles de sécurité différents : ADEN unstructured fait confiance implicitement à l'utilisateur en chat (session unique) ; akko-rag applique allowed_roles par collection.

La fusion future est UNE fonctionnalité : « sauvegarder le PDF de cette conversation dans une collection » — un bouton dans ADEN qui POST le document éphémère vers akko-rag avec une collection + rôles choisis. Suite Sprint 54, pas un P0.

Référence rapide — endpoints et pages¶

Action	Où
Drop un PDF et poser une question	demo.akko-ai.com → page ADEN → widget upload
Créer une collection persistante	demo.akko-ai.com → page RAG → « + New collection »
Ajouter un document à une collection	Page RAG → sélectionner la collection → upload doc
Supprimer une collection	Page RAG → icône poubelle sur la collection (PR #63)
Quérer une collection depuis un notebook	`POST http://akko-akko-rag:8080/collections/{slug}/query`

Voir aussi¶

Page service ADEN — référence ADEN complète (NL→SQL→Dashboard)
Page service akko-rag — référence RAG complète (architecture 3-tier, valeurs chart)
ADR-021 — « ADEN comme la porte d'entrée conversationnelle »
ADR-026 — fonctions SQL akko_ai_* (utilisées en interne par ADEN)