最近这段时间我一直在重构自己手上一个AI相关的应用每天面对几千行纠缠在一起的代码加上到处散落的prompt、模型调用、数据处理逻辑说实话改一个功能要翻半天改完还担心把别的地方弄坏。后来我痛下决心把整个项目按模块重新切了一遍那感觉简直是从泥潭里爬出来。回头看这件事我越发觉得在AI时代代码能力固然重要但“分模块化”的能力才是真正决定一个工程师能不能走得远的底层技能。这篇文章我想把这段时间踩过的坑、总结出来的方法论、以及一套可以直接照着做的实操路径完完整整写出来。不管你是刚入门AI开发的新人还是正在被各种AI项目维护成本折磨的工程师这篇文章都应该能给你一些真正有用的东西。1. 为什么AI时代反而更需要“分模块化”1.1 一段真实经历第一个AI小工具怎么变成维护噩梦去年我开发了一个基于大模型的文本处理工具一开始功能很简单接收用户输入调用模型接口返回处理结果。代码量不大总共也就几百行我当时图省事把所有逻辑都写在一个脚本里。prompt是字符串拼接的模型调用散落在各个函数里数据处理和接口返回的逻辑也混在一起。上线第一个月一切正常第二个月开始加新需求问题就来了。产品说要支持多种输出格式我改了一处模板结果影响了另一个功能的输出结构后来要换模型我又得满文件找所有调用点再后来要加缓存、加日志、加限流每个功能都是在原本纠缠不清的代码里硬塞。那段时间我每天最怕的事情就是收到测试反馈因为每修一个bug大概率会引入两个新bug。这不是因为我编码能力差而是因为我忽略了一个最基本的原则当一个系统的复杂度超过某个阈值如果不主动对它进行结构化管理它就会以肉眼可见的速度走向失控。AI应用尤其如此因为它在传统代码之外还多了模型、prompt、数据流、评估这些全新的维度。1.2 模块化的本质是控制复杂度很多人觉得模块化就是“把代码拆成多个文件”这个理解太表面了。真正的模块化拆的不只是代码更是职责、边界和依赖关系。我经常用一个生活类比来解释这件事一个餐厅的后厨如果所有食材、厨具、调料都堆在一个台面上一个厨师炒菜时随手就能拿到东西看起来很高效。但当客人多起来多个厨师同时开工这个台面就会变成灾难——有人要盐找不到盐有人炒好的菜没地方放有人在清洗区切菜导致地面全是水。模块化就是把后厨划分成清洗区、切配区、灶台区、出餐区每个区域有专人负责、有明确的交接流程。代码的模块化是一样的道理每个模块有清晰的职责模块之间有明确的接口约定一个模块内部怎么折腾不影响其他模块的正常运转。在传统软件开发中模块化是一个最佳实践到了AI时代它从一个“好习惯”变成了“生存技能”。为什么因为AI应用的复杂度增长是非线性的模型的能力在膨胀业务的需求在膨胀如果你的代码结构跟不上爆掉只是时间问题。1.3 AI时代模块化的三个新变化传统软件的模块化主要围绕函数、类、服务来组织。AI应用带来了几个全新的拆分维度这是我这次重构过程中体会最深的。第一个新维度是模型层与业务逻辑层的分离。过去写代码调用一个API就完事了但在AI应用里模型是一个高度可变的组件。你今天用A模型明天可能换B模型同一套业务逻辑可能要支持多个模型来回切换。如果你把模型调用硬编码在业务代码里每次换模型都是一次伤筋动骨的手术。第二个新维度是prompt的模块化。prompt在AI应用里就是一段特殊的“代码”它直接决定模型输出质量。但prompt又和普通代码不一样它是文本、是配置、是需要反复试验迭代的东西。好的做法是把它当成独立的资源模块来管理而不是散落在业务代码的字符串拼接里。第三个新维度是数据流的模块化。AI应用通常涉及数据清洗、格式转换、上下文管理、结果校验等多个环节这些环节天然就是可以拆分的模块。把数据流拆清楚每个环节单独调试、单独优化整个系统的可维护性会大幅提升。2. AI工程里的模块到底该怎么切2.1 纵向切数据、模型、服务、应用四层模块划分没有唯一标准答案但在AI工程里一种经过大量实践验证的切法是先按“纵向分层”再按“横向拆块”。纵向分层是什么意思就是按照数据的流向和系统的职责把整个应用切成四层第一层是数据层负责数据的获取、清洗、存储和预处理。这一层不关心模型是什么也不关心业务逻辑是什么它只负责把数据变成“可以喂给模型的样子”。第二层是模型层负责模型的加载、调用、切换和版本管理。这一层是AI应用最特殊的地方它把“模型”这个外部依赖封装成一个独立的服务对外暴露一个稳定的调用接口。上层业务不需要关心你用的是哪个模型、模型部署在哪里、输入怎么拼接只要调用一个方法传入数据拿到结果。第三层是服务层负责业务逻辑的编排和组合。比如一个AI写作助手用户选择了“写一篇产品文案”这个功能服务层就负责决定要不要先做关键词提取要不要先生成大纲再调用模型生成正文最后做一遍语法检查这一层更像传统代码处理的是业务规则和流程控制。第四层是应用层负责用户交互、接口暴露和体验呈现。比如Web界面、命令行工具、API接口都属于这一层。这个四层结构的核心思想是让每一层只依赖下一层不让上层逻辑渗漏到下层也不让下层实现影响上层设计。我这次重构就是把原先一锅粥的代码按这四层重新摆放很多以前理不清的问题在分层之后思路一下就通透了。2.2 横向切按职责拆出可独立替换的零件纵向分层解决的是“从上到下”的结构问题横向切块解决的是“同一层内”的组织问题。拿服务层举例。假设你的AI应用有多个功能文案生成、摘要提取、情感分析、智能对话。如果这些功能的所有逻辑都写在一个大文件里随着功能增加文件会膨胀、互相干扰、彼此牵制。正确做法是每个功能独立成一个模块它们只通过统一的入口被调用内部实现互不可见。横向切块有一个很重要的判断标准就是可替换性。如果你切出来的模块换一个实现方式不需要动其他模块说明你切对了如果每次替换都要牵连到调用方说明边界没切好。我这次重构时把“模型调用”单独摘出来做成一个模块后来测试不同供应商的模型时我只需要换这个模块的内部实现上层代码一行没改。这个体验让我真正明白了什么叫“高内聚、低耦合”。2.3 判断模块划分好坏的标准很多人在划分模块时很纠结不知道到什么程度算好什么程度算差。我自己总结了三把尺子每次拿不准的时候就拿出来量一量。第一把尺子叫单一职责。一个模块应该只有一个让它被修改的理由。如果你发现改一个需求要动三个模块或者一个模块里有两件不相干的事情那就是划分错了。比如我之前把“数据清洗”和“结果格式化”放在同一个模块里后来发现数据清洗是因为上游数据格式变化而改动结果格式化是因为下游展示需求变化而改动两个改动理由完全不同硬拆到一处就是灾难。第二把尺子叫依赖方向清晰。模块之间的依赖关系应该形成一个清晰的、单向的结构尽量避免循环依赖。A依赖B、B依赖C这是健康的A依赖B、B又依赖A这是警报。出现循环依赖时要么是边界没划对要么是需要引入一个抽象的第三方来打破循环。第三把尺子叫可独立测试。如果一个模块可以脱离整个系统单独测试它的设计就是成功的。我重构后最明显的一个感受是测试好写多了。以前要测一个业务逻辑得把模型调用、数据库、外部接口全部mock一遍现在只需要把依赖的模块接口mock掉就能专注测当前模块的逻辑。3. 实操记录从零搭建一个分模块的AI应用3.1 一个具体的例子AI文档问答系统光讲理论没用我拿一个具体的项目来说清楚整个实操过程。假设我们要做一个AI文档问答系统用户上传一批文档系统解析文档内容用户可以基于这些文档进行提问模型根据文档上下文给出回答。这个系统看起来不复杂但如果一上来就写代码大概率会写成一坨。按照分模块化的思路第一步不是写代码而是画边界。我把这个系统拆成了五个模块文档解析模块负责读取PDF、Word、TXT等格式抽取文本内容。它不关心下游怎么用这些文本只负责输出干净的纯文本。文本处理模块负责把长文档切分成合适大小的片段做清洗、去重、索引。它接收文档解析模块的输出产出一个可检索的文本库。检索模块负责根据用户问题从文本库中找到最相关的片段。它不关心模型怎么用这些片段只负责返回“相关片段列表”。答案生成模块负责调用大模型把用户问题和相关片段组装成prompt生成最终答案。它不关心检索怎么实现的只关心拿到的是什么。应用入口模块负责接收用户请求、串联整个流程、返回结果给前端。3.2 定义接口是模块化最关键的步骤模块划分好之后紧接着做的最重要的事情就是定接口。接口就是模块之间的“合同”合同定清楚了每个模块内部怎么做就变成了自己的事情。实际操作时我会先定义每个模块的输入输出数据结构。比如检索模块它的输入是一个字符串用户问题加上可选的参数返回片段数量输出是一个列表每个元素包含片段内容和对应的相似度分数。这个接口一旦定下来文档解析模块和答案生成模块都不需要知道检索模块内部是怎么实现的。这里我要特别强调一个技巧接口的数据结构要比模块的实现更稳定。我见过很多人接口设计得很随意今天传个字符串明天传个对象后天又要加参数。结果就是模块之间频繁联动改接口比改实现还频繁。好的接口设计应该尽量稳定宁可多定义几个明确的类型也不要用松散的结构。3.3 把模型调用封装成独立模块后的好处答案生成模块是整个系统里最特殊的一块因为它核心依赖外部大模型。我在重构时把它单独拎出来并且做了很薄的一层封装。这个封装对外暴露的方法很简单传入一个问题、一组上下文片段、一些生成参数返回一个答案字符串。这个封装带来的好处我在项目过程中体会得非常深刻。第一次是项目初期模型服务不稳定经常超时或者报错。因为调用都集中在一个模块里我只在这个模块里做重试、降级和超时处理整套机制就生效了其他模块完全不受影响。第二次是换模型的时候。我们一开始用了通用模型后来发现专业领域回答效果不好要切换到一个微调过的模型。因为模型调用被封装起来了切换时我只改了这个模块的内部配置接口完全没变上层几个模块一行代码都没动整个切换过程只花了一个下午。如果模型调用还是像以前那样散落在各个业务函数里这两次调整每一回都意味着全项目的排查和修改。3.4 prompt和配置也要模块化这是我这次重构中收获最大、也最想提醒大家的一点prompt要当作一等公民来管理绝不混在业务代码里。我在项目里专门建了一个prompt管理模块它做的几件事情包括第一把每个场景的prompt模板抽象成独立文件不再散布在调用代码中。文案生成的模板、问答系统的模板、摘要提取的模板各自独立存放通过名称来引用。第二把prompt中的变量占位符规范化。我用的是统一的{变量名}格式这样模板和代码之间的契约非常清晰代码负责传值模板负责组织语言两者互不干扰。第三对prompt做版本管理。prompt是会被反复调整的调整一次就换一个版本并且记录它对应的模型和效果指标。这样以后要回溯“为什么输出变好了/变差了”的时候能快速找到是哪个版本造成的。类似的模型的配置参数比如温度、最大token数、top-p这些也不应该硬编码在代码里。我都把它们放到配置文件中按场景分组管理。同一个场景调优时改配置文件就能生效不需要重新发布代码。4. 我在模块化落地中踩过的坑4.1 坑一模块切得太细反而拖慢效率模块化不是越细越好。我刚开始重构时抱着“彻底模块化”的心态把一个小功能也拆出四五个模块结果每改一个需求要跨好几个文件光是找到要改的地方就要翻半天。代码是“干净”了但效率反而下降了。后来我意识到模块划分的粒度要跟项目的复杂度和团队的规模匹配。一个十几行的小函数不值得硬拆成一个模块一个几十个文件的复杂系统也不能所有逻辑塞一个文件。我总结的经验是一个模块的体量大概控制在两三百行到上千行之间职责单一优先体量适中也重要两者要平衡。4.2 坑二模型升级导致接口崩溃有一次我给系统的模型层模块升级了新版本的模型服务SDK结果发现SDK的返回值结构变了原来直接能拿到文本内容新版本变成了嵌套了更多层级的结构。因为我当时只改了一处调用漏掉了另外几处上线后部分功能直接报错。这件事给我两个教训第一封装模型调用的模块在内部处理好SDK的兼容问题输出给上层的数据结构永远保持稳定第二任何模块升级后都要跑一遍完整的回归测试不能只测主流程。现在我做模块升级都会先看一眼这个模块的所有依赖方有哪些确保每个调用点都被覆盖到。4.3 坑三团队成员跨模块改代码不是所有项目都是一个人开发。我参与过的一个团队项目里大家虽然分了模块但实际开发时经常出现“顺手”改别的模块代码的情况。最典型的是有人为了给自己的模块加一个功能在别的模块里硬塞了一段代码结果那个模块的负责人根本不知道后续维护时被坑得很惨。解决这个问题的办法是在代码评审环节就设好红线。凡是涉及其他模块的修改必须经过该模块负责人的同意并且要在评审记录里写明原因。模块边界本质上是一种“团队契约”光靠自觉维系不住要靠流程来规范。4.4 问题速查表现象根因解决办法改一个需求要动三四层模块职责划分不清用“单一职责”标准重新审视每个模块模块A改动导致模块B失效模块间存在隐藏依赖检查是否有绕过接口的直接变量或全局状态换模型要改全项目模型调用没有封装建立独立的模型层模块上层只依赖稳定接口prompt修改后无法回溯prompt散落且无版本管理建立prompt管理模块统一模板和版本新功能无处安放模块粒度过细/过粗重新评估模块边界必要时合并或拆分接口频繁变动接口设计未提前约定先定数据结构再写实现让接口先于实现稳定5. 模块化之外AI工程师还需要这些配套能力5.1 配置化与版本控制是模块化的左膀右臂模块化不是孤立存在的它需要配套的工程能力才能真正发挥作用。第一个配套能力是配置化。模块之间的切换、模型参数的调整、prompt模板的替换都应该尽量通过配置完成而不是改代码。把配置从代码中剥离出来模块化才能做到“接口稳定、实现可变”。第二个配套能力是版本控制。这不只是指代码的Git管理更是指对模型、prompt、数据集、评估结果这些AI特有的资产做版本管理。我在项目里会为每个prompt版本记录对应的模型、参数和评测结果这样在做回归对比时能精准定位是哪个因素导致了效果变化。5.2 测试与评估要跟着模块走很多AI项目的测试做得很薄弱要么只测接口通不通要么只看一两个样例的输出效果。模块化之后测试就可以做得更有层次。我的做法是每个模块维护自己的一组单元测试验证输入输出符合接口约定模块之间的联调测试放在服务层验证数据流转正确最后是针对模型输出的评估测试用一批固定的评测用例定期跑监控效果波动。这三层测试跟模块结构一一对应哪一层出了问题能快速定位到对应的模块。5.3 模块Owner机制让边界有人守护最后说一个团队协作层面的心得。多人在一个AI项目上协作时每个模块都应该有一个明确的Owner这个Owner不是“写了这个模块的人”而是“对这个模块的质量和稳定负责的人”。别人要改动这个模块必须要有Owner的参与和确认。我当时吃过亏觉得大家都是一个团队的边界不用太较真。结果就是一个模块被三个人分别改过每个人都按自己的习惯加了逻辑最后模块里堆了三种风格完全不一致的代码接口也出现了两套并行的用法。后来确立了Owner机制这种事才彻底杜绝。模块化的本质是用结构化的方式对抗复杂度。在AI时代模型能力越来越强、应用场景越来越丰富、系统边界越来越宽复杂度只会不断上升。与其依赖个人的记忆力去维护一个混乱的系统不如从一开始就把模块边界划清楚用契约和规范去管理复杂度。我在这轮重构中实际感受到的最大变化是以前改代码靠胆量现在改代码靠地图——我知道每个模块在哪、边界在哪、改动的风险范围在哪。这篇文章里写的每一招都是我自己动手验证过的希望也能帮你在AI项目里少踩几个坑。