LLM locaux (Ollama, LM Studio)

L'endpoint de génération IA prend en charge un fournisseur spécial, provider: "local", qui dirige le moteur vers n'importe quel serveur de chat-completions compatible OpenAI que vous hébergez vous-même. Le serveur continue de faire tout le gros du travail (rendu du QR, validation ISO 18004, garantie de scan) : seul le modèle de langage qui propose le design tourne sur votre machine.

Quand l'utiliser

• Architectures axées sur la confidentialité. Vos prompts ne quittent jamais votre réseau pour atteindre le LLM. L'API Signet ne voit que la configuration JSON obtenue, jamais la description en langage naturel que vous avez saisie.
• Maîtrise des coûts. Vous faites déjà tourner Ollama / LM Studio pour d'autres usages et voulez réutiliser le modèle que vous avez payé ou téléchargé.
• Modèles ajustés sur mesure. Vous avez affiné un petit modèle ouvert sur des prompts de design de QR et voulez y connecter Signet.

Ne convient pas pour :

• Les appelants SaaS qui essaient d'atteindre localhost sur le serveur de l'API : l'API Signet tourne sur Azure Functions et ne peut pas joindre directement votre ordinateur portable. Il vous faut un tunnel public (voir ci-dessous).
• Les offres cloud d'Ollama hébergées que vous ne contrôlez pas : pour celles-ci, utilisez plutôt le fournisseur natif correspondant (openai, groq, etc.).

Configuration

1. Démarrez votre serveur local

Ollama :

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

Ollama expose d'emblée une API compatible OpenAI à l'adresse http://localhost:11434/v1/chat/completions.

LM Studio :

Chargez un modèle dans l'interface, ouvrez l'onglet « Local Server » et cliquez sur « Start Server ». L'endpoint par défaut est http://localhost:1234/v1.

Serveur vLLM / llama.cpp : les deux exposent /v1/chat/completions nativement. Utilisez l'hôte et le port sur lesquels vous les avez lancés.

2. Rendez votre serveur accessible publiquement

Azure Functions ne peut pas joindre localhost sur votre machine : il vous faut donc un tunnel. Deux options sans configuration :

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

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

Utilisez l'URL HTTPS publique obtenue comme localEndpoint. L'API refuse les IP RFC1918 / link-local (10.x, 172.16-31.x, 192.168.x, 169.254.x) pour éviter les attaques SSRF : seules les adresses publiques ou localhost (pour le développement local de l'API elle-même) sont acceptées.

3. Appelez 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"
  }'

Remarques :

• apiKey est exigé par le validateur de champs, mais sa valeur n'a pas d'importance pour la plupart des serveurs locaux. Ollama accepte n'importe quelle chaîne non vide ; par convention, passez "ollama". LM Studio l'ignore aussi, sauf si vous avez explicitement configuré une clé API.
• model est obligatoire en local : il n'y a pas de valeur par défaut côté serveur. Passez exactement le nom de modèle exposé par votre serveur (llama3.3, qwen2.5:14b, mistral, etc.).
• localEndpoint peut être l'URL de base (https://host/v1) ou le chemin complet (https://host/v1/chat/completions) : l'API normalise les deux.
• Le mode JSON (response_format: { type: "json_object" }) n'est pas transmis aux serveurs locaux. Certains environnements d'exécution ne le prennent pas en charge et renverraient une erreur. Le prompt système est suffisamment strict pour que les modèles disciplinés renvoient quand même un JSON propre. Si votre modèle entoure le JSON de texte, rapprochez creativity de 0.0 ou choisissez un modèle mieux ajusté au suivi d'instructions.

Pannes possibles

Remarques de sécurité

• L'API Signet ne journalise jamais le contenu de localEndpoint ni de apiKey. Elle journalise en revanche le nom du fournisseur (local) et l'identifiant du modèle pour la télémétrie de facturation.
• Traitez l'URL de votre tunnel comme un secret, au même titre qu'une clé API : quiconque la connaît peut appeler votre modèle local sur votre matériel.
• Pour les architectures de production où la garantie de confidentialité compte, préférez Cloudflare Tunnel à ngrok : les URL ngrok sont devinables et l'offre gratuite n'a pas d'authentification.