Tricoder/doc/平台设计/后端服务拆分设计.md

后端服务拆分设计

版本号：v0.1.0 最后更新：2026-04-04

1. 目的

本文档用于定义第一阶段后端服务的拆分方式，明确各服务的职责、边界和协作关系。

2. 拆分原则

第一阶段的服务拆分应遵循以下原则：

• 按职责拆分，而不是按技术炫技拆分
• 先保证主链路清晰，再考虑进一步解耦
• 能单体时不强拆，能边界清晰时不混杂

3. 第一阶段服务建议

第一阶段建议逻辑上拆为四个核心部分：

1. API 服务
2. AI 编排服务
3. 实验执行服务
4. 模型服务

其中：

• API 服务与 AI 编排服务在第一阶段可以部署在同一 Python 进程或同一应用中
• 模型服务可以独立部署
• 实验执行服务建议独立出来

4. API 服务

4.1 职责

API 服务负责：

• 接收终端请求
• 鉴权与会话入口
• Observation 创建
• 分析任务创建
• 查询 Experiment 和 Conclusion
• 推送状态变更

4.2 不负责

API 服务不负责：

• 直接实现复杂 AI 决策
• 直接运行重型算法链

5. AI 编排服务

5.1 职责

AI 编排服务负责：

• 汇总当前上下文
• 调用模型
• 生成假设
• 生成实验计划
• 生成阶段性结论和最终结论

5.2 输入

• Observation 摘要
• Evidence 列表
• Experiment 历史摘要
• 可用链模板与模块摘要

5.3 输出

• OrchestratorPlan
• InterimConclusion
• FinalConclusion

6. 实验执行服务

6.1 职责

实验执行服务负责：

• 读取实验计划
• 用注册表校验计划
• 调用算法模块
• 收集中间输出
• 生成 Evidence
• 生成 ScoreCard
• 记录 failureReasons

6.2 不负责

实验执行服务不负责：

• 解释业务意义
• 直接面向用户输出最终结论

7. 模型服务

7.1 职责

模型服务负责：

• 托管 Gemma 4
• 提供稳定推理接口
• 统一模型版本和配置

7.2 与 AI 编排服务的关系

AI 编排服务是模型服务的调用方。

模型服务不理解实验业务，只负责模型推理。

8. 存储层职责

虽然存储层不是“服务”，但它在拆分设计中非常关键。

建议统一保存：

• Observation
• Evidence
• Experiment
• Conclusion
• Session 状态

这样所有服务都围绕同一批核心实体协作，而不是各自维护私有状态。

9. 推荐协作流程

推荐第一阶段流程如下：

1. Flutter 终端上传样本
2. API 服务创建 Observation 和分析任务
3. API 服务触发本地或远端初始 probe
4. AI 编排服务读取当前上下文，生成实验计划
5. 实验执行服务执行计划并写回 Experiment/Evidence
6. AI 编排服务继续判断是否进入下一轮
7. 形成 Conclusion
8. API 服务返回给终端

10. 第一阶段部署建议

第一阶段建议偏保守部署：

• API 服务 + AI 编排服务：一起部署
• 实验执行服务：独立部署
• 模型服务：独立部署
• PostgreSQL：独立实例

这样可以在保持边界清晰的同时，避免第一阶段服务过多导致运维复杂。

11. 后续可扩展方向

当系统成熟后，可进一步扩展：

• 独立任务队列
• 独立调度器
• 多执行 worker
• 多模型路由
• 多模态执行器拆分

但这些不应成为第一阶段前置条件。

12. 结论

第一阶段后端服务拆分建议为：

• API 服务
• AI 编排服务
• 实验执行服务
• 模型服务

其中 API 与 AI 编排可暂时合并部署，实验执行与模型服务保持独立，既保证边界清晰，也保持实现可控。