85.1.29. pepsi-detect-language¶

classify one message the way the pipeline would, offline

Section du manuel:: 1

85.1.29.1.1. Nom¶

pepsi-detect-language - outil de diagnostic et d’ajustement pour la détection de langue de Pepsi.

85.1.29.1.2. Synopsis¶

pepsi-detect-language [OPTIONS] [FILE]

85.1.29.1.3. Description¶

pepsi-detect-language répond à une seule question : que noterait pepsi-stage-detect-language(1) pour ce message ? Il lit un unique message, y exécute la classification propre de l’étape et écrit la valeur state.language résultante — et rien d’autre — sur la sortie standard.

C’est un outil de diagnostic et d’ajustement, non une partie du pipeline. Il n’ouvre jamais la base, ne touche jamais la file d’attente et n’a besoin d’aucune ligne pepsi.workqueue : on peut donc l’exécuter sans risque sur une copie sauvegardée d’un message mal classifié en production, sur un hôte qui n’est pas le serveur de messagerie, et à répétition avec différents ensembles –languages pendant qu’on cerne l’option à configurer.

Utilisez-le pour :

reproduire une erreur de classification à partir d’un message sauvegardé, et voir avec –explain pourquoi le détecteur a choisi ce qu’il a choisi — le texte extrait, la prose ayant survécu au filtrage (ce que le détecteur a réellement vu), et la confiance de chaque langue candidate ;
ajuster l’option LANGUAGES de l’étape : une langue candidate que le trafic ne contient jamais concourt tout de même pour la probabilité, et la retirer est souvent tout le remède. Relancez le même message contre différents ensembles avec –languages jusqu’à ce que la réponse soit bonne, puis configurez cet ensemble ;
vérifier un corpus en boucle (for m in Maildir/cur/*; do …; done) avant et après un changement de configuration.

C’est le même exécutable que pepsi-stage-detect-language(1), installé comme second nom pour lui — les deux partagent tout le chemin de classification, ainsi que les modèles de langue liés statiquement, raison pour laquelle ils sont aussi empaquetés ensemble. Le programme à exécuter est choisi d’après le nom sous lequel il a été invoqué, de sorte qu’une compilation dépourvue d’un tel lien symbolique atteint l’outil par pepsi-stage-detect-language pepsi-detect-language [OPTIONS] [FICHIER], qui se réexécute sous le second nom.

85.1.29.1.4. Entrée¶

Le message est lu depuis FILE, ou depuis l’entrée standard si aucun fichier n’est donné (ou si FILE vaut -). Un message par invocation. Trois formes d’entrée sont acceptées, et laquelle est fournie est détectée :

mbox: Une ligne de séparation From_ en tête — la convention mbox : From suivi d’une espace et de l’expéditeur d’enveloppe — est retirée, et la protection mboxrd >From dans le corps est annulée. (L’annulation n’a lieu que si une ligne de séparation a réellement été trouvée : ailleurs, une ligne commençant par >From est du texte cité par quelqu’un.) Notez qu’un fichier contenant plusieurs messages mbox est traité comme un seul message ; découpez-le au préalable.
un message RFC 5322 complet: Utilisé tel quel, exactement comme l’étape le verrait après que pepsi-ingress(1) l’a stocké.
un corps nu, sans bloc d’en-têtes: Enveloppé dans un en-tête Content-Type: text/plain minimal — déclarant utf-8 ou iso-8859-1 selon ce que sont les octets — de sorte que l’analyseur MIME le lise comme du texte.

Un bloc d’en-têtes n’est reconnu que lorsque chaque ligne avant la première ligne vide est un champ d’en-tête ou une continuation repliée de l’un d’eux. C’est ce qui empêche un corps commençant par quelque chose comme Re: the meeting d’être pris pour un bloc d’en-têtes à un seul champ ; –body-only force la lecture en corps nu lorsque l’entrée est réellement un tel corps.

Les fins de ligne sont normalisées en CRLF, comme le fait pepsi-ingress(1), de sorte qu’un message sauvegardé dans un fichier se classifie identiquement à la copie que détenait la file d’attente.

Le bloc d’en-têtes est conservé, et c’est délibéré. Aucun texte d’en-tête n’atteint jamais le classifieur — l’étape n’extrait que les parties de corps en ligne, de sorte que Subject:, From: et la trace Received: sont écartés de ce qui est classifié. Mais Content-Type, charset et Content-Transfer-Encoding décident de ce qu”est le corps : les retirer classifierait un message quoted-printable, base64 ou HTML d’après son encodage plutôt que d’après sa prose — ce qui est l’une des erreurs de classification que cet outil existe pour trouver.

85.1.29.1.5. Sortie¶

En cas de succès, une ligne sur la sortie standard : la chaîne de style Accept-Language que l’étape fusionnerait dans state.language, par exemple

en;q=1, de;q=0.45

Rien d’autre n’est jamais écrit sur la sortie standard, de sorte que la valeur peut être capturée directement

lang=$(pepsi-detect-language message.eml)

Lorsque l’étape ne noterait aucune langue — le message n’a pas de texte en ligne, rien de ce texte n’est de la prose (un corps qui n’est que des URL), il y a trop peu de prose pour classifier, ou aucune langue candidate n’atteint le seuil de confiance de 5 % —, la sortie standard reste vide et la raison est rapportée sur la sortie d’erreur standard. Ce n’est pas une erreur : c’est ce que fait l’étape, en faisant avancer le message sans ajouter de clé language.

Le format est décrit dans pepsi-stage-detect-language(1) et pepsi.state(7).

85.1.29.1.6. Options¶

–languages CODES

Détecter parmi ces langues candidates au lieu de celles qui sont configurées, écrites comme l’est l’option LANGUAGES de l’étape (codes ISO 639-1 séparés par des espaces ou des virgules, au moins deux, par exemple "en de fr" ; * sélectionne toutes les langues prises en charge, comme dans l’option). Le fichier de configuration n’est alors pas lu du tout : c’est donc aussi ainsi qu’on exécute l’outil sur un hôte sans configuration Pepsi. C’est le réglage sur lequel jouer : l’ensemble de candidates est l’option qui explique le plus souvent une réponse fausse — comparez --languages '*' (ce que l’assistant pepsi-setup configure par défaut) à un ensemble restreint aux langues que votre trafic contient réellement.

–stage NAME

Prendre les langues candidates dans [stage-NAME]. Nécessaire seulement lorsqu’une configuration exécute l’étape de détection plus d’une fois (par exemple sur le chemin entrant et sur le chemin de soumission avec des ensembles de langues différents) ; avec une seule étape de ce type, elle est trouvée automatiquement.

–body-only

Traiter l’entrée comme un corps de message nu, même si elle commence par quelque chose qui ressemble à un bloc d’en-têtes.

–explain

Écrire les étapes intermédiaires sur la sortie d”erreur standard : comment l’entrée a été encadrée, l’ensemble de candidates et d’où il venait, le texte de corps extrait, la prose restant après filtrage (ce qui a réellement été donné au détecteur, et si cela provenait de l’alternative HTML), la confiance de chaque langue candidate et lesquelles les règles des trois premières et des 5 % ont conservées, ainsi que l’issue finale. La sortie standard n’est pas affectée : –explain peut donc être ajouté à toute invocation sans perturber un script qui lit le résultat.

Les deux blocs de texte sont ceux à lire ensemble. L’étape ne classifie pas le corps tel qu’extrait : elle retire d’abord tout ce qui ne peut pas être un mot — URL, adresses e-mail, blocs base64, enregistrements DNS, identifiants — parce que de tels jetons ne sont des mots dans aucune langue, et un corps dominé par eux est classifié d’après eux plutôt que d’après sa prose. Lorsqu’une classification paraît fausse, la question porte le plus souvent sur ce qui est dans le second bloc, non le premier.

-c FILE, –config FILE

Lire la configuration depuis FILE au lieu de parcourir les emplacements par défaut. Seul l’ensemble de langues candidates en est tiré.

-L LOGLEVEL, –log LOGLEVEL

Définir la verbosité de journalisation (info par défaut). Les journaux vont sur la sortie d’erreur standard.

-v, –verbose

Affiche les messages de journal de toutes les sources.

-h, –help ; -V, –version

Affiche un résumé d’utilisation / la version et quitte.

85.1.29.1.7. Configuration¶

Sans –languages, l’ensemble de candidates est l’option LANGUAGES de l’étape de détection configurée — l’unique section [stage-<name>] dont le PROGRAM est pepsi-stage-detect-language, ou celle que nomme –stage. Si la configuration n’exécute aucune étape de ce type, l’ensemble par défaut intégré à l’étape est utilisé et un avertissement le dit. Aucune autre option n’est lue, et rien n’est écrit.

85.1.29.1.8. Code de sortie¶

0: Le message a été classifié. La sortie standard contient la chaîne state.language, ou est vide si l’étape n’en noterait aucune.
1: Le message n’a pas pu être lu, la configuration n’a pas pu être chargée (passez –languages pour fonctionner sans), –stage a nommé une section qui n’existe pas ou qui exécute un autre programme, plusieurs étapes exécutent le programme et aucune n’a été nommée, ou –languages était invalide. La raison est écrite sur la sortie d’erreur standard.

85.1.29.1.9. Exemples¶

Qu’a fait le pipeline de ce message ?

pepsi-detect-language -c /etc/pepsi/pepsi.conf message.eml

Pourquoi a-t-il dit cela ?

pepsi-detect-language --explain message.eml >/dev/null

Un ensemble de candidates plus étroit y remédierait-il ?

pepsi-detect-language --languages "en de" message.eml

Classifier un corps tapé au terminal (terminer par Ctrl-D)

pepsi-detect-language --languages "en de fr" -

Passer en revue un maildir avant de changer LANGUAGES

for m in ~/Maildir/cur/*; do
    printf '%s\t%s\n' "$(pepsi-detect-language --languages "en de" "$m")" "$m"
done | sort | uniq -c

85.1.29.1.10. Voir aussi¶

pepsi-stage-detect-language(1), pepsi-stage-block-language(1), pepsi-stage-vacation(1), pepsi.conf(5), pepsi.state(7)

85.1.29.1.11. Bogues¶

Signalez les bogues au gestionnaire de tickets de Pepsi.