Some checks failed
CI / Linux x86_64 (Forgejo) (push) Failing after 2s
Ollama unloads a model five minutes after its last request, and the next request then pays a full reload: 30 to 40 seconds for a large local model, long enough that an operator assumes something is broken. The stromnetz demonstrator runs on a notebook from around 12.10. and hits exactly that after any idle period; it works around it today by setting OLLAMA_KEEP_ALIVE on the server, which is not expressible in a flow. Measured against a live Ollama: without the input the model expired 5:02 after the request, with `keep_alive: "90s"` it expired after 92 seconds. Worth knowing for callers: Ollama keeps the value for the loaded instance, so a later request that omits keep_alive does not fall back to five minutes until the model has actually been unloaded. `-1` is sent as a number rather than a string, because Ollama reads only the numeric form as "never unload"; quoted it is parsed as a duration and the setting silently does nothing. With any other wire format the input is REFUSED, not ignored. It expresses an expectation about the server, and dropping it quietly would leave the caller paying the reload while believing it was handled. The message says what to do instead. Capability goes 0.2.0 to 0.2.1: the addition is optional and additive, so `@^0.2` and `@^0` both keep resolving, and an unset value leaves the request byte-identical to the previous version. Five guards, including that unset omits the field entirely and that the other wire formats never carry it. Mutation-checked three ways. Signed-off-by: flemming-it <sf@flemming.it>
182 lines
7.2 KiB
Markdown
182 lines
7.2 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.2.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. |
|
|
| `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. |
|
|
|
|
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.
|