F-05 Reconnaissance vocale (STT)

Brique F de la plateforme Enterprise AI. Technologie : faster-whisper (CTranslate2) sur des workers GPU ou CPU + transcription LiteLLM pour les fournisseurs externes. Version anglaise : ../../en/bricks/F-05-speech-to-text.md.

Rôle et responsabilités

• Transcrire l'audio avec détection de langue, horodatage par mot, traduction optionnelle vers l'anglais.
• Horodatage par mot : word_timestamps: true sur POST /v1/multimodal/stt ajoute output.words (start, end, word ; mots masqués quand la DLP masque) ; sur POST /v1/gateway/audio/transcriptions, timestamp_granularities (word, segment) exige response_format=verbose_json et est transmis sous la forme timestamp_granularities[]. Une valeur ou un fournisseur non pris en charge donne un refus 422 traduit.
• Enchaîner optionnellement la diarisation F-06 et le masquage des données personnelles F-11 sur la transcription.

Position et interactions

• Chemin d'exécution : synchrone pour l'audio court, job asynchrone pour l'audio long, streaming dans F-08.
• POST /v1/multimodal/stt crée toujours un job dans eai.multimodal_jobs : l'adaptateur faster-whisper local (EAI_WHISPER_MODEL, EAI_WHISPER_DEVICE) ou l'adaptateur compatible OpenAI (EAI_STT_URL, EAI_STT_MODEL) le traite, et le client suit le job par GET /v1/multimodal/jobs/{id}.
• La transcription peut être ingérée dans une base de connaissances (brique E) en héritant de la classification du média.

Part open source et part développée

• Open source réutilisé : faster-whisper, CTranslate2, Silero VAD pour le découpage.
• Développé dans la plateforme : Stratégie de découpage, politique de langue, format de transcription (segments, mots), réponse unifiée entre fournisseurs.

Modèle de données

Tables du Control Plane (schéma eai) : eai.media, eai.multimodal_jobs, eai.usage_events.

Chaque table de tenant a tenant_id uuid NOT NULL et une politique de sécurité au niveau des lignes sur current_setting('app.tenant_id', true)::uuid. ClickHouse usage_events est la réplique analytique de eai.usage_events (ReplacingMergeTree par event_id).

Contrat : contracts/v1/multimodal-contract.schema.json (schema_version 1.0). L'usage est toujours remonté avec contracts/v1/usage-event.schema.json, l'audit avec contracts/v1/audit-event.schema.json.

Endpoints d'API

Méthode	Chemin
POST	/v1/multimodal/stt
POST	/v1/gateway/audio/transcriptions
GET	/v1/multimodal/jobs/{id}

POST /v1/multimodal/stt

Requête :

{
  "media_id": "med_AUD1",
  "model": "faster-whisper-large-v3",
  "language": "fr",
  "dlp_mode": "detect"
}

Réponse :

{
  "job_id": "mmj_S01",
  "status": "succeeded",
  "text": "Bonjour, je vous appelle au sujet de ma facture.",
  "language": "fr",
  "segments": [
    {
      "start": 0.0,
      "end": 2.8,
      "text": "Bonjour, je vous appelle"
    }
  ],
  "usage": {
    "audio_seconds": 184.2,
    "output_tokens": 912
  }
}

POST /v1/gateway/audio/transcriptions

Requête : multipart/form-data avec une partie file (l'audio) et les champs model (obligatoire), language, prompt, response_format (json, text, srt, verbose_json, vtt), temperature et eai, par exemple curl -F file=@meeting.mp3 -F model=whisper-1 -F response_format=verbose_json. La même route accepte aussi du JSON avec l'audio dans content_base64 (plus mime_type et filename) :

{
  "model": "whisper-1",
  "filename": "meeting.mp3",
  "mime_type": "audio/mpeg",
  "content_base64": "SUQzBAAAAAAA...",
  "language": "fr",
  "response_format": "verbose_json"
}

Réponse :

{
  "text": "Bonjour, je vous appelle au sujet de ma facture.",
  "duration": 184.2
}

GET /v1/multimodal/jobs/{id}

Réponse :

{
  "job_id": "mmj_V01",
  "operation": "video_process",
  "status": "succeeded",
  "outputs": {
    "frames": 118,
    "audio_media_id": "med_AUD7"
  },
  "attempts": 1
}

Exemples SDK

Python

from enterprise_ai import EnterpriseAI

client = EnterpriseAI(base_url="<control-plane-url>", api_key="eai_live_xxx", tenant="acme", locale="fr")
client.multimodal.stt.transcribe("med_AUD1", model="faster-whisper-large-v3", language="fr")
client.gateway.transcribe("whisper-1", open("call.wav", "rb").read(), filename="call.wav", language="fr")
client.multimodal.job(job_id="mmj_V01")

TypeScript

import { EnterpriseAI } from "@enterprise-ai/sdk";

const client = new EnterpriseAI({ baseUrl: "<control-plane-url>", apiKey: process.env.EAI_API_KEY, tenant: "acme", locale: "fr" });
await client.multimodal.stt({ media_id: "med_AUD1", model: "faster-whisper-large-v3", language: "fr" });
await client.gateway.audio.transcribe({ model: "whisper-1", fileMediaId: "med_AUD1" });
await client.multimodal.getJob("mmj_V01");

Java

EnterpriseAIClient client = EnterpriseAIClient.builder()
    .baseUrl("<control-plane-url>")
    .apiKey(System.getenv("EAI_API_KEY"))
    .tenant("acme")
    .locale(Locale.FRENCH)
    .build();
client.multimodal().stt(Map.of("media_id", "med_AUD1", "model", "faster-whisper-large-v3", "language", "fr"));
client.gateway().audioTranscriptions(Map.of("model", "whisper-1", "content_base64", "UklGRiQAAABXQVZF", "mime_type", "audio/wav"));
client.multimodal().job("mmj_V01");

Go

client, err := eai.NewClient(eai.WithBaseURL("<control-plane-url>"), eai.WithAPIKey(os.Getenv("EAI_API_KEY")), eai.WithTenant("acme"), eai.WithLocale("fr"))
if err != nil { log.Fatal(err) }
ctx := context.Background()
_, err = client.Multimodal.Stt(ctx, map[string]any{"media_id": "med_AUD1", "model": "faster-whisper-large-v3", "language": "fr"})
_, err = client.Gateway.AudioTranscriptions(ctx, map[string]any{"model": "whisper-1", "content_base64": "UklGRiQAAABXQVZF", "mime_type": "audio/wav", "filename": "call.wav"})
_, err = client.Multimodal.Job(ctx, "mmj_V01")

// worker package: run a media worker consuming multimodal jobs
w, err := worker.New(worker.Config{Source: jobs, Handler: handle, Client: client, Concurrency: 2})
if err != nil { log.Fatal(err) }
err = w.Run(ctx)

Configuration

Variables d'environnement : EAI_STT_MODEL.

Clés de valeurs Helm (deploy/helm/enterprise-ai/values.yaml) : controlPlane.config.EAI_WHISPER_DEVICE, workers.items, workers.nats.

Sécurité

• L'audio et la transcription gardent la classification du média ; les transcriptions de médias secrets ne quittent jamais les modèles locaux.
• Tenant déduit de l'identifiant d'accès, jamais du corps ; sécurité au niveau des lignes PostgreSQL sur chaque table de tenant.
• Chaque mutation et décision de politique écrit un événement d'audit chaîné par hachage (G-11).
• Les erreurs utilisent l'enveloppe standard avec message_i18n en et fr.

Observabilité

• Facteur temps réel (secondes de traitement / secondes audio) exporté en histogramme eai_stt_rtf.
• traceparent W3C propagé, X-Request-Id renvoyé, les spans portent eai.tenant_id, eai.project, eai.agent_id, eai.run_id.

Unités FinOps

• usage_type stt : audio_seconds (base de facturation de la plupart des fournisseurs) et tokens de sortie si le fournisseur facture en tokens ; les exécutions locales ajoutent gpu_seconds.

Modes de défaillance et résilience

• Codec non supporté -> transcodage par F-12 puis nouvelle tentative.
• Texte halluciné sur des silences -> le pré-filtre VAD retire les segments sans parole.

Adoption autonome

Un centre d'appels peut adopter le STT seul avec les API média et FinOps, sans agents.

Tests d'acceptation

1. Un WAV français de 3 minutes donne un WER sous la cible sur le jeu de référence et audio_seconds=184.2.
2. Un fichier de 2 heures renvoie un id de job et se termine avec des horodatages de segments.

Feuille de route d'implémentation

Preuves vocales du kit L4

faster-whisper tiny.en sur CPU via le worker vocal HTTP (tests/test_voice_engines_real.py) : parole Kokoro transcrite, recouvrement des mots 1,00. Transcriptions temps réel filtrées par la DLP avant stockage (MULT-003, MULT-009). Voir le guide du runtime vocal.