个人 Session 与用途选择
Zhin 将大模型的**使用场景(Purpose)与底层模型配置(Profile)**解耦:你可以只配一个主力模型跑通所有功能,也可以把高频轻量任务(如旁听判断、上下文压缩、工具挑选)分流给便宜快速的小模型,把复杂对话留给推理模型。
核心用途(Purposes)速查
| 用途(Purpose) | 作用 | 未单独配置时的默认行为 | 推荐模型策略 |
|---|---|---|---|
chat | 主对话与工具调用推理 | 必填(部署默认聊天 Profile) | 主力对话/推理模型(如 deepseek-chat、gpt-4o、claude-sonnet-4-20250514、qwen-plus) |
compaction(summary) | 长对话历史自动摘要压缩 | 继承部署 chat Profile | 便宜、长窗口的快模型(如 gpt-4o-mini、qwen-turbo) |
ambient | 群聊旁听判断(决定没人 @ 时要不要接话) | 继承部署 chat Profile | 低延迟、低成本小模型 |
perception / vision | 为纯文本主模型描述图片(多模态感知及备用链) | 仅在显式配置时启用 | 视觉模型(如 gpt-4o-mini、qwen-vl-plus、gemini-2.5-flash) |
selection(decisions.*) | 结构化决策(skills / tools / memory / agents / approval / ambient) | 默认关闭(off) | 轻量决策模型(配合 @zhin.js/service-typesafe) |
示例:一套 Profile 通吃 vs 快慢模型分流
# ai.plan.yml
version: 1
services:
deepseek:
driver: deepseek
models:
deepseek-chat:
id: deepseek-chat
kinds: [language]
protocol: openai-chat
input: [text]
streaming: true
toolCalling: true
accounts:
main:
service: deepseek
auth:
method: api-key
source: env://DEEPSEEK_API_KEY
profiles:
main-chat:
account: main
model: deepseek-chat
fast-aux:
account: main
model: deepseek-chat
parameters:
maxOutputTokens: 1024
purposes:
chat:
profile: main-chat # 主对话用主力配置
compaction:
profile: fast-aux # 可选:摘要压缩与旁听用轻量配置(省略时自动复用 chat)
ambient:
profile: fast-aux备用模型(fallbacks)
每个语言用途都可以配置按顺序尝试的备用模型:chat、summary、ambient、agents.<name>、adapters|endpoints.<key>.chat、scenes.<key>.chat,以及原有的 perception。写法是 Profile 名字符串,或 { profile, fallbacks }:
purposes:
chat:
profile: gemini-free # 主模型
fallbacks: [cnb, deepseek] # 依次尝试
summary: { profile: gemini-free, fallbacks: [deepseek] }
agents:
researcher: { profile: gemini-free, fallbacks: [deepseek] }
adapters:
qq:
chat: { profile: gemini-free, fallbacks: [cnb] }
scenes:
"github:...":
chat: { profile: cnb, fallbacks: [deepseek] }- 何时切换:主模型以「额度用完」(如 Gemini 免费档日配额)、「余额不足」或「密钥被拒」(401、
UNAUTHENTICATED、API_KEY_INVALID一类)失败时,换下一个备用模型继续回答。单纯的 403(网关按内容或地区拒绝)不切换。同一次请求里同一个模型连续 2 次超时(模型请求自身的超时与首包超时;调用方自己设的截止时间不算)后,下一次尝试也换到备用模型,但只影响这一次请求;2 分钟内有至少 2 个不同请求都这样超时,才让所有请求暂时跳过它。偶发的一次超时仍按原来的同模型重试。**网络错误(连不上、连接被重置)和服务端 5xx(502、503 等)**先在同一模型上按providerResilience重试(默认 2 次);重试用完仍失败时换下一个备用模型,备用模型也一样失败就再换下一个。这一切换同样只影响这一次请求;2 分钟内至少 2 个不同请求都因此放弃同一个模型,才让所有请求暂时跳过它。限流(429)、请求被拒(400 一类)、内容拦截、上下文超长不切换。 - 不重复执行工具:切换发生在单次模型请求上,从当前对话继续;本回合已经执行过的工具不会再执行。已经向用户输出了部分文字时不切换。
- 只换到能接得住的模型:备用模型不支持对话里的图片 / 音频、估算的上下文超过它的
contextWindow,或接不上正在进行的工具调用(Gemini 需要thoughtSignature、Mistral 需要 9 位工具 id)时跳过它、试下一个;Anthropic 开着思考时缺少签名思考块,就在这一次请求里关掉思考,而不是报 400。换过去之后每次请求都会重新检查上下文是否还放得下,放不下就换下一个、都不行则明确报「上下文超长」而不是发出必然失败的请求(上下文压缩目前仍按主模型的窗口估算,后续再改)。换过去的请求使用备用模型自己的输出上限和重试 / 超时设置,用量记在实际回答的 Profile 上。 - 暂时跳过:额度用完的模型在恢复前直接跳过——有供应商给出的重置时间就按它;Gemini 等日配额默认到美国太平洋时间午夜;其他配额与余额不足 1 小时,密钥被拒 15 分钟,多个请求连续超时、或都因网络错误 / 5xx 放弃同一模型时 5 分钟。跳过状态只在内存中,重启后会再试一次。
- 写入即替换整条链:在 Console 保存某个用途、导入
ai.plan.yml,或重新运行向导(zhin setup --ai/ scaffold-wizard 生成的是不带fallbacks的chat: { profile })再导入,都会替换该用途的整条备用链;要保留备用模型,写入时请把fallbacks一并写上。 - 报错指明位置:备用链写错(引用不存在的 Profile、重复、包含主项),或删除仍被某条链引用的 Profile 时,错误会指出具体路径,例如
purposes.adapters.qq.chat.fallbacks[1]。 - 每层各管各的链:场景 / Adapter 覆盖了聊天模型,就只用该层写的备用链;摘要、旁听没单独配置时沿用部署聊天及其备用链。生图和六类决策不支持备用链;个人 Session 自选的聊天模型也不带备用链。
- 能看到:用了备用模型的回合在
zhin trace中标记「本轮由备用模型回答」(model_fallbacks,含原因与换到的模型),日志为model_fallback;模型失败却没有切换时,trace 记model_fallback_skips(时间线fallback_skipped),日志为fallback_skipped,并写明原因:no_fallbacks(没配备用模型)、not_switching(这类错误不切换,或只超时了一次)、exhausted(备用模型都试过、被跳过或接不住)、streamed(已向用户输出了文字)、retry_forbidden(调用方不允许再试)。Console 用途页可读取当前被跳过的模型和最近的切换记录。
备用 Profile 与主项一样必须是部署(Host)所有的 Profile。设计细节见 ADR 0047 增补。
个人 Session 与分层选择顺序
同一个人在具体私聊、群或频道中分别拥有独立 Session。切换模型保留聊天历史;恢复继承移除该 Session 的明确选择。群公共事件通过场景上下文引用,不把所有成员合成一个私人会话。
聊天解析顺序是:个人 Session 明确选择 > 场景 > Endpoint > Adapter > 部署聊天。角色任务使用明确的 agents.<name> Profile;选择 Host 角色模型不把私人调用者提升成 Host 管理员。
子 Agent 的模型优先级
ask / delegate / follow_up 拉起的子 Agent 回合按下面的顺序选模型(#1250):
- 子 Agent 绑定:生效的
purposes.agents.<key>(Console「用途 → Agent」)。先按插件限定名<插件>__<agent>找,再按裸名找(裸名只在没有别的子 Agent 同名、也没有同名 Agent 绑定时生效)。项目自己的agents/<name>/与同名的ai.agents.<name>是同一个 Agent,purposes.agents.<name>对它生效;插件里同名的子 Agent 不会拿到绑定的键,请用限定名配置。 - 适配器 / Endpoint / 场景的聊天覆盖(以及个人 Session 的明确选择):只在子 Agent 没有生效的绑定时才用,顺序同上面的聊天解析顺序。
- 部署聊天(
purposes.chat)。
也就是说,给子 Agent 显式绑定的模型优先于 purposes.adapters.<adapter>.chat 等渠道级覆盖;汇总回合(入口 Agent 继续处理结果)沿用主回合的用途。
被路由到的专家 Agent 同样适用:消息被路由给某个专家 Agent 时(@planner …、Endpoint 的首选 Agent、声明了该平台的 Agent),这一轮的入口 Agent 就是它。主回合和它这次协作里的汇总回合按它的 purposes.agents.<key> 选模型;它没有生效的键时沿用绑定的用途(zhin 即聊天)。
回合与子回合 trace 的 model_selection 写出实际用的用途(purpose)、Profile、选中这一层(source:agent / adapter / endpoint / scene / session / default)及其键(source_key),以及查了哪个 Agent 的键(agent)。agent 有值而 purpose 是 chat,表示这个 Agent 没有生效的绑定。Console 的「用途效果」与提醒按同一规则判断某个键是否生效。
可覆盖范围固定:
| 层级 | 可选择的用途 |
|---|---|
| 部署 | 聊天、摘要、旁听语言模型、识图(均可带备用链)、生图、六类决策、Agent 角色(可带备用链) |
| Adapter/Endpoint | 聊天、识图(均可带备用链) |
| 场景 | 聊天(可带备用链) |
| 个人 Session | 聊天 Profile |
摘要省略时继承部署聊天,始终不用个人密钥。旁听 Language Profile 省略时也继承部署聊天,不受个人或场景聊天选择影响;结构化 decisions.ambient 单独选择。参数和连接不能作为各层任意覆盖字段。
在 Console 中调整
服务、账号、模型 Profile 和部署用途从模型管理页配置。个人页面只显示该 Console 身份由管理员预绑定的真实账号范围,个人首轮使用 API Key 连接;Session 页可以选择可见的聊天 Profile 或恢复继承。
保存是持久化到 Host 数据库,下一回合生效,不修改启动文件或重启进程。在途回合、工具续轮和重试保持开始时固定的配置图与账号。普通 token 刷新不改变配置图;实际请求通过同一账号的当前凭据版本发出。
身份与恢复
Session 保存的是 Profile 与账号 incarnation 的不可复用身份,不是标签,也不长期保存短期 revision。修改同一 Profile 的参数或原生模型后,下回合解析它的当前版本,在途仍使用旧模型;模型切换隔离供应商 opaque 状态;删除重建同名账号后,旧 Session 不自动继承新账号。
一个已选 Profile 不存在、越权或不可用时,明确报错,不改用部署聊天。存储读取失败也不当作“没有个人设置”。配置变更结果未知时,保留同一 mutationId 查询 receipt。
独立文件 ai.plan.yml 是可读的导入提案;首次启动数据库为空时会自动种子化导入,后续也可在 Console 中预览并显式确认。旧配置和个人 preset 通过显式迁移映射,原数据保留用于审查和恢复。