Hacker-Software/ARIA-AGENT
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 267 Wiki Activity

feat(llm): Cluster — Programme fragen ein Modell, der Cluster waehlt die Karte

Browse Source 
Programme sollen nicht Box und Karte aussuchen muessen. Die ARIA-Bridge kennt
alle Boxen samt Karten-Belegung und verteilt (bridge/llm_cluster.py):

- Auswahl: unter allen online Boxen mit dem Modell die mit den wenigsten
  laufenden Anfragen, bei Gleichstand reihum. Eine Karte / alles frei →
  alles dorthin ("verteilen, wenn noetig").
- Ausfall: geht eine Box waehrend der Anfrage offline (kein Ping mehr), wird
  sie EINMAL an eine andere Box mit demselben Modell gegeben. Modell-Fehler
  (z.B. Kontext zu lang) werden nicht wiederholt — waeren ueberall gleich.
- Fehler kommen als Fehler (ok=false + errorCode), nie als Antwort-Text: ein
  Programm wuerde ihn sonst als Aussage der KI in seinen Verlauf schreiben —
  so ist bei ARIA schon mal ein ganzer Chat kaputtgegangen.

RVS: llm_cluster_models_request → llm_cluster_models (jedes Modell EINMAL,
ctx = kleinstes Kontextfenster unter seinen Karten), llm_cluster_request →
llm_cluster_response. In der RVS-Allow-List freigegeben.

ARIA nutzt denselben Router (mit ihrer 30-s-Frist fuer den lokalen
Schnellweg) — vorher Round-Robin ohne Ausfall-Ersatz, und errorCode ging
verloren.

xtts/openai_rvs_wrapper: fuer Programme, die nur "OpenAI-kompatibel" koennen
(OpenHands & Co.). Kleiner Container NEBEN dem Programm, fuer das der Cluster
dann http://127.0.0.1:8099/v1 ist; braucht nur eine ausgehende Verbindung zum
RVS. /v1/models (jedes Modell einmal, context_length), /v1/chat/completions
(auch stream und tools), Fehler als HTTP mit OpenAI-Fehlerobjekt. Hilfsseite
auf / zeigt Status, Base URL und Modelle. Fuer Programme in Docker: Netz
aria-llm, Name openai-rvs-wrapper. .env.example mit RVS_HOST/PORT/TOKEN.
(Ein OpenAI-Endpunkt direkt auf der VM war kurz drin und ist wieder raus —
der Wrapper braucht keinen offenen Port auf der VM.)

docs/LLM-SCHNITTSTELLE.md neu gegliedert: A) Cluster ueber RVS (empfohlen),
B) Wrapper, C) direkt an eine Box (Sonderfall), plus "Umstellen" fuer
bestehende Clients (Software-Schmiede).

Tests: mit echtem RVS und zwei echten llm-adaptern als zwei Boxen —
Modell einmal gelistet, 6 parallele Anfragen 3/3 verteilt, Box friert
mitten in der Anfrage ein → nach 15 s von der anderen beantwortet
(attempts=2), danach direkt die gesunde, nicht geladenes Modell →
model_unavailable ohne content. Wrapper als Docker-Container gegen das
offizielle OpenAI-SDK: models.list, create mit/ohne stream, NotFoundError,
AuthenticationError. Das Doku-Beispiel lief unveraendert (nur Adresse).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
duffyduck
2026-10-19 01:43:09 +02:00
co-authored by Claude Opus 5.5
parent 60f2d2e087
commit c26b27f09f
14 changed files with 977 additions and 234 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/LLM-SCHNITTSTELLE.md
+236 -175
View File
@@ -1,47 +1,43 @@
# Lokale Sprachmodelle nutzen — Schnittstelle für Drittprogramme
# Lokale Sprachmodelle nutzen — Schnittstelle für Programme
Diese Seite beschreibt, wie ein Programm die lokalen Sprachmodelle auf den
KI-Boxen von ARIA nutzt: über den RVS (WebSocket) oder direkt über den
OpenAI-kompatiblen Port einer Box.
Wie ein Programm die lokalen Sprachmodelle auf den KI-Boxen von ARIA nutzt.
**Kurz:** Du fragst ein **Modell**, nicht eine Box oder Karte. Der Cluster
sucht sich aus, wo es läuft. Eigene Programme sprechen dafür über den RVS
(Abschnitt A). Programme, die nur „OpenAI-kompatibel" können, bekommen den
OpenAI-RVS-Wrapper neben sich gestellt (Abschnitt B).
## Die Grundregel
**Clients wählen aus, laden aber nie.**
**Programme wählen ein Modell aus — laden aber nie.**
- Jede KI-Box hat eine oder mehrere Grafikkarten fürs LLM. Jede dieser Karten
hält **genau ein Modell, dauerhaft geladen**.
- Welches Modell auf welcher Karte liegt, legt ausschließlich der Betreiber in
der ARIA-Diagnostic fest (Modell-Katalog → Laden → Karte).
- Ein Client — ARIA selbst, ein Drittprogramm, OpenHands — sieht nur die
**geladenen** Modelle aller Boxen und schickt seine Anfrage an eines davon.
- Eine Anfrage für ein Modell, das nicht geladen ist, wird **abgelehnt**. Sie
lädt nichts nach und verdrängt nichts. Kein Client kann einem anderen das
Modell wegnehmen.
- Mehrere Clients dürfen **gleichzeitig dasselbe Modell** nutzen. Die Karte
bedient sie parallel; jede einzelne Antwort wird dabei etwas langsamer, die
Karte schafft in Summe aber mehr.
- Welches Modell wo liegt, legt nur der Betreiber in der ARIA-Diagnostic fest
(Einstellungen → LLM-Karten).
- Ein Programm sieht die geladenen Modelle des ganzen Clusters — jedes
**einmal**, egal auf wie vielen Karten es liegt — und wählt eins.
- Liegt das Modell auf mehreren Karten, **verteilt der Cluster bei Last**.
Fällt eine Box mitten in einer Anfrage aus, übernimmt eine andere mit
demselben Modell. Davon merkt das Programm nichts.
- Ist das Modell nirgends geladen, gibt es einen **Fehler** — nie eine normale
Antwort mit Fehlertext. Ein Programm würde so einen Text sonst als Aussage
der KI in seinen Verlauf schreiben.
- Mehrere Programme dürfen **gleichzeitig dasselbe Modell** nutzen. Die Karte
bedient sie parallel; jede einzelne Antwort wird dabei etwas langsamer.
Welche Karten einer Box dem LLM gehören, steht in deren `.env`:
## Welcher Zugang?
```bash
# Beispiel: Karte 0 für Spracherkennung + Sprachausgabe, Karten 1 und 2 fürs LLM
WHISPER_GPU=0
F5TTS_GPU=0
LLM_GPUS=1,2
```
## Zwei Zugänge
| | RVS (WebSocket) | OpenAI-Port der Box |
|---|---|---|
| Erreichbar | überall, wo der RVS erreichbar ist | nur im Netz der Box (Standard: nur `localhost`) |
| Sieht | alle Boxen und ihre Karten | nur diese eine Box |
| Format | eigene Nachrichten (unten) | OpenAI `/v1/chat/completions` |
| Typische Nutzer | eigene Programme, ARIA | OpenHands, Continue, Open WebUI |
| | A) Cluster über RVS | B) OpenAI-RVS-Wrapper | C) Direkt an eine Box |
|---|---|---|---|
| Für | eigene Programme | OpenHands, Continue, Open WebUI … | Sonderfälle |
| Sieht | alle Modelle, jedes einmal | alle Modelle, jedes einmal | nur diese Box |
| Verteilung + Ausfall-Ersatz | ja | ja | nein |
| Braucht | ausgehende Verbindung zum RVS | Wrapper-Container auf demselben Rechner | ausgehende Verbindung zum RVS |
---
## A) Über den RVS
## A) Cluster über RVS — empfohlen
### Verbinden
@@ -49,13 +45,19 @@ LLM_GPUS=1,2
wss://<RVS_HOST>:<RVS_PORT>/?token=<RVS_TOKEN>
```
- Das **Token ist der Raum**. Es ist dasselbe Token, das ARIA, die Diagnostic
und die KI-Boxen nutzen (`RVS_TOKEN`). Wer das Token hat, ist im Raum.
- Der RVS ist ein **Verteiler**: Jede Nachricht geht an *alle anderen*
Teilnehmer des Raums. Du siehst also auch Antworten, die für andere Clients
bestimmt sind — ordne Antworten immer über die `requestId` zu.
- Der RVS lässt nur bekannte Nachrichtentypen durch. Unbekannte Typen
verschwinden **ohne Fehlermeldung**. Die hier beschriebenen sind freigegeben.
- Das **Token ist der Raum** — dasselbe `RVS_TOKEN` wie bei ARIA und den
KI-Boxen. Wer es hat, ist im Raum.
- Der Programm-Rechner braucht nur eine **ausgehende** Verbindung zum RVS.
Keine Portfreigabe, kein VPN — er kann in jedem Netz stehen.
- Der RVS ist ein **Verteiler**: Jede Nachricht geht an alle anderen im Raum.
Du siehst also auch Antworten für andere — ordne sie immer über die
`requestId` zu.
- Unbekannte Nachrichtentypen verwirft der RVS **ohne Fehlermeldung**. Die hier
beschriebenen sind freigegeben.
- **Nur ein Leser pro Verbindung.** Schickst du mehrere Anfragen gleichzeitig,
liest eine Schleife alle Nachrichten und verteilt sie per `requestId` an die
Wartenden (siehe Beispiel). Mehrere gleichzeitige `recv()` auf derselben
Verbindung gehen nicht.
Jede Nachricht hat diese Hülle:
@@ -63,25 +65,33 @@ Jede Nachricht hat diese Hülle:
{ "type": "<typ>", "payload": { … }, "timestamp": 1760000000000 }
```
### 1. Welche Modelle gibt es? — `llm_models_request`
Beantwortet werden `llm_cluster_*`-Nachrichten von der **ARIA-Bridge** — sie
kennt alle Boxen und entscheidet, wohin eine Anfrage geht. Läuft ARIA nicht,
kommt keine Antwort (dein Programm sollte einen Timeout haben).
### 1. Welche Modelle gibt es? — `llm_cluster_models_request`
```json
{ "type": "llm_models_request", "payload": { "requestId": "abc-1" } }
{ "type": "llm_cluster_models_request", "payload": { "requestId": "a1" } }
```
**Jede** Box im Raum antwortet einzeln mit `llm_models`. Sammle die Antworten
ein paar Sekunden lang ein (2–3 s reichen):
Antwort:
```json
{
"type": "llm_models",
"type": "llm_cluster_models",
"payload": {
"requestId": "abc-1",
"instanceId": "llm@ki-box",
"node": "ki-box",
"requestId": "a1",
"models": [
{ "model": "qwen3-8b", "gpu": "1", "gpuName": "NVIDIA GeForce RTX 3060", "ctx": 8192, "state": "ready" },
{ "model": "qwen3-4b", "gpu": "2", "gpuName": "NVIDIA GeForce RTX 3060", "ctx": 8192, "state": "ready" }
{
"model": "qwen3-8b",
"ctx": 8192,
"available": 2,
"cards": [
{ "node": "ki-box", "instanceId": "llm@ki-box", "gpu": "1", "gpuName": "NVIDIA GeForce RTX 3060", "state": "ready" },
{ "node": "werkstatt", "instanceId": "llm@werkstatt", "gpu": "0", "gpuName": "NVIDIA RTX A4000", "state": "ready" }
]
}
]
}
}
@@ -89,29 +99,18 @@ ein paar Sekunden lang ein (2–3 s reichen):
| Feld | Bedeutung |
|---|---|
| `instanceId` | Adresse der Box — brauchst du gleich als `targetInstance` |
| `node` | lesbarer Name der Box |
| `models[].model` | Modellname, so in der Anfrage angeben |
| `models[].gpu` | Karte, auf der es läuft |
| `models[].ctx` | **Kontextfenster in Tokens**, mit dem das Modell gestartet ist — Eingabe und Ausgabe zusammen. Diesen Wert verwenden, nicht den, den das Modell theoretisch kann: Die Box gibt nur so viel her, wie hier steht. `0` = unbekannt. |
| `models[].state` | `ready` = bereit, `starting` = startet gerade neu (Anfragen warten dann kurz), `unknown` = Box konnte es nicht prüfen |
| `model` | Name — genau so in der Anfrage angeben. **Das** zeigst du dem Nutzer zur Auswahl. |
| `ctx` | **Kontextfenster in Tokens** (Eingabe + Ausgabe zusammen). Das kleinste unter allen Karten mit diesem Modell — darauf kannst du dich verlassen, egal wohin verteilt wird. Nicht mehr annehmen. `0` = unbekannt. |
| `available` | auf wie vielen Karten es gerade liegt |
| `cards` | nur zur Info (Anzeige, Fehlersuche) — für die Anfrage nicht nötig |
Es stehen **nur geladene** Modelle in der Liste. Was dort nicht steht, kannst
du nicht nutzen.
Mitlesen statt fragen: Die Boxen melden sich außerdem regelmäßig selbst
(`worker_hello` etwa alle 30 s, `worker_ping` alle 10 s, jeweils mit
`service: "llm"`, `models` und `slots`). Ein Client, der länger verbunden
bleibt, kann die Liste daraus aktuell halten.
### 2. Fragen — `llm_request`
### 2. Fragen — `llm_cluster_request`
```json
{
"type": "llm_request",
"type": "llm_cluster_request",
"payload": {
"requestId": "abc-2",
"targetInstance": "llm@ki-box",
"requestId": "a2",
"model": "qwen3-8b",
"messages": [
{ "role": "system", "content": "Du antwortest kurz." },
@@ -125,172 +124,234 @@ bleibt, kann die Liste daraus aktuell halten.
| Feld | Pflicht | Bedeutung |
|---|---|---|
| `requestId` | ja | eindeutig pro Anfrage (z.B. UUID) — damit findest du deine Antwort |
| `requestId` | ja | eindeutig pro Anfrage (z.B. UUID) |
| `model` | ja* | aus `llm_cluster_models`. *Darf fehlen, wenn im Cluster genau ein Modell geladen ist. |
| `messages` | ja | Verlauf im OpenAI-Format (`system` / `user` / `assistant` / `tool`) |
| `model` | dringend empfohlen | eines aus `llm_models`. Ohne Angabe nimmt die Box das Modell ihrer ersten LLM-Karte. |
| `targetInstance` | dringend empfohlen | die `instanceId` aus `llm_models`. Siehe „Ohne `targetInstance`". |
| `max_tokens` | nein | Standard 512 |
| `temperature` | nein | Standard 0.7 |
| `stop` | nein | Liste von Stop-Strings |
| `tools` | nein | Tool-Definitionen im OpenAI-Format; Antwort enthält dann ggf. `tool_calls` |
| `tools` | nein | Tool-Definitionen im OpenAI-Format; die Antwort enthält dann ggf. `tool_calls` |
### 3. Antwort — `llm_response`
### 3. Antwort — `llm_cluster_response`
Erfolg:
```json
{
"type": "llm_response",
"type": "llm_cluster_response",
"payload": {
"requestId": "abc-2",
"requestId": "a2",
"ok": true,
"content": "Die Zugspitze ist 2962 Meter hoch.",
"tool_calls": null,
"model": "qwen3-8b",
"instanceId": "llm@ki-box",
"node": "ki-box",
"gpu": "1",
"node": "werkstatt",
"gpu": "0",
"usage": { "prompt_tokens": 31, "completion_tokens": 12, "total_tokens": 43 },
"elapsedMs": 640
"elapsedMs": 640,
"attempts": 1
}
}
```
Im Fehlerfall ist `ok` `false`, dazu kommen `error` (Text für Menschen) und
`errorCode` (für Programme):
`tool_calls` steht drin, wenn das Modell ein Werkzeug aufrufen will (OpenAI-Format).
`node`/`gpu` sagen, wer geantwortet hat; `attempts: 2` heißt, die erste Box ist
ausgefallen und eine andere hat übernommen.
Fehler — `ok: false`, dazu `error` (Text für Menschen) und `errorCode`:
| `errorCode` | Bedeutung | Was tun |
|---|---|---|
| `model_not_loaded` | Das Modell liegt auf dieser Box nicht. `loadedModels` nennt, was dort geladen ist. | Ein geladenes Modell wählen. Die Liste neu holen (`llm_models_request`). |
| `no_model_loaded` | Auf dieser Box ist keine LLM-Karte belegt. | Andere Box wählen. |
| *(fehlt)* | Fehler des Modells selbst, z.B. Kontext zu lang | `error` lesen |
| `model_unavailable` | Das Modell ist gerade auf keiner Karte im Cluster geladen. `available` nennt, was es gibt. | Dem Nutzer anzeigen; Liste neu holen. |
| `bad_request` | Anfrage unvollständig, z.B. `messages` leer oder `model` fehlt bei mehreren Modellen | Anfrage korrigieren |
| `timeout` | Keine Antwort innerhalb der Frist (Standard 600 s) — auch nach Ersatzversuch | später nochmal |
| `box_offline` | Box ist während der Anfrage weggefallen, und es gab keine Ersatz-Box | später nochmal |
| `model_error` | Das Modell selbst hat einen Fehler gemeldet, z.B. Kontext zu lang. Wird nicht anderswo wiederholt — wäre dort genauso. | `error` lesen |
### Ohne `targetInstance`
Ohne `targetInstance` geht die Anfrage an alle Boxen. Antworten werden nur die,
die das Modell geladen haben — die anderen **schweigen**, damit du nicht von
jeder Box einen Fehler bekommst. Hat keine Box das Modell, kommt also **gar
keine** Antwort und dein Client läuft in seinen Timeout. Darum: immer
`targetInstance` setzen. Dann bekommst du bei einem Problem sofort eine klare
Absage.
Haben mehrere Boxen dasselbe Modell geladen und du lässt `targetInstance`
weg, antworten **alle**. Auch das spricht für `targetInstance`.
### Was Clients nicht senden
`llm_provision_model`, `llm_unload_model` und `llm_remove_model` sind der
Diagnostic vorbehalten. Technisch könnte jeder im Raum sie senden — der RVS
unterscheidet die Teilnehmer nicht. Ein Programm, das sich daran nicht hält,
tauscht anderen Clients das Modell unter den Füßen weg; genau das soll diese
Schnittstelle verhindern.
**Fehler nie als Antwort der KI behandeln.** Zeig `error` dem Nutzer als
Fehlermeldung an, aber schreib ihn nicht als Assistant-Nachricht in den
Verlauf.
### Beispiel (Python)
Braucht Python 3.11+ und `websockets` (`pip install websockets`). Genau so gegen einen
echten RVS, llm-adapter und llama-swap getestet — nur die Adresse war eine andere.
Braucht Python 3.11+ und `websockets` (`pip install websockets`). Ein Leser
pro Verbindung, mehrere Anfragen gleichzeitig möglich.
```python
import asyncio, json, uuid
import websockets
RVS = "wss://rvs.example.org:443/?token=DEIN_RVS_TOKEN"
RVS = "wss://rvs.example.org:444/?token=DEIN_RVS_TOKEN"
async def models(ws, wait=2.5):
"""Alle geladenen Modelle aller Boxen: [(instanceId, node, model, gpu)]."""
rid = str(uuid.uuid4())
await ws.send(json.dumps({"type": "llm_models_request", "payload": {"requestId": rid}}))
found = []
loop = asyncio.get_running_loop()
end = loop.time() + wait
while (left := end - loop.time()) > 0:
try:
msg = json.loads(await asyncio.wait_for(ws.recv(), left))
except asyncio.TimeoutError:
break
p = msg.get("payload") or {}
if msg.get("type") == "llm_models" and p.get("requestId") == rid:
found += [(p["instanceId"], p["node"], m["model"], m["gpu"]) for m in p["models"]]
return found
class AriaCluster:
"""Eine RVS-Verbindung, ein Leser. Antworten gehen per requestId an die
wartende Anfrage — der Raum ist ein Verteiler, Fremdes wird ignoriert."""
def __init__(self, ws):
self.ws, self.wait = ws, {}
self.reader = asyncio.create_task(self._read())
async def ask(ws, instance_id, model, prompt, timeout=120):
rid = str(uuid.uuid4())
await ws.send(json.dumps({"type": "llm_request", "payload": {
"requestId": rid, "targetInstance": instance_id, "model": model,
"messages": [{"role": "user", "content": prompt}], "max_tokens": 256}}))
async with asyncio.timeout(timeout):
while True:
msg = json.loads(await ws.recv())
async def _read(self):
async for raw in self.ws:
msg = json.loads(raw)
p = msg.get("payload") or {}
# Der Raum ist ein Verteiler: nur UNSERE Antwort nehmen.
if msg.get("type") == "llm_response" and p.get("requestId") == rid:
if not p["ok"]:
raise RuntimeError(f"{p.get('errorCode')}: {p.get('error')}")
return p["content"]
fut = self.wait.get((msg.get("type"), p.get("requestId")))
if fut and not fut.done():
fut.set_result(p)
async def _call(self, mtype, answer, payload, timeout):
rid = str(uuid.uuid4())
fut = asyncio.get_running_loop().create_future()
self.wait[(answer, rid)] = fut
try:
await self.ws.send(json.dumps({"type": mtype, "payload": dict(payload, requestId=rid)}))
return await asyncio.wait_for(fut, timeout)
finally:
self.wait.pop((answer, rid), None)
async def models(self):
res = await self._call("llm_cluster_models_request", "llm_cluster_models", {}, 6)
return res["models"]
async def chat(self, model, messages, timeout=660, **opts):
res = await self._call("llm_cluster_request", "llm_cluster_response",
dict(opts, model=model, messages=messages), timeout)
if not res["ok"]:
raise RuntimeError(f"{res.get('errorCode')}: {res.get('error')}")
return res
async def main():
async with websockets.connect(RVS, max_size=2**24) as ws:
available = await models(ws)
for iid, node, model, gpu in available:
print(f"{node} / Karte {gpu}: {model} ({iid})")
if available:
iid, node, model, gpu = available[0]
print(await ask(ws, iid, model, "Sag Hallo in einem Satz."))
cluster = AriaCluster(ws)
models = await cluster.models()
for m in models:
print(f"{m['model']} (Kontext {m['ctx']}, auf {m['available']} Karte(n))")
if models:
res = await cluster.chat(models[0]["model"],
[{"role": "user", "content": "Sag Hallo in einem Satz."}],
max_tokens=64)
print(res["content"], f"— von {res['node']} / Karte {res['gpu']}")
asyncio.run(main())
```
### Umstellen von der direkten Box-Ansprache
Wer schon gegen Abschnitt C gebaut hat (`llm_models_request` /
`llm_request` mit `targetInstance`), stellt so um:
1. **Modelliste:** `llm_cluster_models_request` statt `llm_models_request`.
Statt einer Antwort pro Box kommt **eine** Antwort mit jedem Modell
einmal. Kein Einsammeln über Sekunden mehr.
2. **Auswahl:** Dem Nutzer nur den **Modellnamen** zeigen — nicht mehr
„Modell · Karte · Box". Wo es läuft, entscheidet der Cluster.
3. **Kontextfenster:** `ctx` aus der Liste übernehmen statt einen eigenen Wert
einzustellen. Die Box gibt nur so viel her, wie dort steht — rechnet ein
Programm mit mehr, scheitern lange Aufträge oder werden falsch gekürzt.
4. **Anfrage:** `llm_cluster_request` statt `llm_request`; **kein**
`targetInstance` mehr. Die Antwort kommt als `llm_cluster_response`.
5. **Fehler:** `ok: false` als Fehler anzeigen, nicht als Antwort in den
Verlauf. Neue Codes siehe Tabelle oben.
6. **Lesen:** ein Leser pro Verbindung, Antworten per `requestId` zuordnen.
Felder und Format von `messages`, `tools`, `tool_calls` und `usage` bleiben
gleich.
---
## B) Über den OpenAI-Port einer Box
## B) OpenAI-RVS-Wrapper — für Programme, die nur OpenAI können
Jede KI-Box bietet einen OpenAI-kompatiblen Endpunkt — für Programme, die nur
„OpenAI-kompatibel" können (OpenHands, Continue, Open WebUI …).
Ein kleiner Container, der **auf demselben Rechner** wie das Programm läuft.
Für das Programm ist der Cluster dann ein ganz normaler OpenAI-Endpunkt:
```
http://<IP der Box>:<LLM_OPENAI_PORT>/v1 (Standard-Port 8081)
Programm ──HTTP──▶ Wrapper (127.0.0.1:8099) ──RVS──▶ ARIA-Bridge ──▶ KI-Box / Karte
```
- `GET /v1/models` listet **nur die geladenen** Modelle dieser Box.
- `POST /v1/chat/completions` mit `"model": "<Name>"` wie gewohnt.
- Ein nicht geladenes Modell wird mit **HTTP 404** abgelehnt
(`"no router for requested model"`) — es wird nichts nachgeladen.
- Ist in der Diagnostic ein API-Key gesetzt, mit
`Authorization: Bearer <KEY>` schicken.
- Standardmäßig hört der Port nur auf `localhost` der Box. Für Zugriff aus dem
Netz `LLM_OPENAI_BIND=0.0.0.0` in der `.env` der Box setzen — dann
**unbedingt** einen API-Key vergeben.
- Dieser Zugang sieht nur seine eigene Box. Wer mehrere Boxen nutzen will,
nimmt den RVS.
Liegt im Repo unter [`xtts/openai_rvs_wrapper/`](../xtts/openai_rvs_wrapper/):
```bash
curl http://192.168.177.153:8081/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model": "qwen3-8b", "messages": [{"role": "user", "content": "Hallo"}]}'
cd xtts/openai_rvs_wrapper
cp .env.example .env # RVS_HOST, RVS_PORT, RVS_TOKEN eintragen
docker compose up -d --build
```
Im Browser zeigt **http://127.0.0.1:8099/** eine Hilfsseite: ob die Verbindung
steht und welche Modelle es gibt. Im Programm eintragen:
| Feld | Wert |
|---|---|
| Base URL | `http://127.0.0.1:8099/v1` |
| API-Key | beliebig — oder `WRAPPER_API_KEY`, falls gesetzt |
| Modell | ein Name von der Hilfsseite |
| Kontextfenster | der Wert von der Hilfsseite |
- `GET /v1/models` — jedes Modell einmal, mit `context_length`
- `POST /v1/chat/completions` — auch `stream: true` (kommt derzeit in einem
Rutsch) und `tools`
- Fehler als HTTP-Fehler mit OpenAI-Fehlerobjekt: nicht geladenes Modell →
404 `model_not_found`, Cluster nicht erreichbar → 503, Zeitüberschreitung → 504
- Antwort-Header `X-Aria-Node` / `X-Aria-Gpu` sagen, wer geantwortet hat
- **Läuft das Programm selbst in Docker**, ist `127.0.0.1` dort der eigene
Container. Dann das Docker-Netz `aria-llm` anhängen und
`http://openai-rvs-wrapper:8099/v1` nehmen (Details in der README des Wrappers).
Mit dem offiziellen OpenAI-Python-SDK getestet (`models.list`,
`chat.completions.create` mit und ohne Stream, Fehlerklassen).
---
## C) Direkt an eine Box — Sonderfall
Ohne den Cluster, eine bestimmte Box gezielt. Keine Verteilung, kein
Ausfall-Ersatz. Nur nötig, wenn ein Programm bewusst eine bestimmte Box will
oder ARIA nicht läuft.
**Modelle der Boxen:** `llm_models_request` `{requestId}` → **jede** Box
antwortet einzeln mit `llm_models` `{requestId, instanceId, node, models:
[{model, gpu, gpuName, ctx, state}]}`. Ein paar Sekunden einsammeln.
**Anfrage:** `llm_request` `{requestId, targetInstance, model, messages, …}`
→ `llm_response` `{requestId, ok, content, tool_calls, model, instanceId,
node, gpu, usage, elapsedMs}`. Bei Fehler `errorCode`:
`model_not_loaded` (mit `loadedModels`) oder `no_model_loaded`.
Ohne `targetInstance` antworten nur Boxen, die das Modell geladen haben — die
anderen schweigen. Hat keine es, kommt **keine** Antwort. Darum hier immer
`targetInstance` setzen.
**OpenAI-Port einer Box:** Jede Box hat zusätzlich einen eigenen
OpenAI-Endpunkt (`http://<IP der Box>:8081/v1`, Standard nur `localhost` der
Box). Er sieht nur diese Box; nicht geladene Modelle → HTTP 404. Für mehrere
Boxen den Wrapper (B) nehmen.
---
## Was Programme nicht senden
`llm_provision_model`, `llm_unload_model` und `llm_remove_model` sind der
ARIA-Diagnostic vorbehalten. Technisch könnte jeder im Raum sie senden — der
RVS unterscheidet die Teilnehmer nicht. Ein Programm, das sich nicht daran
hält, tauscht anderen das Modell unter den Füßen weg.
## Gleichzeitige Nutzung und Geschwindigkeit
- Mehrere Clients können **dasselbe Modell gleichzeitig** nutzen. llama.cpp
bedient sie parallel (Continuous Batching); jede Antwort wird etwas
langsamer, insgesamt schafft die Karte mehr.
- Der Kontext (`-c`, Standard 8192 Tokens) ist bei aktuellen llama.cpp-Versionen
ein **gemeinsamer Vorrat** aller gleichzeitigen Anfragen. Schicken mehrere
Clients gleichzeitig sehr lange Verläufe, wird es dort eng.
- Ältere llama.cpp-Versionen arbeiten Anfragen an dasselbe Modell nacheinander
ab statt parallel. Welche Version eine Box fährt, hängt am Image von
llama-swap (`docker compose pull llama-swap` holt die aktuelle).
- Mehrere Anfragen an dasselbe Modell laufen auf einer Karte **parallel**.
Jede einzelne wird etwas langsamer, in Summe schafft die Karte mehr.
- Liegt ein Modell auf mehreren Karten, schickt der Cluster neue Anfragen an
die Karte mit den wenigsten laufenden.
- Der Kontext (`ctx`) ist bei aktuellen llama.cpp-Versionen ein **gemeinsamer
Vorrat** aller gleichzeitigen Anfragen auf einer Karte. Schicken mehrere
Programme gleichzeitig sehr lange Verläufe, wird es dort eng.
## Wenn sich etwas ändert
- Lädt der Betreiber ein anderes Modell in eine Karte, ist das alte sofort
weg; laufende Clients bekommen dann `model_not_loaded` und sollten die Liste
neu holen.
- Beim Laden oder Entladen startet die Box **alle** ihre Modelle kurz neu
(wenige Sekunden). Anfragen in diesem Moment warten, bis das Modell wieder
bereit ist (`state: "starting"`).
- Lädt der Betreiber ein anderes Modell in eine Karte, ist das alte dort weg.
Liegt es noch auf einer anderen Karte, merkt ein Programm nichts; sonst kommt
`model_unavailable` — dann die Liste neu holen.
- Beim Laden oder Entladen startet die betroffene Box **alle** ihre Modelle
kurz neu (wenige Sekunden). Anfragen in diesem Moment warten oder gehen an
eine andere Box.
- Diese Schnittstelle wird erweitert, nicht umgebaut: Neue Felder können
dazukommen. Ein Client sollte unbekannte Felder ignorieren.
dazukommen. Unbekannte Felder ignorieren.