AI Engine - Unified RAG Gateway¶

Version: 2.0.0
Date: 25 Mars 2026
Statut: Production

Table des Matières¶

1. Vue d'Ensemble
2. Architecture RAG Gateway
3. Collections Qdrant Multi-Niveaux
4. Endpoint Search (Cross-Projet)
5. Endpoint Chat (SSE Streaming)
6. Feedback & Score de Fiabilité
7. Synchronisation Qdrant
8. Configuration & Variables d'Environnement
9. Modèles de Données AI
10. Intégration Frontend v2

1. Vue d'Ensemble¶

1.1 Contexte¶

Le Unified RAG Gateway (Approche B) unifie le pipeline RAG existant et l'assistant IA en un service central (RAGContextGateway) qui alimente deux modes d'interaction :

1. AI Search — Recherche sémantique cross-projet (one-shot, Dashboard)
2. AI Chat — Conversation multi-turn project-scoped avec streaming SSE

1.2 Avant / Après¶

1.3 Architecture Globale¶

2. Architecture RAG Gateway¶

2.1 Service : RAGContextGateway¶

Le RAGContextGateway est un singleton (get_rag_context_gateway()) qui centralise tous les accès vectoriels Qdrant pour les deux modes AI.

Fichier : src/services/rag_context_gateway.py

Dépendances :

2.2 Méthodes Publiques¶

2.3 Stratégie de Budget Tokens¶

Le gateway gère un budget strict pour éviter les dépassements de contexte OpenAI :

Fenêtre totale GPT-4o : ~128K tokens
├── System prompt fixe : ~200 tokens
├── Contexte RAG : 8 000 tokens (RAG_CONTEXT_TOKEN_BUDGET)
├── Historique conversation : 4 000 tokens (RAG_HISTORY_TOKEN_BUDGET)
├── Message utilisateur : ~500 tokens
└── Réponse AI : ~4 000 tokens (réservé)

Mécanisme :

1. get_chat_context() récupère les top-k chunks depuis Qdrant
2. Les chunks sont ajoutés un par un jusqu'à atteindre le budget RAG_CONTEXT_TOKEN_BUDGET
3. L'historique est tronqué en supprimant les messages les plus anciens
4. Le comptage utilise tiktoken.encoding_for_model("gpt-4o") (fallback: cl100k_base)

2.4 Re-Ranking Cross-Source¶

Les résultats Qdrant sont repondérés selon le type de source :

# Poids par défaut
WEIGHTS = {
    "transcript": 1.0,        # Priorité maximale
    "contextual_file": 0.9,   # Légèrement inférieur
    "meeting_summary": 0.8,   # Synthèses
}

# Score final = score_qdrant * poids_source
weighted_score = raw_score * weights[source_type]

Les résultats sont dédupliqués par contenu textuel pour éviter les doublons cross-collection.

3. Collections Qdrant Multi-Niveaux¶

3.1 Architecture 2 Niveaux¶

L'architecture Qdrant est organisée en 2 niveaux de collections :

3.2 Stratégie Search Cross-Projet¶

Pour une recherche cross-projet (POST /ai-engine/search), le gateway :

1. Identifie toutes les collections transcript de l'utilisateur (_get_user_collections())
2. Filtre par project_ids si spécifié
3. Lance une recherche sur chaque collection en parallèle
4. Agrège et re-rank les résultats avec les poids source
5. Déduplique par contenu textuel

3.3 Payload Qdrant¶

Chaque point dans les collections contient ce payload :

{
  "text": "Le directeur technique a validé le budget...",
  "source_type": "transcript",
  "source_id": "uuid-transcript",
  "project_id": "uuid-projet",
  "transcript_id": "uuid-transcript",
  "chunk_index": 3,
  "speaker": "Sophie Martin",
  "all_participants": ["Sophie Martin", "Jean Dupont"],
  "keywords": ["budget", "validation", "technique"],
  "created_at": "2025-03-15T14:30:00Z"
}

4. Endpoint Search (Cross-Projet)¶

4.1 Spécification API¶

4.2 Request Body¶

{
  "query": "Quelles décisions ont été prises cette semaine ?",
  "project_ids": ["uuid-projet-1", "uuid-projet-2"],
  "source_types": ["transcript", "contextual_file"],
  "limit": 10
}

4.3 Response¶

{
  "query": "Quelles décisions ont été prises cette semaine ?",
  "results": [
    {
      "source_type": "transcript",
      "source_id": "uuid-transcript-1",
      "project_id": "uuid-projet-1",
      "text": "Le comité a décidé de lancer la phase 2 du projet...",
      "score": 0.87,
      "metadata": {
        "speaker": "Sophie Martin",
        "transcript_id": "uuid-transcript-1"
      }
    }
  ],
  "total_results": 5
}

4.4 Flow¶

5. Endpoint Chat (SSE Streaming)¶

5.1 Spécification API¶

5.2 Request Body¶

{
  "message": "Résume les points clés de ma dernière réunion",
  "conversation_id": "uuid-conversation",
  "project_id": "uuid-projet",
  "attachments": [
    {
      "type": "transcript",
      "name": "Comité qualité",
      "source_id": "uuid-transcript-1"
    }
  ]
}

5.3 Événements SSE¶

Le stream émet 3 types d'événements :

5.4 Flow Complet¶

5.5 Gestion des Sessions DB¶

Le streaming SSE utilise deux sessions DB pour éviter les problèmes de connexion :

1. Session principale — Utilisée pour les opérations pré-streaming (conversation, user message)
2. Session SessionLocal() — Créée dans le générateur SSE pour la sauvegarde post-streaming

Cette séparation est nécessaire car la session principale est fermée par FastAPI avant la fin du générateur async.

6. Feedback & Score de Fiabilité¶

6.1 Endpoint Feedback¶

Request :

{
  "message_id": "uuid-message",
  "rating": 4,
  "correction_text": "Le nom correct est Jean Dupont, pas Jean Martin"
}

Validations :

• Le message doit exister
• La conversation associée doit appartenir à l'utilisateur
• Le rating doit être entre 1 et 5

6.2 Endpoint Reliability Score¶

Response :

{
  "score": 0.87,
  "total_feedbacks": 21,
  "window_size": 100
}

Calcul :

Score = moyenne(ratings des N derniers feedbacks) / 5.0

Exemple : ratings = [5, 4, 5, 3, 5, 4, 4, 5]
         moyenne = 4.375
         score = 4.375 / 5.0 = 0.875 → affiché 87%

Le window_size est configurable via FEEDBACK_WINDOW_SIZE (défaut: 100).
Si aucun feedback n'existe, le score est 1.0 (confiance par défaut).

6.3 Flow Feedback¶

7. Synchronisation Qdrant¶

7.1 Points d'Accroche (Hooks)¶

Le RAGContextGateway est appelé automatiquement par 3 hooks dans le code existant :

7.2 Diagramme de Sync¶

7.3 Idempotence¶

Les opérations sync_to_project() sont idempotentes :
- Les points utilisent des point_id déterministes basés sur le contenu
- Un upsert d'un point existant le met à jour sans erreur
- En cas d'échec, la synchronisation peut être relancée sans effet de bord

8. Configuration & Variables d'Environnement¶

8.1 Variables RAG Gateway¶

8.2 Variables Pré-requises (Existantes)¶

8.3 tiktoken¶

Le module tiktoken télécharge ses fichiers d'encodage depuis le CDN OpenAI au premier appel.

• Cache : ~/.cache/tiktoken/ (Linux) ou %AppData%\Local\cache\tiktoken\ (Windows)
• Fallback : Si le modèle gpt-4o n'est pas disponible, utilise cl100k_base
• Taille cache : ~200 KB

9. Modèles de Données AI¶

9.1 Diagramme ERD¶

9.2 Tables Nouvelles (Migration v2.0)¶

9.3 Modification Existante¶

10. Intégration Frontend v2¶

10.1 Endpoints Résumé¶

10.2 Connexion SSE (Chat)¶

// Frontend — Connexion SSE au chat
const response = await fetch('/api/ai-engine/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`,
  },
  body: JSON.stringify({
    message: userMessage,
    conversation_id: conversationId,
    project_id: selectedProjectId,
  }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n\n');

  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const event = JSON.parse(line.slice(6));

      if (event.type === 'token') {
        appendToken(event.content);
      } else if (event.type === 'done') {
        setConversationId(event.conversation_id);
        setSources(event.sources);
        setConfidence(event.confidence_score);
      } else if (event.type === 'error') {
        showError(event.content);
      }
    }
  }
}

10.3 Dashboard Search¶

// Frontend — Recherche sémantique
const results = await api.post('/ai-engine/search', {
  query: searchQuery,
  project_ids: selectedProjects,
  limit: 10,
});

// results.data.results contient les résultats + sources
// results.data.total_results contient le nombre total

10.4 Feedback¶

// Frontend — Envoi feedback
await api.post('/ai-engine/feedback', {
  message_id: aiMessageId,
  rating: isThumbUp ? 5 : 1,
  correction_text: correctionText || undefined,
});