[haski] Cluster

API-Dokumentation

OpenAI-kompatible REST-API für verteilte LLM-Inferenz

Basis-URLs

Zugriff	URL	Auth
Intern (LAN)	`http://192.168.206.3:8080/v1`	Keine
Extern	`https://llm.stwhas.de/v1`	Bearer Token
Extern (alt)	`https://llm.rzhas.de/v1`	Bearer Token

Authentifizierung

Externer Zugriff erfordert einen Bearer-Token im Authorization-Header:

Authorization: Bearer YOUR_API_KEY

Interner LAN-Zugriff (192.168.206.x) benötigt keine Authentifizierung.

Chat

Web-basierte Chat-Oberfläche mit Streaming, Token-Statistiken und Einstellungen.

Direkt im Browser verfügbar unter /chat (Passwort-geschützt).

LLM-Endpunkte

GET /v1/models

Verfügbare Modelle auflisten.

curl https://llm.stwhas.de/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /v1/chat/completions

Chat-Completion erstellen. Unterstützt Streaming.

curl https://llm.stwhas.de/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mlx-community/MiniMax-M2.5-4bit",
    "messages": [
      {"role": "system", "content": "Du bist ein hilfreicher Assistent."},
      {"role": "user", "content": "Was ist MLX?"}
    ],
    "max_tokens": 512,
    "temperature": 0.7,
    "stream": true
  }'

Das Feld model ist erforderlich. Verwenden Sie den vollständigen Modellnamen oder fragen Sie zuerst GET /v1/models ab, um die exakte ID des geladenen Modells zu erhalten.

POST /v1/completions

Text-Completion erstellen (kein Chat).

curl https://llm.stwhas.de/v1/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mlx-community/MiniMax-M2.5-4bit",
    "prompt": "The capital of Germany is",
    "max_tokens": 64
  }'

Anfrage-Parameter

Parameter	Typ	Standard	Beschreibung
`model`	string	erforderlich	Modellname (Wert von `GET /v1/models` verwenden)
`messages`	array	erforderlich	Chat-Nachrichten (für /chat/completions)
`prompt`	string	erforderlich	Prompt-Text (für /completions)
`max_tokens`	int	4096	Maximale Tokens zur Generierung
`temperature`	float	0.7	Sampling-Temperatur (0.0 = deterministisch)
`top_p`	float	1.0	Nucleus-Sampling-Schwellwert
`stream`	bool	false	Antwort als SSE streamen
`stop`	string/array	null	Stopp-Sequenz(en)
`repetition_penalty`	float	1.0	Wiederholte Tokens bestrafen

Python-Beispiel (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    base_url="https://llm.stwhas.de/v1",
    api_key="YOUR_API_KEY",
)

response = client.chat.completions.create(
    model="mlx-community/MiniMax-M2.5-4bit",
    messages=[{"role": "user", "content": "Hallo!"}],
    max_tokens=256,
)
print(response.choices[0].message.content)

Audio-Transkription (Whisper)

Speech-to-Text mit Silero-VAD + MLX-Whisper + pyannote Speaker Diarization auf HASKI-5. Pipeline: Audio-Preprocessing (16kHz Mono) → VAD-Segmentierung → Whisper-Transkription → Sprechererkennung.

POST /v1/audio/transcriptions

Audiodatei transkribieren mit optionaler Sprechererkennung. Akzeptiert multipart/form-data.

curl https://llm.stwhas.de/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F file=@audio.mp3 \
  -F diarize=true

Optionale Parameter: language (Default: de), diarize (true/false, Default: true), prompt (zusätzlicher Kontext für Whisper).

Antwort:

{
  "text": "Vollständiger Text...",
  "timestamped_text": "[0.0-5.2] [Sprecher A] Erster Punkt...
[5.2-12.1] [Sprecher B] Ja, stimme zu...",
  "segments": [{"start": 0.0, "end": 5.2, "text": "...", "speaker": "Sprecher A"}, ...],
  "diarized": true
}

GET /v1/audio/health

Whisper-Service-Status prüfen (keine Auth erforderlich). Zeigt auch ob Diarization verfügbar ist.

Dateitransfer & Verarbeitung

Dateien hochladen, transkribieren, bereinigen und zusammenfassen. Audio-Uploads starten automatisch die Pipeline: Transkription → Bereinigung.

Web-UI verfügbar unter /transfer (Passwort-geschützt). SFTP-Zugriff: sftp haski@192.168.206.2 → ~/transfer/

Transfer-Endpunkte unterstützen zwei Auth-Methoden:

# Web-UI (Passwort)
X-Haski-Token: YOUR_PASSWORD

# API (Bearer Token — gleicher Token wie LLM/Whisper API)
Authorization: Bearer YOUR_API_KEY

Web-Endpunkte (Sitzungsbasiert)

POST /transfer/api/upload

Datei hochladen (multipart/form-data, max 500 MB).

curl https://llm.stwhas.de/transfer/api/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F file=@recording.mp3

GET /transfer/api/files

Alle hochgeladenen Dateien auflisten (mit Dateityp-Flags: is_audio, is_text, is_refined, is_summary).

GET /transfer/api/files/{name}

Datei herunterladen.

DELETE /transfer/api/files/{name}

Datei löschen.

POST /transfer/api/transcribe/{name}

Audiodatei mit Whisper transkribieren (inkl. Sprechererkennung). Streamt Fortschritt via SSE (event: progress, event: done). Ergebnis wird als .txt mit Sprecher-Labels gespeichert.

POST /transfer/api/refine/{name}

Roh-Transkript mit Qwen2.5-32B bereinigen (Grammatik, Füllwörter, Formatierung). Streamt via SSE. Ergebnis wird als *_bereinigt.txt gespeichert.

POST /transfer/api/summarize/{name}?pattern=...

Textdatei mit KI-Pattern zusammenfassen. Patterns via GET /transfer/api/patterns abrufen. Spezial-Patterns: _free (freie Zusammenfassung), _custom (eigener Prompt im Body).

GET /transfer/api/patterns

Verfügbare Zusammenfassungs-Patterns auflisten.

POST /transfer/api/cleanup

Alle Textdateien der aktuellen Sitzung löschen.

GET /transfer/api/activity

Laufende Operationen abfragen (keine Auth erforderlich). Wird vom Dashboard für den Busy-Indikator genutzt.

Jobs API (Isolierte Verarbeitung)

Job-basierte API für automatisierte Workflows. Jeder Job erhält ein eigenes Verzeichnis — keine Vermischung mit anderen Sitzungen. Jobs werden nach 24h automatisch gelöscht. Erfordert Bearer-Token-Authentifizierung.

POST /transfer/api/jobs

Neuen Job erstellen. Gibt eine job_id zurück.

curl -X POST https://llm.stwhas.de/transfer/api/jobs \
  -H "Authorization: Bearer YOUR_API_KEY"
# → {"ok": true, "job_id": "20260315_143022_a1b2c3d4"}

POST /transfer/api/jobs/{id}/upload

Datei in den Job hochladen (multipart/form-data).

POST /transfer/api/jobs/{id}/transcribe/{name}

Audiodatei im Job transkribieren. Synchrone Antwort (kein SSE). Ergebnis wird als .txt im Job gespeichert.

POST /transfer/api/jobs/{id}/refine/{name}

Transkript im Job bereinigen. Synchrone Antwort. Ergebnis als *_bereinigt.txt im Job.

POST /transfer/api/jobs/{id}/summarize/{name}?pattern=...

Textdatei im Job zusammenfassen. Gleiche Pattern-Optionen wie Web-API.

GET /transfer/api/jobs

Alle aktiven Jobs auflisten (mit Dateizähler und Dateinamen).

GET /transfer/api/jobs/{id}/files

Dateien eines Jobs auflisten.

GET /transfer/api/jobs/{id}/files/{name}

Datei aus einem Job herunterladen.

DELETE /transfer/api/jobs/{id}

Job und alle zugehörigen Dateien löschen.

Typischer Workflow: Job erstellen → Audio hochladen → Transkribieren → Bereinigen → Zusammenfassen → Ergebnisse herunterladen → Job löschen.

Cluster-Status

GET /api/status

Cluster-Status abrufen (Nodes, API, Modell, Netzwerk). Wird vom Dashboard genutzt.

curl https://llm.stwhas.de/api/status

Verfügbare Modelle

Modell	Parameter	Läuft auf	~Geschwindigkeit
MiniMax-M2.5-4bit	230B	HASKI-1–4 (JACCL-Ring)	~31 tok/s
Qwen2.5-32B-Instruct-4bit	32B	HASKI-5 (on-demand)	~40 tok/s
Whisper large-v3 (VAD+MLX+Diarization)	1.5B	HASKI-5	Echtzeit

MiniMax ist das primäre Chat-Modell auf dem 4-Node-Cluster. Qwen2.5 wird automatisch für Transkript-Bereinigung gestartet/gestoppt (teilt sich RAM mit Whisper auf HASKI-5). Whisper läuft dauerhaft als Hintergrundservice.