LLMs locais (Ollama, LM Studio)

O endpoint de geração com IA aceita um provider: "local" especial que aponta o motor para qualquer servidor de chat completions compatível com a OpenAI que você mesmo hospede. O servidor continua fazendo todo o trabalho pesado (renderização do QR, validação ISO 18004, garantia de leitura) — só o modelo de linguagem que propõe o design fica na sua máquina.

Quando usar

Stacks com foco em privacidade. Os prompts nunca saem da sua rede a caminho do LLM. A Signet API só vê a configuração JSON resultante, não a descrição em linguagem natural que você digitou.
Controle de custos. Você já roda Ollama / LM Studio para outras cargas de trabalho e quer reaproveitar o modelo que já pagou / baixou.
Modelos ajustados. Você fez fine-tuning de um modelo aberto pequeno com prompts de design de QR e quer apontar a Signet para ele.

Não é uma boa opção para:

Chamadores SaaS que tentam acessar localhost no servidor da API — a Signet API roda no Azure Functions e não consegue acessar o seu notebook diretamente. Você precisa de um túnel público (veja abaixo).
Nuvens de Ollama hospedadas que você não controla — nesses casos, use o provedor nativo correspondente (openai, groq etc.).

Configuração

1. Inicie o seu servidor local

Ollama:

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

O Ollama expõe, por padrão, uma API compatível com a OpenAI em http://localhost:11434/v1/chat/completions.

LM Studio:

Carregue um modelo na interface gráfica, abra a aba "Local Server" e clique em "Start Server". O endpoint padrão é http://localhost:1234/v1.

Servidor vLLM / llama.cpp: os dois expõem /v1/chat/completions nativamente. Use o host / a porta em que você os iniciou.

2. Torne o seu servidor acessível publicamente

O Azure Functions não consegue acessar localhost na sua máquina, então você precisa de um túnel. Duas opções sem configuração:

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

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

Use a URL HTTPS pública resultante como localEndpoint. A API rejeita IPs RFC1918 / link-local (10.x, 172.16-31.x, 192.168.x, 169.254.x) para evitar SSRF — só são aceitos endereços públicos ou localhost (para o desenvolvimento local da própria API).

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

Observações:

apiKey é exigido pelo validador do campo, mas o valor é irrelevante para a maioria dos servidores locais. O Ollama aceita qualquer texto não vazio; por convenção, passe "ollama". O LM Studio também o ignora, a menos que você tenha configurado explicitamente uma chave de API.
model é obrigatório no modo local — não há padrão no servidor. Passe exatamente o nome do modelo que o seu servidor expõe (llama3.3, qwen2.5:14b, mistral etc.).
localEndpoint pode ser a URL base (https://host/v1) ou o caminho completo (https://host/v1/chat/completions) — a API normaliza os dois.
O modo JSON (response_format: { type: "json_object" }) não é repassado aos servidores locais. Alguns runtimes não o suportam e dariam erro. O prompt de sistema é rigoroso o bastante para que modelos obedientes ainda devolvam JSON limpo. Se o seu modelo envolver o JSON em texto, reduza creativity para perto de 0.0 ou escolha um modelo mais ajustado para seguir instruções.

Modos de falha

Sintoma	Causa	Solução
400 `localEndpoint must be a publicly reachable address`	Você passou um IP `10.x` / `192.168.x` / `127.0.0.1` a partir da internet pública	Use um túnel (ngrok, Cloudflare Tunnel) e passe a URL pública
400 `For provider='local' the 'llmModel' field is required`	Você esqueceu `model`	Defina `model` com o modelo que o seu servidor local expõe
500 `AI generated an invalid configuration`	O modelo local devolveu JSON malformado	Teste um modelo mais forte (≥ 7B parâmetros) ou reduza `creativity`
`502 / connection refused` do serviço de IA	Túnel fora do ar / servidor parado	Reinicie `ollama serve` e execute `cloudflared tunnel` de novo

Notas de segurança

A Signet API nunca registra em log o conteúdo de localEndpoint nem de apiKey. Ela registra o nome do provedor (local) e o identificador do modelo para a telemetria de faturamento.
Trate a URL do seu túnel como um segredo do mesmo nível de uma chave de API — quem a tiver pode chamar o seu modelo local no seu hardware.
Em stacks de produção em que a garantia de privacidade importa, prefira o Cloudflare Tunnel ao ngrok: as URLs do ngrok são adivinháveis e o plano gratuito não tem autenticação.