Lokale LLMs (Ollama, LM Studio)

Der KI-Generierungsendpunkt unterstützt einen speziellen provider: "local", der die Engine auf einen beliebigen OpenAI-kompatiblen Chat-Completions-Server lenkt, den du selbst hostest. Die eigentliche Arbeit (QR-Rendering, Prüfung nach ISO 18004, Scan-Garantie) erledigt weiterhin der Server – nur das Sprachmodell, das das Design vorschlägt, läuft auf deiner Maschine.

Wann sich das lohnt

• Datenschutz zuerst. Prompts verlassen auf dem Weg zum LLM nie dein Netzwerk. Die Signet API sieht immer nur die resultierende JSON-Konfiguration, nicht die Beschreibung in natürlicher Sprache, die du eingegeben hast.
• Kostenkontrolle. Du betreibst Ollama / LM Studio schon für andere Aufgaben und willst das Modell wiederverwenden, das du bezahlt oder heruntergeladen hast.
• Eigens angepasste Modelle. Du hast ein kleines offenes Modell auf QR-Design-Prompts feinabgestimmt und willst Signet darauf zeigen lassen.

Nicht geeignet für:

• SaaS-Aufrufer, die vom API-Server aus localhost erreichen wollen – die Signet API läuft auf Azure Functions und kann deinen Laptop nicht direkt erreichen. Du brauchst einen öffentlichen Tunnel (siehe unten).
• Gehostete Ollama-Clouds, die du nicht kontrollierst – nutze dafür stattdessen den passenden nativen Anbieter (openai, groq usw.).

Einrichtung

1. Lokalen Server starten

Ollama:

ollama serve
# in another shell, pull a model
ollama pull llama3.3

Ollama stellt ab Werk eine OpenAI-kompatible API unter http://localhost:11434/v1/chat/completions bereit.

LM Studio:

Lade ein Modell in der Oberfläche, öffne den Tab „Local Server“ und klicke auf „Start Server“. Der Standard-Endpunkt ist http://localhost:1234/v1.

vLLM- / llama.cpp-Server: Beide stellen /v1/chat/completions nativ bereit. Nutze den Host / Port, mit dem du sie gestartet hast.

2. Server öffentlich erreichbar machen

Azure Functions kann localhost auf deiner Maschine nicht erreichen, also brauchst du einen Tunnel. Zwei Optionen ohne Konfiguration:

# ngrok
ngrok http 11434
# → https://your-tunnel.ngrok.io

# Cloudflare Tunnel
cloudflared tunnel --url http://localhost:11434
# → https://random-words.trycloudflare.com

Nutze die resultierende öffentliche HTTPS-URL als localEndpoint. Die API lehnt RFC1918- / Link-Local-IPs (10.x, 172.16-31.x, 192.168.x, 169.254.x) ab, um SSRF zu verhindern – akzeptiert werden nur öffentliche Adressen oder localhost (für die lokale Entwicklung der API selbst).

3. API aufrufen

curl -X POST https://signetqr-core.azurewebsites.net/api/qr/ai/generate \
  -H "Content-Type: application/json" \
  -H "X-RapidAPI-Proxy-Secret: $RAPIDAPI_PROXY_SECRET" \
  -d '{
    "provider": "local",
    "localEndpoint": "https://your-tunnel.ngrok.io/v1",
    "model": "llama3.3",
    "apiKey": "ollama",
    "prompt": "Tech startup QR, neon cyan and magenta on near-black, hexagonal modules with subtle glow",
    "content": "https://example.com"
  }'

Hinweise:

• apiKey verlangt der Feldvalidator zwar, aber sein Wert ist für die meisten lokalen Server egal. Ollama akzeptiert jeden nicht leeren String; per Konvention übergibst du "ollama". Auch LM Studio ignoriert ihn, solange du nicht ausdrücklich einen API-Schlüssel konfiguriert hast.
• model ist bei local Pflicht – es gibt keinen serverseitigen Standard. Übergib genau den Modellnamen, den dein Server bereitstellt (llama3.3, qwen2.5:14b, mistral usw.).
• localEndpoint kann die Basis-URL (https://host/v1) oder der vollständige Pfad (https://host/v1/chat/completions) sein – die API normalisiert beides.
• Der JSON-Modus (response_format: { type: "json_object" }) wird nicht an lokale Server weitergegeben. Manche Runtimes unterstützen ihn nicht und würden einen Fehler werfen. Der System-Prompt ist streng genug, dass konforme Modelle trotzdem sauberes JSON liefern. Wenn dein Modell das JSON in Fließtext verpackt, senk creativity Richtung 0.0 oder wähle ein stärker auf Anweisungen trainiertes Modell.

Fehlerbilder

Sicherheitshinweise

• Die Signet API protokolliert nie den Inhalt von localEndpoint oder apiKey. Protokolliert werden der Anbietername (local) und die Modellkennung für die Abrechnungstelemetrie.
• Behandle deine Tunnel-URL als Geheimnis auf derselben Stufe wie einen API-Schlüssel – wer sie hat, kann dein lokales Modell auf deiner Hardware aufrufen.
• Für Produktivumgebungen, in denen die Datenschutzgarantie zählt, nimm lieber Cloudflare Tunnel als ngrok: ngrok-URLs sind erratbar, und die Gratisstufe hat keine Authentifizierung.