0. 引子AI工程不是写几个模型就完事这两年“AI工程”这个词被反复提起可真正动手把一个AI项目从头做到能上线、能维护的人其实并没有想象中那么多。我身边不少朋友的状态是跑通了开源模型、微调了一把、在笔记本上出过几个还挺像样的结果但一旦要面对真实业务场景就发现到处都是坑——数据处理不规范、实验没有记录、模型上线要靠手工拷贝文件、线上效果和线下评估对不上……每个问题单看都不大叠在一起却足以让项目烂尾。这个“ai-engineering-from-scratch”项目的初衷就是把我自己从零构建一个AI应用的心路历程整理成一条清晰的主线不是上来就调库、套模型而是把“AI工程”这件事拆成一套可复制、可回顾、可演进的流程。从环境搭建、数据管理到模型训练、评估、部署、监控每一环都亲手走一遍理解每个环节为什么这么做、做了有什么收益、不做又会踩什么坑。如果你正处于“模型能跑通但工程化无从下手”的阶段或者你被领导要求“快速把AI能力落地”却不知道怎么组织代码和流程这篇文应该能让你少走不少弯路。我尽量讲真实踩过坑之后的理解不空谈概念所有内容都对应我实际操作过的方案。1. 项目整体规划什么叫“从零开始”的AI工程1.1 先想清楚你要解决什么问题而不是先想用什么模型我见过太多项目死在第一步——需求没讲清楚就急着找模型。比如有人想做“智能客服”可“智能”这个词太模糊是检索历史工单给答案是让大模型做知识库问答还是基于规则做意图分类三者技术路线完全不一样。“ai-engineering-from-scratch”里我给自己立了一条规矩在写第一行代码之前必须把问题定义成几句话能说清楚的形式。比如“给客服同学做一个工单分类器输入工单标题和描述输出12个预定义分类中的一个”这才算合格的问题描述。相比之下“做一个懂业务的AI助手”这种需求放到工程流程里基本上等于没有需求。问题定义清楚之后下一步是设定评估指标。分类问题用准确率、召回率、F1回归问题用MAE、RMSE生成类任务相对复杂可能要结合人工评估集。指标不是越高级越好而是必须和业务目标挂钩。比如工单分类任务里如果误判会把用户问题转错部门那精确率就比召回率更敏感模型调优的方向也会随之变化。1.2 整体架构设计的几条主线“从零开始”不代表什么都自己造轮子而是每一层选型都清楚为什么。我在这个项目里把整体架构分成五层每层职责单一、接口清晰数据层负责采集、清洗、标注、版本管理解决“数据从哪来、怎么保证质量”的问题。实验层负责特征工程、模型训练、超参数调优、实验记录解决“模型怎么选、参数怎么定、效果怎么复现”的问题。评估层负责离线评估、交叉验证、误差分析解决“模型好不好、哪里不好”的问题。部署层负责模型导出、API服务化、推理优化解决“模型怎么上线、线上怎么调用”的问题。监控层负责线上指标、数据漂移、日志追踪解决“上线之后怎么保证一直好”的问题。这个分层不是拍脑袋定的而是我在维护一个早期AI项目时被现实教育后的反思。当时模型训练和部署代码混在同一个Notebook里数据改了没记录指标用的是临时脚本算的出了问题根本不知道该查哪一环。分层之后每一层都有明确的产物和负责范围排查问题时也能沿着数据流一路定位。1.3 为什么坚持“可复现”优先于“跑得快”每个人的个人项目也好企业项目也罢都有一个很容易犯的毛病追求尽快看到结果而忽略记录过程。训练完一个模型准确率82%看起来不错可问你用的哪个版本的数据、哪些特征、多少次迭代却一个都答不上来——这样的模型基本等于没做。我在“ai-engineering-from-scratch”里把“可复现”当成第一优先级。所有实验都有记录所有数据都有版本所有超参数都写进配置文件。这样做短期内确实会多花一些时间但长期来看收益极大当你需要分析为什么换了新数据后效果变差了有一个完整的实验历史可以追溯几分钟就能定位到是哪一层出了问题。注意可复现不等于所有实验都用相同的数据。数据版本管理和代码版本管理同等重要。很多项目最后查不出“为什么结果和上周不一样”就是因为代码没变、数据却悄悄换了。1.4 三条设计原则简单、自动、可观测除了架构分层我还在项目里给自己定了三条设计原则写进了项目文档的首页简单优先每个环节优先选最简单的可运行方案不追求一步到位的复杂架构。先全流程跑通再逐步优化比一次设计一个完美系统更现实。自动优先凡是重复性的工作数据校验、模型导出、回归测试一律脚本化、自动化。手动操作越多出错概率越大。可观测优先每个环节都留日志和指标上线后的系统要能看到业务指标哨兵。没有监控的AI系统就像没有仪表盘的飞机飞得越高越危险。2. 环境搭建与技术选型踩过坑之后推荐的组合2.1 Python环境管理别再到处装包了开始这个项目时我的第一个教训来自Python环境。以前我习惯直接 pip install 装一堆包结果就是不同项目之间的依赖互相打架升级一个库导致另一个项目跑不起来非常痛苦。随着实践深入我换成了 uv 来管理Python环境和依赖。它比传统 pip virtualenv 组合快很多而且锁文件机制能保证每个环境的依赖完全一致。如果你的项目已经有多个同事协作这一步尤其重要——不然“在我机器上跑得好好的”会成为全场使用率最高的甩锅借口。初次使用 uv 的步骤大致是这样# 创建Python 3.11环境 uv venv .venv --python 3.11 # 激活环境Windows/Linux略有差异 source .venv/bin/activate # 初始化项目 uv init # 添加核心依赖 uv add numpy pandas scikit-learn fastapi mlflow dvc依赖版本锁定之后项目里会有 uv.lock 文件任何人拉下代码后执行 uv sync 就能还原一模一样的环境。光是这一步就能省掉无数“同样代码不同结果”的排查时间。2.2 实验追踪用MLflow记录每一次尝试没有实验追踪工具的AI项目就像没有git的代码项目迟早会出事故。每次改一个参数、跑一次训练都应该留下完整的记录谁跑的、什么时间、用的什么配置、效果如何。我选的是MLflow理由很接地气部署简单、文档清晰、社区活跃而且支持自动记录超参数和指标。我习惯把每个项目的config文件、训练代码版本、数据集版本都挂到MLflow的run上这样就可以随时回溯“准确率82%的那个模型到底是用哪套配置跑出来的”。MLflow的代码集成并不复杂import mlflow mlflow.set_experiment(ai-engineering-from-scratch) with mlflow.start_run(): # 记录超参数和指标 mlflow.log_param(learning_rate, 0.001) mlflow.log_param(max_depth, 8) # ...训练代码... mlflow.log_metric(f1_score, 0.87) # 保存模型 mlflow.sklearn.log_model(model, model)使用MLflow过程中我的一个体会是最好把“记录参数”和“记录结果”散落在训练的各个关键节点而不是等到训练结束后一次性记录。这样如果训练中途挂了前面几轮的信息还能保留下来。2.3 数据版本管理把数据集当成代码对待AI工程和传统软件开发的一个显著差异是代码变了会导致行为变化数据变了同样会导致模型行为变化。可绝大多数项目只有代码在git里管理数据散落在各个目录换了一版数据连自己都未必记得。我在项目中引入了DVC做数据版本管理。它的工作方式很像git但管理的是大文件。具体来说DVC会把数据文件的元信息记录下来而实际内容可以存在本地、S3或者NAS上。用起来逻辑很自然# 添加数据目录并进行版本管理 dvc add data/raw/orders.csv git add data/raw/orders.csv.dvc git commit -m add initial dataset v1 # 后期切换数据版本 git checkout v2-orders.dvc dvc checkout这样每次实验的数据版本就变得可追溯了。我这里不是说DVC是唯一选择而是强调“数据版本管理”这个动作本身。不用DVC用git-lfs也完全可以关键是养成记录数据版本的习惯。2.4 容器化Docker镜像让环境真正“一致”即使在本地环境锁定了依赖部署到服务器时仍可能遇到差异——系统库版本、CUDA版本、Python解释器的微妙差异都可能在最终时刻冒出来。用Docker容器统一运行时环境是我这个项目里最省心的决定之一。理论上环境复现的链条可以做到这样简单从git拉代码用uv同步Python依赖用Docker构建包含全部系统依赖的镜像在容器里跑训练和推理。本地开发和线上部署共用同一个镜像最大程度避免“开发环境正常生产环境崩了”的现象。Dockerfile我一般写得尽量精简基础镜像选用带CUDA的官方PyTorch镜像再把项目代码和依赖打进去FROM pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . CMD [python, src/train.py]注意Docker镜像构建时要尽量利用层缓存——先拷贝依赖文件并安装再拷贝代码这样代码变化时不会重新安装所有依赖构建速度快很多。3. 数据管线的搭建从杂乱原料到高质量训练集3.1 数据采集与清洗别急着做特征工程很多人一拿到数据就急着提取特征、训练模型却忽略了数据质量的基本检查。我在项目里首先做的是“描述性统计数据体检”缺失率、分布形状、数值范围、重复记录、类别分布不均衡情况全部先打印出来看一遍。拿一个实际的场景举例做用户复购预测时原始数据里用户行为日志有上百万行但很多用户只有一两条记录。如果不查看数据分布而对所有用户一视同仁地提取特征结果模型大概率被少数高活跃用户带偏对普通用户完全没有区分能力。清洗数据时有一个很有意思的原则“数据清洗的终点是让下游消费数据的代码足够简单”。如果清洗完的数据还需要下游一遍遍处理异常值那说明清洗这步没有做透。我在项目里会把常见的清洗逻辑缺失值填充、时间字段解析、类别编码封装成独立的Pipeline组件而不是散落在训练脚本里。3.2 特征工程怎么把业务经验变成模型的语言特征工程是AI工程里最具“手工感”的环节也是最难标准化、却最能体现业务理解的地方。纯粹把原始字段喂给模型远远不够好的特征工程往往来自于对业务问题的拆解。以一个流失预测项目为例原始的原始维度可能只是用户ID、注册时间、每天登录次数。通过业务思考后我们就可以构造出更有意义的特征最近7天登录天数 / 最近30天登录天数频率变化趋势最后一次登录距今天数最近活跃度每日平均使用时长会话深度连续不登录的历史最长天数沉默惯性这些特征背后的逻辑是抓住“流失”这个行为在发生之前的一系列微弱信号。模型是无偏见的统计机器你给它什么信号它就学什么规律。如果特征设计得好有时比盲目换复杂模型更有效。3.3 数据校验在进入训练前设一道关卡数据质量是AI项目最容易出“隐蔽Bug”的地方。比如上线后某天数据源增加了一个新字段的取值训练的代码没变但模型的表现却突然变差了——这类问题如果没有数据校验机制往往要等业务投诉才能发现。我在Pipeline里加入了一步“数据校验”具体做法是检查数据集的schema列名、类型是否符合预期检查数值字段的范围是否在合理区间检查类别字段的取值是否在选择范围内检查目标变量的分布是否和训练集有显著差异如果校验不通过Pipeline要发出告警并中断训练。这一步看似简单但价值极高——很多AI系统的线上事故本质上都是训练和线上数据分布不一致造成的而数据校验就是拦住这类问题的最前一道防线。3.4 训练集与验证集的划分别让数据泄漏悄悄发生数据泄漏是训练评估中最隐蔽也最危险的问题。简单说就是验证集的信息在训练阶段被模型看到了导致评估指标虚高上线后立刻现原形。常见的泄漏途径在划分训练集/验证集之前就做了全量数据的归一化归一化参数应该只用训练集计算做时间序列预测时随机划分样本导致未来信息泄漏到训练集合特征工程中使用了全量数据的统计量比如用全量均值做填充对类别特征编码时用全量数据统计出的类别频率作为特征我建议每个项目都在数据集划分完成之前专门检查一遍“特征构造的过程是否接触过验证集信息”。这件事需要仔细因为多数泄漏不是代码层面的Bug而是设计层面的疏忽。4. 模型开发与训练从baseline到可靠的实验闭环4.1 永远先跑一个最小可用的baseline拿到干净的、经过校验的数据后我几乎不会立刻开始调试复杂模型。而是先跑一个最简单的baseline——比如逻辑回归或浅层决策树用默认参数不做任何花哨处理。这么做的目的非常明确验证数据链路是否通畅为后续模型的提升幅度提供对比基准。baseline的准确率也许不高但它的价值是确定了“这件事到底可不可行”。如果数据连最简单的模型都学不出有效模式那问题大概率不在模型选择而在数据质量或特征设计。这时候花几周时间调深度学习模型是典型的方向性错误。我经历过一个文本分类项目baselineTF-IDF逻辑回归的F1只有0.42感觉很低。本来打算上BERT精调后来深入看数据才发现标注质量参差不齐大量错误标签把学习上限压死了。回头清洗重建了标注集同一个baseline直接跳到0.71。这个经验让我坚信比模型更重要的是先把数据和任务本身搞明白。4.2 训练脚本的结构配置、数据、模型、训练逻辑分层刚开始做AI项目时我喜欢把一切都写进一个大脚本后来脚本越来越长修改一个参数都要翻好几屏。现在的实践是训练脚本严格分成四个模块各自职责解耦config.yaml所有超参数、路径、开关都在这里不写死在代码里dataset.py只负责加载数据和特征工程返回PyTorch Dataset/TF Datasetmodel.py定义模型结构只接受config中的参数train.py组织训练循环负责日志、评估、检查点保存这样做的好处很明显要调参改config就能完成要换模型替换model.py即可要换数据接一个新的dataset实现。每个部分都可以独立测试整个训练的“实验闭环”变得清晰可控。config.yaml的示例片段data: train_path: data/processed/train.parquet val_path: data/processed/val.parquet batch_size: 64 model: name: lightgbm max_depth: 8 learning_rate: 0.05 n_estimators: 500 train: seed: 42 early_stopping_rounds: 20 eval_metric: auc4.3 超参数调优网格搜索、随机搜索到贝叶斯优化超参数的选择在传统机器学习中往往是效果差异的重要来源。随着项目推进我逐渐从手工试参数过渡到更系统的方法。手工试参数虽然直觉性强但总会有盲区而且容易“memory bias”——记得某次跑出了好结果却说不清当时的完整配置。随后我切换到随机搜索在给定范围内随机采样参数组合每个组合跑一轮完整实验记录结果。随机搜索的实现简单效果却经常比网格更好这主要因为参数空间中每个维度的灵敏度不同随机采样能更均匀地覆盖组合空间。当实验规模进一步增大、每次训练耗时较长时我引入了Bayesian Optimization用Optuna。它会根据历史实验结果选择最有潜力的下一组参数显著减少了无效训练次数。使用Optuna的体验很友好我一般会配合MLflow一起用把每一次trial的参数和指标都记录到同一个实验里。import optuna def objective(trial): params { max_depth: trial.suggest_int(max_depth, 4, 12), learning_rate: trial.suggest_float(learning_rate, 0.01, 0.1, logTrue), n_estimators: trial.suggest_int(n_estimators, 200, 800), } # ...运行训练并返回评估指标... return score4.4 过拟合识别与应对策略训练集表现迅速走高、验证集表现止步不前这是所有AI项目迟早都会撞上的问题。要识别正在过拟合并不难观察训练和验证指标的分叉曲线。重点是如何应对。我的经验排序是数据层面增加更多训练数据含数据增强这是最稳的打法模型层面降低模型复杂度适当减少层数、加正则化L2、Dropout训练层面早停early stopping一般效果明显把验证集最优的轮次保存成最终模型集成层面多模型加权平均提升鲁棒性但推理解释性略降另外我强烈建议在样本量有限时使用k-fold交叉验证评估模型而不是只切一次验证集。交叉验证的结论更稳健能有效防止“在某一验证集上运气好”造成虚高判断。5. 模型评估、部署与服务化从实验产物到线上服务5.1 离线评估的正确姿势不只关注单一指标训练完成后很多人习惯看一眼测试集准确率就下结论但这远远不够。离线评估的目标是尽可能准确地预测线上表现并且帮助定位模型的薄弱环节。我会把评估拆成几个层次总体指标准确率、精确率、召回率、F1、AUC先看整体水平分层指标按业务维度拆分比如用户地区、商品品类、时段看模型在不同子群体上的表现是否有明显差异误差分析将预测错误的样本分门别类是标注问题、特征缺失还是模型判断逻辑本身的缺陷分层指标和误差分析尤其重要。比如一个推荐模型总体准确率80%但仔细一看新用户的准确率只有40%说明模型对无行为冷启动用户几乎失效这就是需要通过策略重点优化的问题。5.2 模型导出与打包别只保存一个pickle文件模型训练好之后不能直接丢一个pickle就交给部署同事。模型导出需要包含完整的元信息模型文件、特征列表、预处理流水线包括归一化参数、类别编码表、推理依赖的版本。我用MLflow的model registry功能管理模型版本。每训练出一个候选模型注册到Model Registry标记状态staging/production方便追踪哪个版本的模型正在线上服务。当新模型效果确实更好时再标记production并部署整个过程在“代码—训练—注册—部署”之间有清晰流转。MLflow注册模型很简单# 注册模型到registry mlflow.register_model( model_uriruns:/run_id/model, nameorder-classifier )5.3 模型推理服务FastAPI搭建轻量级服务模型上线环节我一般用FastAPI写推理服务。它是一个轻量级的Python Web框架和Flask相比自带OpenAPI文档、类型校验、异步支持对模型推理服务非常友好。一个典型的推理服务入口长这样from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class PredictRequest(BaseModel): features: list[float] class PredictResponse(BaseModel): prediction: int probability: float app.post(/predict, response_modelPredictResponse) def predict(req: PredictRequest): proba model.predict_proba([req.features])[0] return PredictResponse( predictionint(proba.argmax()), probabilityfloat(proba.max()) )一个容易被忽视的细节线上推理的输入格式必须和训练时一致否则模型拿到的数值分布会错位。这个统一由预处理层的Pipeline承接推理请求先经过和数据管线里相同的特征处理逻辑再喂给模型。千万别在部署环境里另外写一份特征处理代码——那几乎是“线上效果崩了”的标配原因。5.4 推理性能优化从并发设计到推理加速当线上请求量上来之后推理性能会成为新的瓶颈。我在项目里踩过不少坑整理出几个经验性的方向并发设计模型本身一般是线程安全的但在加载时要注意只加载一次不要每来一个请求重新加载输入批处理对高吞吐场景收集多个请求组成batch一次性推理GPU或向量化运算的利用率会明显提升模型轻量化如果延迟要求严苛可以考虑蒸馏小模型、量化为int8、或使用ONNX Runtime加速缓存策略对相同或相似输入可以用简单缓存如Redis降低重复计算开销优化要遵循“先测量、再优化”的原则。不做压力测试就盲目上调优手段往往事倍功半。我通常会先用wrk或locust打一轮压力测试找出瓶颈在哪一侧是CPU推理、网络IO还是内存——再针对具体瓶颈动手。6. 持续监控与模型维护AI系统上线只是开始6.1 线上监控模型效果不止是准确率AI模型上线后最危险的事情不是模型效果不好而是模型效果悄悄变差而无人察觉。线上系统的监控体系需要覆盖两层指标业务指标比如推荐点击率、客服转人工率、预测准确率如果能拿到标签的话技术指标接口延迟、QPS、显存占用、错误率、依赖服务的可用性业务指标监控是模型监控的核心。很多业务指标天然有延迟——比如下单转化率要等用户行为发生之后才知道。所以还要设计一套定期滞后的评估方式把线上预测结果和延迟到达的监督信号做定期比对。6.2 数据漂移检测提前发现模型退化的信号数据漂移Data Drift是线上模型效果变差最主要的诱因之一。用户行为变了、数据结构变了、业务规则变了都会导致输入分布和训练分布不一致模型自然就不准了。检测实践中我会对每个关键特征做两种监测单特征分布监控比如用户年龄分布、地区分布定期用KS检验或PSI指标对比当前分布和历史训练分布预测分布监控模型输出的各类别概率分布是否发生了明显变化一旦监测到某个特征的PSI超过阈值就触发告警。这类告警不一定意味着模型立刻失效但它提醒我们是时候检查线上数据、评估模型是否需要重新训练了。6.3 定期重训策略不是越频繁越好模型训练频率是一个需要认真权衡的问题。过度频繁地重训不仅增加计算成本还可能导致模型在不同时段之间振荡而重训过慢又无法适应数据变化。实践中我采取了分级策略每日自动重训仅当数据漂移指标超过阈值时触发每周固定重训作为一个稳妥的常规周期保证模型能跟上中长期趋势人工触发重训当业务规则、数据格式或者产品逻辑发生重大变化时由工程师判断是否重训每个重训流程都复用同样的Pipeline训练完成后自动注册到Model Registry先跑一遍离线回归测试通过后才自动部署到生产环境。人工干预环节只保留在“重大变更”场景真正做到了自动化与可控性的平衡。7. 问题排查实录那些让人失眠的AI工程事故7.1 训练误差疯涨先检查学习率再检查数据管线有一次训练过程中Loss曲线已经正常下降了十几个epoch突然开始一路飙升。我第一反应是学习率太大或者梯度爆炸翻了一圈代码没发现问题。后来通过回溯MLflow的记录发现那个epoch的数据加载顺序不同了——一个随机shuffle的seed在重构代码时不小心丢掉了导致数据的分布变化影响到了训练稳定性。这个小问题让我印象深刻AI工程里很多“模型问题”追到根上其实是“工程问题”。训练Pipeline里的任何一个随机性来源shuffle seed、数据读取顺序、多线程采样顺序都应该被严格记录和控制。7.2 离线效果很好线上效果很差的经典原因线上效果和离线评估差异明显的场景我是深有体会的。有一次做一个定价预测模型离线验证的MAE看着亮眼上线后业务反馈“预测价格偏差很大”。排查到最后发现线上推理请求的特征构造代码和离线训练时有一处不一致——一个表示用户会员等级的特征离线使用的是数值编码线上服务却传入了原始字符串模型直接把该特征当成缺失处理预测自然就偏了。从此之后我养成了一个习惯在离线评估时刻意模拟线上特征处理的代码路径而不是单独写一份“评估专用”的特征工程逻辑。这是最能降低线上线下效果差异的做法之一。7.3 GPU显存不足与推理服务OOM的处理训练阶段显存不足还好办加大batch size的相反方向——减小batch size或者用梯度累积。真正让人头疼的是推理服务在高峰期OOM。有一次部署一个在线OCR服务白天还好晚上业务高峰时进程频繁被杀。排查后原因有两个一个是一次性加载了多个版本的模型文件另一个是FastAPI框架的同步阻塞导致并发请求堆积在内存里。修复方式也不复杂只加载当前需要服务的单一模型文件并把推理接口改成异步处理同时给推理函数加上显式批处理逻辑。从那以后我对“推理服务的内存预算”有了更敏感的认知——显存占用不只是模型大小的函数还包括输入输出缓冲区和并发请求的累积。7.4 自动重训导致效果退化自动重训听着美好但也可能带来麻烦。有次系统自动重训后线上推荐点击率反而明显下降。查了MLflow后发现重训的触发条件其实是某个特征的数据分布轻微漂移可那次重训使用的样本量太少训练出的模型不仅没有适应变化反而被最近的随机波动带偏了。从那之后我给自动重训加了两条铁律一是重训必须使用累计一段时间的数据量而非最近一天的数据二是重训模型必须通过离线回归测试与线上旧模型在历史一致的数据上做对比不达标就回滚并告警。8. 结尾AI工程真正的门槛在哪里做完了这一整套流程我最深的感受是AI工程最难的从来不是某个模型有多复杂而是把散落的环节串成一条稳定可靠的流水线。模型选型、参数调优这类问题网上随便一搜就有无数教程而数据版本管理、实验记录规范、线上监控体系、自动回滚机制这些“工程化的细节”才真正决定了项目能不能走长远。如果你正打算从零开始做一个AI项目我的建议很简单先别追求一步到位哪怕刚开始用最笨的脚本也把数据、实验、模型部署三个环节的边界清清楚楚地画出来然后逐步自动化、精细化。每踩一个坑就把对应的防线补上——这个过程本身就是“ai-engineering-from-scratch”最有价值的部分。模型会过时、框架会迭代但这条“从问题出发、用数据驱动、拿工程保障”的路径在任何时代都不会过时。 AI工程从零构建：从数据管理到模型部署监控的全流程实战指南
0. 引子AI工程不是写几个模型就完事这两年“AI工程”这个词被反复提起可真正动手把一个AI项目从头做到能上线、能维护的人其实并没有想象中那么多。我身边不少朋友的状态是跑通了开源模型、微调了一把、在笔记本上出过几个还挺像样的结果但一旦要面对真实业务场景就发现到处都是坑——数据处理不规范、实验没有记录、模型上线要靠手工拷贝文件、线上效果和线下评估对不上……每个问题单看都不大叠在一起却足以让项目烂尾。这个“ai-engineering-from-scratch”项目的初衷就是把我自己从零构建一个AI应用的心路历程整理成一条清晰的主线不是上来就调库、套模型而是把“AI工程”这件事拆成一套可复制、可回顾、可演进的流程。从环境搭建、数据管理到模型训练、评估、部署、监控每一环都亲手走一遍理解每个环节为什么这么做、做了有什么收益、不做又会踩什么坑。如果你正处于“模型能跑通但工程化无从下手”的阶段或者你被领导要求“快速把AI能力落地”却不知道怎么组织代码和流程这篇文应该能让你少走不少弯路。我尽量讲真实踩过坑之后的理解不空谈概念所有内容都对应我实际操作过的方案。1. 项目整体规划什么叫“从零开始”的AI工程1.1 先想清楚你要解决什么问题而不是先想用什么模型我见过太多项目死在第一步——需求没讲清楚就急着找模型。比如有人想做“智能客服”可“智能”这个词太模糊是检索历史工单给答案是让大模型做知识库问答还是基于规则做意图分类三者技术路线完全不一样。“ai-engineering-from-scratch”里我给自己立了一条规矩在写第一行代码之前必须把问题定义成几句话能说清楚的形式。比如“给客服同学做一个工单分类器输入工单标题和描述输出12个预定义分类中的一个”这才算合格的问题描述。相比之下“做一个懂业务的AI助手”这种需求放到工程流程里基本上等于没有需求。问题定义清楚之后下一步是设定评估指标。分类问题用准确率、召回率、F1回归问题用MAE、RMSE生成类任务相对复杂可能要结合人工评估集。指标不是越高级越好而是必须和业务目标挂钩。比如工单分类任务里如果误判会把用户问题转错部门那精确率就比召回率更敏感模型调优的方向也会随之变化。1.2 整体架构设计的几条主线“从零开始”不代表什么都自己造轮子而是每一层选型都清楚为什么。我在这个项目里把整体架构分成五层每层职责单一、接口清晰数据层负责采集、清洗、标注、版本管理解决“数据从哪来、怎么保证质量”的问题。实验层负责特征工程、模型训练、超参数调优、实验记录解决“模型怎么选、参数怎么定、效果怎么复现”的问题。评估层负责离线评估、交叉验证、误差分析解决“模型好不好、哪里不好”的问题。部署层负责模型导出、API服务化、推理优化解决“模型怎么上线、线上怎么调用”的问题。监控层负责线上指标、数据漂移、日志追踪解决“上线之后怎么保证一直好”的问题。这个分层不是拍脑袋定的而是我在维护一个早期AI项目时被现实教育后的反思。当时模型训练和部署代码混在同一个Notebook里数据改了没记录指标用的是临时脚本算的出了问题根本不知道该查哪一环。分层之后每一层都有明确的产物和负责范围排查问题时也能沿着数据流一路定位。1.3 为什么坚持“可复现”优先于“跑得快”每个人的个人项目也好企业项目也罢都有一个很容易犯的毛病追求尽快看到结果而忽略记录过程。训练完一个模型准确率82%看起来不错可问你用的哪个版本的数据、哪些特征、多少次迭代却一个都答不上来——这样的模型基本等于没做。我在“ai-engineering-from-scratch”里把“可复现”当成第一优先级。所有实验都有记录所有数据都有版本所有超参数都写进配置文件。这样做短期内确实会多花一些时间但长期来看收益极大当你需要分析为什么换了新数据后效果变差了有一个完整的实验历史可以追溯几分钟就能定位到是哪一层出了问题。注意可复现不等于所有实验都用相同的数据。数据版本管理和代码版本管理同等重要。很多项目最后查不出“为什么结果和上周不一样”就是因为代码没变、数据却悄悄换了。1.4 三条设计原则简单、自动、可观测除了架构分层我还在项目里给自己定了三条设计原则写进了项目文档的首页简单优先每个环节优先选最简单的可运行方案不追求一步到位的复杂架构。先全流程跑通再逐步优化比一次设计一个完美系统更现实。自动优先凡是重复性的工作数据校验、模型导出、回归测试一律脚本化、自动化。手动操作越多出错概率越大。可观测优先每个环节都留日志和指标上线后的系统要能看到业务指标哨兵。没有监控的AI系统就像没有仪表盘的飞机飞得越高越危险。2. 环境搭建与技术选型踩过坑之后推荐的组合2.1 Python环境管理别再到处装包了开始这个项目时我的第一个教训来自Python环境。以前我习惯直接 pip install 装一堆包结果就是不同项目之间的依赖互相打架升级一个库导致另一个项目跑不起来非常痛苦。随着实践深入我换成了 uv 来管理Python环境和依赖。它比传统 pip virtualenv 组合快很多而且锁文件机制能保证每个环境的依赖完全一致。如果你的项目已经有多个同事协作这一步尤其重要——不然“在我机器上跑得好好的”会成为全场使用率最高的甩锅借口。初次使用 uv 的步骤大致是这样# 创建Python 3.11环境 uv venv .venv --python 3.11 # 激活环境Windows/Linux略有差异 source .venv/bin/activate # 初始化项目 uv init # 添加核心依赖 uv add numpy pandas scikit-learn fastapi mlflow dvc依赖版本锁定之后项目里会有 uv.lock 文件任何人拉下代码后执行 uv sync 就能还原一模一样的环境。光是这一步就能省掉无数“同样代码不同结果”的排查时间。2.2 实验追踪用MLflow记录每一次尝试没有实验追踪工具的AI项目就像没有git的代码项目迟早会出事故。每次改一个参数、跑一次训练都应该留下完整的记录谁跑的、什么时间、用的什么配置、效果如何。我选的是MLflow理由很接地气部署简单、文档清晰、社区活跃而且支持自动记录超参数和指标。我习惯把每个项目的config文件、训练代码版本、数据集版本都挂到MLflow的run上这样就可以随时回溯“准确率82%的那个模型到底是用哪套配置跑出来的”。MLflow的代码集成并不复杂import mlflow mlflow.set_experiment(ai-engineering-from-scratch) with mlflow.start_run(): # 记录超参数和指标 mlflow.log_param(learning_rate, 0.001) mlflow.log_param(max_depth, 8) # ...训练代码... mlflow.log_metric(f1_score, 0.87) # 保存模型 mlflow.sklearn.log_model(model, model)使用MLflow过程中我的一个体会是最好把“记录参数”和“记录结果”散落在训练的各个关键节点而不是等到训练结束后一次性记录。这样如果训练中途挂了前面几轮的信息还能保留下来。2.3 数据版本管理把数据集当成代码对待AI工程和传统软件开发的一个显著差异是代码变了会导致行为变化数据变了同样会导致模型行为变化。可绝大多数项目只有代码在git里管理数据散落在各个目录换了一版数据连自己都未必记得。我在项目中引入了DVC做数据版本管理。它的工作方式很像git但管理的是大文件。具体来说DVC会把数据文件的元信息记录下来而实际内容可以存在本地、S3或者NAS上。用起来逻辑很自然# 添加数据目录并进行版本管理 dvc add data/raw/orders.csv git add data/raw/orders.csv.dvc git commit -m add initial dataset v1 # 后期切换数据版本 git checkout v2-orders.dvc dvc checkout这样每次实验的数据版本就变得可追溯了。我这里不是说DVC是唯一选择而是强调“数据版本管理”这个动作本身。不用DVC用git-lfs也完全可以关键是养成记录数据版本的习惯。2.4 容器化Docker镜像让环境真正“一致”即使在本地环境锁定了依赖部署到服务器时仍可能遇到差异——系统库版本、CUDA版本、Python解释器的微妙差异都可能在最终时刻冒出来。用Docker容器统一运行时环境是我这个项目里最省心的决定之一。理论上环境复现的链条可以做到这样简单从git拉代码用uv同步Python依赖用Docker构建包含全部系统依赖的镜像在容器里跑训练和推理。本地开发和线上部署共用同一个镜像最大程度避免“开发环境正常生产环境崩了”的现象。Dockerfile我一般写得尽量精简基础镜像选用带CUDA的官方PyTorch镜像再把项目代码和依赖打进去FROM pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . CMD [python, src/train.py]注意Docker镜像构建时要尽量利用层缓存——先拷贝依赖文件并安装再拷贝代码这样代码变化时不会重新安装所有依赖构建速度快很多。3. 数据管线的搭建从杂乱原料到高质量训练集3.1 数据采集与清洗别急着做特征工程很多人一拿到数据就急着提取特征、训练模型却忽略了数据质量的基本检查。我在项目里首先做的是“描述性统计数据体检”缺失率、分布形状、数值范围、重复记录、类别分布不均衡情况全部先打印出来看一遍。拿一个实际的场景举例做用户复购预测时原始数据里用户行为日志有上百万行但很多用户只有一两条记录。如果不查看数据分布而对所有用户一视同仁地提取特征结果模型大概率被少数高活跃用户带偏对普通用户完全没有区分能力。清洗数据时有一个很有意思的原则“数据清洗的终点是让下游消费数据的代码足够简单”。如果清洗完的数据还需要下游一遍遍处理异常值那说明清洗这步没有做透。我在项目里会把常见的清洗逻辑缺失值填充、时间字段解析、类别编码封装成独立的Pipeline组件而不是散落在训练脚本里。3.2 特征工程怎么把业务经验变成模型的语言特征工程是AI工程里最具“手工感”的环节也是最难标准化、却最能体现业务理解的地方。纯粹把原始字段喂给模型远远不够好的特征工程往往来自于对业务问题的拆解。以一个流失预测项目为例原始的原始维度可能只是用户ID、注册时间、每天登录次数。通过业务思考后我们就可以构造出更有意义的特征最近7天登录天数 / 最近30天登录天数频率变化趋势最后一次登录距今天数最近活跃度每日平均使用时长会话深度连续不登录的历史最长天数沉默惯性这些特征背后的逻辑是抓住“流失”这个行为在发生之前的一系列微弱信号。模型是无偏见的统计机器你给它什么信号它就学什么规律。如果特征设计得好有时比盲目换复杂模型更有效。3.3 数据校验在进入训练前设一道关卡数据质量是AI项目最容易出“隐蔽Bug”的地方。比如上线后某天数据源增加了一个新字段的取值训练的代码没变但模型的表现却突然变差了——这类问题如果没有数据校验机制往往要等业务投诉才能发现。我在Pipeline里加入了一步“数据校验”具体做法是检查数据集的schema列名、类型是否符合预期检查数值字段的范围是否在合理区间检查类别字段的取值是否在选择范围内检查目标变量的分布是否和训练集有显著差异如果校验不通过Pipeline要发出告警并中断训练。这一步看似简单但价值极高——很多AI系统的线上事故本质上都是训练和线上数据分布不一致造成的而数据校验就是拦住这类问题的最前一道防线。3.4 训练集与验证集的划分别让数据泄漏悄悄发生数据泄漏是训练评估中最隐蔽也最危险的问题。简单说就是验证集的信息在训练阶段被模型看到了导致评估指标虚高上线后立刻现原形。常见的泄漏途径在划分训练集/验证集之前就做了全量数据的归一化归一化参数应该只用训练集计算做时间序列预测时随机划分样本导致未来信息泄漏到训练集合特征工程中使用了全量数据的统计量比如用全量均值做填充对类别特征编码时用全量数据统计出的类别频率作为特征我建议每个项目都在数据集划分完成之前专门检查一遍“特征构造的过程是否接触过验证集信息”。这件事需要仔细因为多数泄漏不是代码层面的Bug而是设计层面的疏忽。4. 模型开发与训练从baseline到可靠的实验闭环4.1 永远先跑一个最小可用的baseline拿到干净的、经过校验的数据后我几乎不会立刻开始调试复杂模型。而是先跑一个最简单的baseline——比如逻辑回归或浅层决策树用默认参数不做任何花哨处理。这么做的目的非常明确验证数据链路是否通畅为后续模型的提升幅度提供对比基准。baseline的准确率也许不高但它的价值是确定了“这件事到底可不可行”。如果数据连最简单的模型都学不出有效模式那问题大概率不在模型选择而在数据质量或特征设计。这时候花几周时间调深度学习模型是典型的方向性错误。我经历过一个文本分类项目baselineTF-IDF逻辑回归的F1只有0.42感觉很低。本来打算上BERT精调后来深入看数据才发现标注质量参差不齐大量错误标签把学习上限压死了。回头清洗重建了标注集同一个baseline直接跳到0.71。这个经验让我坚信比模型更重要的是先把数据和任务本身搞明白。4.2 训练脚本的结构配置、数据、模型、训练逻辑分层刚开始做AI项目时我喜欢把一切都写进一个大脚本后来脚本越来越长修改一个参数都要翻好几屏。现在的实践是训练脚本严格分成四个模块各自职责解耦config.yaml所有超参数、路径、开关都在这里不写死在代码里dataset.py只负责加载数据和特征工程返回PyTorch Dataset/TF Datasetmodel.py定义模型结构只接受config中的参数train.py组织训练循环负责日志、评估、检查点保存这样做的好处很明显要调参改config就能完成要换模型替换model.py即可要换数据接一个新的dataset实现。每个部分都可以独立测试整个训练的“实验闭环”变得清晰可控。config.yaml的示例片段data: train_path: data/processed/train.parquet val_path: data/processed/val.parquet batch_size: 64 model: name: lightgbm max_depth: 8 learning_rate: 0.05 n_estimators: 500 train: seed: 42 early_stopping_rounds: 20 eval_metric: auc4.3 超参数调优网格搜索、随机搜索到贝叶斯优化超参数的选择在传统机器学习中往往是效果差异的重要来源。随着项目推进我逐渐从手工试参数过渡到更系统的方法。手工试参数虽然直觉性强但总会有盲区而且容易“memory bias”——记得某次跑出了好结果却说不清当时的完整配置。随后我切换到随机搜索在给定范围内随机采样参数组合每个组合跑一轮完整实验记录结果。随机搜索的实现简单效果却经常比网格更好这主要因为参数空间中每个维度的灵敏度不同随机采样能更均匀地覆盖组合空间。当实验规模进一步增大、每次训练耗时较长时我引入了Bayesian Optimization用Optuna。它会根据历史实验结果选择最有潜力的下一组参数显著减少了无效训练次数。使用Optuna的体验很友好我一般会配合MLflow一起用把每一次trial的参数和指标都记录到同一个实验里。import optuna def objective(trial): params { max_depth: trial.suggest_int(max_depth, 4, 12), learning_rate: trial.suggest_float(learning_rate, 0.01, 0.1, logTrue), n_estimators: trial.suggest_int(n_estimators, 200, 800), } # ...运行训练并返回评估指标... return score4.4 过拟合识别与应对策略训练集表现迅速走高、验证集表现止步不前这是所有AI项目迟早都会撞上的问题。要识别正在过拟合并不难观察训练和验证指标的分叉曲线。重点是如何应对。我的经验排序是数据层面增加更多训练数据含数据增强这是最稳的打法模型层面降低模型复杂度适当减少层数、加正则化L2、Dropout训练层面早停early stopping一般效果明显把验证集最优的轮次保存成最终模型集成层面多模型加权平均提升鲁棒性但推理解释性略降另外我强烈建议在样本量有限时使用k-fold交叉验证评估模型而不是只切一次验证集。交叉验证的结论更稳健能有效防止“在某一验证集上运气好”造成虚高判断。5. 模型评估、部署与服务化从实验产物到线上服务5.1 离线评估的正确姿势不只关注单一指标训练完成后很多人习惯看一眼测试集准确率就下结论但这远远不够。离线评估的目标是尽可能准确地预测线上表现并且帮助定位模型的薄弱环节。我会把评估拆成几个层次总体指标准确率、精确率、召回率、F1、AUC先看整体水平分层指标按业务维度拆分比如用户地区、商品品类、时段看模型在不同子群体上的表现是否有明显差异误差分析将预测错误的样本分门别类是标注问题、特征缺失还是模型判断逻辑本身的缺陷分层指标和误差分析尤其重要。比如一个推荐模型总体准确率80%但仔细一看新用户的准确率只有40%说明模型对无行为冷启动用户几乎失效这就是需要通过策略重点优化的问题。5.2 模型导出与打包别只保存一个pickle文件模型训练好之后不能直接丢一个pickle就交给部署同事。模型导出需要包含完整的元信息模型文件、特征列表、预处理流水线包括归一化参数、类别编码表、推理依赖的版本。我用MLflow的model registry功能管理模型版本。每训练出一个候选模型注册到Model Registry标记状态staging/production方便追踪哪个版本的模型正在线上服务。当新模型效果确实更好时再标记production并部署整个过程在“代码—训练—注册—部署”之间有清晰流转。MLflow注册模型很简单# 注册模型到registry mlflow.register_model( model_uriruns:/run_id/model, nameorder-classifier )5.3 模型推理服务FastAPI搭建轻量级服务模型上线环节我一般用FastAPI写推理服务。它是一个轻量级的Python Web框架和Flask相比自带OpenAPI文档、类型校验、异步支持对模型推理服务非常友好。一个典型的推理服务入口长这样from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class PredictRequest(BaseModel): features: list[float] class PredictResponse(BaseModel): prediction: int probability: float app.post(/predict, response_modelPredictResponse) def predict(req: PredictRequest): proba model.predict_proba([req.features])[0] return PredictResponse( predictionint(proba.argmax()), probabilityfloat(proba.max()) )一个容易被忽视的细节线上推理的输入格式必须和训练时一致否则模型拿到的数值分布会错位。这个统一由预处理层的Pipeline承接推理请求先经过和数据管线里相同的特征处理逻辑再喂给模型。千万别在部署环境里另外写一份特征处理代码——那几乎是“线上效果崩了”的标配原因。5.4 推理性能优化从并发设计到推理加速当线上请求量上来之后推理性能会成为新的瓶颈。我在项目里踩过不少坑整理出几个经验性的方向并发设计模型本身一般是线程安全的但在加载时要注意只加载一次不要每来一个请求重新加载输入批处理对高吞吐场景收集多个请求组成batch一次性推理GPU或向量化运算的利用率会明显提升模型轻量化如果延迟要求严苛可以考虑蒸馏小模型、量化为int8、或使用ONNX Runtime加速缓存策略对相同或相似输入可以用简单缓存如Redis降低重复计算开销优化要遵循“先测量、再优化”的原则。不做压力测试就盲目上调优手段往往事倍功半。我通常会先用wrk或locust打一轮压力测试找出瓶颈在哪一侧是CPU推理、网络IO还是内存——再针对具体瓶颈动手。6. 持续监控与模型维护AI系统上线只是开始6.1 线上监控模型效果不止是准确率AI模型上线后最危险的事情不是模型效果不好而是模型效果悄悄变差而无人察觉。线上系统的监控体系需要覆盖两层指标业务指标比如推荐点击率、客服转人工率、预测准确率如果能拿到标签的话技术指标接口延迟、QPS、显存占用、错误率、依赖服务的可用性业务指标监控是模型监控的核心。很多业务指标天然有延迟——比如下单转化率要等用户行为发生之后才知道。所以还要设计一套定期滞后的评估方式把线上预测结果和延迟到达的监督信号做定期比对。6.2 数据漂移检测提前发现模型退化的信号数据漂移Data Drift是线上模型效果变差最主要的诱因之一。用户行为变了、数据结构变了、业务规则变了都会导致输入分布和训练分布不一致模型自然就不准了。检测实践中我会对每个关键特征做两种监测单特征分布监控比如用户年龄分布、地区分布定期用KS检验或PSI指标对比当前分布和历史训练分布预测分布监控模型输出的各类别概率分布是否发生了明显变化一旦监测到某个特征的PSI超过阈值就触发告警。这类告警不一定意味着模型立刻失效但它提醒我们是时候检查线上数据、评估模型是否需要重新训练了。6.3 定期重训策略不是越频繁越好模型训练频率是一个需要认真权衡的问题。过度频繁地重训不仅增加计算成本还可能导致模型在不同时段之间振荡而重训过慢又无法适应数据变化。实践中我采取了分级策略每日自动重训仅当数据漂移指标超过阈值时触发每周固定重训作为一个稳妥的常规周期保证模型能跟上中长期趋势人工触发重训当业务规则、数据格式或者产品逻辑发生重大变化时由工程师判断是否重训每个重训流程都复用同样的Pipeline训练完成后自动注册到Model Registry先跑一遍离线回归测试通过后才自动部署到生产环境。人工干预环节只保留在“重大变更”场景真正做到了自动化与可控性的平衡。7. 问题排查实录那些让人失眠的AI工程事故7.1 训练误差疯涨先检查学习率再检查数据管线有一次训练过程中Loss曲线已经正常下降了十几个epoch突然开始一路飙升。我第一反应是学习率太大或者梯度爆炸翻了一圈代码没发现问题。后来通过回溯MLflow的记录发现那个epoch的数据加载顺序不同了——一个随机shuffle的seed在重构代码时不小心丢掉了导致数据的分布变化影响到了训练稳定性。这个小问题让我印象深刻AI工程里很多“模型问题”追到根上其实是“工程问题”。训练Pipeline里的任何一个随机性来源shuffle seed、数据读取顺序、多线程采样顺序都应该被严格记录和控制。7.2 离线效果很好线上效果很差的经典原因线上效果和离线评估差异明显的场景我是深有体会的。有一次做一个定价预测模型离线验证的MAE看着亮眼上线后业务反馈“预测价格偏差很大”。排查到最后发现线上推理请求的特征构造代码和离线训练时有一处不一致——一个表示用户会员等级的特征离线使用的是数值编码线上服务却传入了原始字符串模型直接把该特征当成缺失处理预测自然就偏了。从此之后我养成了一个习惯在离线评估时刻意模拟线上特征处理的代码路径而不是单独写一份“评估专用”的特征工程逻辑。这是最能降低线上线下效果差异的做法之一。7.3 GPU显存不足与推理服务OOM的处理训练阶段显存不足还好办加大batch size的相反方向——减小batch size或者用梯度累积。真正让人头疼的是推理服务在高峰期OOM。有一次部署一个在线OCR服务白天还好晚上业务高峰时进程频繁被杀。排查后原因有两个一个是一次性加载了多个版本的模型文件另一个是FastAPI框架的同步阻塞导致并发请求堆积在内存里。修复方式也不复杂只加载当前需要服务的单一模型文件并把推理接口改成异步处理同时给推理函数加上显式批处理逻辑。从那以后我对“推理服务的内存预算”有了更敏感的认知——显存占用不只是模型大小的函数还包括输入输出缓冲区和并发请求的累积。7.4 自动重训导致效果退化自动重训听着美好但也可能带来麻烦。有次系统自动重训后线上推荐点击率反而明显下降。查了MLflow后发现重训的触发条件其实是某个特征的数据分布轻微漂移可那次重训使用的样本量太少训练出的模型不仅没有适应变化反而被最近的随机波动带偏了。从那之后我给自动重训加了两条铁律一是重训必须使用累计一段时间的数据量而非最近一天的数据二是重训模型必须通过离线回归测试与线上旧模型在历史一致的数据上做对比不达标就回滚并告警。8. 结尾AI工程真正的门槛在哪里做完了这一整套流程我最深的感受是AI工程最难的从来不是某个模型有多复杂而是把散落的环节串成一条稳定可靠的流水线。模型选型、参数调优这类问题网上随便一搜就有无数教程而数据版本管理、实验记录规范、线上监控体系、自动回滚机制这些“工程化的细节”才真正决定了项目能不能走长远。如果你正打算从零开始做一个AI项目我的建议很简单先别追求一步到位哪怕刚开始用最笨的脚本也把数据、实验、模型部署三个环节的边界清清楚楚地画出来然后逐步自动化、精细化。每踩一个坑就把对应的防线补上——这个过程本身就是“ai-engineering-from-scratch”最有价值的部分。模型会过时、框架会迭代但这条“从问题出发、用数据驱动、拿工程保障”的路径在任何时代都不会过时。