介绍
# LM Studio Models
在质量满足要求时，将任务分派给本地模型。Base URL：http://127.0.0.1:1234。Auth：`Authorization: Bearer lmstudio`。instance_id = `loaded_instances[].id`（同一模型可能有多个，例如 `key` 和 `key:2`）。
## 关键术语
- **model**：来自 GET models 的 key；用于聊天和可选加载。 - **lm_studio_api_url**：默认 http://127.0.0.1:1234（路径 /api/v1/...）。 - **response_id** / **previous_response_id**：聊天返回 response_id；作为 previous_response_id 传递以保持状态。 - **instance_id**：用于卸载时，仅使用 GET /api/v1/models 中该模型的值：每个 `loaded_instances[].id`。不要假设它等于 model key；对于多个实例，id 可能类似 key:2。LM Studio 文档：List (loaded_instances[].id), Unload (instance_id)。
在 frontmatter 中触发；以下是实现。
## 前置要求
LM Studio 0.4+，服务器 :1234，磁盘上有模型；通过 API 加载/卸载（JIT 可选）；脚本需要 Node（curl 也可）。
## 快速开始
最小路径：列出模型，然后进行一次聊天。将 `<model>` 替换为 GET /api/v1/models 返回的一个 key，将 `<task>` 替换为任务文本。
```bash curl -s -H 'Authorization: Bearer lmstudio' http://127.0.0.1:1234/api/v1/models node scripts/lmstudio-api.mjs <model> '<task>' --temperature=0.5 --max-output-tokens=200 ```
有状态多轮对话：从上一个脚本输出传递 `--previous-response-id=<id>`。或者使用 `--stateful` 自动持久化 response_id。可选 `--log <path>` 用于记录请求/响应。
```bash node scripts/lmstudio-api.mjs <model> 'First turn...' --previous-response-id=$ID1 node scripts/lmstudio-api.mjs <model> 'Second turn...' --previous-response-id=$ID2 ```
## 完整工作流程
### 步骤 0：预检
GET <base>/api/v1/models；非 200 或连接错误 = 服务器未就绪。
```bash exec command:"curl -s -o /dev/null -w '%{http_code}' -H 'Authorization: Bearer lmstudio' http://127.0.0.1:1234/api/v1/models" ```
### 步骤 1：列出模型并选择
GET /api/v1/models 列出模型。解析每个条目：key, type, loaded_instances, max_context_length, capabilities。如果模型已有 loaded_instances.length > 0 且适合任务，跳转到步骤 5；否则选择一个 key 用于聊天（以及步骤 3 中的可选加载）。根据任务选择：vision -> capabilities.vision；embedding -> type=embedding；context -> max_context_length。优先选择已加载的；为了速度优先选小的，为了推理优先选大的。记下 loaded_instances[].id 以备后续可选卸载。
**示例 — 列出模型：** ```bash exec command:"curl -s -H 'Authorization: Bearer lmstudio' http://127.0.0.1:1234/api/v1/models" ```
解析 models[]（key, type, loaded_instances, max_context_length, capabilities, params_string）。如果模型有 loaded_instances.length > 0 且适合任务，跳转到步骤 5；否则选择 key 用于聊天（以及可选加载）。记下 loaded_instances[].id 以备可选卸载。
### 步骤 2：模型选择
从 GET 响应中选择 key；在聊天中用作 model（可选加载）。约束条件：vision -> capabilities.vision；embedding -> type=embedding；context -> max_context_length。优先选已加载的（loaded_instances 非空），为了速度选小的/为了推理选大的；主要回退选项。如果不确定，使用该 key 的第一个已加载实例，或适合任务的最小已加载模型。可选 POST 加载；否则在第一次聊天时 JIT。
### 步骤 3：加载模型（可选）
可选：POST /api/v1/models/load { model, context_length?, ... }。或运行 scripts/load.mjs <model>。JIT：第一次聊天时加载；显式加载仅用于特定选项。
### 步骤 4：验证已加载（可选）
如果是显式加载：GET models，确认 loaded_instances。如果是 JIT：无需验证；第一次聊天返回 model_instance_id, stats.model_load_time_seconds。
### 步骤 5：调用 API
从技能文件夹运行：node scripts/lmstudio-api.mjs <model> '<task>' [options]。
```bash exec command:"node scripts/lmstudio-api.mjs <model> '<task>' --temperature=0.7 --max-output-tokens=2000" ```
有状态：添加 --previous-response-id=<response_id>。Curl：POST <base>/api/v1/chat，body model, input, store, temperature, max_output_tokens；可选 previous_response_id。解析：output (type message) -> content；response_id, model_instance_id, stats。脚本输出 content, model_instance_id, response_id, usage。
### 步骤 6：卸载（可选）
对于您使用的 model key：GET /api/v1/models，然后对于该模型的**每个** `loaded_instances[].id`，POST /api/v1/models/unload 并在 body 中传递 `{"instance_id": "<that id>"}`。仅使用响应中的 id（除非 model key 正好等于该 id，否则不要发送 model key）。或者运行 scripts/unload.mjs <model_key>（脚本会先执行 GET 然后卸载每个实例 id）。可选 --unload-after（默认关闭）；使用 --keep 保持加载状态。仅卸载该模型的实例。JIT+TTL 自动卸载；需要时显式卸载。
```bash # One unload per instance_id; repeat for each id in that model's loaded_instances exec command:"curl -s -X POST http://127.0.0.1:1234/api/v1/models/unload -H 'Content-Type: application/json' -H 'Authorization: Bearer lmstudio' -d '{\"instance_id\": \"<instance_id>\"}'" ```
### 步骤 7：验证卸载（可选）
卸载后，确认该 model key 没有剩余实例。运行下面的 jq 检查；结果必须为 `0`。如果非零，卸载该模型剩余的 instance_id 并重新运行检查。不要从“模型对象存在”推断；即使对象仍然存在，`loaded_instances` 数组也是空的。
```bash exec command:"curl -s -H 'Authorization: Bearer lmstudio' http://127.0.0.1:1234/api/v1/models | jq '.models[]|select(.key==\"<model_key>\")|.loaded_instances|length'" ```
预期输出 `0`。如果不是，卸载剩余的 instance_ids 并重新运行。
## 错误处理
- 脚本在瞬态故障时重试（2-3 次尝试，带有退避）。 - 模型未找到 -> 从 GET 响应中选择另一个模型。 - API/服务器错误 -> GET models，检查 URL。 - 无效输出 -> 重试。 - 内存 -> 卸载或使用更小的模型。 - 卸载失败 -> instance_id 必须精确来自 GET /api/v1/models 中该模型的 loaded_instances[].id（除非匹配，否则不是 model key）。
## 复制粘贴
将 `<model>` 替换为 GET /api/v1/models 返回的一个 key，将 `<task>` 替换为任务文本。根据步骤 6 进行可选卸载（instance_id 来自 GET models 中该 key 的值）。
```bash exec command:"curl -s -H 'Authorization: Bearer lmstudio' http://127.0.0.1:1234/api/v1/models" exec command:"node scripts/lmstudio-api.mjs <model> '<task>' --temperature=0.7 --max-output-tokens=2000" ```
## LM Studio API 详情
Helper/API：参见步骤 5。输出：content, model_instance_id, response_id, usage。Auth：Bearer lmstudio。列表 GET /api/v1/models。加载 POST /api/v1/models/load（可选）。卸载 POST /api/v1/models/unload { instance_id }。
## 脚本
lmstudio-api.mjs：聊天；选项 --stateful, --unload-after, --keep, --log <path>, --previous-response-id, --temperature, --max-output-tokens。load.mjs：按 key 加载模型。unload.mjs：按 model key 卸载（所有实例）。test.mjs：冒烟测试（加载、聊天、卸载一个模型）。
## 注意事项
- LM Studio 0.4+。 - JIT（第一次聊天时加载；stats 中的 model_load_time_seconds）；有状态（response_id / previous_response_id）。