Grundlagen der LLM-API: Anforderungs-, Antwort- und Nachrichtenrollen

Gewinne:

• Kann die Grundstruktur einer LLM-API-Anfrage beschreiben (Endpunkt, Modell, Nachrichten, max_tokens)
• Versteht den Unterschied zwischen System-, Benutzer- und Assistentenrollen und dem zustandslosen Gesprächsverlauf
• Kann Felder (Inhaltsblöcke, stop_reason, Verwendung) der zurückgegebenen Antwort lesen und interpretieren

In den vorherigen Modulen haben wir künstliche Intelligenz aus einem Chatfenster genutzt. Wenn Sie jedoch KI in Ihr eigenes Produkt, Ihre Automatisierung oder Ihren Arbeitsablauf einbetten möchten, reicht eine Chat-Schnittstelle nicht aus; Sie müssen programmgesteuert eine Verbindung zum Modell herstellen, d. h. mit Code oder einem Automatisierungstool. Der Name dieser Brücke ist API (Application Programming Interface, der Vertrag, der es zwei Softwareprogrammen ermöglicht, mit bestimmten Regeln zu kommunizieren). Wenn Sie diese Einheit abgeschlossen haben, wissen Sie, was eine LLM-API-Anfrage (Large Language Model) ausmacht, welche Nachrichtenrollen funktionieren und wie die Antwort gelesen wird. Dies ist die Grundlage, auf der der Rest des Moduls aufgebaut wird.

Wie funktioniert die API?

Der grundlegende Ablauf in der API ist folgender: Sie senden eine Anfrage in einem bestimmten Format; Der Server gibt eine Antwort in einem bestimmten Format zurück. In LLMs ist dies normalerweise ein HTTP-Aufruf (HTTP: Standardprotokoll zur Übertragung von Anfragen und Antworten im Web) an eine einzelne Adresse (Endpunkt, die feste Adresse auf dem Server, der Ihre Anfrage bearbeitet). In einer Messaging-API gehen beispielsweise alle Anfragen an eine einzige Adresse und werden im Text als JSON (JavaScript Object Notation – ein Textformat bestehend aus Schlüssel/Wert-Paaren, das sowohl von Menschen als auch von Maschinen gelesen werden kann) übertragen.

In einer Anfrage geben Sie mindestens diese drei Dinge an:

• Modell: Welches Modell Sie verwenden werden (z. B. ein schnelles und günstiges Modell oder ein leistungsstarkes Modell).
• max_tokens: Die maximale Anzahl an Token (die kleinste Einheit, in der der Text verarbeitet wird, die in der nächsten Einheit detailliert verarbeitet wird), die das Modell produzieren kann; d.h. Leistungsgrenze.
• Nachrichten: Liste der Nachrichten, aus denen die Konversation besteht.

Schritt für Schritt: So richten Sie eine Anfrage ein

1. Bereiten Sie den Endpunkt und die Anmeldeinformationen vor. Sie fügen der Anfrage in einem Header Ihren API-Schlüssel (die geheime Zeichenfolge, die Ihre Identität nachweist) hinzu. Sie betten den Schlüssel niemals in den Code ein; Wir kümmern uns um die sichere Lagerung in Einheit 9.
2. Wählen Sie das Modell und die Leistungsgrenze aus. Leichtes Modell + kleine max_tokens für eine einfache Aufgabe; Leistungsstarkes Modell + größeres Limit für eine komplexe Aufgabe.
3. Richten Sie die Nachrichtenliste ein. List the system instruction, user message, and past rounds (if any).
4. Senden Sie die Anfrage und analysieren Sie die Antwort. Lesen Sie den Textinhalt, den Stoppgrund und die Tokennutzung aus dem zurückgegebenen JSON.

Nachrichtenrollen: System, Benutzer, Assistent

Eine Konversation besteht aus Nachrichten, die in einer Reihenfolge angeordnet sind, und jede Nachricht hat eine Rolle. Die Rolle bestimmt, wie das Modell diesen Text behandelt.

Rolle

Wer schreibt

Zweck

System

Entwickler/Betreiber

Permanente Anweisungen, Persönlichkeit und Regeln, die während des gesamten Gesprächs gelten

Benutzer

Endbenutzer

Die aktuelle Frage oder Eingabe des Benutzers

Assistent

Modell

Vom Modell erzeugte Antwort (und frühere Antworten)

Die Systemrolle ist bei den meisten Anbietern als separates Systemfeld im Anfragetext verfügbar; Benutzer und Assistent werden nacheinander in der Nachrichtenliste aufgeführt. Critical point: the system instruction is the high-level instruction, the user message is the request to be answered at that moment.

{ „model“: „claude-opus-4-8“, „max_tokens“: 1024, „system“: „Sie sind ein Assistent für den Unternehmenssupport. Geben Sie eine kurze, formelle und überprüfte Antwort. Erfinden Sie keine Informationen, bei denen Sie sich nicht sicher sind.“, „messages“: [ { „role“: „user“, „content“: „Wie starte ich meinen Rückgabeprozess?“ } ]}

Sprache ist staatenlos

Hier ist das häufigste Missverständnis: LLM-API-Aufrufe sind zustandslos – der Server behält zwischen zwei Anfragen keinen Speicher. Das Modell erinnert sich nicht an Ihre vorherige Anfrage. Wenn Sie einen Chat mit mehreren Runden einrichten, müssen Sie vergangene Runden bei jeder neuen Anfrage erneut senden. Der „Speicher“ des Modells besteht aus einer Liste der von Ihnen gesendeten Nachrichten.

{ „model“: „claude-opus-4-8“, „max_tokens“: 512, „messages“: [ { „role“: „user“, „content“: „Hallo, mein Name ist Deniz.“ }, { „role“: „assistant“, „content“: „Hallo Deniz, wie kann ich dir helfen?“ }, { „role“: „user“, „content“: „Ich habe gerade meinen Namen gesagt, erinnerst du dich?“ } ]}

Die richtige Beantwortung der dritten Nachricht hängt davon ab, dass Sie beide vorherigen Nachrichten senden. Wenn Sie es nicht senden, kennt das Modell „Meer“ nicht und antwortet falsch. Dies wirkt sich auch direkt auf die Kosten aus: Je länger die Konversation, desto größer die Liste, und jede Anfrage verbraucht mehr Token.

Tipp: Bei langen Gesprächen reduziert das Zusammenfassen und Verschieben alter Runden (Zusammenfassung + letzte paar Runden) anstelle des Sendens des gesamten Verlaufs die Kosten und bewahrt das Kontextfenster. Wir werden dies in den Einheiten 6 und 11 vertiefen.

Lesen Sie die Antwort

Wenn das Modell eine Antwort zurückgibt, erhalten Sie ein strukturiertes Objekt, keinen einfachen Text. Typische Bereiche:

{ „id“: „msg_01ABC…“, „model“: „claude-opus-4-8“, „role“: „assistant“, „content“: [ { „type“: „text“, „text“: „Um eine Rücksendung zu veranlassen, gehen Sie zur Seite „Meine Bestellungen“ in Ihrem Konto ...“ } ], „stop_reason“: „end_turn“, „usage“: { „input_tokens“: 47, "output_tokens": 88 }}

• Inhalt: Die Antwort selbst; Es handelt sich um eine Liste von Inhaltsblöcken. Das Textfeld des Textblocks ist die eigentliche Antwort.
• stop_reason: Warum das Modell gestoppt wurde. end_turn = natürliches Ende; max_tokens = bleibt beim Ausgabelimit hängen (Antwort ist möglicherweise unvollständig); Ablehnung = aus Sicherheitsgründen abgelehnt. Ihr Code sollte sich immer zuerst stop_reason ansehen.
• Verwendung: Ein- und Ausgabe-Token-Nummern. Es ist die Grundlage der Kosten- und Limitverfolgung.

Achtung: Wenn stop_reason max_tokens ist, ist die Antwort nicht abgeschlossen. Dies als „erfolgreiche Antwort“ zu behandeln und dem Benutzer den halben Text anzuzeigen, ist einer der häufigsten Fehler in der Produktion. Entweder max_tokens erhöhen oder Streaming verwenden.

Schwache Eingabeaufforderung / Starke Eingabeaufforderung

Gleiche Aufgabe mit zwei unterschiedlichen Systemaufforderungen:

# SCHWACHDu bist ein Assistent. Beantworten Sie die Fragen.

# STARKSie sind ein Assistent für den Unternehmenssupport. Regeln: - Verlassen Sie sich ausschließlich auf die Informationen im bereitgestellten Versicherungsdokument. Wenn sie nicht im Dokument enthalten ist, sagen Sie: „Ich habe diese Informationen nicht, ich leite sie an die zuständige Einheit weiter.“ - Die Antworten sollten 3 Sätze nicht überschreiten, formell und klar sein. - Fragen Sie nicht nach persönlichen Daten (TC-ID-Nummer, Kartennummer) und wiederholen Sie diese nicht. - Raten Sie nicht, wenn Sie sich nicht sicher sind.

Leistungsstarke Version; Es definiert Umfang, Form, Sicherheitsmarge und Verhalten bei Unsicherheit. Die Konsistenz der Modellausgabe ergibt sich direkt aus dieser Klarheit.

Drei Mini-Hüllen

Fall 1 – Support-Bot (Staatenlosigkeitsfalle). Ein E-Commerce-Team hat den Bot live geschaltet; Als der Benutzer „Vorherige Bestellung stornieren“ sagte, „vergaß“ der Bot die Bestellnummer. Grund: Sie schickten jede Anfrage nur mit der letzten Nachricht. Lösung: Sie haben die letzten 6 Runden zur Nachrichtenliste hinzugefügt. Ergebnis: Der Kontext bleibt erhalten, aber die Eingabe pro Anfrage wurde von 40 Token auf etwa 600 Token erhöht. Die Kostenlektion behandeln wir in Einheit 2.

Fall 2 – Unvollständige Vertragszusammenfassung. Ein Rechtsteam erstellte einen zehnseitigen Vertragsentwurf; max_tokens: 300 blieb niedrig, Zusammenfassungen wurden mitten im Satz abgeschnitten. stop_reason war jedes Mal max_tokens, aber niemand schaute hin. max_tokens auf 1500 erhöht und stop_reason-Prüfung hinzugefügt; Die Rate verkürzter Zusammenfassungen sank von 18 % auf 0 %.

Fall 3 – Rollenvermischung. Ein Marketingteam schrieb alle Anweisungen in die Benutzernachricht und ließ das System leer. Wenn Benutzereingaben mit Anweisungen vermischt wurden, befolgte das Modell manchmal den Befehl des Benutzers, „die vorherigen Regeln zu vergessen“. Sie haben dauerhafte Regeln in das System verschoben; Durch die Trennung von Benutzereingaben und Anweisungen gingen Regelverstöße deutlich zurück.

Häufige Fehler

• Vergessen, die Vergangenheit zu senden: Es wird angenommen, dass sich das Modell „nicht erinnert“; wohingegen es staatenlos ist. Sie tragen den Kontext.
• Nicht auf „stop_reason“ achten: Die mit max_tokens gestoppte Antwort gilt als abgeschlossen.
• Einbetten der Anweisung in „Benutzer“: Persistente Regeln im System; Die sofortige Eingabe geht an den Benutzer. Durch das Mischen entstehen Sicherheitslücken.
• „Inhalt“ mit einer einfachen Zeichenfolge verwechseln: Die Antwort ist eine Liste von Blöcken; Lesen Sie das Textfeld des ersten Textblocks und überprüfen Sie seinen Typ, bevor Sie den Inhalt[0] mit einem Blindindex abrufen.
• Einbetten des Schlüssels in den Code: Verwenden Sie eine Umgebungsvariable (Einheit 9).

Tiefer: Inhaltsblöcke und mehrteilige Antworten

Für die erweiterten Funktionen, die Sie später kennenlernen werden, ist es von grundlegender Bedeutung, zu verstehen, warum das Inhaltsfeld in der Antwort eine Liste ist. Manchmal gibt das Modell nicht einen einzelnen Textblock zurück, sondern mehrere Blöcke: einen Denkblock, gefolgt von einem Textblock; oder ein Textblock, gefolgt von einem Werkzeugverwendungsblock. Aus diesem Grund ist es fragil, Content[0] blind als „Antwort“ zu zählen. Der richtige Ansatz besteht darin, die Liste durchzugehen und nach Typ zu sortieren: Sie sammeln den Textinhalt von Blöcken, deren Typfeld Text ist, und behandeln andere Typen (Denken, Werkzeug) separat.

In der Praxis bedeutet diese Unterscheidung, dass Sie die Argumentation des Modells (falls vorhanden) protokollieren können, ohne sie dem Benutzer preiszugeben, Toolaufrufe an eine separate Logik umleiten und nur die tatsächliche Antwort auf dem Bildschirm ausdrucken können. Im Verlauf des Moduls (insbesondere in den Einheiten 4 und 11) werden Sie sehen, wie nützlich diese Blockstruktur für die Validierung und Steuerung der Ausgabe ist.

Ein weiterer praktischer Punkt: Sie können von verschiedenen Anbieterplattformen aus auf dasselbe Modell zugreifen (direkte API, über einen Cloud-Anbieter). Obwohl sich die Endpunktadresse und das Authentifizierungsformat ändern können, bleiben grundlegende Konzepte wie Nachrichtenrollen, Zustandslosigkeit und Antwortstruktur gleich. Die Grundlagen dieser Einheit gelten also unabhängig davon, welche Plattform Sie verwenden.

Zusammenfassend

Eine LLM-API-Anfrage besteht aus dem Modell, dem Ausgabelimit und der Nachrichtenliste; Rollen (System, Benutzer, Assistent) bestimmen das Verhalten des Modells. Anrufe sind zustandslos: Sie tragen den Kontext mit jeder Anfrage. Die Antwort ist ein strukturiertes Objekt; Das Lesen und Interpretieren der Felder „Inhalt“, „stop_reason“ und „Nutzung“ ist die Grundlage für die Haltbarkeit in der Produktion.

Anwendungsaufgabe

Wählen Sie eine Aufgabe aus Ihrem eigenen Beruf (z. B. eingehende E-Mails sortieren, kurze Zusammenfassungen erstellen). Auf ein Blatt Papier: (1) Schreiben Sie die Systemeingabeaufforderung mit 4-5 Regeln, (2) richten Sie eine Beispielbenutzernachricht und ggf. einen 2-Runden-Verlauf ein, (3) Bestimmen Sie einen angemessenen Wert für max_tokens und schreiben Sie die Begründung, (4) Listen Sie auf, welche stop_reason-Werte Sie in der zurückgegebenen Antwort behandeln und wie.

Checkliste

• [ ] Ich kann die drei obligatorischen Teile einer Anfrage zählen (Modell, max_tokens, Nachrichten).
• [ ] Ich kann den Unterschied zwischen System-, Benutzer- und Assistentenrollen erklären.
• [ ] Ich weiß, dass Anrufe zustandslos sind und dass ich die Vergangenheit mit mir herumtragen muss.
• Ich kann [ ] Inhalt, stop_reason und Nutzungsfelder lesen und kommentieren.
• [ ] Mit max_tokens kann ich die abgeschnittene Antwort erkennen und verarbeiten.