LM Studio Provider¶
1. 定位¶
LM Studio 是桌面端本地模型 Provider,通过 GUI 管理本地大模型.优势: - 友好的桌面 GUI - 无需命令行 - 支持热加载模型 - OpenAI 兼容 API
2. 支持的模型¶
LM Studio 动态获取模型列表,从 /v1/models 端点获取.
常见模型: - Llama 3.3 - Mistral - Qwen 2.5 - Phi-4 - DeepSeek R1
注意: 通过 LM Studio GUI 下载模型,模型自动可用.
3. 配置示例¶
import "git.flytoex.net/yuanwei/git.flytoex.net/yuanwei/flyto-agent/pkg/providers/lmstudio"
p := lmstudio.New(lmstudio.Config{
BaseURL: "http://localhost:1234", // 默认
Timeout: 5 * time.Minute, // 可选, 默认 300s, 见 §3.1
})
3.1 Timeout (P1 契约加固, 2026-04-13)¶
Config.Timeout 通过 http.Transport.ResponseHeaderTimeout 实现, 约束"请求发出到收到响应首字节"的时间, 不影响 SSE 流式 body 读取.
LM Studio 默认 300s (5 分钟), 与 ollama 对称: 本地推理冷启动需 load 权重 + warm-up, 30-90s 是常态.详见 docs/providers/ollama.md §3.1 的完整论证 - 两个本地 provider 采用同一策略.
| 场景 | Config 字段 | 行为 |
|---|---|---|
| 默认 | HTTPClient=nil, Timeout=0 |
使用 defaultTimeout=300s |
| 显式 Timeout | HTTPClient=nil, Timeout=Xs |
使用 Xs |
| 自定义 client | HTTPClient=&http.Client{...} |
完全交给消费者, Timeout 被忽略 |
陷阱警告: 不要误用 http.Client.Timeout - 详见 anthropic.md §3.1.
4. 认证方式¶
无认证 - LM Studio 默认不需要 API Key.
5. 能力矩阵¶
| 能力 | 支持 | 备注 |
|---|---|---|
| Streaming | ✓ | SSE |
| Tool Use | ✓ | 取决于加载的模型 |
| Extended Thinking | ✗ | 不支持 |
| Vision | ✗ | 不支持 |
| JSON Mode | ✓ | 取决于模型 |
| Caching | ✗ | 不支持 |
| Batch API | ✗ | 不支持 |
6. 已知 quirks¶
模型获取差异¶
LM Studio 用 /v1/models(与 OpenAI 相同),而 Ollama 用 /api/tags.Provider 会自动适配.
字段映射¶
LM Studio 返回的 /v1/models 中 owned_by 字段为空字符串,Provider 会填充 provider: "lmstudio".
Schema Adaptation¶
使用 "openai" schema adaptation(非 strict),与 Ollama 相同.
Tool 限制¶
Tool 数量无硬限制(MaxTools = 0).
适用场景¶
LM Studio 的 GUI 比 Ollama 的 CLI 更适合不熟悉命令行的用户.
7. 错误处理¶
| 错误 | 含义 | 处理建议 |
|---|---|---|
| connection refused | LM Studio 未启动 | 启动 LM Studio 并开启 API Server |
| 404 | 模型未加载 | 在 GUI 中加载模型 |
8. 与 Ollama 对比¶
| 特性 | LM Studio | Ollama |
|---|---|---|
| 界面 | GUI(桌面) | CLI |
| 模型格式 | .gguf | .gguf, Modelfile |
| 热加载 | 支持 | 支持 |
| API 兼容性 | OpenAI | OpenAI |
| 服务器部署 | 桌面共享 | 服务部署 |
9. 使用场景¶
最佳场景: - 不熟悉 CLI:GUI 更直观 - 快速原型:拖拽即可加载模型 - 模型比较:GUI 切换模型方便 - 隐私敏感:同 Ollama
10. 数据驱动能力(Capabilities)¶
参见
docs/architecture/data-driven-capabilities-rfc.md了解整体机制.PR2.2(2026-04)落地,是 ollama 的 1:1 模板复刻.
本 provider 的能力决策来自 req.Capabilities(engine 从 ModelRegistry 注入).包内 const lmstudioMaxTools = 0 降级为兜底.
本 provider 的决策路径:
| 路径 | helper | 兜底策略 |
|---|---|---|
MaxTools + Exhaustive |
resolveMaxTools |
lmstudioMaxTools = 0(本地模型无硬限制) |
SupportsThinking |
resolveThinkingSupport |
兜底 false(LM Studio 装载的本地开源模型默认不支持 thinking;未来 QwQ/DeepSeek-R1 等进 registry 后会被识别) |
SupportsCaching |
不使用 | LM Studio 不支持 caching,无 Config 字段 |
lmstudio 与 ollama 的孪生关系:lmstudio 和 ollama 结构几乎 1:1 对称--同样用 wire.OpenAICompatClient,同样只有 max_tools 一路径可检测,同样不转发 NeedsThinking 是已知债务.PR2.1 和 PR2.2 验证了"同类 provider 改造收敛到逐行对称的 diff"--通用模板的可迁移性.
双开关协议(want × can):req.NeedsThinking=true 是 want 信号;registry 或兜底 false 是 can 信号.want=true can=false → warning.