Skip to content

个人 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 快慢模型分流 ​

yaml
# 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 }:

yaml
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):

  1. 子 Agent 绑定:生效的 purposes.agents.<key>(Console「用途 → Agent」)。先按插件限定名 <插件>__<agent> 找,再按裸名找(裸名只在没有别的子 Agent 同名、也没有同名 Agent 绑定时生效)。项目自己的 agents/<name>/ 与同名的 ai.agents.<name> 是同一个 Agent,purposes.agents.<name> 对它生效;插件里同名的子 Agent 不会拿到绑定的键,请用限定名配置。
  2. 适配器 / Endpoint / 场景的聊天覆盖(以及个人 Session 的明确选择):只在子 Agent 没有生效的绑定时才用,顺序同上面的聊天解析顺序。
  3. 部署聊天(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 通过显式迁移映射,原数据保留用于审查和恢复。