Hexis API ist eine RESTful API, die Zugang zu den in unserem Labor entwickelten Sprachanalyse-Tools bietet. Zurzeit umfasst dies ein hochleistungsfähiges Textklassifizierungsmodell zur Erkennung anstößiger Sprache.

Hexis API ist so konzipiert, dass sie möglichst einfach zu nutzen ist. Für die Interaktion mit der API können Sie eine Programmiersprache Ihrer Wahl verwenden. Zum Testen kann auch ein Werkzeug wie Postman, Insomnia oder cURL auf der Befehlszeile nützlich sein.

Für den Anfang bietet diese Dokumentation Code-Beispiele in Javascript, Python, PHP und Unix-Shell. Sie veranschaulichen, wie man Anfragen an den API-Endpunkt stellt und Antworten von dort erhält.

Diese API verwendet einen Basispfad von https://api.hexis.ai. Sie ist nur über eine SSL-gesicherte HTTP-Verbindung verfügbar.

Um mit Hexis API zu arbeiten, können Sie entweder Standard-Netzwerkbibliotheken für die Programmiersprache Ihrer Wahl verwenden oder das Swagger Generator 3-Tool zur automatischen Generierung von Client-Bibliotheken für eine Vielzahl von Sprachen einsetzen. Wir übernehmen jedoch keine Garantie dafür, dass diese automatisch generierten Bibliotheken mit der Hexis API "out of the box" kompatibel sind. Um mit der automatischen Client-Generierung zu beginnen, finden Sie hier unsere OpenAPI 3.0-Spezifikation.

Der HTTP-Inhaltstyp ist application/json, und die zwischen einem Client und dem API-Endpunkt ausgetauschten Payloads sind gültige JSON-Objekte. Dinge, die im Textinhalt zu beachten sind: Doppelte Anführungszeichen (") müssen escaped werden (\") und Zeilenumbrüche sollten durch |LBR| ersetzt werden.

Die Score ist ein Indikator für die Wahrscheinlichkeit, nicht für den Schweregrad. Höhere Zahlen stehen für eine höhere Wahrscheinlichkeit, dass die Muster im Text den Mustern in Kommentaren ähneln, die von Personen als beleidigend gekennzeichnet wurden. Die Scores sollen es den Entwicklern ermöglichen, Schwellenwerte auszuwählen und Textnachrichten auf der Grundlage dieser Schwellenwerte automatisch zu akzeptieren, zu prüfen oder abzulehnen. Obwohl die Zahlen nicht direkt abbilden wie beleidigend ein bestimmter Kommentar ist, kann der Schwellenwert je nach dem vorliegenden Anwendungsfall festgelegt werden.

Für einen Anwendungsfall mit hohem Recall, in dem es vorteilhaft ist, mit falsch positiven anstelle von falsch negativen Ergebnissen umzugehen, kann man einen Schwellenwert um 0,5 oder darüber wählen. Es ist zwar möglich, fälschlicherweise eine Nachricht zu kennzeichnen, die nur leicht toxisch ist (idealerweise gibt es einen manuellen Überprüfungsprozess), aber dadurch werden auch die weniger auffälligen, impliziten Fälle erfassen.

Auf der anderen Seite gibt es Anwendungsfälle mit hoher Präzision, bei der die Priorität darin besteht, nur definitive Fälle von anstößiger Sprache automatisch zu filtern. Hier ist es sicher, einen Schwellenwert bei 0,9 oder höher zu wählen.

Als einfache Heuristik: Bei manueller Moderation wäre ein sinnvoller Schwellenwert 0,5. Alternativ können auch direkt die Klassifikations-Scores zur Einstufung der zu überprüfenden Texte verwendet werden. Es ist auch möglich, das System ohne manuelle Moderation zu betreiben. Mit einem Schwellenwert von 0,9 (und in einigen wenigen Fällen potenziell overblocking) oder 0,99 (und in einigen wenigen Fällen potenziell underblocking).

Derzeit erlaubt die API standardmäßig maximal 10 Anfragen pro Sekunde. Sobald dieses Limit erreicht ist, werden Fehlermeldungen mit einem HTTP-Statuscode von 429 zurückzugeben. Die maximale request body size beträgt 10 Kilobyte. Anfragen, die größer sind, lösen einen Statuscode von 413 aus. Bitte beachten Sie, dass die maximale Textlänge für das Klassifizierungsmodell 120 Wörter beträgt. Jede Anfrage, die darüber hinausgeht, wird in 120 Wörter große Teile aufgeteilt und separat gezählt. Wenn ein Benutzerkonto vorübergehend suspendiert ist (z.B. Testguthaben aufgebraucht und keine Zahlungsinformationen hinterlegt), wird ein Statuscode von 401 ausgegeben.

In der Praxis braucht man meist nicht über das genaue Timing zwischen den Anfragen nachzudenken, da am Endpunkt immer noch kleine bursts von übermäßigen Anfragen bearbeitet werden. Eine Ausnahme bildet die Massenverarbeitung, bei der eine Pause von 100 ms zwischen den Anfragen implementiert werden sollte.

Wenn Sie mit uns ein individuelles Modell erstellen möchten, beachten Sie bitte folgende Spezifikation für die Trainingsdaten.

Das Annotationsschema folgt weitgehend den Richtlinien der GermEval Shared Task on the Identification of Offensive Language, wie sie z.B. in der Übersicht des GermEval 2018 Shared Task on the Identification of Offensive Language beschrieben sind. Der primäre Task ist Task 1: Grobkörnige binäre Klassifikation, bei der Texte entweder als OFFENSE oder OTHER gekennzeichnet werden. Optional ist es möglich, auch Annotationen zu Task 2: Feinkörnige 4-Wege-Klassifikation anzufertigen, wofür die Texte entweder als PROFANITY, INSULT, ABUSE, oder OTHER gekennzeichnet werden. Wir erweitern die zweite Aufgabe um eine weitere Klasse, nämlich THREAT.

Die Daten sollten in einer UTF-8-kodierten Klartextdatei platziert werden. Ein Trainingsbeispiel pro Zeile, im folgenden Format:

<TEXT> tab <LABEL-TASK-I> tab <LABEL-TASK-II>

Zeilenumbrüche im Text sollten durch |LBR| ersetzt werden.