本地 LLM(Ollama、LM Studio)

AI 生成端点支持一个特殊的 provider: "local"，可以让引擎指向你自己托管的任何兼容 OpenAI 的 chat-completions 服务器。繁重的工作（二维码渲染、ISO 18004 验证、扫描保证）仍由服务器完成，只有负责提出设计方案的语言模型运行在你的机器上。

何时使用

隐私优先的技术栈。 提示词在发往 LLM 的途中不会离开你的网络。Signet API 只能看到最终的 JSON 配置，看不到你输入的自然语言描述。
成本控制。 你已经在为其他工作负载运行 Ollama / LM Studio，想复用已付费 / 已下载的模型。
自定义微调的模型。 你已经用二维码设计提示词微调了一个小型开源模型，想让 Signet 使用它。

以下情况不适合：

试图访问 API 服务器上 localhost 的 SaaS 调用方：Signet API 运行在 Azure Functions 上，无法直接访问你的笔记本电脑。你需要一个公共隧道（见下文）。
不受你控制的托管 Ollama 云服务：这种情况请改用相应的原生提供商（openai、groq 等）。

设置

1. 启动本地服务器

Ollama：

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

Ollama 开箱即在 http://localhost:11434/v1/chat/completions 提供兼容 OpenAI 的 API。

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 会拒绝 RFC1918 / 链路本地 IP（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 密钥。
本地模式下 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`	你从公网传入了 `10.x` / `192.168.x` / `127.0.0.1` IP	使用隧道（ngrok、Cloudflare Tunnel）并传入公共 URL
400 `For provider='local' the 'llmModel' field is required`	你忘了设置 `model`	将 `model` 设为本地服务器公开的模型名称
500 `AI generated an invalid configuration`	本地模型返回了格式错误的 JSON	换一个更强的模型（≥ 7B 参数）或降低 `creativity`
AI 服务返回 `502 / connection refused`	隧道断开 / 服务器未运行	重启 `ollama serve` 并重新运行 `cloudflared tunnel`

安全说明

Signet API 从不记录 localEndpoint 或 apiKey 的内容。出于计费遥测目的，它会记录提供商名称（local）和模型标识符。
请把你的隧道 URL 当作与 API 密钥同等级别的机密：任何拿到它的人都可以在你的硬件上调用你的本地模型。
对于隐私保证至关重要的生产环境，建议优先使用 Cloudflare Tunnel 而不是 ngrok：ngrok 的 URL 可以被猜到，而且免费档没有认证。