Aufbau einer KI-Prompt-Definition#

Eine KI-Prompt-Definition ist eine YAML-Datei im Verzeichnis site/prompts/. Sie legt fest, welche Aufgabe ein Prompt übernimmt, welche Daten an das Sprachmodell gehen und wie die Antwort zurückkommt. Damit ist sie das Herzstück jeder Integration. Dieses Kapitel zeigt den typischen Aufbau und erklärt, wie Processing-Instructions und Platzhalter ineinandergreifen.

Anatomie eines Prompts#

Ein Prompt besteht im Wesentlichen aus vier Bausteinen: Metadaten wie ID oder Beschreibung, die Nachrichten an das Modell (System und User), ein Schema für die Antwort sowie ein Transformer, der das Ergebnis ins Metainfo einträgt.

Ein minimales Beispiel sieht so aus:

id: my_prompt
label: Beispielprompt
description: Erzeugt eine JSON-Struktur aus dem Eingabetext
transformer: DEFAULTAI

systemprompt: |
  Beschreibe die Aufgabe.
  Antworte nur als JSON {"result":"..."}.

template: |
  Eingabetext:
  {P[0]}

schema:
  type: object
  properties:
    result: { type: string }
  required: [result]
  strict: true

System- und Usernachricht#

Bei der Generierung wird immer genau eine Systemnachricht und eine Usernachricht an das LLM geschickt. Der Systemteil beschreibt die Aufgabe und ist oft konstant. Er kann als systemprompt fest im YAML stehen oder als systemtemplate dynamisch mit Parametern gerendert werden.

Die Usernachricht enthält die eigentlichen Inhalte, also Textblöcke oder Previews. Auch hier gibt es zwei Varianten: userprompt (statischer Text) oder template (dynamisch, mit {P[n]} und Imperia-Platzhaltern).

Platzhalter `{P[n]}` und die PI#

Die Variable {P[n]} wird im Prompt nicht automatisch gefüllt, sondern durch die Processing-Instruction im Template. Dort lassen sich Parameter auf zwei Arten setzen:

_param_0: foo → schreibt den festen Wert "foo" in auf {P[0]}
_value_1: title → nimmt den Inhalt des imperia Metafeldes title und setzt ihn auf {P[1]}

Beispiel:

<?imperia aiprompt
    id: translate
    prompt: translation
    _param_0: de
    _param_1: en
    _value_2: input_text
?>

Im Prompt selbst können dann {P[0]}, {P[1]} und {P[2]} referenziert werden. Vor dem Versand werden diese Platzhalter ersetzt, anschließend läuft noch einmal die normale Imperia-Templating-Engine.

systemtemplate: |
  Übersetze von {P[0]} nach {P[1]}.
  Antworte mit {"translations":["..."]}.

template: |
  Eingabe:
  {P[2]}

Schema und Validierung#

Damit die Antwort zuverlässig weiterverarbeitet werden kann, enthält jeder Prompt ein JSON-Schema. Dieses Schema definiert die erwarteten Felder, ihre Typen und ob zusätzliche Felder erlaubt sind.

Ein Beispiel für ein strenges Schema:

schema:
  type: object
  properties:
    teaser_short:
      type: array
      items: { type: string }
    teaser_long:
      type: array
      items: { type: string }
  required: [teaser_short, teaser_long]
  strict: true

Mit strict: true wird sichergestellt, dass das Modell keine überflüssigen Felder zurückgibt.

Ergebnisübernahme#

Nach der Antwort ruft Imperia den angegebenen Transformer auf. Der Standard DEFAULTAI legt die gesamte Antwort in __imperia_ai_suggestions ab und erzeugt zusätzlich für jedes Top-Level-Feld ein eigenes Metainfo-Feld wie __imperia_ai_teaser_short. Eigene Transformer können implementiert werden, wenn Ergebnisse gezielt in projektspezifische Felder wandern sollen.

Bilder einbeziehen#

Für Media-Asset-Management-Prompts gibt es das Flag assetinclude: 1. Damit wird beim Request nicht nur der Text übergeben, sondern auch ein Bild, das automatisch in Base64 umgewandelt und an das Modell gesendet wird.

Feld-Referenz#

Damit lässt sich die Struktur jeder Prompt-Datei beschreiben:

Feld	Bedeutung	Hinweise / Defaults
`id`	Eindeutige Kennung	ohne `id`: Dateiname (ohne Endung)
`label`	Anzeigename	optional
`description`	Kurzbeschreibung	optional
`systemprompt`	statischer System-Text	Alternative zu `systemtemplate`
`systemtemplate`	dynamischer System-Text (unterstützt `{P[n]}` + Imperia-Templating)	wird bevorzugt, wenn vorhanden
`userprompt`	statischer User-Text	Alternative zu `template`
`template`	dynamischer User-Text (unterstützt `{P[n]}` + Imperia-Templating)	wird bevorzugt, wenn vorhanden
`schema`	JSON-Schema der erwarteten Antwort	`strict: true` empfohlen
`transformer`	Ergebnisverarbeitung	Default: `DEFAULTAI`
`assetinclude`	Bild mitsenden (MAM)	`1` aktiviert, sonst `0`

Best Practices#

Für feste Instruktionen genügt ein einfacher Prompt.
Wo Variablen ins Spiel kommen, immer mit Templates arbeiten und {P[n]} nutzen.
In der PI eindeutige Nummern für _param_* und _value_* vergeben
Templates klein halten, nur die wirklich nötigen Daten übergeben.