Локальні LLM (Ollama, LM Studio)

Ендпоінт генерації ШІ підтримує спеціальний provider: "local", який спрямовує рушій на будь-який OpenAI-сумісний сервер chat-completions, розгорнутий вами. Уся важка робота (рендеринг QR, перевірка ISO 18004, гарантія сканування) і далі виконується на сервері — на вашій машині працює лише мовна модель, яка пропонує дизайн.

Коли це варто використовувати

Стеки з пріоритетом приватності. Промпти не залишають вашу мережу на шляху до LLM. Signet API бачить лише отриману конфігурацію JSON, а не введений вами опис природною мовою.
Контроль витрат. Ви вже запускаєте Ollama / LM Studio для інших завдань і хочете повторно використати модель, за яку заплатили / яку завантажили.
Моделі з власним донавчанням. Ви донавчили невелику відкриту модель на промптах для дизайну QR і хочете спрямувати Signet на неї.

Не підходить для:

SaaS-клієнтів, які намагаються звернутися до localhost на сервері API — Signet API працює на Azure Functions і не може напряму дістатися до вашого ноутбука. Потрібен публічний тунель (див. нижче).
Хмарних сервісів Ollama, які ви не контролюєте — для них використовуйте відповідного нативного провайдера (openai, groq тощо).

Налаштування

1. Запустіть локальний сервер

Ollama:

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

Ollama одразу після встановлення надає OpenAI-сумісний API за адресою http://localhost:11434/v1/chat/completions.

LM Studio:

Завантажте модель у графічному інтерфейсі, відкрийте вкладку «Local Server» і натисніть «Start Server». Ендпоінт за замовчуванням — http://localhost:1234/v1.

Сервер vLLM / llama.cpp: обидва нативно надають /v1/chat/completions. Використовуйте хост / порт, на якому ви їх запустили.

2. Зробіть сервер доступним із публічної мережі

Azure Functions не може дістатися до localhost на вашій машині, тому потрібен тунель. Два варіанти без налаштувань:

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

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

Використайте отриманий публічний HTTPS URL як localEndpoint. Щоб запобігти SSRF, API відхиляє IP-адреси RFC1918 / link-local (10.x, 172.16-31.x, 192.168.x, 169.254.x) — приймаються лише публічні адреси або localhost (для локальної розробки самого API).

3. Викличте 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"
  }'

Примітки:

apiKey вимагає валідатор полів, але для більшості локальних серверів його значення не має значення. Ollama приймає будь-який непорожній рядок; за домовленістю передавайте "ollama". LM Studio теж його ігнорує, якщо ви явно не налаштували ключ API.
Для local параметр model обов’язковий — серверного значення за замовчуванням немає. Передавайте точно ту назву моделі, яку надає ваш сервер (llama3.3, qwen2.5:14b, mistral тощо).
localEndpoint може бути як базовим URL (https://host/v1), так і повним шляхом (https://host/v1/chat/completions) — API нормалізує обидва варіанти.
Режим JSON (response_format: { type: "json_object" }) не пересилається локальним серверам. Деякі середовища виконання його не підтримують і видали б помилку. Системний промпт достатньо суворий, тож моделі, що дотримуються інструкцій, усе одно повертають чистий JSON. Якщо ваша модель обгортає JSON текстом, знизьте creativity ближче до 0.0 або виберіть модель, краще навчену виконувати інструкції.

Типові збої

Симптом	Причина	Як виправити
400 `localEndpoint must be a publicly reachable address`	Ви передали IP `10.x` / `192.168.x` / `127.0.0.1` з публічного інтернету	Використайте тунель (ngrok, Cloudflare Tunnel) і передайте публічний URL
400 `For provider='local' the 'llmModel' field is required`	Ви забули `model`	Задайте в `model` назву моделі, яку надає ваш локальний сервер
500 `AI generated an invalid configuration`	Локальна модель повернула некоректний JSON	Спробуйте потужнішу модель (≥ 7B параметрів) або знизьте `creativity`
`502 / connection refused` від сервісу ШІ	Тунель упав / сервер не запущено	Перезапустіть `ollama serve` і знову виконайте `cloudflared tunnel`

Примітки щодо безпеки

Signet API ніколи не журналює вміст localEndpoint чи apiKey. Для телеметрії білінгу він журналює назву провайдера (local) та ідентифікатор моделі.
Ставтеся до URL свого тунелю як до секрету того ж рівня, що й ключ API: будь-хто, хто його має, може викликати вашу локальну модель на вашому обладнанні.
Для продакшн-стеків, де важлива гарантія приватності, віддавайте перевагу Cloudflare Tunnel, а не ngrok: URL ngrok можна вгадати, а безкоштовний рівень не має автентифікації.