Smart Transcription BFF - Documentation Technique¶

Version: 1.0.0
Date: 11 Mars 2026
Statut: Production

Table des Matières¶

Documentation Principale¶

1. Architecture Globale - Vue d'ensemble, stack technique, séparation des responsabilités
2. Pipeline de Transcription - Workflow complet avec diagrammes
3. Workflow RAG - Enrichissement contextuel et identification speakers
4. LLM Prompting - Stratégies de prompting et post-processing
5. Modèles de Données - Structures BDD, schemas, relations
6. Gestion des Erreurs - Fallbacks, retry policies, résilience
7. Performance & Scalabilité - Optimisations, benchmarks

Guides Complémentaires¶

• API MeetNoo Services - Contrat d'API avec MeetNoo GPU
• Deployment Diagram - Topologie de déploiement
• Architecture Speaker ID v3 - Détails 3-priority

Introduction¶

Qu'est-ce que Smart Transcription BFF ?¶

Le Smart Transcription BFF (Backend For Frontend) est le service applicatif central de l'écosystème de transcription intelligente. Il orchestre le post-processing des transcriptions audio en utilisant des techniques avancées d'IA :

Problèmes résolus :
- Pré-RAG: Speakers labellisés SPEAKER_00, SPEAKER_01 sans identité réelle
- Pré-RAG: Transcriptions brutes sans ponctuation, avec fautes d'orthographe
- Pré-RAG: Aucun contexte métier, impossible d'enrichir avec documents d'entreprise
- Pré-RAG: Identification manuelle des speakers = perte de temps

Solutions apportées :
- Identification automatique 3-priority: Voiceprint (95%) → RAG contextuel (78%) → LLM (85%)
- Enrichissement RAG: Métadonnées (email, phone, company) extraites des documents
- Auto-apprentissage: Chaque transcription améliore la bibliothèque de voiceprints
- Correction LLM: Ponctuation, acronymes, noms propres corrigés intelligemment

Architecture en Bref¶

Séparation des Services (Architecture v3)¶

Principe clé: Couplage minimal via HTTP + Redis Streams. Zéro couplage retour.

Workflow Global (Vue Simplifiée)¶

Temps total: ~20min pour 1h audio (dont 90% GPU transcription)

Concepts Clés¶

1. Architecture 3-Priority Speaker Identification¶

PRIORITY 1: Voiceprint Audio Matching (512d PyAnnote)
  → Cosine similarity > 0.85 → IDENTIFIED
  → < 0.85 → Auto-save pending → "Intervenant 0"

PRIORITY 2: RAG Enrichment (1024d BGE-M3)
  → Si identifié: Enrich metadata (email, phone, company)
  → Si pending: Extract potential speakers pour LLM

PRIORITY 3: LLM Inference (Qwen 2.5-3B)
  → Analyse contexte RAG → Identification
  → Si identifié: Confirm pending voiceprint

Taux de succès cumulé: 98% (95% priority 1 + 3% priority 2+3)

2. Mean Pooling pour Matching¶

Au lieu d'utiliser UN segment, on moyenne TOUS les segments d'un speaker :

segments = [seg1, seg2, seg3, ...]  # Tous les segments du speaker
embeddings = [embed(seg1), embed(seg2), ...]
pooled = mean(embeddings)
normalized = L2_normalize(pooled)  # Must be 1.0 for cosine

Amélioration accuracy: 45% → 78-82%

3. Voiceprint Dual Embeddings¶

Chaque speaker a 2 types de voiceprints :

4. Metadata Propagation¶

Document complet → LLM extraction → Metadata globales
    ↓
Chunking sémantique (42 chunks)
    ↓
Metadata propagée à TOUS les chunks
    ↓
+ Metadata per-chunk (mentioned_participants, chunk_type)

Quick Start¶

Prérequis¶

• Docker + Docker Compose
• Python 3.11+
• PostgreSQL 15
• Qdrant 1.8+
• Redis 7+

Installation Locale¶

# 1. Clone repository
git clone <repo-url>
cd smart-transcription

# 2. Setup environment
cp .env.example .env
# Edit .env avec vos credentials

# 3. Start services
docker-compose up -d postgres redis qdrant

# 4. Install dependencies
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# 5. Run migrations
alembic upgrade head

# 6. Start backend
uvicorn src.main:app --reload --port 8001

Test Endpoint¶

# Health check
curl http://localhost:8001/health

# Login
curl -X POST http://localhost:8001/api/auth/login/json \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@meetnoo.com","password":"admin123"}'

Guides de Lecture Recommandés¶

Pour Architectes Système¶

1. Architecture Globale
2. Deployment Diagram
3. Performance

Pour Développeurs Backend¶

1. Pipeline Workflow
2. Data Models
3. Error Handling

Pour Data/ML Engineers¶

1. Workflow RAG
2. LLM Prompting
3. Architecture Speaker ID v3

Pour DevOps¶

1. Deployment Diagram
2. Architecture Globale (Section Déploiement)
3. Performance (Monitoring)

Métriques Production¶

Liens Rapides¶

Code Source¶

• Services: src/services/ - Logic métier
• Routers: src/routers/ - API endpoints
• Models: src/models/ - SQLAlchemy models
• Schemas: src/schemas/ - Pydantic schemas

Tests¶

• E2E Tests: RAG workflow test/Test_RAG/Test E2E/
• Unit Tests: tests/
• Logs de test: backend_logs_after_fix.txt

Configuration¶

• Environment: .env - Variables d'environnement
• Alembic: alembic/ - Migrations DB
• Docker: docker-compose.yml

Contributeurs¶

• Backend Lead - Smart Transcription BFF, RAG workflow
• ML Engineer - MeetNoo GPU Services, LLM infrastructure

Changelog¶

v1.0.0 (11 Mars 2026)¶

• Architecture v3 (BFF + MeetNoo séparés)
• 3-Priority speaker identification
• Mean pooling pour matching accuracy
• RAG enrichment avec Qdrant
• LLM post-processing (Qwen 2.5-3B)
• Auto-save pending voiceprints
• Dual embeddings (audio 512d + text 1024d)
• Fix: unhashable type: 'dict' bug (lines 607-609, 1163-1164)

License¶

Propriétaire - MeetNoo SAS © 2026

Navigation: Architecture → | Pipeline → | RAG →