ABBYY Phoenix Plus aus einer Benutzerdefinierten Aktivität aufrufen

Ein Skript einer Benutzerdefinierten Aktivität kann ABBYY Phoenix Plus aufrufen – den von ABBYY bereitgestellten und betriebenen LLM-Endpoint – ohne dass dafür HTTP-, Authentifizierungs- oder providerspezifischer Code geschrieben werden muss. Die Aktivität wird als Schritt in einem Process-Skill ausgeführt, sodass das Modell auf den aktuellen Vorgang zugreifen kann und nachfolgende Schritte dessen Ergebnis weiterverwenden können.

ABBYY Phoenix Plus steht in ABBYY Vantage Cloud zur Verfügung und erfordert eine vertraglich vereinbarte Berechtigung. Um die Funktion für Ihren Tenant zu aktivieren, wenden Sie sich an Ihr ABBYY Account Team. Einen Überblick finden Sie unter LLMs in ABBYY Vantage.

Bevor Sie beginnen

Die Phoenix Plus-Berechtigung ist für Ihren Tenant aktiviert, und die Verbindung ABBYY Phoenix Model wird unter ADMIN → Configuration → Connections angezeigt.
Sie verfügen über einen Process-Skill mit einer Benutzerdefinierten Aktivität. Die einzelnen Schritte finden Sie unter Benutzerdefinierte Aktivität.
Wählen Sie auf der Registerkarte Available Files der Aktivität die Exportformate aus, die Ihr Skript benötigt. Die meisten Skripte benötigen OcrJson. Um Seitenbilder zu senden, benötigen Sie zusätzlich einen JPEG-Export, der vor der Ausführung der Aktivität erzeugt werden muss.

Chat-Sitzung erstellen

Rufen Sie Context.CreateLlmChatSession() ohne Argumente auf, um eine Sitzung über die von ABBYY verwaltete Verbindung Ihres Tenants zu öffnen. Wird ein Verbindungsname übergeben, wird stattdessen eine Sitzung über eine Ihrer eigenen Mandantenverbindungen geöffnet.

var session = Context.CreateLlmChatSession();              // von ABBYY verwaltete Verbindung
var byo     = Context.CreateLlmChatSession('My OpenAI');   // eigene Mandantenverbindung, über den Namen

Der übrige Teil dieser Seite beschreibt die verwaltete Verbindung. Eine Sitzung, die über Ihre eigene Verbindung geöffnet wird, verhält sich genauso, wird jedoch über Ihren Provider abgerechnet und unterliegt nicht der Nutzungsberechtigung. Das Modell hinter der Sitzung wird von ABBYY ausgewählt und gepflegt. Die Sitzung weist jeden Versuch zurück, es zu ändern; über die verwaltete Verbindung lässt sich daher weder ein bestimmtes Modell noch eine bestimmte Version anfordern.

Sitzungseigenschaften

Name	Typ	Access	Beschreibung
Model	string	Read-write	Das anzufordernde Modell. Standardmäßig wird das eigene Modell der Verbindung verwendet. Die von ABBYY verwaltete Verbindung akzeptiert nur ihr eigenes Modell, sodass diese Einstellung dort wirkungslos ist
SystemPrompt	string	Read-write	Anweisungen, die als erste Nachricht jedes Requests in der Sitzung gesendet werden
Temperature	number	Read-write	Sampling-Temperatur. Wird nicht in den Request aufgenommen, wenn sie nicht gesetzt ist
TopP	number	Read-write	Nucleus-Sampling. Wird nicht in den Request aufgenommen, wenn es nicht gesetzt ist
MaxTokens	integer	Read-write	Obergrenze für die in einer Antwort erzeugten Tokens. Siehe MaxTokens bewusst festlegen
History	list	Read-only	Die bisher ausgetauschten Nachrichten, als `{ Role, Content }`. Rollen sind `user` und `assistant`; Bilder erscheinen als `[image]`
Timeout	integer	Read-write	Request-Timeout in Minuten; wird so begrenzt, dass es das Zeitlimit für die Skriptausführung nie überschreiten kann
LastUsage	object	Read-only	Tokenverbrauch des letzten Aufrufs
TotalUsage	object	Read-only	Über die Sitzung hinweg kumulierter Tokenverbrauch
LastFinishReason	string	Read-only	Grund, warum das Modell die Generierung beendet hat, zum Beispiel `stop` oder `length`

LastUsage und TotalUsage sind Objekte, die PromptTokens, CompletionTokens und TotalTokens enthalten.

var usage = session.TotalUsage;
Context.LogMessage("Tokens: prompt " + usage.PromptTokens
  + ", completion " + usage.CompletionTokens
  + ", total " + usage.TotalTokens);

Eine Sitzung zurücksetzen

Reset() löscht den Gesprächsverlauf sowie alle ausstehenden Anhänge, sodass die nächste Nachricht von vorn beginnt. Einstellungen wie SystemPrompt und Temperature bleiben erhalten, ebenso die kumulierte Nutzung.

Inhalte an eine Nachricht anhängen

Hängen Sie die Vorgangsdaten an, die das Modell sehen soll, und senden Sie die Nachricht anschließend.

Methode	Beschreibung
AttachJson(label, json)	Hängt JSON als beschrifteten Block an. Verwenden Sie dies für OCR-JSON und extrahierte Felddaten.
AttachText(label, text)	Hängt Klartext als beschrifteten Block an.
AttachDocument(document)	Hängt die extrahierten Daten eines Documents als beschriftetes JSON an.
AttachExtractedData(extractedData)	Hängt extrahierte Daten als beschriftetes JSON an.
AttachPageImage(page)	Hängt eine Seite als Bild an – für Vision-Modelle.
AttachImage(export)	Hängt ein einzelnes Seitenbild aus einem DocumentExportResult an, ohne Beschriftung und ohne Medientyp. Rufen Sie die Methode einmal pro Seite auf.

Anhänge werden nicht sofort gesendet, sondern in die Warteschlange der nächsten Benutzernachricht eingereiht. Sie können auch einen Gesprächsverlauf aufbauen, ohne etwas zu senden – das ist nützlich für Few-Shot-Priming:

Methode	Beschreibung
AddUserMessage(message)	Fügt dem Verlauf eine Benutzernachricht hinzu, ohne sie zu senden
AddAssistantMessage(message)	Fügt dem Verlauf eine Assistentennachricht hinzu

AttachFile, AttachBinary und ein generisches Attach existieren nicht. Verwenden Sie die oben genannten Methoden.

Seitenbilder in Seitenreihenfolge anhängen

JPEG-Exporte sind nach Properties["PageIndex"] sortiert. Wenn Sie sie in genau dieser Reihenfolge anhängen, stimmt die Reihenfolge der Anhänge mit den vom Modell gemeldeten Seitenzahlen überein.

var exports = Context.Transaction.Documents[0].Exports;
exports
  .filter(result => result.ExportFormat === ExportFormat.Jpeg)
  .forEach(result => {
    session.AttachImage(result);   // ein Aufruf pro Seite
  });

Nachricht senden und Antwort lesen

Methode	Rückgabewert
SendJson(prompt)	Ein geparstes Objekt. Aktiviert den JSON-Antwortmodus, sodass verschachtelte Arrays und Zahlen direkt verwendbar sind, zum Beispiel `result.items[1].total`
Send(prompt)	Die Antwort des Assistenten als Text
Send()	Sendet den ausstehenden Verlauf und die Anhänge in ihrem aktuellen Zustand

var result = session.SendJson(prompt);

SendJson gibt ein Objekt zurück. Wird stattdessen ein string zurückgegeben, hat das Modell kein parsbares JSON erzeugt – in diesem Fall sollte der Prompt präzisiert und nicht der Aufruf wiederholt werden.

Prüfen, wie die Antwort beendet wurde

Lesen Sie LastFinishReason aus, bevor Sie einer Antwort vertrauen. Der Wert "length" bedeutet, dass die Antwort beim Token-Limit abgeschnitten wurde. Das ist kein Fehler, und nichts anderes weist darauf hin – ein Skript, das diesen Wert ignoriert, verarbeitet ein unvollständiges Ergebnis daher so, als wäre es vollständig. Abhilfe schafft ein höherer Wert für MaxTokens oder ein kleinerer Feldsatz.

Struktur prüfen, bevor Werte geschrieben werden

Eine Antwort kann vollständig eintreffen und dennoch strukturell falsch sein: mit den richtigen skalaren Feldern, aber ohne die sich wiederholenden Inhalte, die ein Skill definiert. Prüfen Sie, ob die Antwort die angeforderten Tabellen und Wiederholungsfelder enthält, und fragen Sie erneut nach, falls nicht, anstatt die Antwort ungeprüft in das Document zu schreiben. Setzen Sie die Sitzung zwischen den Versuchen zurück und legen Sie anschließend SystemPrompt erneut fest.

Was die verwaltete Verbindung voraussetzt

Dokumentkontext. Für eine Ausführung ohne Dokumentseiten wird die verwaltete Verbindung abgelehnt. So wird verhindert, dass die gemeinsam genutzten Anmeldedaten der Plattform als allgemeines LLM-Gateway missbraucht werden. Eine Benutzerdefinierte Aktivität, die auf einem Vorgang mit Dokumenten ausgeführt wird, erfüllt diese Voraussetzung; ein Skript, das eine Sitzung außerhalb dieses Kontexts öffnet, dagegen nicht. Verbrauchserfassung. Aufrufe über die verwaltete Verbindung werden auf Ihr ABBYY-Kontingent angerechnet. Aufrufe über eine selbst konfigurierte Verbindung werden dagegen über Ihren eigenen Provider abgerechnet. Bedenken Sie das Volumen, bevor Sie eine umfangreiche erneute Verarbeitung über die verwaltete Verbindung laufen lassen.

Nachrichtengrenzen

Beide Grenzwerte werden durchgesetzt, und eine Nachricht, die einen davon überschreitet, wird direkt abgelehnt. Prüfen Sie die Größe der Nachricht bereits im script, bevor Sie sie senden, anstatt den Aufruf fehlschlagen zu lassen.

Grenzwert	Verhalten
Prompt-Budget	Eine maximale Anzahl von Zeichen pro Nachricht, wobei alles mitzählt: System-prompt, Benutzernachricht, angehängtes JSON und base64-kodierte Bildinhalte
Anhänge	10 pro Nachricht. Der elfte wird abgelehnt
Anfragen pro Ausführung	Eine begrenzte Anzahl von LLM-Aufrufen pro Skriptausführung, skaliert nach der Seitenzahl des Vorgangs. Siehe Fehler, die Ihr script nicht abfangen kann

Die Prompt-Obergrenze ist kein einzelner fester Wert. Sie wird pro Umgebung konfiguriert und skaliert mit der Anzahl der verarbeiteten Seiten, bis zu einem Maximum. In ABBYY Vantage Cloud sind derzeit pro Seite 500.000 Zeichen zulässig, gezählt über höchstens drei Seiten, bis zu einer Obergrenze von 1.500.000:

Seiten im Vorgang	Zulässige Zeichen pro Nachricht
1	500.000
2	1.000.000
3 oder mehr	1.500.000

Da die Obergrenze umgebungsabhängig konfiguriert wird und sich ändern kann, sollten Sie diese Werte als Orientierung und nicht als verbindliche Zusage betrachten. Bestimmen Sie die Nachrichtengröße zur Laufzeit und reduzieren Sie den Umfang, wenn sie nicht passt, anstatt von einem festen Budget auszugehen. Eine Überschreitung erzeugt eine Meldung der folgenden Form:

The LLM prompt exceeds the maximum allowed size of N characters

Fehler, die sich durch erneute Versuche nicht beheben lassen

Ein Sendefehler mit dem Hinweis exceeds the maximum allowed size, maximum number of attachments, context length oder too large ist endgültig. Die Nachricht ist zu groß oder enthält zu viele Daten, und derselbe Aufruf wird erneut fehlschlagen. Abhilfe schaffen Sie, indem Sie die JPEG-Exportauflösung verringern, weniger Seiten senden oder die Bilder weglassen und die Verarbeitung allein mit dem OCR-JSON ausführen.

Fehler, die Ihr Skript nicht abfangen kann

Die meisten Fehler lassen sich im Skript mit try/catch abfangen: Verbindungsprobleme, eine fehlgeschlagene Anfrage, eine Antwort, die kein gültiges JSON ist, oder ein Prompt, der die Größenbeschränkung überschreitet. Behandeln Sie diese Fälle und fahren Sie fort. Beim Überschreiten der Obergrenze für Anfragen ist das anders. Es gibt eine Grenze dafür, wie viele LLM-Aufrufe eine einzelne Skriptausführung vornehmen darf; sie richtet sich nach der Seitenzahl des Vorgangs. Wird sie überschritten, bricht das Skript mit einem Beschränkungsfehler ab, den ein try/catch nicht abfangen kann – genauso wie bei der bestehenden Obergrenze für HTTP-Anfragen. Wichtig wird das, wenn Sie Wiederholungsversuche einsetzen. Eine Schleife aus Validierung und erneuter Abfrage verbraucht bei jedem Durchlauf einen Aufruf, und eine Schleife ohne eigene Obergrenze läuft irgendwann in eine Grenze, die sie nicht behandeln kann. Begrenzen Sie daher Ihre Wiederholungsversuche.

Seitenbilder senden

Seitenbilder funktionieren – innerhalb einer praktischen Obergrenze, die das Prompt-Budget vorgibt. Zwei gemessene Beispiele, bezogen auf die oben genannten Obergrenzen:

Ein einzelnes Seitenbild mit 1584x1000 kostet rund 311.776 Base64-Zeichen und etwa 2.015 Prompt-Tokens. Bei einem einseitigen Vorgang passt das in das Kontingent von 500.000 Zeichen und lässt Raum für das OCR-JSON und den Prompt.
Ein zweiseitiges A4-Formular, mit 300 dpi eingescannt, ergibt rund 1.326.136 Zeichen an Bilddaten. Ein zweiseitiger Vorgang erlaubt 1.000.000 Zeichen, die Anfrage wird also abgelehnt. Um es als Bilder zu senden, müsste jede Seite auf etwa ein Viertel ihrer 300-dpi-Größe verkleinert werden.

Die Rechnung ändert sich mit der Seitenzahl und mit jeder Änderung der Obergrenze der Umgebung. Deshalb muss die Nachricht vor dem Senden gemessen werden, statt einfach anzunehmen, dass sie passt. Planen Sie mit dem Budget statt dagegen:

Senden Sie das OCR-JSON als primäre Nutzlast und ergänzen Sie Seitenbilder nur für das, was der text layer nicht abbilden kann, etwa stamps, Unterschriften und Fotografien.
Messen Sie die Nachricht vor dem Senden. Passen die Bilder nicht, lassen Sie sie weg und passen Sie den Prompt entsprechend an, damit das Document weiterhin allein auf Basis des OCR-JSON verarbeitet wird.
Halten Sie beim Dimensionieren der Bilder Raum für das OCR-JSON frei, damit ein großes Bild nicht die Nutzlast verdrängt, aus der Ihre Koordinaten stammen.
Reduzieren Sie die image resolution vor dem Export, wenn das Modell lediglich das layout oder einen stamp erkennen muss und keine Feindetails.

Orte und Begrenzungsrahmen

Fragen Sie das Modell nicht nach Koordinaten. Das Modell hinter der verwalteten Verbindung kann einen Begrenzungsrahmen nicht auf einem Seitenbild verankern, und eine Antwort, die wie Koordinaten aussieht, ist keine Messung.

Wird das Modell aufgefordert, Koordinaten aus einem Seitenbild zurückzugeben, liefert es Werte auf einem Zehner-Raster: jede Zahl ein Vielfaches von zehn, einheitliche Höhen und zwei verschiedene Felder mit identischem Rechteck. Das ist ein konstruiertes und kein gemessenes Layout, und keine Einstellung zur Koordinatenkonvention behebt das. Beziehen Sie die Geometrie stattdessen aus dem OCR-Layer von Vantage. Der OCR-JSON-Export enthält gemessene Positionen sowohl für Text- als auch für Nicht-Text-Inhalte, einschließlich layout.pages[].pictures[] und barcodes[], sodass ein Foto, ein Logo oder ein Barcode genauso zuverlässig lokalisiert werden kann wie ein Wort. Ein robustes Skript:

Kopiert Koordinaten, statt sie zu schätzen. Jedes Rechteck stammt aus einem Positionswert im OCR-JSON, wird gegen die OCR-Seitengröße validiert und auf das Seitenbild in Vantage skaliert, wenn beide voneinander abweichen.
Erzwingt den Herkunftsnachweis. Jede Region, die das Modell zurückgibt, wird vor der Annahme gegen die OCR-Geometrie geprüft. Eine Region, die nicht auf den OCR-Layer zurückgeführt werden kann, wird abgelehnt, während der extrahierte Wert selbst erhalten bleibt.
Verlangt eine Seitenzuordnung. Bei einem mehrseitigen Dokument wird eine Region, die ohne Seitennummer eintrifft, abgelehnt und nicht standardmäßig Seite 1 zugeordnet.

Nutzen Sie das Modell für das, was es gut kann: Lesen und Klassifizieren. Die Geometrie liefert ABBYY OCR.

MaxTokens bewusst festlegen

Wenn Sie MaxTokens auf dem Standardwert des Providers belassen, riskieren Sie bei inhaltsdichten Dokumenten eine unbemerkte Kürzung, die sich nur über LastFinishReason erkennen lässt. Legen Sie den Wert explizit fest, damit die Obergrenze von Ihnen bestimmt und nachvollziehbar ist. Zur Einordnung: Die zellenweise Extraktion einer neunspaltigen Tabelle über drei Seiten hinweg schlägt mit rund 28.000 Completion-Tokens zu Buche.

Ausreichend Zeit einplanen

Die Latenz skaliert mit der Anzahl der erzeugten Ausgabe-Tokens, nicht mit der Größe der Eingabe. Phoenix Plus erzeugt etwa 100 Completion-Tokens pro Sekunde, sodass eine Antwort mit 28.000 Tokens mehrere Minuten benötigt. Timeout wird in Minuten angegeben und ist durch das Zeitlimit für die Skriptausführung begrenzt. Ein Timeout von zwei Minuten schlägt bei einem Document, das 28.000 Ausgabe-Tokens benötigt, nach etwa 121 Sekunden fehl – dann ist nur ein Bruchteil der Antwort erzeugt.

OCR-Nutzlast vor dem Senden reduzieren

Ein unbearbeiteter OCR-JSON-Export wird von der Zeichenebene dominiert, die typischerweise 97 bis 98 Prozent der Größe ausmacht. Bereinigt man ihn, bleiben genau der Text und die Wortpositionen übrig, die das Modell tatsächlich benötigt – bei einem Bruchteil des Prompt-Budgets. In einem gemessenen Fall ließ sich ein Export mit 43.437 Zeichen auf 4.842 Zeichen reduzieren, wobei die Wortpositionen erhalten blieben. In einem anderen Fall schrumpfte ein Export mit 317.296 Zeichen auf 32.712 Zeichen. Bei der Kostenschätzung ist für OCR-JSON von etwa 2 Zeichen pro Token auszugehen. JSON-Interpunktion lässt sich schlecht tokenisieren, daher gelten aus Prosa abgeleitete Verhältnisse hier nicht.

Bekannte Einschränkungen

Um eine Seite als Bild anzuhängen, verwenden Sie AttachPageImage(page). Die Übergabe von Page.Image an AttachImage löst Value cannot be null. (Parameter 'fileLink') aus – sowohl bei aufgeteilten als auch bei nicht aufgeteilten Documents –, da AttachImage eine exportierte Datei erwartet und nicht die Bildeigenschaft einer Seite. Ein JPEG-Export aus Document.Exports funktioniert mit AttachImage.

Beispiel

Dieses Skript sendet ein bereinigtes OCR-JSON und fordert strukturierte Feldwerte an, wobei die gesamte Geometrie aus dem OCR-Layer übernommen wird.

var document = Context.Transaction.Documents[0];

// Liest den OCR-JSON-Export, der auf dem Tab „Available Files“ der Activity konfiguriert ist.
var ocrExport = document.Exports.GetByFormat(ExportFormat.OcrJson);
var prunedOcr = pruneOcr(ocrExport.ToJson());   // Ihre eigene Bereinigungsfunktion

var session = Context.CreateLlmChatSession();
session.SystemPrompt =
  "You read documents. Return only the requested fields as JSON. " +
  "Never return coordinates. Quote values exactly as they appear in the OCR text.";
session.MaxTokens = 32000;
session.Timeout = 8;            // Minuten
session.Temperature = 0;

session.AttachJson("OCR JSON", prunedOcr);

var prompt = "Return vendor name, invoice number, invoice date and total as JSON.";
var result = session.SendJson(prompt);

if (session.LastFinishReason === "length") {
  Context.LogMessage("Response truncated. Raise MaxTokens or reduce the field set.");
}

var usage = session.TotalUsage;
Context.LogMessage("Tokens: prompt " + usage.PromptTokens
  + ", completion " + usage.CompletionTokens
  + ", total " + usage.TotalTokens);

​Bevor Sie beginnen

​Chat-Sitzung erstellen

​Sitzungseigenschaften

​Eine Sitzung zurücksetzen

​Inhalte an eine Nachricht anhängen

​Seitenbilder in Seitenreihenfolge anhängen

​Nachricht senden und Antwort lesen

​Prüfen, wie die Antwort beendet wurde

​Struktur prüfen, bevor Werte geschrieben werden

​Was die verwaltete Verbindung voraussetzt

​Nachrichtengrenzen

​Fehler, die sich durch erneute Versuche nicht beheben lassen

​Fehler, die Ihr Skript nicht abfangen kann

​Seitenbilder senden

​Orte und Begrenzungsrahmen

​MaxTokens bewusst festlegen

​Ausreichend Zeit einplanen

​OCR-Nutzlast vor dem Senden reduzieren

​Bekannte Einschränkungen

​Beispiel

​Verwandte Themen

Bevor Sie beginnen

Chat-Sitzung erstellen

Sitzungseigenschaften

Eine Sitzung zurücksetzen

Inhalte an eine Nachricht anhängen

Seitenbilder in Seitenreihenfolge anhängen

Nachricht senden und Antwort lesen

Prüfen, wie die Antwort beendet wurde

Struktur prüfen, bevor Werte geschrieben werden

Was die verwaltete Verbindung voraussetzt

Nachrichtengrenzen

Fehler, die sich durch erneute Versuche nicht beheben lassen

Fehler, die Ihr Skript nicht abfangen kann

Seitenbilder senden

Orte und Begrenzungsrahmen

MaxTokens bewusst festlegen

Ausreichend Zeit einplanen

OCR-Nutzlast vor dem Senden reduzieren

Bekannte Einschränkungen

Beispiel

Verwandte Themen