Konfiguration, Parameter & Best Practices

Dieser Artikel erklärt im Detail, wie eine AI-Workflow Action innerhalb der DataEngine aufgebaut ist, welche Eingabe- und Ausgabeparameter es gibt und was man für eine bestmögliche Antwort beachten muss .

Voraussetzungen

Um die KI-Workflow-Aktion zu verwenden, benötigst du ein Konto bei einem KI-Anbieter deiner Wahl, beispielsweise OpenAI, Anthropic (Claude) oder Microsoft Azure AI Foundry. Außerdem benötigst du:

• OpenAI: API-Schlüssel
• Claude (Anthropic): API-Schlüssel
• Microsoft Foundry: Endpoint, API-Schlüssel und zuvor in Azure erstellte Deployments

Unter Administration > Externe Services kannst du die Systemeinstellungen für diese externen Anbieter konfigurieren. Wähle deinen Anbieter aus und hinterlege den Endpoint, den API-Schlüssel sowie ein Deployment-Schema im JSON-Format, in dem du die Parameter definierst. Im Workflow können nur Anbieter ausgewählt werden, die vollständig und gültig konfiguriert wurden.

Mit Test Prompt kannst du alle konfigurierten Modelle testen. Die Ergebnisse werden für jedes Modell unter Test Results angezeigt.

Erste Schritte

Nachdem du die Voraussetzungen erfüllt hast, kannst du mit der Konfiguration der KI-Workflow-Aktion beginnen.

1. Öffne den Bereich Aktionen, wähle KI-Aktion aus und vergebe einen Namen.
2. Wähle im Abschnitt Dynamischen Prompt erstellen deinen KI-Anbieter aus und entscheide dich für ein Modell.
3. Modellkonfiguration: Abhängig vom ausgewählten Modell kannst du anbieterspezifische Parameter konfigurieren, z. B. einen Endpoint auswählen, die Temperatur festlegen oder die maximale Anzahl an Tokens definieren.
4. Prompt: Gib den Prompt ein, der an das KI-Modell gesendet werden soll.
5. Zielfeld: In diesem Feld wird die vom Modell generierte Antwort gespeichert. Es empfiehlt sich, ein Feld mit WYSIWYG-Editor zu verwenden, da dieses die HTML-Formatierung unterstützt und eine ansprechend formatierte Ausgabe ermöglicht.

Anbieterspezifische Informationen

Da sich die verfügbaren Modelle und Parameter häufig ändern, solltest du immer die aktuelle Dokumentation des jeweiligen Anbieters verwenden, um sicherzustellen, dass du die richtigen Modelle und Parameter einsetzt.

Anbieterspezifische Informationen zu Modellen sowie zu Ein- und Ausgabeparametern und den Parametern des Request-Bodys findest du in der jeweiligen Dokumentation.

• OpenAI-Documentation

Input & Output Parameter (Felder des WorkFlow-Moduls)

Jeder AI-Workflow benötigt klar definierte Felder zur Verarbeitung einer Anfrage. Diese werden im Workflow-Modul zugeordnet:

• Quellfeld: Das Quellfeld ist das Eingabefeld, dessen Inhalt an das OpenAI-Modell gesendet wird. Es dient als Prompt, also textliche Aufforderung, die das Modell bearbeiten soll.
• JSON Request Field : Das Feld, in dem die vollständige JSON-Anfrage gespeichert wird. Das ist besonders hilfreich zur Nachvollziehbarkeit oder zum Debugging.
• Zielfeld : Das Zielfeld ist das Speicherfeld für die generierte Antwort. Es wird empfohlen, Felder mit WYSIWYG-Editor zu nutzen, da diese HTML-Formatierungen unterstützen und somit optisch ansprechende Ausgaben ermöglichen.
• JSON-Antwort Feld: Das Feld, in dem die vollständige JSON-Antwort gespeichert wird. Ideal für Support-Teams und Entwickler, um zu verstehen, wie das Modell auf die Anfrage reagiert hat.

OpenAI Workflow Action

Request Body Parameters – Beschreibung & Info

Eine Chat-Completion Anfrage besteht aus mehreren wichtigen Parametern, die beeinflussen, wie das Modell arbeitet. Hier wird ein Überblick über allgemeine Parameter gegeben, die allen Modellen gemein sind. Einzelne Modelle können aber nochmal spezifischere Parameter haben – diese kannst du in der offiziellen OpenAI-Dokumentation nachlesen.

• Model: Der Parameter model in einer Chat-Vervollständigungsanfrage definiert das spezifische GPT-Modell, das für die Generierung der Antwort verwendet werden soll. Die verfügbaren Modelle können sich ändern, also überprüfe die aktuelle OpenAI-Dokumentation, um sicherzustellen, dass du den neuesten Modellnamen verwendest. Normalerweise wirst du Modelle wie „text-davinci-003“ verwenden, aber es gibt auch spezialisierte Modelle für bestimmte Anwendungen. Falls du dir nicht sicher bist, welches Modell du verwenden sollst, ist hier eine webbasierte Plattform zum Experimentieren mit verschiedenen Modellen von OpenAI.
  Wichtig: Aktuelle Modelle & Preise müssen immer direkt bei OpenAI eingesehen werden. Die Preisliste findest du hier.
• Prompt: Im Prompt-Feld wird die eigentliche Anfrage an das Modell formuliert, d.h. was das Modell tun soll, wie es antworten soll und welche Daten (z.B. via Platzhalter) einfließen sollen. Platzhalter aus anderen Modulen können genutzt werden, um Inhalte dynamisch einzubinden. Ein Platzhalter beginnt mit „/“. Das System ersetzt dann beim Ausführen automatisch mit dem Feldinhalt.
  Beispiel: /bsp_Person.name fügt den Namen aus dem Modul bsp_Person ein.

• Tools: Unter Tools stehen Erweiterungen wie Web Search zur Verfügung. Damit kann das Modell zusätzlich auf aktuelle Informationen aus dem Internet zugreifen, die automatisch in die Antwort integriert werden. Das ist besonders nützlich für Recherchen, Preisangaben, Faktenchecks und aktuelle Marktinformationen.
• Ziel: Hier wird festgelegt, wo die generierte Antwort gespeichert werden soll. Besonders empfehlenswert ist ein WYSIWYG-Datentyp, da dieser HTML-Formatierungen unterstützt und somit eine ansprechende Darstellung der Ergebnisse ermöglicht.
• Playground: Der Playground der OpenAI-Plattform ist ein webbasiertes Testlabor. Dort kann man Modelle ausprobieren, Parameter ausgiebig testen, Tokenverbrauch live beobachten, Beispiel-Prompts simulieren und vieles mehr. Der Playground eignet sich hervorragend, um den Workflow vor der Implementierung zu optimieren und auf eigene Anforderungen anzupassen.

Zusammenfassung

Ein OpenAI-Workflow besteht im Wesentlichen aus:

• Inputfeldern (Prompt)
• JSON-Request
• Modellparametern
• Tools wie Web Search
• Zielfeldern für formatierten Output
• vollständiger JSON-Antwort für Nachvollziehbarkeit

Durch die richtigen Einstellungen und klar definierten Prompts lässt sich ein leistungsfähiger, transparent dokumentierter KI-Workflow erstellen.

Microsoft Foundry Workflow Action (Azure OpenAI)

Request Body Parameter Beschreibung & Info

Der Ablauf der Workflow Action ist sehr ähnlich zu der OpenAI Workflow Action. Der Unterschied besteht darin, dass die KI in einem gesonderten Azure Container existiert und nur Informationen aus dem Container nutzen kann. Dies lässt deutlich zielgerichtetere Ergebnisse zu, erfordert aber auch selektierte Daten im vorliegenden Container.

Model : Name der Bereitstellung. Aktuell werden die Werte in der „Azure OpenAI Einstellungen“ im Marini Systems Admin Bereich eingetragen. Hier lässt sich das gewünschte Modell für die Verarbeitung des Prompts auswählen. Die offizielle OpenAI-Dokumentation bietet einen guten Überblick über die verfügbaren Modelle sowie deren Stärken Einsatzbereiche. Je nach Modell können außerdem verschiedene Parameter individuell angepasst werden, um optimale Ergebnisse zu erzielen. Die Preisliste der jeweiligen Modelle findest du hier. 

Max Tokens: Begrenzt die Antwortlänge. Die maximale Anzahl von Token, die in der Chatvervollständigung generiert werden können. Die Gesamtlänge der Eingabetoken und generierten Token wird durch die Kontextlänge des Modells begrenzt. Das Übergeben von NULL bewirkt, dass das Modell seine maximale Kontextlänge verwendet.

Temperature: Beeinflusst Antwortkreativität (eine Zahl zwischen 0 und 2,0; vorgegebener Wert 1). Niedrig (0,2) für konservative, hoch (0,8) für kreative Antworten. Nicht negative Zahl Gibt 422 zurück, wenn der Wert vom Modell nicht unterstützt wird.

Top P Kontrolliert Token-Auswahl (eine Zahl zwischen 0 und 1,0; vorgegebener Wert 1). Niedrig (0,1) für wahrscheinliche, hoch (1,0) für diverse Antworten. Eine Alternative zur Stichprobenentnahme mit Temperatur, die sogenannte Kernstichprobenentnahme (Nucleus Sampling), bei dem das Modell die Ergebnisse der Token mit der Wahrscheinlichkeitsmasse „top_p“ berücksichtigt. Daher bedeutet 0,1, dass nur die Token berücksichtigt werden, die die oberen 10 % der Wahrscheinlichkeitsmasse umfassen.

Frequency Penalty Beeinflusst die Wiederholung von Tokens. Niedrig (0) ermutigt, hoch (0,8) vermeidet (eine Zahl zwischen -2,0 und 2,0; vorgegebener Wert 0). Verhindert Wortwiederholungen, indem die Wahrscheinlichkeit reduziert wird, dass ein Wort ausgewählt wird, wenn es bereits verwendet wurde. Je höher die Häufigkeitsstrafe ist, desto geringer ist die Wahrscheinlichkeit, dass das Modell dieselben Wörter in seiner Ausgabe wiederholt. Gibt einen 422-Fehler zurück, wenn der Wert oder Parameter vom Modell nicht unterstützt wird.

Presence Penalty Ein höherer Wert (z. B. 1,5) verringert die Wahrscheinlichkeit von Wiederholungen in den Antworten des Modells (eine Zahl zwischen -2,0 und 2,0; vorgegebener Wert 0). Verhindert, dass dieselben Themen wiederholt werden, indem ein Wort bestraft wird, wenn es bereits in der Vervollständigung vorhanden ist, selbst wenn es nur einmal ist. Gibt einen 422-Fehler zurück, wenn der Wert oder Parameter vom Modell nicht unterstützt wird.

API Version: Die Version der API, die benutzt werden sollte. Aktuell werden die Werte in der „Azure OpenAI Einstellungen“ im Marini Systems Admin Bereich eingetragen. Die Version der API im Format „JJJJ-MM-TT“ oder „JJJJ-MM-TT-Vorschau“.

Zusammenfassung

• Model: Name der Bereitstellung. Aktuell werden die Werte in der „Azure OpenAI Einstellungen“ im Marini Systems Admin Bereich eingetragen.
• Max Tokens: Begrenzt die Antwortlänge.
• Temperature: Beeinflusst Antwortkreativität. Niedrig (0,2) für konservative, hoch (0,8) für kreative Antworten.
• Top P: Kontrolliert Token-Auswahl. Niedrig (0,1) für wahrscheinliche, hoch (1,0) für diverse Antworten.
• Frequency Penalty: Beeinflusst die Wiederholung von Tokens. Niedrig (0) ermutigt, hoch (0,8) vermeidet.
• Presence Penalty: Ein höherer Wert (z. B. 1,5) verringert die Wahrscheinlichkeit von Wiederholungen in den Antworten des Modells.
• API Version: Die Version der API, die benutzt werden sollte. Aktuell werden die Werte in der „Azure OpenAI Einstellungen“ im Marini Systems Admin Bereich eingetragen.

Best Practices

Damit ein AI-Workflow zuverlässig, effizient und in konsistent hoher Qualität arbeitet, sollten bei der Einrichtung und Nutzung folgende Punkte beachtet werden.

• Klare, eindeutige Aufgabenstellung formulieren – schreibe immer aus, was das Modell tun soll und was nicht. Je klarer die Aufgabe gestellt ist, desto besser die Antwort.
• Kontext mitgeben – das Modell weiß nichts über deinen Anwendungsfall, wenn du es ihm nichts sagst. Den Kontext direkt im Prompt mitzugeben, hilft dem Modell, zielgerichtet zu arbeiten.
• Regeln und Einschränkungen – wenn etwas nicht passieren soll, dann benenne es explizit. Diese Einschränkungen erhöhen die Zuverlässigkeit enorm.
• Formatvorgaben beschreiben – das Modell liefert das Format, das du vorgibst z. B. „Gib die Antwort als Satz aus“ oder „Nutze eine Liste mit drei Punkten“. Das verhindert abweichende Antwortformen. Du kannst dem Modell hier zusätzlich ein Beispiel geben, das wirkt oft besser als reine Erklärung.
• Immer nur eine Aufgabe pro Prompt – wenn ein Prompt zwei Dinge gleichzeitig verlangt, kann es passieren, dass das Modell Inhalte vermischt.