LLM locali (Ollama, LM Studio)

L'endpoint di generazione IA supporta uno speciale provider: "local" che indirizza il motore verso qualsiasi server di chat completions compatibile con OpenAI ospitato da te. Il server continua a fare tutto il lavoro pesante (rendering del QR, convalida ISO 18004, garanzia di scansione): solo il modello linguistico che propone il design vive sulla tua macchina.

Quando usarlo

• Stack orientati alla privacy. I prompt non escono mai dalla tua rete nel tragitto verso l'LLM. L'API Signet vede soltanto la configurazione JSON risultante, non la descrizione in linguaggio naturale che hai scritto.
• Controllo dei costi. Usi già Ollama / LM Studio per altri carichi di lavoro e vuoi riutilizzare il modello che hai pagato / scaricato.
• Modelli personalizzati. Hai fatto il fine-tuning di un piccolo modello open su prompt di design di QR e vuoi collegarlo a Signet.

Non è adatto per:

• Chiamanti SaaS che cercano di raggiungere localhost sul server dell'API: l'API Signet gira su Azure Functions e non può raggiungere direttamente il tuo portatile. Ti serve un tunnel pubblico (vedi sotto).
• Cloud Ollama ospitati che non controlli: in quei casi usa il provider nativo corrispondente (openai, groq, ecc.).

Configurazione

1. Avvia il tuo server locale

Ollama:

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

Ollama espone di serie un'API compatibile con OpenAI su http://localhost:11434/v1/chat/completions.

LM Studio:

Carica un modello nell'interfaccia grafica, apri la scheda "Local Server" e fai clic su "Start Server". L'endpoint predefinito è http://localhost:1234/v1.

Server vLLM / llama.cpp: entrambi espongono /v1/chat/completions in modo nativo. Usa l'host / la porta con cui li hai avviati.

2. Rendi il tuo server raggiungibile pubblicamente

Azure Functions non può raggiungere localhost sulla tua macchina, quindi ti serve un tunnel. Due opzioni senza configurazione:

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

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

Usa l'URL HTTPS pubblico risultante come localEndpoint. L'API rifiuta gli IP RFC1918 / link-local (10.x, 172.16-31.x, 192.168.x, 169.254.x) per evitare attacchi SSRF: sono accettati solo indirizzi pubblici o localhost (per lo sviluppo locale dell'API stessa).

3. Chiama l'API

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"
  }'

Note:

• apiKey è richiesto dal validatore del campo, ma per la maggior parte dei server locali il suo valore è irrilevante. Ollama accetta qualsiasi stringa non vuota; per convenzione passa "ollama". Anche LM Studio lo ignora, a meno che tu non abbia configurato esplicitamente una chiave API.
• model è obbligatorio con local: non esiste un valore predefinito lato server. Passa esattamente il nome del modello esposto dal tuo server (llama3.3, qwen2.5:14b, mistral, ecc.).
• localEndpoint può essere l'URL di base (https://host/v1) o il percorso completo (https://host/v1/chat/completions): l'API normalizza entrambi.
• La modalità JSON (response_format: { type: "json_object" }) non viene inoltrata ai server locali. Alcuni runtime non la supportano e darebbero errore. Il prompt di sistema è abbastanza rigoroso perché i modelli conformi restituiscano comunque un JSON pulito. Se il tuo modello avvolge il JSON in testo discorsivo, abbassa creativity verso 0.0 o scegli un modello più addestrato a seguire le istruzioni.

Possibili errori

Note di sicurezza

• L'API Signet non registra mai nei log il contenuto di localEndpoint o apiKey. Registra invece il nome del provider (local) e l'identificatore del modello per la telemetria di fatturazione.
• Tratta l'URL del tuo tunnel come un segreto, allo stesso livello di una chiave API: chiunque lo conosca può chiamare il tuo modello locale sul tuo hardware.
• Per gli stack di produzione in cui la garanzia di privacy conta, preferisci Cloudflare Tunnel a ngrok: gli URL di ngrok sono indovinabili e il piano gratuito non ha autenticazione.