LLM Instances（LLM 实例配置）

LLM 实例配置用来控制每个生成槽位具体用哪个 LLM Profile、是否启用、以及额外的生成参数覆盖。

它和 LLM Profiles 的关系是：Profile 管"连什么模型"，Instance Config 管"哪个槽位用哪个 Profile"。

什么时候需要看这页

你要为某个会话单独指定 LLM 配置
你要调整某个槽位（例如 narrator、memory）的生成参数
你要查看当前生效的实例配置

一个简单例子

bash

# 为某个会话的通配槽位指定 LLM Profile
curl -X POST http://localhost:3000/llm-instances/configs \
  -H 'Content-Type: application/json' \
  -d '{
    "scope": "session",
    "scope_id": "sess_001",
    "instance_slot": "*",
    "preset_id": "llm_profile_001",
    "enabled": true
  }'

先理解几个词

词	这里的意思
instance slot	生成槽位，例如 narrator、director、memory
scope	配置生效范围：`global`（全局）或 `session`（某个会话）
fallback	如果没有到精确匹配的配置，就向上找更通用的配置

实例槽位

槽位	说明
`*`	通配符，作为默认 fallback
`narrator`	叙述生成
`director`	Director 模块
`verifier`	Verifier 模块
`memory`	记忆整合

作用域与优先级

配置按以下优先级解析（从高到低）：

session(slot) — 会话级指定槽位配置
session(*) — 会话级通配配置
global(slot) — 全局指定槽位配置
global(*) — 全局通配配置
default — 系统默认值（enabled=true, params=null）

这些解析结果会直接进入真实 turn 执行链路，不再只是只读观察值。

Instance Config 对象

字段	类型	说明
`id`	string	配置记录 ID
`scope`	string	`global` / `session`
`scope_id`	string	作用域 ID
`instance_slot`	string	实例槽位
`preset_id`	string \| null	关联预设 ID
`enabled`	boolean	是否启用
`params`	object \| null	生成参数覆盖
`created_at`	integer	创建时间
`updated_at`	integer	更新时间

列出实例配置

http

GET /llm-instances

查询参数

参数	类型	说明
`scope`	string	按作用域过滤：`global` / `session`
`session_id`	string	按会话 ID 过滤（scope=session 时使用）

响应 `200`

json

{
  "data": [
    {
      "id": "ic_demo123",
      "scope": "global",
      "scope_id": "global",
      "instance_slot": "narrator",
      "preset_id": null,
      "enabled": true,
      "params": { "temperature": 0.8, "max_output_tokens": 1024 },
      "created_at": 1735689600000,
      "updated_at": 1735689660000
    }
  ]
}

查询指定槽位配置

http

GET /llm-instances/:slot

返回指定槽位的所有配置记录（可能包含不同 scope 的多条记录）。

路径参数

参数	类型	说明
`slot`	string	实例槽位：`*` / `narrator` / `director` / `verifier` / `memory`

查询参数

同列出接口。

响应 `200`

返回 { "data": InstanceConfig[] }。

错误

状态码	code	说明
`400`	`validation_error` / `invalid_slot`	路径参数或查询参数校验失败，或 `slot` 不属于实例槽位枚举

创建或更新实例配置

http

PUT /llm-instances/:slot

按 (account_id, scope, scope_id, instance_slot) 唯一约束执行 upsert。

路径参数

参数	类型	说明
`slot`	string	实例槽位

请求体

字段	类型	必填	说明
`scope`	string	否	`global`（默认）/ `session`
`session_id`	string	条件	当 scope=session 时必填
`preset_id`	string \| null	否	关联预设 ID
`enabled`	boolean	否	是否启用（默认 `true`）
`params`	object \| null	否	生成参数覆盖

字段省略语义：

省略 enabled：会按请求 schema 默认值 true 处理；对于已存在配置，这等价于把它重新写成 enabled=true
省略 preset_id：如果目标配置已存在，则保留原有 preset_id；首次创建时写入 null
省略 params：如果目标配置已存在，则保留原有 params
显式传 params: null：清空原有 params 覆盖

运行时语义说明：

enabled=false 且 slot=narrator 时，真实聊天执行会返回 409 instance_slot_disabled_required，不会再回退到环境变量 narrator。
enabled=false 且 slot=director / verifier / memory 时，对应子流程会在本轮 turn 中被强制跳过。
preset_id 在当前实现中作为 narrator Prompt 组装阶段的显式覆盖值；当它为非空字符串时，优先于 session.presetId。
params 采用浅层 merge，同名键覆盖。当前槽位原有参数（包括 Profile 绑定参数和默认运行参数）先建立基线，再由 llm_instance_config.params 覆盖同名字段。
如果你需要查看“Profile 解析结果”，使用 /llm-profiles/runtime；如果你需要查看“实例侧 enabled / preset_id / params 的最终解析结果”，应使用 /llm-instances/resolved。

params 可覆盖的字段：

字段	类型	说明
`max_context_tokens`	integer	最大上下文 token
`max_output_tokens`	integer	最大输出 token
`temperature`	number	温度 0-2
`top_p`	number	0-1
`top_k`	integer	>=0
`frequency_penalty`	number	-2 到 2
`presence_penalty`	number	-2 到 2
`stream`	boolean	是否流式
`timeout_ms`	integer	超时毫秒
`max_retries`	integer	最大重试 0-10
`reasoning_effort`	string	`low` / `medium` / `high`

请求示例

json

{
  "scope": "global",
  "preset_id": null,
  "enabled": true,
  "params": { "temperature": 0.8, "max_output_tokens": 1024 }
}

响应 `200`

json

{
  "data": {
    "id": "ic_demo123",
    "scope": "global",
    "scope_id": "global",
    "instance_slot": "narrator",
    "preset_id": null,
    "enabled": true,
    "params": { "temperature": 0.8, "max_output_tokens": 1024 },
    "created_at": 1735689600000,
    "updated_at": 1735689660000
  }
}

错误

状态码	code	说明
`400`	`validation_error` / `invalid_slot` / `invalid_params`	请求体或路径参数校验失败（包括 `scope=session` 但缺少 `session_id`）、`slot` 非法，或 `params` 归一化失败

删除实例配置

http

DELETE /llm-instances/:slot

路径参数

参数	类型	说明
`slot`	string	实例槽位

查询参数

参数	类型	说明
`scope`	string	`global`（默认）/ `session`
`session_id`	string	当 scope=session 时必填

响应 `200`

json

{
  "data": {
    "instance_slot": "narrator",
    "scope": "global",
    "deleted": true
  }
}

错误

状态码	code	说明
`400`	`validation_error` / `invalid_slot` / `missing_session_id`	路径参数或查询参数校验失败、`slot` 非法，或 `scope=session` 但缺少 `session_id`
`404`	`config_not_found`	目标配置不存在

解析实例配置

http

GET /llm-instances/resolved

按优先级规则解析当前各槽位的实际生效配置。

查询参数

参数	类型	说明
`session_id`	string	指定会话上下文（可选）

响应 `200`

json

{
  "data": {
    "session_id": null,
    "slots": [
      {
        "slot": "*",
        "source": "global_config",
        "scope": "global",
        "config_id": "ic_abc",
        "preset_id": null,
        "enabled": true,
        "params": { "temperature": 0.7 }
      },
      {
        "slot": "narrator",
        "source": "default",
        "scope": null,
        "config_id": null,
        "preset_id": null,
        "enabled": true,
        "params": null
      }
    ]
  }
}

source 可能的值：

值	说明
`session_config`	来自会话级配置
`global_config`	来自全局配置
`default`	无配置，使用系统默认值

LLM Instances（LLM 实例配置） ​

什么时候需要看这页 ​

一个简单例子 ​

先理解几个词 ​

实例槽位 ​

作用域与优先级 ​

Instance Config 对象 ​

列出实例配置 ​

查询参数 ​

响应 200 ​

查询指定槽位配置 ​

路径参数 ​

查询参数 ​

响应 200 ​

错误 ​

创建或更新实例配置 ​

路径参数 ​

请求体 ​

请求示例 ​

响应 200 ​

错误 ​

删除实例配置 ​

路径参数 ​

查询参数 ​

响应 200 ​

错误 ​

解析实例配置 ​

查询参数 ​

响应 200 ​

LLM Instances（LLM 实例配置）

什么时候需要看这页

一个简单例子

先理解几个词

实例槽位

作用域与优先级

Instance Config 对象

列出实例配置

查询参数

响应 `200`

查询指定槽位配置

路径参数

查询参数

响应 `200`

错误

创建或更新实例配置

路径参数

请求体

请求示例

响应 `200`

错误

删除实例配置

路径参数

查询参数

响应 `200`

错误

解析实例配置

查询参数

响应 `200`