llm-chat/MODULE.de.md
flemming-it 72f3037ebe
Some checks failed
CI / Linux x86_64 (Forgejo) (push) Failing after 1s
feat: max_tokens and repeat_penalty inputs, truncated and stop_reason outputs, 0.4.0
A model caught in a repetition loop wrote until the flow's 300 s
timeout. max_tokens bounds the answer on every wire (Ollama
num_predict, OpenAI max_tokens, Anthropic max_tokens), and
truncated tells the caller whether the answer stopped at that
limit. repeat_penalty goes to Ollama and vLLM and is refused where
the backend has no such setting.

Signed-off-by: flemming-it <sf@flemming.it>
2026-11-12 15:49:50 +01:00

9.1 KiB

llm.chat

Generischer LLM-Chat-Adapter. Das Baustein-Modul für jeden Flow, der eine LLM-Einzelantwort braucht — klassifizieren, Felder extrahieren, umformulieren, entscheiden — ohne einen eigenen HTTP-Client zu bauen. Spricht drei Wire-Formate, wählbar über die optionale Eingabe api: Ollama (Default), OpenAI Chat Completions (OpenAI, vLLM, kompatible Server) und die Anthropic Messages API.

Capability

  • llm.chat@0.4.0

Eingaben

Name Typ Beschreibung
prompt text Der User-Prompt.
endpoint text Chat-Endpunkt-URL passend zur gewählten api (siehe unten).
model text Modell-ID (z. B. qwen2.5:14b, claude-fable-5).
api_key text Optionaler API-Key. Erscheint nie in Ausgaben, Logs oder Events.
keep_alive text Nur Ollama: wie lange der Server das Modell nach dieser Anfrage geladen lässt (4h, 30m, -1 = unbegrenzt). Leer = Server-Voreinstellung, die nach fünf Minuten entlädt. Mit anderer api abgelehnt.
think text true oder false: ob ein Reasoning-Modell seine Denkphase durchläuft. Leer = Voreinstellung des Servers (Ollama lässt Modelle wie qwen3 denken). Ollama bekommt think, vLLM chat_template_kwargs.enable_thinking; im OpenAI-Format abgelehnt; Anthropic nimmt nur false. Gemessen mit Ollama 0.40.9: qwen3.8:27b und gemma4:26b halten false ein; qwen3:30b-a3b denkt trotzdem, das Denken steht dann in der Antwort und endet mit </think>.
max_tokens text Obergrenze für die Länge der Antwort in Token (ganze Zahl ab 1). Ollama bekommt options.num_predict, das OpenAI-Format max_tokens, Anthropic max_tokens (4096, wenn leer). Leer = keine Grenze bei Ollama und im OpenAI-Format. Ohne Grenze schreibt ein Modell in einer Wiederholungsschleife bis zur Zeitgrenze des Ablaufs; mit num_predict: 400 brach qwen3.8:27b unter Ollama 0.40.9 eine solche Schleife nach 39 s ab.
repeat_penalty text Abschlag auf wiederholte Token, 1.0 = neutral. Ollama bekommt options.repeat_penalty, vLLM repetition_penalty; im OpenAI-Format und bei Anthropic abgelehnt.
system_prompt text Optionale System-Nachricht. Leer = Default des Modells.
api text Optionales Wire-Format: ollama (Default), openai, anthropic.

Wire-Formate (api)

api Endpunkt-Form Auth-Header Hinweise
ollama http://localhost:11434/api/chat Authorization: Bearer (optional) Verhalten wie v0.1.0, unverändert. Modell-Digest-Probe via /api/show.
openai https://.../v1/chat/completions Authorization: Bearer OpenAI-Chat-Completions-Format — sprechen auch vLLM und die meisten selbst gehosteten Inferenz-Server.
anthropic https://api.anthropic.com/v1/messages x-api-key + anthropic-version Messages API: system ist Top-Level-Feld; max_tokens ist Pflicht; max_tokens setzt es, sonst 4096.

Ausgaben

Name Typ Beschreibung
response text Die Antwort des Assistants als Plain-Text.
truncated text true, wenn die Antwort an der Längengrenze endete, false, wenn das Modell fertig war. Leer, wenn das Backend keinen Grund nannte. Eine abgeschnittene Antwort wird trotzdem geliefert; der Ablauf entscheidet, was damit geschieht.
stop_reason text Der Grund des Backends: Ollama done_reason, OpenAI finish_reason, Anthropic stop_reason. Leer, wenn er fehlt.
model_endpoint text URL, gegen die die Antwort erzeugt wurde.
model_name text Modell-ID wie an die LLM-API gesendet.
model_digest text SHA-256-Digest des bedienenden Ollama-Modells. Leer bei openai/anthropic — diese APIs bieten keinen Digest; das Feld bleibt leer statt erfunden.
tokens_prompt text Was die Anfrage gekostet hat, nach der Zählung des Backends. Leer, wenn die Antwort keine Zählung enthielt.
tokens_completion text Was die Antwort gekostet hat, gleiche Regel. Ollama zählt in eval_count, das OpenAI-Format in usage.completion_tokens, Anthropic in usage.output_tokens.

Zusammen beantworten die drei model_*-Ausgaben die Audit- Frage: „Welches genaue Modell hat diese Antwort erzeugt?" — diese Spur ist der Grund, warum Flows dieses Modul nutzen statt eigene HTTP-Calls zu sprechen.

Berechtigungen

permissions:
  - "net: localhost"
  - "net: 127.0.0.1"
  - "net: api.openai.com"
  - "net: api.anthropic.com"

Loopback (lokales Ollama / vLLM) per Default. Cloud-Endpunkte brauchen einen Operator-Policy-Override in ~/.chain/config.yaml#security.max_permissions.

Warum dieses Modul statt Inline-HTTP

Drei Gründe:

  1. Audit. Jeder LLM-Aufruf erzeugt model_endpoint, model_name, model_digest als separate Ausgaben, die im hash-verketteten Audit-Log neben der Response landen. Eine Aufsichts-Reproduzierbarkeits-Prüfung vergleicht einfach das Digest-Feld mit dem Modell-Snapshot.
  2. Permission-Posture. Operator:innen sehen llm.chat in den installierten Modulen + dessen deklarierte net:-Liste. Ein hausgemachtes HTTP-Modul würde seine Endpunkte entweder verstecken oder bei jeder Installation eine frische Review-Oberfläche schaffen.
  3. Endpunkt-Portabilität. Endpunkt, Modell und Wire-Format sind Flow-Inputs, keine Compile-Time-Konstanten. Derselbe Flow läuft in der Entwicklung gegen localhost:11434 und in Produktion gegen ein vLLM-Cluster — nur die Eingaben wechseln.

Grenzen in v0.2.0

  • Kein Streaming. Die ganze Antwort wird gepuffert, bevor der Output-Step feuert.
  • Keine Tool-Call- / Function-Call-Oberfläche. Ein Flow, der Tool-Use braucht, kombiniert mehrere llm.chat-Schritte mit Prompt-Engineering oder nutzt MCP via Bridge.
  • Anthropic-max_tokens steht fest auf 4096 (die API verlangt das Feld; eine konfigurierbare Eingabe kommt, sobald ein Flow sie braucht).

Beispiel-Flows

name: classify-incoming
inputs:
  text: text
steps:
  - id: classify
    use: llm.chat@^0
    with:
      prompt: $inputs.text
      system_prompt: |
        Klassifiziere den Text als: question, complaint,
        feedback, spam. Antworte nur mit dem Label.
      endpoint: "http://localhost:11434/api/chat"
      model: "qwen2.5:14b"
outputs:
  category: $classify.response
  audit_model: $classify.model_digest

Gegen einen vLLM-Server (OpenAI-kompatibel):

steps:
  - id: classify
    use: llm.chat@^0
    with:
      api: "openai"
      endpoint: "http://inference.internal:8000/v1/chat/completions"
      model: "meta-llama/Llama-3.1-8B-Instruct"
      prompt: $inputs.text

Gegen die Anthropic Messages API:

steps:
  - id: classify
    use: llm.chat@^0
    with:
      api: "anthropic"
      endpoint: "https://api.anthropic.com/v1/messages"
      model: "claude-fable-5"
      api_key: $inputs.anthropic_key
      prompt: $inputs.text

Build

cargo build --release --target wasm32-wasip2
# Ausgabe: target/wasm32-wasip2/release/llm_chat.wasm

Ein lokales Modell geladen halten

Ollama entlädt ein Modell fünf Minuten nach der letzten Anfrage. Die nächste Anfrage zahlt dann den vollen Ladevorgang, bei einem großen lokalen Modell 30 bis 40 Sekunden: lang genug, dass ein Bediener einen Defekt vermutet.

keep_alive setzt dieses Fenster je Anfrage:

- id: antwort
  use: llm.chat@^0.2
  with:
    endpoint: http://localhost:11434/api/chat
    model: qwen2.5:7b
    keep_alive: "4h"
    prompt: $inputs.frage

Gegen ein laufendes Ollama gemessen (07.10.2026): ohne den Eingang lief das Modell 5:02 nach der Anfrage ab, mit keep_alive: "90s" nach 92 Sekunden. Zu beachten: Ollama behält den Wert für die geladene Instanz, eine spätere Anfrage ohne keep_alive fällt also erst dann wieder auf fünf Minuten zurück, wenn das Modell zwischendurch entladen wurde.

-1 wird als Zahl gesendet, nicht als Zeichenkette, weil Ollama nur die numerische Form als „nie entladen" liest.

Diese Einstellung gibt es nur bei Ollama. Mit api: openai, vllm oder anthropic wird der Eingang abgelehnt statt ignoriert: er drückt eine Erwartung an den Server aus, und ein stilles Verwerfen würde Sie den Ladevorgang zahlen lassen, während Sie ihn für erledigt halten. Bei vLLM und OpenAI-kompatiblen Servern wird die Verweildauer am Server eingestellt.