基于 FastAPI Qdrant 构建可解释、可约束的教育 Agent一整体架构与请求生命周期项目背景本文介绍一个面向高校人工智能通识课的个性化教学智能体Learning Agent启芯智教的整体设计。项目将智能问答、学习画像、知识库检索、学习规划、资源生成、题目练习与教学管理整合为一套连续的学习工作台。与常见的大模型 API 聊天界面封装不同本项目的核心目标是构建一条可解释、可约束、可评测的 Agent 链路覆盖检索、路由、预算、复核与调用关联。本文为系列第一篇先给出整体架构与一次请求的完整生命周期后续文章再逐个拆解模块。技术栈React 18 TypeScript、FastAPIPython 3.11、Qdrant、BGE-M3、SQLite/PostgreSQL、Redis。文章目录基于 FastAPI Qdrant 构建可解释、可约束的教育 Agent一整体架构与请求生命周期1. 问题与设计目标2. 整体架构3. 一次请求的生命周期3.1 准备上下文3.2 风险评估3.3 路由选路3.4 执行生成3.5 交付收口4. 统一 Agent Runtime5. 技术选型6. 工程实践中的问题与处理7. 系列规划结语1. 问题与设计目标在真实教学场景中一个仅完成接收问题 → 调用大模型 → 返回结果的系统会很快遇到几类问题答非所问与幻觉回答不基于课程资料模型会生成看似合理但无依据的内容行为不一致对话、资源生成等不同入口各自实现取画像、带记忆、做安全校验的逻辑随迭代逐渐产生策略漂移成本不可控缺少对模型调用次数、token 与成本的硬性约束不可审计没有统一的运行标识与调用关联出现问题时无法复现、无法定位外部数据风险Agent 可读取上传文档若不做隔离与消毒易受提示注入prompt injection影响。据此确定的设计原则是关注一次 Agent 运行的完整链路而非单次模型调用。具体要求为检索可追溯、路由可解释、预算可约束、风险可复核、结果可评测。2. 整体架构系统整体采用分层架构主链路纵向处理业务知识引擎RAG作为旁路为对话与资源生成提供证据各层职责如下。接入层前端为 React 学习工作台承载学习、问学、资源、成长、我的五个入口请求经 FastAPI 网关完成鉴权、限流与参数校验。业务管线层分为 Chat Pipeline同步 / 流式对话与 Resource Pipeline资源生成工作流对应两类不同业务但共用同一套运行时。统一 Agent Runtime系统核心包含模型路由、硬预算、风险复核、检查点与调用链追踪五个部分。聊天与资源生成复用同一运行时以保证画像、记忆、证据与安全策略的一致性。模型服务层对接对话大模型、Embedding、Rerank 与视觉版面模型支持多供应商主备与真实选路。知识引擎旁路将上传的 PDF、PPT、Word 等文档经过解析、清洗、结构感知切片、多路召回与 Rerank 精排产出 EvidencePack证据包注入业务管线。向量库使用 QdrantEmbedding 使用 BGE-M3。数据层轻量部署使用 SQLite生产环境可切换 PostgreSQLRedis 用于缓存、会话与限流。一个关键约束是证据以 EvidencePack 的形式注入模型回答必须基于证据知识库未检索到依据时系统需要明确说明模型自行生成的无依据内容只能标记为通用补充。3. 一次请求的生命周期架构是静态结构下面按时间顺序描述一次请求的完整处理过程3.1 准备上下文在模型生成之前系统依次拉齐学生画像、长期记忆、问题意图、RAG 证据包以及按需的联网补充profileself.profile_source(payload,user,context)# 学习画像memory_stateself.memory_source(payload,user,context)# 长期记忆problem_intentself.problem_intent_source(payload,user,context)# 问题意图evidence_packself.knowledge_source(payload,user,context)# RAG 证据包harnessself.harness_source(payload,user,context)# 联网补充按需在生成前固定上下文有两个目的一是可以对全部上下文计算context_hashSHA-256 指纹二是能够明确界定本次回答所依赖的信息保证结果可复现。3.2 风险评估系统将请求划分为low / medium / high / critical四个风险等级。例如证据较弱或存在证据冲突时至少为 medium需要复核携带附件的请求通常为 high需要缓冲与验证一旦判定为 critical典型为检测到提示注入则直接阻断不生成初稿。3.3 路由选路路由组件先进行硬资格过滤模型能力是否满足、上下文窗口是否足够、服务是否健康再依据路由策略进行确定性评分。路由策略包括fixed固定、balanced均衡、quality_first质量优先与cost_first成本优先最终输出可解释的选路决策。3.4 执行生成执行阶段对预算采取先预留、后结算在真正调用模型前锁定本次运行允许的最大调用次数、token 与成本。随后生成 draft 初稿支持流式仅在风险评估判定需要时才追加 review 复核阶段调用失败时在同一模型上先重试再考虑候选切换。3.5 交付收口交付阶段为关键结论附加引用角标章节 / 页码 / 片段、添加 AI 生成标识以流式方式输出并将必要信息回写记忆与日志。整个过程由两级标识串联run_id标识一次 Agent 运行每次模型调用记录call_id与parent_call_id用于关联阶段、重试、延迟与成本。4. 统一 Agent Runtime对话与资源生成若分别实现公共逻辑在画像读取、记忆携带、证据检索与安全策略上几乎必然出现不一致。为此项目将公共逻辑抽取为统一运行时内部结构如下Runtime 以 StageContext阶段上下文为单位逐阶段执行prepare → draft → review每个阶段按需调用三个组件RouteSelector路由选择器完成硬资格过滤与策略评分输出模型选路决策BudgetLedger预算账本管理调用数、token 与成本执行硬约束Invocation调用器发起真实模型调用并记录 call_id / parent_call_id。横切能力包括Checkpoint / Cancel检查点增量保存支持取消与恢复与Trace 关联串联事件与告警。最终输出AgentRunResult其中包含完整的调用记录、事件、告警以及partial部分结果标记。对于资源生成过程中视频未渲染、旁白未合成、联网未命中这类半成品状态系统统一标记为 partial 并交付可恢复的草稿而不是将其标记为完整成功。5. 技术选型整套方案以主流开源组件与自研逻辑为主保证可复现前端React 18、TypeScript、Vite、React Flow流程编排、CodeMirror 6代码编辑、React Markdown、KaTeX公式、Graphology图谱可视化后端Python 3.11、FastAPI、Pydantic、UvicornAgent 层分阶段 Runtime、策略路由、预算控制、风险复核、金标评测自研数据与检索SQLite / PostgreSQL、Redis、Qdrant、BGE-M3文档解析PyMuPDF、pypdf、python-docx、python-pptx可选接入 MinerU工程化Pytest、Docker Compose、GitHub Actions、统一验证脚本。在评测方面项目内置了 48 条第一版 Agent 金标数据覆盖知识问答、流式输出、路由、预算、安全与资源工作流等场景评测默认离线执行、不调用外部模型。6. 工程实践中的问题与处理记录几个在实现过程中得到验证的工程结论。统一公共逻辑避免策略漂移。对话与资源生成复用同一 Runtime 后画像、记忆、证据与安全策略只需维护一处避免了多入口分别迭代导致的规则不一致。预算必须是硬约束。调用数、token 与成本在调用前预留、调用后结算超限直接拦截。依赖自然语言提示无法可靠控制资源消耗。外部检索内容默认不可信。检索文本在进入上下文前先做消毒NFKC 归一化、去除控制字符、替换尖括号并识别忽略以上指令你现在是 …等注入企图随后以明确的不可信数据边界包裹后再放入提示词。证据不足时显式承认。教学场景下语气确定但无依据的回答比未检索到相关内容危害更大。针对职业安全、设备参数、考核标准等问题系统设置了严格门禁缺少权威依据时阻断确定性结论。7. 系列规划整个系列按四个主题组织共 16 篇知识工程与 RAG文档解析三层降级、数据清洗与结构感知切片、多路召回、Rerank 与证据包画像与记忆13 维画像的双通道采集、证据与置信度管理、长期记忆因材施教基于 FSRS 的知识状态模型、两阶段可解释推荐、自适应学习路径工程内核多模型协作、统一 Runtime、安全防护、金标评测与部署。下一篇将聚焦知识入口介绍文档在进入向量库之前如何通过 MinerU、PyMuPDF、pypdf 三层降级完成解析以及表格、图片、页眉页脚等内容的处理方式。结语本文给出了 Learning Agent 的整体架构与一次请求的生命周期核心在于将模型调用纳入可解释、可约束、可评测的工程链路。相关设计仍在持续迭代若文中存在可改进之处欢迎在评论区指出并讨论。