> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abbyy.com/llms.txt
> Use this file to discover all available pages before exploring further.
# ABBYY Phoenix Plus aus einer Benutzerdefinierten Aktivität aufrufen
> Nutzen Sie die von ABBYY verwaltete LLM-Verbindung aus einem Skript einer Benutzerdefinierten Aktivität in einem Process-Skill: Erstellen Sie eine Chat-Sitzung, hängen Sie OCR-Daten und Seitenbilder an, senden Sie eine Nachricht und lesen Sie eine strukturierte Antwort.
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](/de/vantage/documentation/llms/llms).
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](/de/vantage/documentation/skill-designer/process/custom-activity/custom-activity).
* 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.
```javascript theme={null}
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](#set-maxtokens-deliberately) |
| **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.
```javascript theme={null}
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](/de/vantage/documentation/skill-designer/process/custom-activity/document-export-result) 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.
```javascript theme={null}
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 |
```javascript theme={null}
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](#errors-your-script-cannot-catch) |
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:
```text theme={null}
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.
```javascript theme={null}
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);
```
* [LLMs in ABBYY Vantage](/de/vantage/documentation/llms/llms)
* [Benutzerdefinierte Aktivität](/de/vantage/documentation/skill-designer/process/custom-activity/custom-activity)
* [Context](/de/vantage/documentation/skill-designer/process/custom-activity/context)
* [DocumentExportResult](/de/vantage/documentation/skill-designer/process/custom-activity/document-export-result)
* [OCR-JSON-Schema](/de/vantage/documentation/skill-designer/process/custom-activity/ocr-skill-schema-json)