models.toml：模型目录与任务分档¶

真实文件是 config/models.toml。先在厂商配置建立连接，再添加模型。 面板「模型与厂商」维护目录，「功能分配」给任务选择候选。 逐字段说明见模型模板。

模型名、真实 ID 与连接¶

每个 [[models]] 是一条模型目录记录。 name 是本地引用名，model_identifier 是服务商接口接受的真实 ID。 api_provider 指向厂商条目的 name，不是厂商预设标识。 换模型版本通常只改真实 ID；改本地名称才需要更新任务候选。

visual = true 声明该模型可接收图片，是视觉候选的准入条件。 不能通过给纯文本模型勾选视觉能力，让它获得真实图片理解能力。 omni = true 声明该模型能同时理解画面和声音（全模态），是视频理解候选的准入条件； 只能看图的视觉模型听不到视频里的人声和配乐。 思考强度等厂商参数写在模型条目的 extra_body，写法以厂商文档为准 （例如百炼全模态模型：{"reasoning_effort": "medium"}）。 单价字段用于用量统计计算费用，写法见下面「单价、缓存命中价与分时段价格」； 它不会改变服务商的实际计费，也不会让路由自动选出最便宜的模型。 embedding_dim 只用于嵌入模型，必须对应接口实际返回的维度。

单价、缓存命中价与分时段价格¶

每个 [[models]] 可以写三类单价，单位都是元 / 百万 token，只用于用量统计算费用：

一次调用的费用：

费用（元）= (输入 − 缓存命中) / 1e6 × price_in
          + 缓存命中 / 1e6 × cache_price_in（不写时按 price_in）
          + 输出 / 1e6 × price_out

单价在调用结束时按调用开始那一刻生效的那组算好，累加进统计。改单价、重启之后的 新调用按新单价算，已经记下的费用不会重算；填单价之前的调用费用永远是 0，所以先填 单价再看费用。两项都是 0 的模型在统计页上会标出来，提醒是没填还是真的免费。

分时段价格每段写一个 [[models.price_periods]] 子表，放在该模型所有字段之后（TOML 里子表之后的键都归子表）。每段含 start、end（HH:MM，24 小时制）、price_in、 price_out，可选 cache_price_in（不写表示与该时段 price_in 相同）。规则：

• 时刻按运行月璃的那台机器的本地时间，与作息、日程一致；
• 含开始、不含结束：08:00～12:00 覆盖 08:00 整到 11:59:59；
• 结束早于开始表示跨午夜，例如 23:00～07:00；结束写 00:00 表示到当天结束；
• 不在任何时段内时用模型的基础单价；
• 开始等于结束、时刻写成 7:00 或 24:00 这类不合法写法、两段时间重叠，都在启动时 报错并指出是哪个模型的第几段。

下面的数字只示意格式，按你所用服务商的价目表填写：

[[models]]
name = "my-chat"
model_identifier = "vendor-model-id"
api_provider = "my-provider"
price_in = 2.0
price_out = 8.0
cache_price_in = 0.5

[[models.price_periods]]
start = "00:30"
end = "08:30"
price_in = 1.0
price_out = 4.0
cache_price_in = 0.25

不写 cache_price_in 与 price_periods 的老配置不需要改动就能照常加载。WebUI 的 模型与厂商编辑框里可以直接填这三类单价，保存时写出的就是上面 的格式。

首装预填的七档¶

七个条目都引用 dashscope 这一条百炼连接。 下表是随本版本代码分发的配置，不是远端实时模型清单。

记忆抽取在后台执行，但错误事实会影响后续召回，模型选择仍需保证判断质量。 语音任务 tts 默认没有候选；语音、视觉、向量功能仍各有独立开关。 新增模型不会自动出现在任务里，要把本地名称加入对应 model_list。 实际模型权限与 ID 是否可调用，需使用实际密钥验证。

任务候选与继承¶

chat 至少保留一个候选。 planner、replyer、scene、proactive、summary、memory、schedule、expression 留空时， 继承 chat 的候选和挑选策略；各自的首字超时与慢阈值仍按各自任务设置。 vision、video、tts、embedding 不继承 chat；候选列表为空时，对应任务没有可用模型。

因此「清空摘要候选」不等于关闭摘要，而是改用对话模型做摘要。 要关某项能力，检查相应功能开关，而不是随意清空候选。 任务段名写错会被拒绝，不会当作新任务接受。

三种挑选策略¶

只有顺序策略下，拖动候选顺序才决定首选。 只配一个候选时，换策略不会凭空增加备用线路。 熔断按厂商连接归组；同一连接下放多个模型不能隔离厂商整体故障。 要有独立连接的候选，必须先配置另一条真实可用的厂商连接。

首字超时、慢阈值与网络超时¶

first_token_timeout_ms 默认 30000，是当前候选开始输出前的切换窗口。 该窗口包含连接的首字等待与内部重试；超时后尝试下一个候选。 它不是完整一轮对话的总时长，也不是前端打字气泡的等待上限。

slow_threshold_ms 默认 8000，只记录响应偏慢，不会在 8 秒时主动切换。 它必须小于首字超时，设 0 才是关闭慢响应记账。 厂商的 timeout_ms 管网络连接与读取，默认 120000，见厂商配置。 仅增大网络超时，不会延长任务自身配置的首字等待窗口。 已经输出的普通流式内容不会因中途断流而从头自动重试，以免重复输出。

生成参数与思考开关¶

[generation.<任务>] 控制该任务温度与输出上限。 模板当前统一温度为 0.85、max_tokens = 0，0 表示不另设输出上限。 注释中的「稳定」描述不改变实际参数值，任务温度应以配置为准。 模型条目的 temperature、max_tokens 可覆盖任务值，排查时须同时核对两级配置。

思考开关是厂商请求参数，放在模型条目的 extra_body。 本版本五个文本或视觉模型预填：

extra_body = { enable_thinking = false }

嵌入模型的模板实际为 extra_body = {}；嵌入请求不透传此字段。 任务或模型的顶层 thinking 字段已取消，继续使用会导致加载失败。 reasoning_parse_mode 只改变返回思考内容的解析方式，设 none 不会关闭厂商思考。 换厂商时核对它接受的请求体格式，不能保证同一键名适用于所有接口。

嵌入模型的特殊边界¶

同一 embedding 任务的候选必须共享模型 ID、接口协议与向量维度；同维不同模型也不可比较，可用同一模型跨厂商备份。 embedding_dim 必须填写且大于 0，留空或填 0 时启动报错。 openai 协议下它只是本地声明，不会改变远端输出维度；返回维度与它不符时，这一批向量作废。 openai 协议的嵌入请求只发送模型与输入，无法用 extra_body.dimensions 调整输出维度。 百炼多模态向量协议会把它作为 dimension 参数发给服务端，只能填模型支持的值， 例如 tongyi-embedding-vision-flash-2026-03-06 只接受 64、128、256、512、768。 更换嵌入模型还会改变向量空间，即使维度相同也不应直接混用旧向量。 先保留数据库与索引，按开发手册：记忆模块核对重建要求。

修改后核对¶

保存并重启后端，检查启动模型路由是否列出预期名称。 再发一轮消息，在会话观察与调用记录中确认实际使用的任务和候选。 连接测试或拉取模型列表成功，不能替代该模型的一轮真实请求。 调用失败时，应依据模型 ID、能力声明及厂商返回信息确定原因，再评估是否调整超时。

模型接口协议¶

每个模型用 api_format 选择接口：openai（OpenAI 兼容，默认）、responses（OpenAI Responses）、 dashscope_multimodal（百炼多模态向量）、ark_multimodal（方舟多模态向量）。对话任务支持前两种， 语音与重排仅支持 openai；向量任务支持 openai 和两种多模态向量协议。

走 Responses 且开思考的模型，模型级 max_tokens 必须给思考留余量：max_output_tokens 包含思考 token。 extra_body 应按所选协议的字段写，Responses 思考档位例如 reasoning = { effort = "medium" }。 Responses 固定关闭服务端存储，不允许覆盖 model、input、stream、previous_response_id 或启用 store。

重排¶

model_tasks.rerank 在界面显示为「重排」，留空即不重排，不继承其它任务。配置后，回想（recall）与 查知识（consult）先取一个更大的候选池，交给重排模型逐条打相关度分，按分数排序，分数低于 「检索调参」里的重排相关度下限 rerank_min_score（默认 0.5）的不返回；一条都不剩时，月璃会说没想起来。 留空时两个动作按词面与向量的融合分取前几条，不设下限。

重排使用通用重排接口：请求体为 model、query、documents，响应为 results 里每条的 index 与 relevance_score。服务商的 base_url 写到版本号（如 https://api.siliconflow.cn/v1）时自动补 /rerank；路径写法不同的服务商，在服务商里把完整地址填进 base_url，以 /rerank 或 /reranks 结尾的地址原样使用，例如百炼为 https://dashscope.aliyuncs.com/compatible-api/v1/reranks。 这类服务商连接只给重排用，对话模型不要挂在上面。

每次回想或查知识多一次请求。候选约 50 条时，一次约几千 token、耗时一秒以内。重排请求失败时， 这次检索直接报失败，不会悄悄退回不设下限的排序。不同重排模型的分数刻度不一样，换模型后应重新确认下限。

表情包多模态向量¶

model_tasks.multimodal_embedding 在界面显示为「多模态向量」，仅接受 dashscope_multimodal 或 ark_multimodal。 候选的模型 ID、协议和维度必须一致，可以使用同一模型的不同厂商连接作为备份。留空不继承其它任务。

配置此槽后，表情包使用图片首帧与标签的融合向量，查询仍只发送情绪文字。 送出前取首帧、最长边缩到 512，不透明的图转 JPEG，带透明通道的保留 PNG；含图片的请求每批最多 5 张。 首次启用要为整库补算，本机 456 张约 12 分钟，期间表情包按标签匹配。 百炼融合模型应使用 2026-03-06 及以后的版本，旧版丢弃文字时会明确报错。维度应填写模型实际支持的值。

不配置专用槽时，表情包只使用 embedding 任务的标签文字向量，即使该任务的协议本身支持图片也不发送图片。 两槽都为空时保留现有标签匹配。事实与知识始终使用 embedding，仍由 [vector].enabled 控制；表情包专用槽不受这个开关限制。

启动时按模型、协议、维度和配方比对向量空间：首次登记假定已有向量来自当前配置，不清空；空间变化时清空该消费方的向量并打印条数。 表情包的缺失向量在后台补算，含封禁行；单张文件失败会告警并跳过，关停时未完成的行留待下次启动续算。