Textnormalisierung

Was ist Textnormalisierung?

Textnormalisierung ist eine Funktion, die Bot-Antworten in ein Format umwandelt, das für Text-to-Speech (TTS)-Systeme optimiert ist. Sie konvertiert geschriebenen Text in eine Form, die beim lauten Sprechen natürlich klingt, und stellt sicher, dass Daten, Telefonnummern, Abkürzungen und andere spezielle Formate vom TTS-Engine korrekt ausgesprochen werden.

Ohne Textnormalisierung könnte ein TTS-System „01.08.2023“ fälschlicherweise als „null eins Punkt null acht Punkt zwei null zwei drei“ aussprechen oder Schwierigkeiten mit Telefonnummern und Fachbegriffen haben. Die Textnormalisierung löst dieses Problem, indem sie solchen Text in Formate umwandelt, die TTS-Engines ordnungsgemäß verarbeiten können.

Warum ist es wichtig?

Wenn Benutzer über einen Telefonkanal mit Ihrem Bot interagieren, ist die Qualität der gesprochenen Ausgabe entscheidend für eine gute Benutzererfahrung. Die Textnormalisierung stellt sicher, dass:

• Daten natürlich gesprochen werden (z. B. „der erste August zweitausenddreiundzwanzig“)
• Telefonnummern und IBANs Ziffer für Ziffer mit korrektem Abstand gelesen werden
• Fachbegriffe und Abkürzungen bei Bedarf Buchstabe für Buchstabe buchstabiert werden
• Währungsbeträge korrekt ausgesprochen werden
• Zahlen in ihre Wortäquivalente umgewandelt werden, wenn dies angebracht ist

Wie verhält sich die Textnormalisierung?

Die Textnormalisierung erfolgt während der Bot-Antwortphase, nachdem das LLM eine Antwort generiert hat, aber bevor sie an die Text-to-Speech-Engine gesendet wird. Der Prozess funktioniert in zwei Stufen:

Stufe 1: LLM-Tagging (Optional)

Wenn der System-Prompt aktiviert ist, wird das LLM angewiesen, bestimmte Inhalte in seinen Antworten mit speziellen XML-ähnlichen Tags zu kennzeichnen:

• <date>01.08.2023</date> - für Daten in verschiedenen Formaten
• <literal>042165838493</literal> - für Inhalte, die Zeichen für Zeichen gelesen werden sollen

Diese Stufe ist optional und wird durch den Prompt Enabled-Schalter in den allgemeinen Einstellungen gesteuert.

Stufe 2: Normalisierungsverarbeitung

Der Textnormalisierer verarbeitet die Antwort des Bots gemäß den aktivierten Regeln:

1. Erkennt getaggte Inhalte - Verarbeitet alle vom LLM hinzugefügten <date>- und <literal>-Tags
2. Wendet Normalisierungsregeln an - Konvertiert Zahlen, Währungen, Zeiten usw. basierend auf den aktivierten Regeln
3. Wendet Synonyme an - Ersetzt Wörter gemäß dem benutzerdefinierten Wörterbuch
4. Gibt normalisierten Text aus – Das Ergebnis wird im normalized_text-Feld des BotUtteredEvent gespeichert, das dann vom Telefonserver verwendet wird.

Die Normalisierung erfolgt nur, wenn alle Bedingungen erfüllt sind (System aktiviert, Knoten aktiviert, Funktion aktiviert), wie im Abschnitt zur Hierarchie unten erläutert.

Telefoneinstellungen

Um die Textnormalisierung zu konfigurieren, navigieren Sie zum Telefon-Kanal im Konfigurationspanel Ihres Bots. Die Textnormalisierungseinstellungen sind in mehrere Abschnitte unterteilt.

Allgemeine Einstellungen

Textnormalisierung aktivieren

Der Hauptschalter („Textnormalisierung für die ausgewählte Sprache anwenden“) aktiviert oder deaktiviert das gesamte Textnormalisierungssystem für diese Sprache. Wenn dies deaktiviert ist, erfolgt keine Normalisierung, unabhängig von anderen Einstellungen.

Sprache

Derzeit unterstützt die Textnormalisierung nur Deutsch (de).

System-Prompt

Der System-Prompt weist das LLM an, wie es seine Antworten für eine optimale TTS-Ausgabe formatieren soll. Wenn Prompt Enabled aktiv ist, wird dieser Prompt automatisch zur Systemnachricht des LLM hinzugefügt.

Standard-System-Prompt:

OUTPUT INFO:
Your output will be fed into a Text-to-Speech model, thus please follow these guidelines:

Luckily, we have a text normalizer in place to help communicate with the user. The text normalizer accepts the following tags: <date>$DATE</date> and <literal>$LITERAL</literal>. So you don't have to change your behavior.

Text Formatting Tags:
- <date> tag for dates. Supported formats:
  • DD.MM.YYYY or DD/MM/YYYY (e.g., <date>01.08.2023</date> or <date>01/08/2023</date>)
  • DD.MM.YY or DD/MM/YY with short year (e.g., <date>01.08.23</date>)
  • MM/YYYY or MM/YY for credit card expiry (e.g., <date>06/27</date>)
- <literal> tag for anything where each character or digit must be spelled out individually. Use for EVERY initialism BUT NOT abbreviation or acronym (e.g. <literal>CDU</literal>, <literal>GPT</literal>, <literal>DPD</literal>, but not NASA, GIF etc.), version numbers (e.g. <literal>3.2.101</literal>), license plates (e.g. <literal>HB-CE-349</literal>), error codes (e.g. <literal>HTTPS 404</literal>), ibans (e.g. <literal>DE93 3845 7384 7573 2253 12</literal>), telephone numbers (e.g. <literal>042165838493</literal>) etc.

Important Rules:
- Ordinal numbers should be written out in full words (e.g., write "der zwölfte Platz" instead of "der 12. Platz")
- Keep all other numbers in their standard numeric format (e.g., "5 Äpfel", "100 Euro", "das Jahr 2024")
- Tool calls and their outputs are NOT sent to Text-to-Speech - therefore, do not use any formatting tags (<date>, <literal>, etc.) within tool call parameters or when processing tool call results
- Only apply these formatting tags to the final text that will be spoken to the user

Sie können diesen Prompt an Ihre spezifischen Anwendungsfälle anpassen. Beispielsweise könnten Sie Anweisungen für branchenspezifische Terminologie hinzufügen oder die Richtlinien für den Kommunikationsstil Ihres Bots anpassen.

Toggle Prompt Enabled steuert, ob dieser Prompt zur Systemnachricht des LLM hinzugefügt wird. Deaktivieren Sie dies, wenn Sie nur die regelbasierte Normalisierung ohne LLM-Tagging verwenden möchten.

Synonyme

Die Synonymfunktion ermöglicht es Ihnen, benutzerdefinierte Ersetzungen für bestimmte Wörter oder Phrasen zu definieren. Dies kann Ihnen helfen, die Sprachausgabe Ihres Bots für Ihren Anwendungsfall anzupassen.

Hier sind einige Anwendungsbeispiele:

• Branding: Ersetzen Sie „ABC telecom“ durch „A B C Telekommunikation“.
• Acronyme als Wörter: Ersetzen Sie „NATO“ durch „Nah-toh“.
• Abkürzungen standardisieren: Ersetzen Sie „z.B.“ durch „zum Beispiel“.

Sie können Synonyme für fast jede Art von routinemäßiger Ersetzung verwenden, bei der die Standardaussprache nicht korrekt ist oder ein bestimmtes Ausgabeformat benötigt wird.

Wie man Synonyme hinzufügt

1. Klicken Sie auf Synonym hinzufügen im Synonyme-Abschnitt
2. Geben Sie den Schlüssel ein (das zu ersetzende Wort)
3. Geben Sie den Wert ein (das Ersatzwort/-phrase)
4. Schalten Sie Synonyme aktiviert ein, um die Funktion zu aktivieren

Synonyme werden nach allen regelbasierten Normalisierungen angewendet, sodass sie auf den Text wirken, nachdem Daten, Zahlen und andere Regeln verarbeitet wurden.

Funktionsspezifische Einstellungen

Die Textnormalisierung kann für bestimmte LLM-API-Funktionen aktiviert oder deaktiviert werden. Dies gibt Ihnen eine feinkörnige Kontrolle darüber, welche Arten von Bot-Antworten normalisiert werden.

Verfügbare Funktionen

• a_call_llm: Standard-LLM-Aufrufe ohne Tools
• a_call_llm_w_tools: LLM-Aufrufe mit Tool-/Funktionsaufrufen aktiviert
• a_infer_with_chat_model: Chat-Modell-Inferenzaufrufe
• stream_call_llm: Streaming-LLM-Antworten
• a_stream_call_llm_w_tools: Streaming-LLM-Antworten mit Tools
• _raw_llm_call: Low-Level-Direkt-LLM-API-Aufrufe
• a_call_llm_with_response_model: LLM-Aufrufe mit strukturierten Antwortmodellen
• fixed_utter: Feste Äußerungen aus Antwortknoten und skriptbasierten Ausgaben

Jede Funktion kann unabhängig umgeschaltet werden. Beispielsweise könnten Sie die Normalisierung für fixed_utter (Antwortknoten) aktivieren, sie jedoch für _raw_llm_call deaktivieren, wenn Sie eine benutzerdefinierte Verarbeitung für diese Antworten haben.

Normalisierungsregeln

Normalisierungsregeln definieren, welche Arten von Texttransformationen angewendet werden. Jede Regel kann unabhängig ein- oder ausgeschaltet werden.

Tageszeit

Konvertiert Zeitausdrücke wie „14:30“ oder „9:15 Uhr“ in ein gesprochenes Format. Beispiele:

• 14:30 → „vierzehn Uhr dreißig“
• 9:15 Uhr → „neun Uhr fünfzehn“

Datum

Um Daten in ihre natürlich gesprochene deutsche Form zu konvertieren, schließen Sie das Datum in ein <date>-Tag ein. Das Textnormalisierungssystem wird automatisch eine Vielzahl von gängigen europäischen Datumsformaten in fließendes, natürlich klingendes Deutsch umwandeln.

Unterstützte Eingaben:

• <date>1.8.23</date> oder <date>1.8.2023</date> → „erster August zweitausenddreiundzwanzig“
• <date>01.08.1999</date> → „erster August neunzehnhundertneunundneunzig“
• <date>01.08.2023</date> → „erster August zweitausenddreiundzwanzig“
• <date>01/08/2023</date> → „erster August zweitausenddreiundzwanzig“
• <date>6/27</date> → „Juni zweitausendsiebenundzwanzig“
• <date>06/27</date> → „Juni zweitausendsiebenundzwanzig“
• <date>06/2027</date> → „Juni zweitausendsiebenundzwanzig“

Literal

Verarbeitet Text, der in <literal>-Tags eingeschlossen ist, und buchstabiert jedes Zeichen einzeln gemäß Ihrer Literal-Mappings-Konfiguration. Sie können das Trennzeichen anpassen, das zwischen den buchstabierten Zeichen in den Literal-Mappings-Einstellungen verwendet wird (Standard: , - Komma und Leerzeichen).

Beispiele (mit Standardtrennzeichen , ):

• <literal>GPT</literal> → „geh, peh, teh“
• <literal>042165838493</literal> → „null, vier, zwei, eins, sechs, fünf, acht, drei, acht, vier, neun, drei“
• <literal>DE93 3845</literal> → „deh, eh, neun, drei, drei, acht, vier, fünf“

Ordinal (nicht perfekt)

Hinweis: Die Ordinalnormalisierung funktioniert nicht perfekt für alle Fälle. Sie sollte nur verwendet werden, wenn Ihr Assistent von einem kleinen oder schwachen LLM betrieben wird, das nicht in der Lage ist, konsistent korrekte grammatikalische Formen selbst zu erzeugen. Aus diesem Grund enthält die Standardkonfiguration eine explizite Anweisung im LLM-Prompt, um korrekte Ordinalformen direkt zu erzeugen, wodurch die Notwendigkeit für diese Regel nach Möglichkeit vermieden wird.

Konvertiert Ordinalzahlen (z. B. „1.“, „12.“) in ihre Wortform:

• der 1. Platz → „der erste Platz“
• am 12. Tag → „am zwölften Tag“

Währung

Konvertiert Währungsbeträge in ein gesprochenes Format:

• 50€ → „fünfzig Euro“
• 100 Euro → „einhundert Euro“

Zahl

Konvertiert numerische Werte in ihre Wortäquivalente:

• 42 → „zweiundvierzig“
• 1000 → „eintausend“

Literal Mappings

Literal Mappings steuern, wie einzelne Zeichen ausgesprochen werden, wenn <literal>-Tags verarbeitet werden. Sie können vier Kategorien anpassen:

Buchstaben: Wie jeder Buchstabe ausgesprochen wird

• Standard: a → „ah“, b → „beh“, c → „zee“ usw.

Zeichen: Wie Sonderzeichen ausgesprochen werden

• Standard: # → „Hashtag“, ! → „Ausrufezeichen“, ? → „Fragezeichen“ usw.

Ziffern: Wie Zahlen ausgesprochen werden, wenn sie buchstabiert werden

• Standard: 0 → „null“, 1 → „eins“, 2 → „zwei“ usw.

Trennzeichen: Das Zeichen oder der Abstand, der zwischen buchstabierten Zeichen verwendet wird

• Standard: , (Komma und Leerzeichen)
• Beispiel: Mit Trennzeichen , wird „GPT“ zu „geh, peh, teh“

Sie können jede dieser Zuordnungen an Ihren bevorzugten Aussprachestil anpassen.

Knotenebeneinstellungen

Zusätzlich zu den globalen Telefoneinstellungen kann die Textnormalisierung auf der Ebene einzelner Knoten gesteuert werden. Dies ermöglicht es Ihnen, die Normalisierung für bestimmte Teile Ihres Gesprächsflusses zu aktivieren oder zu deaktivieren.

Wo es zu finden ist

Der Schalter „Textnormalisierung aktivieren“ erscheint im Konfigurationspanel für:

• Antwortknoten
• Wissensknoten
• Formular-Knoten
• Aktionsknoten

Wie es funktioniert

Der Knotenebene-Schalter bestimmt, ob die Normalisierung für die Ausgabe dieses spezifischen Knotens angewendet wird. Es funktioniert jedoch in Verbindung mit den globalen Einstellungen:

• Wenn globale Textnormalisierung deaktiviert ist, hat der Knotenebene-Schalter keine Wirkung
• Wenn globale Textnormalisierung aktiviert ist, steuert der Schalter jedes Knotens, ob die Normalisierung auf seine Ausgabe angewendet wird

Dies gibt Ihnen die Flexibilität, die Normalisierung selektiv in Ihrem Gesprächsfluss zu verwenden. Beispielsweise könnten Sie:

• Normalisierung für kundenorientierte Antworten aktivieren
• Normalisierung für andere LLM-Aufrufe deaktivieren
• Normalisierung nur für Knoten aktivieren, die sich mit Daten, Zahlen oder Fachbegriffen befassen

Verwendung von use_normalize in der Tracker-API

Für fortgeschrittene Benutzer und Entwickler, die mit benutzerdefinierten Skripten arbeiten, bietet der use_normalize-Parameter eine programmatische Kontrolle über die Textnormalisierung für einzelne LLM-Aufrufe.

Verfügbar in allen LLM-Funktionen

Der use_normalize-Parameter ist in allen Tracker-API-LLM-Funktionen verfügbar:

# Normalisierung für diesen Aufruf erzwingen
response = await tracker_api.a_call_llm(
    messages=[...],
    use_normalize=True
)

# Normalisierung für diesen Aufruf deaktivieren
response = await tracker_api.a_call_llm_w_tools(
    messages=[...],
    tools=[...],
    use_normalize=False
)

# Standardeinstellungen verwenden (Parameter weglassen)
response = await tracker_api.stream_call_llm(
    messages=[...]
)

Verfügbare Funktionen

• tracker_api.a_call_llm(..., use_normalize=True/False)
• tracker_api.a_call_llm_w_tools(..., use_normalize=True/False)
• tracker_api.a_infer_with_chat_model(..., use_normalize=True/False)
• tracker_api.stream_call_llm(..., use_normalize=True/False)
• tracker_api.a_stream_call_llm_w_tools(..., use_normalize=True/False)
• tracker_api._raw_llm_call(..., use_normalize=True/False)
• tracker_api.a_call_llm_with_response_model(..., use_normalize=True/False)
• tracker_api.fixed_utter(..., use_normalize=True/False)

Wie alles zusammenarbeitet

Das Verständnis der Hierarchie der Textnormalisierungseinstellungen ist entscheidend für die korrekte Konfiguration. Die Textnormalisierung verwendet ein mehrstufiges Entscheidungssystem, um zu bestimmen, ob die Normalisierung angewendet wird.

Die Hierarchie

Die Textnormalisierung folgt dieser Prioritätsreihenfolge:

1. Systemebene (Telefonkanal) - Hauptschalter

   • Ort: Telefonkanal → Textnormalisierung → Textnormalisierung für die ausgewählte Sprache anwenden
   • Wirkung: Wenn deaktiviert, erfolgt KEINE Normalisierung, unabhängig von anderen Einstellungen
   • Dies ist die ultimative Überschreibung

2. Überschreibungsebene - use_normalize-Parameter

   • Ort: Im Code, unter Verwendung von tracker_api-Funktionen
   • Wirkung: Wenn explizit auf True oder False gesetzt, überschreibt Knoten- und Funktionseinstellungen
   • Funktioniert nur, wenn die Systemebene aktiviert ist

3. Knotenebene - Textnormalisierung aktivieren-Schalter

   • Ort: Individuelle Knoten-Konfiguration (Antwort-, Wissens-, Aktions-, Formular-Knoten)
   • Wirkung: Steuert die Normalisierung für die Ausgabe dieses spezifischen Knotens
   • Standard: Aktiviert

4. Funktionsebene - Funktionsspezifische Einstellungen

   • Ort: Telefonkanal → Textnormalisierung → Funktionsspezifische Normalisierung
   • Wirkung: Steuert die Normalisierung für spezifische LLM-API-Funktionen
   • Jeder Funktionstyp kann individuell aktiviert/deaktiviert werden

Entscheidungslogik

Damit die Textnormalisierung angewendet wird, müssen alle folgenden Bedingungen erfüllt sein:

System Enabled AND (use_normalize=True OR (Node Enabled AND Function Enabled))

Genauer gesagt:

Szenario 1: System deaktiviert

• Ergebnis: Keine Normalisierung, jemals

Szenario 2: System aktiviert + use_normalize=True

• Ergebnis: Normalisierung angewendet (Knoten- und Funktionseinstellungen ignoriert)

Szenario 3: System aktiviert + use_normalize=False

• Ergebnis: Keine Normalisierung (explizite Überschreibung)

Szenario 4: System aktiviert + Knoten aktiviert + Funktion aktiviert

• Ergebnis: Normalisierung angewendet

Szenario 5: System aktiviert + Knoten deaktiviert

• Ergebnis: Keine Normalisierung (auch wenn Funktion aktiviert ist)

Szenario 6: System aktiviert + Knoten aktiviert + Funktion deaktiviert

• Ergebnis: Keine Normalisierung

Anzeige der Normalisierungsergebnisse

Um Ihnen zu helfen, zu überprüfen, ob die Textnormalisierung korrekt funktioniert, gibt es mehrere Möglichkeiten, die normalisierte Ausgabe zu inspizieren.

Entwicklungs-Chat-UI-Schalter

In der Entwicklungs-Chat-Oberfläche gibt es einen Textnormalisierungsschalter, der es Ihnen ermöglicht, den normalisierten Text neben der ursprünglichen Bot-Antwort anzuzeigen. Dies ist hilfreich für:

• Testen Ihrer Normalisierungskonfiguration
• Überprüfen, ob Daten, Zahlen und spezielle Formate korrekt normalisiert werden
• Debuggen von Problemen mit Normalisierungsregeln

Wenn aktiviert, zeigt die Chat-Oberfläche sowohl die normalisierte Version an, die an die TTS-Engine gesendet würde.

Programmatischer Zugriff (fortgeschrittene Benutzer)

Für Entwickler und fortgeschrittene Benutzer, die programmgesteuert auf normalisierten Text zugreifen müssen, wird die normalisierte Ausgabe im Ereignis-Payload gespeichert:

BotUtteredEvent

Das normalized_text-Feld enthält die normalisierte Version der Bot-Antwort:

# Beispielstruktur
{
    "name": "BotUtteredEvent",
    "payload": {
        "text": "Your appointment is on <date>15.03.2024</date>",
        "normalized_text": "Your appointment is on fünfzehnter März zweitausendvierundzwanzig",
        ...
    },
    ...
}

StreamedUtteranceEvent

Für Streaming-Antworten ist der normalisierte Text auch in Streaming-Ereignissen verfügbar:

# Beispielstruktur für Streaming-Ereignisse
{
    "name": "StreamedUtteranceEvent",
    "payload": {
        "text": "chunk of response...",
        "normalized_text": "normalized chunk...",
        ...
    },
    ...
}

Wenn normalized_text None ist

Wenn normalized_text None ist oder im Ereignis nicht vorhanden ist, bedeutet dies:

• Die Textnormalisierung ist für diese Antwort nicht aktiviert
• Die System-, Knoten- oder Funktionseinstellungen verhinderten die Normalisierung
• Die use_normalize=False-Überschreibung wurde verwendet

Dies ist normal und erwartet, wenn die Normalisierung absichtlich für bestimmte Ausgaben deaktiviert ist.