六层依赖架构如何落地，从影片推荐智能体看分层设计与技术选型逻辑

在构建复杂AI应用时，架构设计常被简化为“用什么框架”或“选哪个模型”，但真正决定项目长期可维护性的，是模块间的依赖关系是否清晰、变更边界是否明确。近期一篇《从零造一个影片推荐智能体》系列文章中提出的“六层依赖架构”，提供了一个具象化的工程范本：它不追求理论完美，而是通过严格的单向依赖约束，将变化关进笼子，让系统在迭代中保持稳定。

该架构自顶向下分为六层：应用/接口层 → Agent编排层 → 推荐引擎层 → 知识/特征层 → 数据接入层 → 基础设施层。其核心表达为一行依赖链：api/ → agent/ → retrieval/ + ranker/ → vector/ + graph/ → etl/ + db/ → config/ + llm/ + data/。这意味着上层可调用下层，但下层绝不可反向引用上层——这一规则被写入编码规范，违者需通过中间层（如retriever/factory）解耦，而非硬连。

这种分层并非凭空而来。作者指出，许多项目烂掉的起点，正是跳过架构设计直接写业务代码：utils.py里塞数据库连接，api/反向import agent/内部函数，改一个召回权重要翻五个文件。当缓存、监控、重试等横切关注点陆续加入时，系统迅速陷入泥潭。而六层架构的本质，是把“谁和谁一起变”作为分包依据——这正呼应了Martin Fowler倡导的单一职责原则在目录层面的落地：一个包只应因一种原因被修改。

图1清晰呈现了该架构的运行流：Vue3前端负责SSE流式渲染、反馈UI与海报轮询；FastAPI暴露/recommend/stream等接口并集成日志、CORS、限流等中间件；LangGraph Agent驱动多步流程；底层则由检索/排序模块对接向量库与图谱。值得注意的是，文档称“六层”，图中仅五块区域，实因“基础设施层”（config/llm/data）未单独绘出，而是作为隐性支撑存在于各层之下——这种“可见层+隐形基座”的划分，在实践中更贴近真实部署形态。

在关键组件选型上，该项目放弃纯LangChain LCEL的线性链路，转而采用LangGraph构建有状态Agent。原因在于：真实推荐流程存在分支与状态传递——用户输入“太空科幻片”后，系统需依次完成意图解析、规划召回策略、执行查询、反思候选集完整性（不足5条则自动补高分榜兜底）、最终生成带解释的推荐。LangGraph的StateGraph允许定义parse_intent → plan → execute → reflect → generate五个节点，其中reflect内部处理“查不够就补”的逻辑，避免图上出现回环箭头，同时保留流程可控性。

推荐引擎层进一步细分为三路召回（content/向量、relation/同剧组、coldstart/高分榜）、融合策略（RRF+MMR多样性+云精排qwen3.7-text-rerank），以及反馈调权机制（genre_affinity/item_boost/item_blacklist）。这种组合不是堆砌，而是针对不同场景的补偿设计：冷启动靠榜单兜底，长尾内容靠关系召回，多样性靠MMR控制，最终由大模型重排统一输出。

知识/特征层采用混合存储方案：MySQL存强一致结构化数据（如影片元信息），Chroma/Qdrant存向量，Neo4j存关系图谱。这种异构设计源于数据特性差异——结构化字段更新频率低、一致性要求高；向量需支持近邻搜索；图谱则服务于“同剧组”“导演关联”等关系推理。若强行统一到单一数据库，要么牺牲查询效率，要么增加冗余计算。

数据接入层包含douban_main、imdb_main及其衍生关系与文本模块，确保原始数据可追溯、可增量更新。而基础设施层整合Redis（限流/缓存）、Ollama（本地LLM服务）、LangSmith（可观测性）与容器编排工具，构成运维底座。

该架构的深层价值，在于它将“变化隔离”转化为可执行的工程约束。例如，当需替换向量库时，只需修改vector/包内的适配器，不影响上层召回逻辑；若切换LLM供应商，仅需调整llm/层封装，Agent节点无需重写。这与另一篇关于企业级Monorepo的讨论高度一致：分层标准不是“技术名词”（如utils/service/db），而是“变化节奏”——数据库连接配置与SQL语句一起改，属同一包；七家模型的参数差异与HTTP客户端一起改，也属同一包；但MySQL schema与Milvus collection定义几乎永不共变，必须拆开。

图2与图3进一步佐证了这一思路：在具体数据结构选型中，需求驱动决策。例如，“单Key多大、多少QPS”对应String或Hash；“能否断开、能不能迁”指向Zset或Bitfield；“涉及几个Key？跨不跨slot？”则需考虑MULTI或CROSSSLOT方案。同样，序列化方式选择（String+JSON vs Hash vs 折多Key）直接影响HSET/GET次数与原子性保障，进而决定服务端并发能力。

这种精细化选型看似繁琐，实则是对“技术债”的前置防御。当系统规模扩大、团队成员增多时，模糊的依赖边界会指数级放大协作成本。六层架构的价值，不在于它多新颖，而在于它用极简的规则（单向依赖+变化归因）锚定了复杂系统的演化路径。

当前AI应用开发正从“能跑通”迈向“可持续”，架构设计的重要性日益凸显。无论是影片推荐智能体还是GEO优化服务，成功的共性在于：先画清依赖地图，再动手写第一行代码。那些省略此步的项目，往往在第三个月开始偿还技术债务；而坚持分层约束的团队，则能把迭代重心放在业务逻辑本身，而非救火式重构。

值得补充的是，该架构并非普适模板。它适配的是中等规模、强调可解释性与反馈闭环的推荐场景；若面向高并发广告排序，可能需强化实时特征管道；若专注生成式内容，则需加强prompt工程与幻觉检测层。架构的生命力，始终在于与业务节奏的贴合度——没有银弹，只有取舍。