从标题“ai-engineering-from-scratch”说开去。这两年“AI工程”这个词被炒得很热但很少有人真正讲清楚从零开始搞一个能跑、能迭代、能上线的AI项目到底要趟过多少坑。我自己从纯业务开发转过来做了三年多最大的感受是AI项目失败的根源往往不在模型调参而在工程化链条断裂——数据集没有版本、实验无法复现、训练脚本和推理逻辑不一致、上线后没有任何监控。这篇文章不聊算法数学只聊一个真实的AI项目是怎么从裸代码长成一套可交付系统的。适合刚入门想动手的开发者也适合带团队的负责人拿来做工程规范参考。1. 为什么建议从零搭一套AI工程而不是直接套模板1.1 框架工程化项目与算法Demo的本质区别很多人第一次接触AI项目是从Kaggle比赛或者开源仓库的notebook开始的。跑通一个baseline很容易但把一个notebook变成可持续迭代的工程中间差的不是一个requirements.txt而是对数据流、实验流、部署流三套体系的完整设计。算法Demo的典型特征是数据一次性加载进内存、脚本全流程直跑、模型保存成单个pickle文件、预测函数写在同一个文件里。这套东西自己研究跑着玩完全没问题但一旦进入真实业务场景——要对接数据库、要定时重训、要给前端提供API、要响应月底涨量——马上就会出现三类问题。第一数据依赖混乱。原始表结构一改脚本立刻跑崩甚至更糟不报错只是悄悄换了一批字段模型就出错了。第二实验管理缺失。你调了十版参数最终只记得“好像第三版效果不错”但对应的特征代码、训练数据范围、随机种子全忘了任何微调都推倒重来。第三训练与推理割裂。训练时对文本做清洗用的是一套正则推断时写的又是另一套线上效果和离线评测差距大到让人怀疑人生。从零搭建AI工程本质上就是在项目第一天就把这些坑堵死。不是多写代码而是换一种组织方式让数据、模型、服务的边界清晰化让每一步都有迹可循。1.2 工程化能带给团队的三个直接收益第一是复现能力。这个太重要了。任何一个稍具规模的项目你几乎必然会面临“这个指标是用哪批数据跑出来的”或者“这个模型是谁在哪个分支上训的”这种灵魂拷问。真正的工程化落地要求任何一次训练都能回溯到代码版本、数据版本、参数配置。我自己的做法是把运行参数统一收进一个JSON文件随模型一起哈希存档。这样即使三个月后再看也能完整还原训练状态。第二是协作可能。没有工程化之前算法工程师交付的是一个“别人看不懂”的黑盒开发工程师要上线只能对着脚本猜过程。而工程化之后数据、模型、服务彼此独立特征管道的代码有统一的抽象接口后端开发只需要关注接口契约就行了。整个协作链条从互踢皮球变成流水线配合。第三是增量优化空间。工程化不是一次性工程它的价值会伴随项目演进持续放大。你投入精力建设的数据版本工具、评估测试集、监控系统在第一个项目结束后可以直接复用到第二个项目尤其是评估逻辑和监控告警几乎不用怎么改。这等于给团队的研发效率做了一个复利账户。2. 从零初始化AI工程时的环境、结构与依赖管理2.1 项目目录怎么分才不会被后人骂我自己经历过最痛苦的事情之一就是接手一个把数据清洗、模型定义、web路由都写在一起的三千行py文件。所以我的目录设计原则很简单按时钟方向解耦——数据相关、特征相关、训练相关、服务相关四类代码互不越界各自只需对下游暴露最简单的接口。一个比较省心的初始化结构大概是这样的project/ ├─ configs/ # 所有yaml/json配置含训练参数、路径、超参 ├─ data/ # 原始数据与中间数据一般用软链或挂载盘 │ ├─ raw/ │ ├─ processed/ │ └─ sample/ ├─ src/ # 核心代码 │ ├─ data/ # 数据加载、切片、预处理器注册 │ ├─ features/ # 特征工程 │ ├─ models/ # 模型定义、损失函数、评估函数 │ ├─ train.py # 训练入口 │ ├─ predict.py # 推理封装和训练共用特征代码 │ └─ serve.py # FastAPI/Flask应用逻辑 ├─ tests/ # 单元测试和训练冒烟测试 ├─ scripts/ # 运维脚本、定时任务、数据同步 └─ experiments/ # 实验记录、notebook、指标快照不入库这里有个容易被忽略的细节src里面不要再按照“utils.py”这种方式平铺散装函数而是以业务模块为粒度组织。比如做电商评论情感分析就应该有comment_fetcher.py、comment_cleaner.py、sentiment_model.py而不是utils.py里装一百个无关函数。模块化不是为了好看而是为了让你在改一处逻辑时明确知道影响范围在哪里。2.2 环境锁定没有lock文件的工程不配谈稳定Python的依赖管理是每个AI工程绕不开的痛点。训练阶段你可能需要torch、transformers、sklearn、pandas这些大件部署阶段又需要fastapi、uvicorn、pydantic。两个阶段对包版本的要求经常冲突所以我从一开始就采用“环境按阶段拆分版本全量锁定”的策略。开发环境用一个宽松的requirements-dev.txt里面是兼容范围内的主版本号方便装新包做实验。部署环境则必须使用完整锁定的requirements-lock.txt把所有传递依赖的精确版本都固定下来。使用pip freeze没有问题但要注意这个命令会连同一些系统级的包一起冻结所以更推荐配合virtualenv创建全新环境后再freeze。如果你们团队已经普及了Poetry或者uv那体验会更好因为它们天然支持锁文件和哈希校验。我个人从pip迁移到Poetry之后再也没遇到过“我这能跑你那跑不了”的问题。另外凡是涉及GPU的项目务必要把CUDA版本和PyTorch版本的匹配关系写进README这是新人入职后最容易卡住半天的坑。2.3 配置管理的规范化比想象中重要配置管理是一个听起来枯燥但能直接决定你加班量的东西。我自己早期犯过的错是把数据路径、模型参数、日志级别全散落在代码各处的硬编码里改一个路径要在五个文件里搜索替换稍不留神就改漏。工程化要求所有配置全部收口我用的是两层设计。第一层是configs/目录下的YAML文件记录业务型配置比如数据源路径、特征开关、模型超参、服务端口。第二层是环境变量只放不能进仓库的敏感项比如数据库密码、API Key。训练脚本启动时统一加载并把最终生效的完整配置dump成快照文件随模型一起存档。这个快照文件的意义在于任何时刻你拿到一个模型产物就能知道它是在什么参数组合下产生的不需要去猜。3. 数据处理从清洗到版本管理的完整链路3.1 原始数据接入的三个必须动作真实项目里数据很少是干干净净躺在CSV里等你的。可能来自关系型数据库可能来自日志文件也可能是第三方API。无论来源是什么我建议接入后先做三件事否则后续排查问题会非常痛苦。第一生成数据概览报告。包括行数、列数、每列缺失比例、取值分布、数值列的均值与分位数。做这事可以不用额外工具pandas的describe()加一个自定义的空值统计函数就够。关键是把这个报告结果存下来而不是在终端看一眼就算了。第二对原始数据做不可变归档。原始数据理论上只允许追加不允许修改把raw目录设置成只读权限会省很多事。第三记录数据批次指纹。最简单的做法是计算整个原始文件的MD5或者行数哈希注册到数据版本表里。这样如果有人偷偷改了原始文件你在训练前就能通过指纹比对发现。3.2 特征清洗与增强的避坑经验特征处理是整个流程里最琐碎的环节但也是模型效果提升空间最大的环节。我在清洗环节的经验是“三要三不要”。要写可测试的清洗函数每个函数只做一类事情——比如去HTML标签、去全角空格、统一缩写不要在一个函数里做十件事。要在清洗后保留清洗前的字段副本无论你觉得原字段有多脏总会有后悔的时候。要对每条清洗操作做抽样人工验收至少看一眼输出结果是否符合直觉清洗正则写错导致全量字段变成空字符串不是没发生过。三不要是不要在清洗步骤里做全局状态修改不要在清洗函数里直接读写文件不要清洗逻辑在训练和推理两侧各写一套。第三个问题尤其致命。我的解决方案是把特征处理方法打包成模块训练时通过FeaturePipeline类统一调用推理时加载同一个模型目录下的特征配置重新实例化同一个类保证两侧逻辑完全一致。关于数据增强我建议从业务理解出发而非盲目堆量。比如做OCR识别可以对图片做随机裁剪、旋转、加噪声做文本分类同义词替换、回译增强都要和实际场景匹配。增强数据的规模需要有度——我曾见过有人把训练集扩了十倍模型效果反而下降因为增强后的样本和真实业务分布差异太大模型学到了增强特有的伪特征。3.3 数据版本管理的轻量方案落地说到数据版本管理很多团队第一反应是上DVC这套重量级工具但小团队和个人项目其实可以先用轻量方案。我的做法是将数据版本号与模型训练记录绑定每次训练前读取当前数据目录的指纹训练后把指纹写进实验记录。这样虽然做不到数据文件级别的完整版本控制但能保证每次实验都能查证原始数据范围这对90%的场景已经够用了。如果数据量不大直接把处理后的特征数据打包存一份和模型同一批次的产物也是完全合理的方案。只有当你需要频繁回溯不同版本的数据做对比实验时再考虑引入正式的数据版本库。工具选择永远为流程目的服务不要为了用工具而用工具。4. 模型训练的工程化改造写代码只是起点4.1 用配置文件驱动训练而不是靠改代码训练脚本的工程化改造第一刀切向参数传递。我见过太多写死在代码里的学习率和batch size改一次参数动一次代码。更好的模式是训练脚本只读取一个配置对象所有参数来自命令行覆盖或配置文件。命令行覆盖适合临时跑个小实验配置文件适合完整的实验复现。我自己常用一个简单的YAML配置模板data: train_path: ./data/processed/train.parquet valid_path: ./data/processed/valid.parquet target_col: label model: name: text_cnn embedding_dim: 300 hidden_size: 128 train: batch_size: 64 epochs: 10 learning_rate: 1e-3 seed: 42 gpu_id: 0 exp: name: baseline_v1 note: 第一次完整管道实验训练脚本启动后除了配置本身、还要把代码版本git提交号、数据指纹、开始结束时间、每个epoch的评估指标全部写进实验记录。这里用MLflow或者自己写一个JSONL日志文件都可以。关键不是工具高级而是形成习惯——每一个模型产物都有一个对应的完整实验上下文。4.2 训练过程监控与模型保存策略训练监控分成两层。底层是硬件层GPU显存、CPU负载、IO等待时长这些可以直接用nvidia-smi加定时采集脚本实现。上层是训练指标层loss和评估指标在训练过程中的变化趋势才是判断是否收敛的关键。训练过程的loss曲线应当稳定下降如果出现震荡常见原因无外乎学习率过大、batch size过小、数据顺序有偏。这时候不要急着调模型结构先调训练动态。模型保存方面我强烈建议不要只保存最后一个epoch的权重。正确做法是开启early stopping以验证集指标为准保存最佳模型同时把最后一个epoch的权重也保留两者对比在分析过拟合和后期训练不稳定时非常有用。保存格式也要统一。PyTorch生态倾向于保存state_dict但如果你定义了自定义的预处理类和模型类最稳妥的做法是把模型结构配置、tokenizer/特征配置一起序列化到产物目录里避免出现“权重加载成功但预处理做不了”的尴尬局面。4.3 训练与推理的一致性铁律这个问题值得单独拿出来强调。文本分类训练时我用jieba.cut做分词推理时忘了加载同样的停用词表线上效果马上打折图像模型训练时输入做了归一化推理接口忘了减均值除方差最直接的影响是预测置信度整体漂移。这些都是血泪教训。我的解决方案是用一条“铁律”所有数据预处理逻辑都必须封装在能被双方共享的函数库中训练入口和推理入口都基于同一个库构建pipeline。实际操作中我会在推理服务启动时加一个“自检模式”用若干条带标签的样本跑一遍模型输入对比推理输出是否与预期标签一致如果不一致直接拒绝启动服务。这个自检机制虽然简单但能拦截掉大量的“训练推理不一致”问题。5. 推理服务的部署与性能优化细节5.1 从模型产物到API服务的封装步骤模型训练完之后线上线下割裂是最大的坑。我推荐最快的上线路径是直接用FastAPI把推理封装成HTTP服务再挂到Docker容器里面。封装服务的核心不是调用model.predict()而是做好三件事。第一服务启动时加载模型和前置pipeline避免每次请求都重新加载权重。第二接口入参和出参都做严格的schema校验不合法输入直接返回400而不是让模型跑一个奇怪的预测。第三所有请求都要有耗时和结果日志方便后续排查问题。下面是一个极简但完整的封装思路# serve.py from fastapi import FastAPI from pydantic import BaseModel import joblib import numpy as np app FastAPI() # 全局加载一次 model joblib.load(/models/exp_baseline_v1/model.pkl) preprocessor joblib.load(/models/exp_baseline_v1/preprocessor.pkl) class Item(BaseModel): text: str user_id: int class PredictOut(BaseModel): label: int score: float app.post(/predict, response_modelPredictOut) def predict(item: Item): clean_text preprocessor.transform(item.text) probs model.predict_proba([clean_text])[0] label int(np.argmax(probs)) score float(probs[label]) return {label: label, score: score}这个例子里面preprocessor是一个已经保存了清洗规则的实例而不是散装函数。这样能确保线上推理用的预处理方式和训练时完全一致。5.2 性能瓶颈定位与批量推理优化HTTP服务上线以后最容易遇到的是QPS上不去。定位瓶颈的时候切忌瞎猜应该分别测三段时间网络传输耗时、预处理耗时、模型推理耗时。我自己遇到的高频瓶颈有两个。一个是预处理里用了正则循环每条数据要跑好几十个规则纯Python正则的性能非常有限。优化方案是能向量化的操作全部向量化能用编译正则的不要用字符串方法。另一个是模型推理的batch太小GPU的利用率还不到10%。这里有个技巧如果业务对延迟不太敏感可以在服务层做动态攒批把并发请求攒成一个大batch再送进模型QPS能翻三倍。当然攒批要设置最大等待时间否则流量低的时候请求会长时间挂起。5.3 容器部署与资源限制的实践容器化是AI工程落地逃不开的一环。我自己的Dockerfile分两段构建阶段安装完整依赖并跑一遍测试运行阶段只拷贝代码、模型产物、锁定的依赖目录。这样镜像体积能小不少安全风险也低一些。部署时务必设置资源限制。CPU上限、内存上限都要写在Docker Compose或者Kubernetes的配置里。对于推理服务我的内存预留建议是“模型文件大小的5倍以上再加2GB系统开销”因为推理时中间激活值和框架自身缓存往往比模型文件更吃内存。另外容器内不建议放训练代码训练任务和推理服务的依赖、生命周期完全不同硬塞一个容器里会让排查问题变得很复杂。6. 评估体系的搭建不只能看准确率6.1 离线评估指标的选型思路模型评估不能只看一个准确率分类问题至少要同时看Precision、Recall和F1如果存在严重的类别不均衡还要看每个类别的单独指标和混淆矩阵。为什么因为业务场景的目标函数几乎都不是单纯准或者单纯全。比如垃圾内容识别宁可把少量正常内容误判为垃圾也不能放垃圾过门这时候Precision权重就高反过来在医疗筛查场景宁可产生很多假阳性也要控制假阴性漏诊Recall权重就高。指标计算时要特别注意样本分布。理想情况是评估集和线上真实流量分布一致但往往开发阶段的评估集来自历史数据抽样分布已有偏移。我的做法是额外维护一个“近期线上回流样本集”定期从生产日志抽一批真实请求人工打标后加入评估集。你会发现这个不断生长的评估集比任何花哨的A/B实验都能说明模型真实水平。6.2 上线后的监控告警体系模型上线不是终点而是监控的起点。最基础的监控项是预测分布、请求量、平均延迟、异常输入比例。进阶一点要监控特征漂移和预测漂移——如果线上某个特征列的分布和训练期相比发生了显著偏移你有理由怀疑当前模型可能已经不适应新数据了。告警阈值怎么定我建议先用历史数据跑一版基线把指标的P95、P99算出来阈值设置在P99以上再加一个容差。不建议直接把阈值设成绝对值因为不同业务时段波动很大。监控数据要保留足够长时间至少要三个月这样才能覆盖完整业务周期。我踩过一个典型坑模型的预测结果被下游业务方用做了长期决策的输入但因为模型每季度重训一次新旧模型输出分布差异巨大下游业务报表直接跳变。这个问题的根源是没有人监控模型的输出分布变化。所以我现在对任何线上模型都强制加预测分布监控分布变化超过设定阈值就告警让算法同学评估是否需要人工介入。7. 常见问题与排查技巧实录7.1 训练阶段的典型问题速查下面这组问题是新项目启动时最容易碰到的直接整理成速查表给大家问题现象可能原因排查方向训练loss不降学习率过大/过小、数据未归一化、标签错位先跑一个batch看loss能否过拟合到近零模型效果与随机猜测无异数据shuffle失效、label泄漏、评估集与训练集重叠检查样本id唯一性、数据划分是否有时间穿越GPU利用率很低数据加载太慢、预处理在CPU上有瓶颈用DataLoader多进程预取或做IO分析验证集指标突变数据顺序影响、随机种子未固定、评估集过小固定若干随机种子跑多次取均值不同运行结果差异很大随机初始化影响过大、early stopping不稳定统一种子、降低学习率、增加迭代上限这里面特别要提醒的是“测试集泄漏”问题尤其是做时间序列相关业务时如果用随机划分把未来数据混进训练集离线指标看着完美一上线立刻打回原形。划分数据时务必要按业务语义来做时序数据就必须按时间切分不能图省事用随机切分。另外训练再用数据并行的时候如果遇到指标收敛变慢先查是不是loss下降时用了reduce后再统一除batch size结果每个卡上都除了多遍导致有效学习率变了好几次。这是我见过最多人犯的隐性错误。7.2 服务阶段的常见问题速查问题现象可能原因排查方向接口偶发超时动态攒批等待时间过长、GC暂停、模型推理阻塞用profile看p99耗时优化攒批阈值部分请求返回异常预测输入文本包含脏数据、特征pipeline崩溃后走默认值检查告警日志里的异常样本加入黑名单过滤重启后首次请求特别慢模型懒加载、缓存未初始化服务启动后做一次warming-up请求模型推理结果与离线不一致预处理逻辑不一致、模型版本加载错误对比训练端与推理端的配置快照跑自检用例内存持续增长请求日志无界增长、预测缓存未清理加上限和清理策略限制缓存容量顺带一提日志打点不是越多越好。我在生产环境遇到过一次因为日志字段太多序列化开销让单请求处理时间翻了倍的案例。日志只打真正要关注的信息入参摘要、耗时、输出、版本号、异常上下文。其余全放到debug级别。7.3 写给大家的几条工程级建议第一保持一份“数据字典”。无论项目多小都要记录每个字段的业务含义、取值范围、清洗规则。这份文档在项目交接和新人上手时价值巨大而它也是绝大多数团队最容易忽略的。第二学会用git做实验分支管理但不要用git存模型文件和数据文件模型产物要另外归档。第三任何模型上线前必须在旧的基准数据上做一次回归测试我见过模型指标涨了五个点但某个核心业务子类效果全断崖的情况——回归测试能提前拦住这种灾难。最后再分享一个小技巧训练和推理两侧的特征对齐问题除了共享代码库我还会在每个模型目录下存一份预处理代码的哈希值推理服务启动时校验这个哈希是否与服务内加载的预处理代码一致。如果不一致就拒绝启动。这个校验逻辑很便宜但能避免“代码明明改过却不记得是哪个版本”的尴尬。从零搭建一套AI工程的本质不是选择一个好框架或调出一个好模型而是把系统里每一个可变因素都锁进明明白白的记录里让每次失败都可复盘每次成功都可复现。限于篇幅关于强化学习、多模态、大规模分布式训练等方向没有展开但那套把工程化做扎实的思路是完全共通的后续可以在实际项目中慢慢体会。