llm-chat/MODULE.de.md
flemming-it 14c63083d7
Some checks failed
CI / Linux x86_64 (Forgejo) (push) Failing after 2s
docs: think input in the German module page
Signed-off-by: flemming-it <sf@flemming.it>
2026-11-07 23:24:40 +01:00

185 lines
8 KiB
Markdown

# 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.3.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>`. |
| `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 und steht fest auf 4096. |
## Ausgaben
| Name | Typ | Beschreibung |
| ---------------- | ---- | --------------------------------------------------------------------- |
| `response` | text | Die Antwort des Assistants als Plain-Text. |
| `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
```yaml
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
```yaml
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):
```yaml
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:
```yaml
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
```bash
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:
```yaml
- 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.