Doc ∃xempℓIA

tekio.org
GitHub

Architecture

Les exemples sont écrits comme on les construirait en contexte professionnel : modèles locaux, garde, évaluation et traces dès le départ. Chacun répond à trois questions — quel besoin il couvre et quand ce modèle d'architecture est le bon choix, comment il fonctionne, comment on le fiabilise. Le public visé : développeurs, architectes et équipes data qui cherchent un point de départ concret et lisible, pas une plateforme clé en main.

Principes

Principe Conséquence
Lisibilité avant abstraction Code explicite, peu de couches. Un framework n'est utilisé que s'il apporte une capacité réelle (LangGraph pour l'état et la pause humaine, MLflow pour le cycle de vie).
Modèles locaux par défaut Tous les appels passent par l'API compatible OpenAI d'Ollama. Un seul exemple utilise un service cloud (Vertex AI + Gemini), volontairement minimal.
Testable sans modèle Le client LLM est injectable. Un faux client scripté permet de tester toute la plomberie (routes, outils, garde, workflows) sans GPU ni réseau. La qualité des réponses se mesure à part, par l'évaluation.
Règles métier hors du LLM Le LLM propose, le code décide : autorisations, plafonds, validations et droits d'accès sont vérifiés dans le code des outils.
Sécurité et mesure transversales La garde et le LLMOps sont des modules partagés, branchés sur chaque exemple, pas des ajouts de fin de projet.
Données neutres et minimales Une seule entreprise fictive sans secteur, juste assez de données pour que chaque exemple ait du sens.
Portable Applications web FastAPI (ou scripts quand l'interface n'apporte rien), infrastructure en docker compose. Pas de notebook.

Vue d'ensemble

flowchart TD
  classDef code fill:#ffffff,stroke:#6b7280,color:#1f2937
  classDef gpu fill:#fecaca,stroke:#dc2626,color:#7f1d1d
  classDef disque fill:#dcfce7,stroke:#16a34a,color:#14532d

  Nav["navigateur<br/>pages HTML + HTMX"]
  subgraph Py["Processus Python : uv run exemplia"]
    Ex["exemples<br/>un routeur par exemple"]
    Garde["garde<br/>entrée et sortie"]
    LLM["socle/llm.py<br/>client OpenAI"]
    Trace["socle/tracage.py<br/>traces MLflow"]
  end
  Ollama["Ollama sur l'hôte<br/>chat, juge, modération,<br/>embeddings"]
  MLflow[("MLflow<br/>traces, runs")]
  PG[("PostgreSQL<br/>données métier")]
  Qdrant[("Qdrant<br/>index vectoriel")]

  Nav -- "① HTTP" --> Ex
  Ex -- "② texte, réponse" --> Garde
  Ex -- "③ conversation" --> LLM
  Garde -- "④ modération, juge" --> LLM
  LLM -- "⑤ HTTP POST /v1" --> Ollama
  Ex -- "⑥ SQL" --> PG
  Ex -- "⑦ HTTP" --> Qdrant
  Trace -- "⑧ HTTP" --> MLflow
  Garde ~~~ Trace
  LLM ~~~ PG
  LLM ~~~ Qdrant

  class Ex,Garde,LLM,Trace code
  class Ollama gpu
  class PG,Qdrant,MLflow disque
  • ① Interface. Le navigateur envoie formulaires et requêtes HTMX à l'application FastAPI, qui regroupe un routeur par exemple ; les pages sont rendues côté serveur (Jinja) et HTMX remplace des fragments sans framework front-end.
  • ② Garde. Chaque exemple fait passer le texte entrant, puis la réponse produite, par les contrôles de la garde : règles, Presidio, modération, LLM juge, selon ce que l'exemple active.
  • ③ ④ Client LLM. Exemples et garde n'appellent les modèles qu'à travers le client du socle, qui ne connaît que l'API compatible OpenAI ; il est remplacé par un faux client scripté dans les tests.
  • ⑤ Ollama. Le client appelle /v1/chat/completions et /v1/embeddings. Le serveur de modèles tourne sur l'hôte, pour l'accès natif au GPU ; son adresse se change dans .env (IACU_LLM_BASE_URL). Seul l'exemple Vertex AI, lancé à part, appelle un modèle cloud.
  • ⑥ ⑦ Données. PostgreSQL porte les données de l'Entreprise Exemple (avec un rôle lecteur en lecture seule pour l'analyse de données), Qdrant l'index documentaire du RAG.
  • ⑧ Traces. Chaque requête est tracée dans MLflow, qui garde aussi les runs d'évaluation et le registry des modèles du tri des tickets.

Briques techniques

Brique Choix
Modèles Ollama, par l'API compatible OpenAI ; Vertex AI pour l'exemple cloud
Agents et workflows LangGraph
Sorties structurées Pydantic
RAG Qdrant (dense + BM25), fastembed (BM25, reranker)
Données PostgreSQL, SQLAlchemy, sqlglot
ML classique scikit-learn ; transformers pour le fine-tuning (GPU)
Garde Règles, Presidio + spaCy, Llama Guard 3, LLM juge
Observabilité, évaluation, MLOps MLflow 3
Web FastAPI, Jinja, HTMX

Infrastructure (compose.yaml)

Service Rôle Note
PostgreSQL Données de l'entreprise Rôle lecteur en lecture seule pour l'analyse de données
Qdrant Index vectoriel hybride (dense + BM25)
MLflow Traces, expériences, prompts, registry Stockage SQLite dans un volume Docker

Ollama tourne sur l'hôte, pour l'accès GPU natif. Le client LLM ne connaît que l'API OpenAI : l'adresse du serveur se change dans .env (IACU_LLM_BASE_URL).

Modules transversaux

Module Rôle Documentation
Garde Injection de prompt, données personnelles, modération, fuite du prompt, LLM juge garde
LLMOps Traces, jeux d'évaluation, scorers, évaluation et surveillance dans MLflow llmops
Socle Configuration, client LLM, base de données, documents, gabarit web, données de l'entreprise fictive socle

Arborescence

compose.yaml                 PostgreSQL, Qdrant, MLflow
docker/postgres/init.sql     rôle lecteur en lecture seule
data/entreprise/documents/   documents de l'Entreprise Exemple (Markdown)
.github/workflows/ci.yml     ruff et pytest sur chaque push
evaluation/                  jeux d'évaluation JSONL
captures/                    captures de chaque page et animation du README
doc/                         installation, architecture, évaluation
src/exemplia/
  app.py                     application web qui regroupe les exemples
  socle/                     configuration, client LLM, base, documents, traces, gabarit web
  garde/                     filtres d'entrée et de sortie
  llmops/                    scorers, évaluation, surveillance
  service_client/ rag/ conformite/ analyse_donnees/ tri_tickets/ workflow_agents/ vertex_gemini/
    README.md                présentation : besoin, vue d'ensemble, limites
    comment-ca-marche.md     explication et diagramme affichés dans la page de l'exemple
    fonctionnement.md        détail technique : composants, choix de conception
    utilisation.md           commandes, scénarios de démonstration, fichiers
    evaluation.md            commande d'évaluation, résultats, comparaisons de modèles
tests/

Ce que les exemples ne couvrent pas

Pas d'authentification : le client connecté se choisit dans une liste. Un seul locataire, une seule instance, pas de redondance. L'interface est en HTML et HTMX, sans framework front-end. Le seul entraînement est celui d'un classifieur de tickets ; aucun LLM génératif n'est fine-tuné.