Aller au contenu
English

D'abord un menu au clavier

  • Leçon 24
  • 40 min
  • Module 7 : Construire un petit serveur vocal interactif

Où nous en sommes

Nous avons une carte des états et des voix pour les messages. Construisons maintenant le SVI le plus simple qui fonctionne. Dans cette leçon, nous créons un menu au clavier qui lit les fréquences vocales et gère le silence et les mauvaises touches. Il offre toujours un accès à une personne.

Lue depuis YouTube. Rien ne se charge depuis YouTube avant que vous appuyiez sur lecture. Confidentialité
Leçon 24 sur 36 · IA de la parole : transcrire, comprendre et parlerD'abord un menu au clavier
Aperçu du cours

Ce que vous saurez faire

Construisez la première version fonctionnelle du serveur vocal interactif (SVI, IVR) de Larkfield. Il lit les tonalités des touches du téléphone et repose la question après un silence ou une mauvaise touche. Il permet toujours à l’appelant de joindre une personne.

Carnet JupyterFaites cette leçon dans un carnet JupyterColab · Kaggle · GitHub · en anglais

Le carnet (notebook) Jupyter construit un détecteur de touches avec l’algorithme de Goertzel et lit les touches des appels de test enregistrés. Il crée ensuite un petit menu au clavier sous forme d’états et y exécute les appels de test au clavier seulement. Vous ajoutez ensuite la touche 0 pour joindre une personne. Il télécharge seulement quelques courts fichiers audio. Environ 40 minutes.

Le carnet est en anglais. Colab et Kaggle ouvrent votre propre copie. Il faut un compte Google ou Kaggle gratuit. Vous êtes bloqué ? Consultez le carnet de solution.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 40 minutes

Ce que vous devez savoir

Ce qu’il vous faut

  • Votre dossier larkspeech avec les fichiers de voix et les nouvelles dépendances de La synthèse vocale pour les messages.
  • Le modèle Whisper base (téléchargé au module 4). Le clavier ne nécessite aucun modèle, mais la commande de réexécution le charge une fois.
  • Testé sur macOS (Apple M4) avec Python 3.12. Les commandes Windows sont fournies, mais n’ont pas été exécutées.

Appuyez sur une touche d’un téléphone et écoutez. Vous entendez un court bip. Ce n’est pas une seule note : ce sont deux notes simultanées, comme deux touches de piano enfoncées ensemble. Chaque touche possède sa propre paire. Cette paire permet donc d’identifier la touche, même sans la voir.

Cette ancienne technique permet à un menu téléphonique de fonctionner sur n’importe quelle ligne téléphonique. La ligne téléphonique a été conçue pour transporter la voix. Les touches produisent donc des sons semblables à la voix : de courtes tonalités au milieu de sa gamme de fréquences.

Le SVI de Larkfield reçoit l’appel sous forme d’un flux de nombres, 8 000 par seconde. Un appel enregistré ne contient aucun message « la touche 5 a été enfoncée ». Les touches sont dans l’audio, mélangées au bruit de la ligne. Avant de réagir à « appuyez sur 1 pour les commandes », le menu doit trouver les touches dans le son.

Écoutez un appelant qui saisit son numéro de commande au clavier :

Appel de test I-017, tour de parole 3, 1,82 secondes, sur une ligne téléphonique VoIP. Fréquences vocales produites par notre code (aucune voix).

Transcription : six tonalités de touches : 5, 8, 6, 0, 3, 2.

Les deux notes de chaque touche sont appelées DTMF, pour dual-tone multi-frequency (multifréquence à deux tonalités). Ce sont deux tonalités choisies parmi un petit ensemble de fréquences. L’une vient d’un groupe de quatre basses fréquences (la rangée de la touche). L’autre vient d’un groupe de trois hautes fréquences (la colonne) :

1209 Hz 1336 Hz 1477 Hz
697 Hz 1 2 3
770 Hz 4 5 6
852 Hz 7 8 9
941 Hz * 0 #

La touche 5 combine 770 Hz et 1336 Hz. La touche 0 combine 941 Hz et 1336 Hz.

Le SVI n’a donc pas besoin de comprendre tout le son. Il doit seulement mesurer l’intensité de ces sept fréquences. L’algorithme de Goertzel fait exactement cela. C’est une courte boucle qui mesure l’intensité d’une fréquence dans un morceau d’audio. Il demande moins de calculs qu’un spectre complet lorsque vous avez besoin de quelques fréquences seulement. Son nom vient de Gerald Goertzel, qui l’a publié en 1958.

Un petit exemple détaillé : une trame de la touche 5

Section intitulée « Un petit exemple détaillé : une trame de la touche 5 »

Le détecteur découpe l’audio en trames de 20 ms (160 échantillons à 8 kHz). Pour chaque trame, il mesure les sept fréquences. Voici une trame au milieu de la première touche de I-017, telle que le fichier dtmf.py du projet la mesure :

Fréquence (Hz) 697 770 852 941 1209 1336 1477
Intensité 23 539 24 6 13 555 2

La tonalité basse la plus forte est 770 Hz et la tonalité haute la plus forte est 1336 Hz. C’est la rangée 2, la colonne 2, donc la touche 5. Le détecteur vérifie aussi trois règles avant d’accepter une touche :

  1. Les deux tonalités portent la majeure partie de l’énergie de la trame : au moins 60 %. Ici, elles portent 98 %. La parole répartit son énergie sur de nombreuses fréquences, donc elle ne respecte pas cette règle.
  2. Chaque tonalité est au moins 4 fois plus forte que la suivante dans son groupe. Ici, 770 Hz est environ 22 fois plus forte que 852 Hz.
  3. La même touche se trouve dans deux trames consécutives (40 ms). Un clic ou un son bref de la parole dure moins longtemps, donc il ne compte pas.
En haut : la forme d'onde de six touches enfoncées sur 1,8 seconde, étiquetées 5, 8, 6, 0, 3 et 2. Une trame de 20 ms de la première touche est marquée en vert. En bas : un diagramme à barres de l'intensité de sept fréquences dans cette trame, la plus grande valant 1 : 697 Hz 0,04, 770 Hz 0,97, 852 Hz 0,04, 941 Hz 0,01, 1209 Hz 0,02, 1336 Hz 1,00, 1477 Hz 0,00.
Appel de test I-017, tour de parole 3, tel que le SVI l'entend. En haut : six touches enfoncées sur la ligne téléphonique. En bas : l'intensité des sept fréquences DTMF dans une trame de 20 ms de la première touche. Elle est mesurée avec l'algorithme de Goertzel (fichier du projet larkspeech/ivr/dtmf.py).
Description textuelle du diagramme

En haut : les six touches produisent six courts blocs de son, chacun d’environ 0,1 seconde, séparés par de courtes pauses. Le détecteur les a lues comme 5, 8, 6, 0, 3, 2. En bas : dans une trame de la première touche, deux barres ressortent : 770 Hz (0,97) et 1336 Hz (1,00). Les cinq autres barres valent 0,04 ou moins. Ensemble, 770 et 1336 Hz correspondent à la touche 5.

Le détecteur lit {dt.keys_read} dans ce tour de parole, soit les six touches que l’appelant a enfoncées.

Le téléphone de test du cours est une page Web que vous utilisez à la fin de ce module. Son clavier à l’écran envoie un message, {"type": "dtmf", "key": "1"}, au lieu d’une tonalité. De nombreux fournisseurs téléphoniques font la même chose : ils envoient les touches comme des événements distincts en parallèle de l’audio. Le SVI traite les deux méthodes de la même façon : une touche reste une touche.

Le menu reprend la carte des états de la première leçon, écrite dans larkspeech/ivr/dialogue.py. Le dialogue ne sait rien de l’audio. Il reçoit des événements (keys, speech ou no_input, soit touches, parole ou aucune entrée) et renvoie ce qu’il faut dire. Vous pouvez donc le tester avec du texte simple, sans aucun son.

Chaque touche a une seule signification dans le menu :

KEY_INTENT = {"1": "order_status", "2": "opening_hours", "3": "start_return", "0": "agent"}

Chaque événement passe par une méthode, step. Elle vérifie d’abord les deux règles qui s’appliquent dans tous les états : 0 joint toujours une personne, et le silence signifie aucune entrée :

def step(self, kind, value=None):
"""kind: speech (value = the recognised text), keys (value = digits), no_input. Returns actions."""
if self.state == "done":
return []
self.log.append({"state": self.state, "event": kind, "value": value})
if kind == "keys" and value and value[0] == "0" and self.state in ("language", "menu", "number", "confirm"):
self.intent = self.intent or "agent"
return self._transfer("caller_asked")
if kind == "no_input":
retry = {"language": "language_retry", "menu": "menu_retry", "number": "number_retry",
"confirm": "confirm_retry"}[self.state]
return self._miss("no_input", retry)
return getattr(self, f"_on_{self.state}")(kind, value)

La dernière ligne appelle la méthode de l’état actuel : _on_language, _on_menu, _on_number ou _on_confirm. Pour les touches, l’état du menu fait une seule recherche dans un dictionnaire :

def _on_menu(self, kind, value):
intent = KEY_INTENT.get(value[:1]) if kind == "keys" else find_intent(value or "", self.language)
if not intent:
return self._miss("no_match", "menu_retry")
...

La partie else, pour la parole, vient dans la prochaine leçon.

Échecs : répéter une fois, puis joindre une personne

Section intitulée « Échecs : répéter une fois, puis joindre une personne »

Lorsqu’un état ne reçoit aucune touche à temps, ou reçoit une touche inconnue, il appelle _miss :

def _miss(self, kind, retry_key, **kw):
"""A no-input or a no-match: ask again in a different way once, then hand over."""
self.misses += 1
self.log.append({"state": self.state, "miss": kind})
if self.misses >= 2:
return self._transfer("no_input" if kind == "no_input" else "no_match")
return [self._say(retry_key, **kw)]

Le message de nouvelle tentative est différent du premier message. Le menu dit « Dites suivi de commande, heures d’ouverture… ». Sa nouvelle tentative dit « Désolé, je n’ai pas compris. Utilisez votre clavier: 1 pour les commandes… ». Quand l’état change, le nombre d’échecs revient à 0.

Un organigramme. Diffuser le message, puis écouter les touches. Si aucune touche n'arrive dans les 5 secondes, c'est un échec de type aucune entrée. Si une touche arrive : la touche 0 mène à une personne; une touche connue de l'état mène à l'état suivant; toute autre touche est un échec de type aucune correspondance. Après un échec : si c'est le deuxième dans cet état, une personne prend le relais. Sinon, reformuler la demande et écouter à nouveau.
Comment chaque état du menu au clavier gère une touche, une mauvaise touche et le silence.
Description textuelle du diagramme

Après le message, l’état écoute. Il vérifie toute touche reçue dans les 5 secondes. La touche 0 mène directement à une personne. Une touche connue de l’état fait passer l’appel à l’état suivant. Toute autre touche signifie aucune correspondance. Aucune touche en 5 secondes signifie aucune entrée. Les deux sont des échecs. Après le premier échec, l’état reformule la demande. Après le deuxième, une personne prend le relais, et le fiche d’appel conserve la raison.

Trois paramètres contrôlent le clavier :

  • Aucune entrée : 5 secondes après la fin du message.
  • Entre les chiffres : 3 secondes. Un appelant qui arrête de taper au milieu d’un numéro de commande a terminé, et les chiffres reçus sont vérifiés.
  • Le nombre de touches : une touche termine la saisie dans les états de langue, de menu et de confirmation. Dans l’état du numéro de commande, la saisie se termine après 6 touches, ou avec #.

Ces valeurs sont un choix, pas une loi. Un appelant qui lit le numéro sur un courriel imprimé froissé a besoin de plus de 3 secondes entre les chiffres. La réexécution de la dernière leçon de ce module mesure l’effet d’un changement.

Un menu au clavier est le SVI le plus sûr : une touche n’est jamais mal entendue comme un mot. Le cours a mesuré ce qu’il fait seul. Le SVI a réexécuté les 60 appels de test publics et ignoré chaque mot prononcé, comme le ferait un menu au clavier seulement :

Tests réussis Appels terminés sans l’aide d’une personne (taux de rétention)
Clavier seulement 23 sur 60 10 %

Dans les appels synthétiques de Larkfield, la plupart des appelants disent leurs réponses, comme beaucoup de vrais appelants. Un menu au clavier seulement transfère la plupart à une personne : il est sûr, mais il aide peu. Le carnet montre l’autre côté. Parmi les 7 appels de test au clavier seulement, un menu sans la touche 0 en réussit 5. Avec cette touche, il réussit les 7. Le clavier est donc une bonne solution de repli, mais un premier choix peu efficace. La prochaine leçon ajoute la parole.

  1. Depuis le dossier contenant larkspeech et nextia-learning-labs, copiez le reste du SVI depuis l’instantané de fin du module 7. Cela comprend le dossier ivr, la commande speech ivr, ses tests et un document.

    macOS et Linux :

    Fenêtre de terminal
    S=nextia-learning-labs/C41/snapshots/end-of-m07
    cp -R $S/larkspeech/ivr larkspeech/larkspeech/
    cp $S/larkspeech/commands/ivr.py larkspeech/larkspeech/commands/
    cp $S/tests/test_ivr.py larkspeech/tests/
    mkdir -p larkspeech/docs
    cp $S/docs/phone-line-options.md larkspeech/docs/

    Windows PowerShell :

    Fenêtre de terminal
    $S = "nextia-learning-labs\C41\snapshots\end-of-m07"
    Copy-Item -Recurse -Force "$S\larkspeech\ivr" larkspeech\larkspeech\
    Copy-Item "$S\larkspeech\commands\ivr.py" larkspeech\larkspeech\commands\
    Copy-Item "$S\tests\test_ivr.py" larkspeech\tests\
    New-Item -ItemType Directory -Force larkspeech\docs
    Copy-Item "$S\docs\phone-line-options.md" larkspeech\docs\

    Votre projet est maintenant identique à l’instantané end-of-m07, sauf son README.

  2. Allez dans le dossier larkspeech, activez l’environnement et exécutez les tests :

    Fenêtre de terminal
    python -m pytest -q
    ................................. [100%]
    33 passed in 1.69s

    Les six nouveaux tests de tests/test_ivr.py communiquent avec le dialogue à l’aide de texte et de touches. Ils produisent des fréquences vocales avec dtmf.tones() et les relisent. Ils réexécutent aussi un faux appel avec un faux système de reconnaissance. Ils ne nécessitent aucun téléchargement.

  3. Lisez les options de la commande de réexécution :

    Fenêtre de terminal
    speech ivr replay --help
    usage: speech ivr replay [-h] [--model MODEL] [--end-of-turn END_OF_TURN]
    [--by {kind,line,noise,language}] [--calls CALLS]
    [--voice]
    ...
    --calls CALLS only these call IDs (comma-separated)
    --voice time the prompts with the real voice (slower)
  4. Réexécutez quatre appels de test où l’appelant utilise le clavier : un suivi de commande au clavier (I-017), les heures d’ouverture au clavier (I-033, I-034) et un appelant qui appuie sur 0 (I-062).

    Fenêtre de terminal
    speech ivr replay --calls I-017,I-033,I-034,I-062
    IVR replay: 4 recorded test calls, Whisper base, end of turn 0.8 s
    calls passed contained wrong intent to a person s to answer
    all 4 4 75% 0% 25% 44.6
    Wrote outputs/ivr-replay.jsonl (one call record per line)

    Les quatre réussissent. Trois sont retenus, sans l’aide d’une personne. I-062 est transféré à une personne, comme le souhaitait cet appelant, donc il réussit aussi.

  5. Consultez le fiche d’appel de I-017 :

    Fenêtre de terminal
    python -c "import json; r = [json.loads(x) for x in open('outputs/ivr-replay.jsonl')][0]; print(r['outcome'], r['heard']); print(r['prompts'])"
    status_given ['1', '1', '586032', '1']
    ['welcome', 'menu', 'menu_retry', 'number', 'number_retry', 'confirm', 'confirm_retry', 'status']

    Le SVI a entendu les bonnes touches et donné le statut. Mais regardez les messages : après chaque touche, un message de nouvelle tentative suit, comme si l’appelant n’avait rien dit. Un vrai appelant entendrait « Désolé, je n’ai pas compris » trois fois. Gardez cela en tête : la dernière leçon de ce module trouve l’origine du problème.

Faites une prédiction : dans l’état du menu, un appelant appuie sur 7, puis encore sur 7. Que dit le SVI, et comment l’appel se termine-t-il? Vérifiez votre prédiction avec le dialogue seul, sans audio :

Fenêtre de terminal
python -c "from larkspeech import data as D; from larkspeech.paths import data_dir; from larkspeech.ivr.dialogue import Dialogue; d = Dialogue(D.orders(data_dir(None))); d.start(); print(d.step('keys', '1')[0]['key']); print(d.step('keys', '7')[0]['key']); print(d.step('keys', '7')); print(d.record()['outcome'], d.record()['handoff_reason'])"
Vérifiez votre réponse
menu
menu_retry
[{'say': 'I am putting you through to a person now. They will see what you told me.', 'key': 'handover'}, {'transfer': 'no_match'}]
handover no_match

La touche 1 choisit l’anglais, et le SVI diffuse le menu. Le premier 7 signifie aucune correspondance : le SVI diffuse la nouvelle tentative du menu. Le deuxième 7 est le deuxième échec dans l’état du menu. Le SVI annonce qu’il transfère l’appelant, puis transfère l’appel avec la raison no_match (aucune correspondance). Le fiche d’appel conserve cette raison. Grace peut ainsi compter les appelants que le menu n’a pas pu aider.

Erreur courante

Des tonalités de touches trop courtes

Symptôme : les appelants utilisant un certain type de téléphone disent « J’ai appuyé sur 1, mais rien ne s’est passé ». Les autres appelants n’ont aucun problème.

Cause : certains téléphones et certaines lignes envoient des tonalités très courtes. Le détecteur compte une touche seulement lorsqu’elle se trouve dans deux trames consécutives de 20 ms. Dans le carnet, les tonalités de 40 ms sont lues, mais pas celles de 20 ms. Une tonalité de 20 ms ne remplit jamais deux trames entières.

Correction : testez le détecteur avec les tonalités les plus courtes envoyées par vos lignes téléphoniques. La norme DTMF exige au moins 40 ms. Si vous devez accepter des tonalités plus courtes, utilisez des trames plus courtes. Vérifiez ensuite à nouveau que la parole ne devient pas des touches. Si le fournisseur envoie les touches comme événements distincts, utilisez-les.

Conséquence pour le travail en IA : chaque détecteur a un signal minimal qu’il peut détecter. Trouvez-le avec des tests conçus pour cela, avant que les appelants le trouvent pour vous.

Vérifiez votre compréhension

Dans une trame de 20 ms, la tonalité basse la plus forte est 852 Hz, et la haute est 1477 Hz. Chacune est beaucoup plus forte que les autres, et elles restent identiques dans la trame suivante. De quelle touche s'agit-il?

Afficher la réponse

9 : 852 Hz est la troisième rangée (7, 8, 9), et 1477 Hz est la troisième colonne (3, 6, 9). Les trois règles sont respectées : les deux tonalités portent la majeure partie de l’énergie. Chacune est beaucoup plus forte que les autres dans son groupe, et elles durent deux trames. Le détecteur lit donc la touche 9.

Vérifiez votre compréhension

Pourquoi le dialogue dans dialogue.py utilise-t-il des événements (keys, speech, no_input) plutôt que de l'audio?

Afficher la réponse

Pour que la logique puisse être testée seule, avec du texte et des touches, rapidement et sans modèle ni son. La partie audio se trouve dans engine.py : trouver les touches, détecter la fin d’un tour et reconnaître les mots. Chaque partie peut ainsi être testée et modifiée sans l’autre. Le même dialogue sert au téléphone de test, à la réexécution et aux tests unitaires.

Vérifiez votre compréhension

En ignorant la parole, le SVI a réussi 23 des 60 appels de test et en a retenu 10 %. Qu'est-ce que cela indique à Larkfield sur un menu au clavier seulement?

Afficher la réponse

Il est sûr, mais insuffisant. La plupart des appelants de test parlent, donc un menu au clavier seulement transfère la plupart à une personne. Le clavier est une bonne solution de repli pour les lignes bruyantes, les numéros et les appelants qui le préfèrent. L’accès à une personne (0) doit fonctionner dans chaque état. Pour retenir plus d’appels, le SVI doit aussi comprendre la parole.

Récapitulatif

  • Une tonalité de touche (DTMF) combine deux tonalités : une parmi quatre basses fréquences et une parmi trois hautes fréquences.
  • L’algorithme de Goertzel mesure seulement ces fréquences, trame par trame. Une touche compte lorsque ses deux tonalités dominent une trame de 20 ms, dans deux trames consécutives.
  • Le dialogue est une machine à états qui reçoit des événements (touches, parole, aucune entrée) et renvoie ce qu’il faut dire. Il peut être testé avec du texte seul.
  • Chaque état gère aucune entrée (5 s de silence) et aucune correspondance (une mauvaise touche). Il reformule la demande une fois, puis transfère à une personne. 0 joint une personne partout.
  • Sur les appels de test synthétiques de Larkfield, un menu au clavier seulement a retenu 10 % des appels. C’est une bonne solution de repli, mais un premier choix peu efficace.

Vous pouvez maintenant construire un menu au clavier qui lit les touches dans l’audio sans jamais bloquer un appelant. Mais la plupart des appelants préfèrent dire ce qu’ils veulent plutôt qu’attendre « appuyez sur 3 ». Ensuite, vous les laissez parler : vous détectez la fin de leur tour, reconnaissez leurs mots et les transformez en intention.

Leçon suivante : Laisser les appelants dire ce qu'ils veulent