模型路由不是 if else：Synapse 里的本地模型与云模型分流

做 Synapse 的过程中，有一个判断越来越明确：模型路由不是在代码里写几个 if else，然后把任务丢给本地模型或云模型。

如果只是 demo，这样当然能跑。但 Synapse 不是为了演示一次回答，而是要长期处理个人笔记、搜索、对话、摘要和实体抽取。这里面有隐私、质量、延迟、成本、可用性，还有一个很现实的问题：本地模型和云模型都不稳定地“完美”。

这篇文章只写当前代码里已经落地的部分。Synapse 的模型路由主要在 synapse-server/app/services/ai_service.py，周围还连着 PrivacyEngine、CircuitBreaker、CostTracker、云端配置热更新和 Web 控制台。

真实链路长什么样

从代码看，模型相关的调用主要有四类：

• summarize：笔记摘要。
• extract_entities：实体抽取。
• chat：基于笔记上下文的对话。
• embed_text：生成 embedding，写入或查询 Qdrant。

这几类任务并不是同一种问题。摘要和实体抽取通常发生在笔记创建后的后台处理里；对话发生在用户显式提问时；embedding 更像检索系统的基础设施。把它们都交给同一个模型，表面简单，实际会把隐私、延迟和质量问题混在一起。

所以当前 Synapse 的后端先做一层路由：

输入内容
  → 隐私检测
  → 判断任务类型
  → 判断文本长度和本地优先策略
  → 本地 Ollama 或云端 OpenAI-Compatible API
  → 记录成本 / 处理熔断 / 必要时降级

这条链路最重要的不是“用了哪个模型”，而是每一步都在降低系统不可控性。

第一层：隐私先挡住

Synapse 里的隐私判断在 app/core/privacy.py。当前实现不是单纯让模型猜，而是先用规则做确定性检测：

• 身份证号、手机号、邮箱、银行卡、信用卡、私钥等正则。
• 密码、token、病历、工资、住址等敏感关键词。
• 可选的本地语义检测，由 Ollama 小模型做 YES / NO 辅助判断。

这一步输出的是 PUBLIC、SENSITIVE、HIGHLY_SENSITIVE 三档。到 AIService 里，HIGHLY_SENSITIVE 会强制走本地模型。

这也是我对隐私优先的理解：不是在产品文案里说“重视隐私”，而是让敏感内容在架构上没有机会进入云端路径。

第二层：本地优先不是全本地

Synapse 的默认配置里有几个关键参数：

• cloud_ai_enabled
• cloud_ai_model_chat
• cloud_ai_model_embed
• ai_use_local_first
• ai_local_text_max_length
• ai_cloud_timeout_seconds

这里最关键的是 ai_use_local_first 和 ai_local_text_max_length。当前默认策略是：如果启用了本地优先，并且文本长度没有超过阈值，就走本地 Ollama；长文本或复杂任务再考虑云端。

这不是“本地模型一定更好”，而是先把低风险、低复杂度、低成本的任务留在本地。

云端未启用 → 本地
高敏感 → 本地
本地优先 + 短文本 → 本地
长文本 / 更复杂任务 → 云端

这个设计来自一个很朴素的现实：本地模型适合处理明确、短小、隐私敏感的任务；云模型更适合长文本、复杂推理和高质量表达。二者不是信仰选择，而是资源调度。

第三层：对话默认更偏向云端

在 AIService.chat 里，对话任务有一个特殊处理：它会用 force_cloud 倾向云端。

原因很简单：用户问问题时，对答案质量和稳定性的预期更高。摘要失败可以晚一点补，实体抽取失败可以重跑，但一次对话如果回答跑偏，体验会直接断掉。

不过代码里没有把云端当成唯一出口。云端调用失败时，会降级到本地 Ollama：

conversation
  → 优先云端
  → 云端不可用
  → 降级本地
  → 本地也不可用
  → 返回空结果，由对话服务给出可理解的错误提示

这比“永远云端”更稳，也比“永远本地”更实际。

第四层：RAG 对话先检索，再生成

对话不直接把用户问题丢给模型。conversation_service.py 里先用 search_semantic 检索相关笔记，再把摘录拼进 prompt。

当前实现有几个真实细节：

• 语义检索 topK 是 8。
• 每条笔记摘录会控制在大约 400 字符。
• 如果向量检索没有命中，会退化到最近几条笔记。
• 返回结果里带 citations，包含 note_id、标题、摘录和相关分数。
• 多轮对话会把最近历史拼进 prompt，并控制总长度。

这里要说一个真实边界：当前 Synapse 的向量检索粒度主要还是 note-level embedding。也就是说，Qdrant 里存的是笔记向量，不是成熟的 chunk 级索引。后续如果笔记越来越长，需要把 chunk 层补上，否则长笔记内部的精确召回会有上限。

第五层：运行时配置，而不是每次改环境变量

Synapse 有一个我很喜欢的点：云端模型配置不只写在 .env 里。

cloud_ai_runtime.py 做了一个进程内覆盖层，管理端可以通过 /api/v1/admin/ai-cloud 修改这些配置：

• 是否启用云端模型。
• 云端 base URL。
• chat 模型和 embedding 模型。
• API Key。
• 本地优先开关。
• 本地文本长度阈值。
• 云端超时时间。

Web 控制台里的 CloudModelsPage 对应了这套能力。它不是为了“看起来像后台”，而是为了让模型路由可以在运行中调整。

这对个人系统也很重要。比如本地模型升级了，可以把阈值调大；云端接口不稳定，可以临时关闭云端；某个模型质量下降，可以切换模型名，而不用重启整个服务。

第六层：熔断、心跳和成本记录

模型调用最怕一种情况：外部服务已经不稳定了，系统还在持续打过去，把延迟、失败和成本一起放大。

Synapse 现在做了三件事：

1. CircuitBreaker：本地和云端各有熔断器，连续失败后短时间拒绝调用，之后进入半开试探。
2. Cloud AI heartbeat：启动后有后台心跳任务，也可以在管理端手动探测云端模型是否健康。
3. CostTracker：云端生成后记录 input / output tokens，并按模型价格估算成本。

这些看起来像运维功能，但实际上会反过来影响产品体验。一个 AI 记忆系统如果不能知道“模型现在是否健康”“这次调用花了多少钱”“失败后怎么降级”，就很难长期稳定运行。

也要诚实说当前边界：成本追踪已经落库和进 Redis，can_use_cloud 也已经有预算判断，但它还没有完整接入 AIService._should_use_cloud 的路由决策。也就是说，当前更像“记录与观察已经具备”，下一步才是“预算成为路由门闸”。

这套设计给我的提醒

如果只看最终效果，用户只会看到一句回答、一段摘要、几个实体标签。但在系统里面，真正难的是这些问题：

• 这段内容能不能出本地？
• 这个任务是否值得用云端？
• 云端失败后是否有退路？
• 检索上下文是否足够可靠？
• 成本是不是可见、可控、可解释？
• 配置能不能在不重启的情况下调整？

Synapse 当前的答案还在演进，但方向已经确定：模型不是系统中心，路由才是系统中心。模型会变，供应商会变，本地硬件会变，真正要沉淀下来的是一套判断和调度机制。

如果把 Synapse 看成一个长期记忆系统，模型路由其实是在回答一个更大的问题：哪些记忆应该留在本地，哪些问题值得借助云端，哪些失败必须被系统消化掉。

这比“接一个更强的模型”慢一点，但更像一个能长期运转的系统。