API-AI-000：AI Runtime 总体架构设计 #161

New Issue

wangdl · 2026-06-10T21:01:45+08:00

wangdl commented

2026-06-10 21:01:45 +08:00

背景

当前知习已完成学习信息收集体系，下一阶段需要接入 AI 学习分析、DeepSeek 调用、学习状态分析、题目 / 卡片生成候选等能力。本批新增 Rust Heavy Runtime 作为内部重任务执行器，但主业务 API 不变。

目标

设计 API 项目与 Rust Heavy Runtime 的总体架构、职责边界、部署方式、通信方式、任务流、数据流、失败处理和后续扩展边界。

核心原则

API 是业务权威层。
Rust Heavy Runtime 是内部重任务执行器。
iOS / Admin / 外部用户不直接访问 Runtime。
Runtime 不暴露公网接口。
本批不迁移 RAG。
本批只处理 AI 分析、DeepSeek 调用、题目 / 卡片候选生成。
Runtime 不直接写最终业务主表。
所有结果最终由 API 校验、落库、对外提供查询。

需要设计的内容

API / Runtime / iOS / Admin / Rust document runtime 职责边界。
Docker 内部网络部署方式。
Runtime 服务发现方式。
API 与 Runtime 的内部通信方式。
AI Job 创建、消费、回传、落库流程。
用户 DeepSeek key 与平台 key 的职责边界。
Runtime 执行失败、超时、重试、取消机制。
Runtime result 与业务数据落库边界。
后续 RAG 迁移的预留边界，但本批不实现。

与现有 RAG / Chat 系统的关系与共存策略

本批 AI Runtime 不迁移现有 RAG。
现有 Chat / RAG 问答链路继续保持。
新 AI Runtime 只处理学习分析、题目生成、卡片生成候选。
若 Chat 结果和 AI Analysis 结果同时存在，前端应区分"对话回答"和"学习分析建议"。
后续 RAG 迁移需要独立里程碑，不在 M-API-AI-RUNTIME 中实现。

不做范围

不迁移 RAG。
不重写主 API。
不让 Runtime 直接对外提供用户 API。
不让 Runtime 直接处理登录、会员、知识库 CRUD。
不做完整 Agent 框架。
不开放用户自定义 baseUrl。

验收标准

输出 docs/ai-runtime-architecture.md。
文档明确 API 是业务权威层。
文档明确 Runtime 是内部重任务执行器。
文档明确 Runtime 不对公网暴露。
文档明确 Docker 内部网络部署方式。
文档明确本批不迁移 RAG。
文档明确 AI Job 异步流程。
文档明确 Runtime 结果最终由 API 校验和落库。
文档明确后续 iOS / Admin 只访问 API，不访问 Runtime。
文档明确后续 RAG 迁移只是预留，不在本批实现。

## 背景当前知习已完成学习信息收集体系，下一阶段需要接入 AI 学习分析、DeepSeek 调用、学习状态分析、题目 / 卡片生成候选等能力。本批新增 Rust Heavy Runtime 作为内部重任务执行器，但主业务 API 不变。 ## 目标设计 API 项目与 Rust Heavy Runtime 的总体架构、职责边界、部署方式、通信方式、任务流、数据流、失败处理和后续扩展边界。 ## 核心原则 1. API 是业务权威层。 2. Rust Heavy Runtime 是内部重任务执行器。 3. iOS / Admin / 外部用户不直接访问 Runtime。 4. Runtime 不暴露公网接口。 5. 本批不迁移 RAG。 6. 本批只处理 AI 分析、DeepSeek 调用、题目 / 卡片候选生成。 7. Runtime 不直接写最终业务主表。 8. 所有结果最终由 API 校验、落库、对外提供查询。 ## 需要设计的内容 1. API / Runtime / iOS / Admin / Rust document runtime 职责边界。 2. Docker 内部网络部署方式。 3. Runtime 服务发现方式。 4. API 与 Runtime 的内部通信方式。 5. AI Job 创建、消费、回传、落库流程。 6. 用户 DeepSeek key 与平台 key 的职责边界。 7. Runtime 执行失败、超时、重试、取消机制。 8. Runtime result 与业务数据落库边界。 9. 后续 RAG 迁移的预留边界，但本批不实现。 ## 推荐架构 ``` iOS / Admin ↓ 主 API ↓ AiRuntimeJob / LearningAnalysisSnapshot ↓ Rust Heavy Runtime ↓ DeepSeek ↓ Rust Heavy Runtime 输出结构化结果 ↓ 主 API 二次校验 / 落库 ↓ iOS 展示 / Admin 诊断 ``` ## 与现有 RAG / Chat 系统的关系与共存策略 1. 本批 AI Runtime 不迁移现有 RAG。 2. 现有 Chat / RAG 问答链路继续保持。 3. 新 AI Runtime 只处理学习分析、题目生成、卡片生成候选。 4. 若 Chat 结果和 AI Analysis 结果同时存在，前端应区分"对话回答"和"学习分析建议"。 5. 后续 RAG 迁移需要独立里程碑，不在 M-API-AI-RUNTIME 中实现。 ## 不做范围 1. 不迁移 RAG。 2. 不重写主 API。 3. 不让 Runtime 直接对外提供用户 API。 4. 不让 Runtime 直接处理登录、会员、知识库 CRUD。 5. 不做完整 Agent 框架。 6. 不开放用户自定义 baseUrl。 ## 验收标准 1. 输出 docs/ai-runtime-architecture.md。 2. 文档明确 API 是业务权威层。 3. 文档明确 Runtime 是内部重任务执行器。 4. 文档明确 Runtime 不对公网暴露。 5. 文档明确 Docker 内部网络部署方式。 6. 文档明确本批不迁移 RAG。 7. 文档明确 AI Job 异步流程。 8. 文档明确 Runtime 结果最终由 API 校验和落库。 9. 文档明确后续 iOS / Admin 只访问 API，不访问 Runtime。 10. 文档明确后续 RAG 迁移只是预留，不在本批实现。

wangdl added this to the M-API-AI-RUNTIME：API AI Runtime 调度与落库 milestone 2026-06-10 21:01:45 +08:00

wangdl added the

labels 2026-06-10 21:01:45 +08:00

wangdl commented

2026-06-11 20:43:59 +08:00

完成证据

产物: docs/ai-runtime-architecture.md (295 行)
提交: 804c414 feat: AI Runtime 总体架构文档 (API-AI-000)

覆盖内容:

API / Rust Heavy Runtime / document runtime / iOS / Admin 职责边界
Docker 内部网络部署（heavy-runtime 不暴露公网端口）
Job 异步任务流（API 创建 → Runtime poll → lock → execute → result）
用户 Key 与平台 Key 管理
失败重试与熔断
Runtime result 落库边界（API 二次校验）
与现有 M1 RAG/Chat 的共存策略
后续 RAG 迁移预留

验收: 10 条验收标准全部覆盖

## 完成证据 **产物**: `docs/ai-runtime-architecture.md` (295 行) **提交**: `804c414` feat: AI Runtime 总体架构文档 (API-AI-000) **覆盖内容**: - API / Rust Heavy Runtime / document runtime / iOS / Admin 职责边界 - Docker 内部网络部署（heavy-runtime 不暴露公网端口） - Job 异步任务流（API 创建 → Runtime poll → lock → execute → result） - 用户 Key 与平台 Key 管理 - 失败重试与熔断 - Runtime result 落库边界（API 二次校验） - 与现有 M1 RAG/Chat 的共存策略 - 后续 RAG 迁移预留 **验收**: 10 条验收标准全部覆盖

wangdl closed this issue

2026-06-11 20:44:00 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/api-server#161