1. 从零搭建AI工程能力这个项目到底在解决什么问题第一次看到 ai-engineering-from-scratch 这个标题我脑子里蹦出来的不是某个具体框架而是一类人的真实困境算法题刷了不少Transformer 结构图也能画出来但真给一台空服务器、一个模糊的业务需求要从数据清洗一路搭到线上推理服务手就不知道往哪儿放了。这个项目标题指向的正是填补懂模型和能交付之间那道鸿沟的工程化训练路径。我自己带过几批刚毕业的同学也见过不少转行做 AI 的朋友。大家普遍卡在同一个地方学习路径是课程式的先学线性代数再学反向传播再跑一个 MNIST然后突然跳到部署一个 LLM 应用。中间那段——数据怎么组织、实验怎么管理、模型怎么打包、服务怎么扛住并发、成本怎么算——几乎没人系统讲过。ai-engineering-from-scratch 这类项目的价值就是把这中间被跳过的部分用一条可复现的动手路线补回来。它适合谁三类人最该认真看一是计算机相关专业的学生课程作业能跑通但没做过完整项目二是从后端、数据分析转 AI 工程的开发者代码功底有但缺 AI 特有的工程直觉三是已经在做 AI 但总觉得自己是调包侠、想搞明白底层链路的人。这篇文章我会按整体设计思路—核心细节—实操落地—问题排查的顺序把这条从零到一的路径拆开讲尽量给到能直接抄作业的步骤和参数。需要先说明一点下面涉及的具体工具选型、目录结构、参数配置是基于我这些年做 AI 工程项目的常见实践做的合理补全不是某个官方仓库的逐行复刻。你可以把它当成一份如果我来从零搭一套 AI 工程训练项目我会怎么做的完整方案。2. 整体设计与思路拆解为什么这样搭而不是那样搭2.1 先想清楚从零到底指哪一层from scratch这个词很容易被误解。有人以为是不用任何框架纯 NumPy 手写神经网络有人以为是从装系统开始。我的理解是它指的是工程链路的从零而不是数学原理的从零。也就是说你可以用 PyTorch、可以用 HuggingFace但你要亲手把数据、训练、评估、打包、服务、监控这条线全部串起来每一环都知道为什么这么接。为什么这么定调因为纯手写框架的训练价值有限——你花两周手写一个反向传播学到的东西和读一遍自动微分原理差不多但工程链路的每一环都是真实项目里绕不开的。反过来如果只是调 API那又回到了调包侠的老路。所以这个项目的核心设计原则是框架可以用但每个环节的输入输出、边界条件、失败模式必须自己掌控。我一般会把整条链路拆成六个阶段每个阶段都有明确的交付物而不是学完一章做个练习这种松散结构阶段核心任务交付物常见卡点数据工程采集、清洗、切分、版本化可复现的数据集快照数据泄漏、切分不随机实验管理配置、日志、指标追踪可对比的实验记录参数散落、结果无法复现模型训练训练循环、检查点、早停可加载的模型权重过拟合、显存溢出评估验证离线指标、错误分析评估报告指标好看但线上拉胯服务化打包、API、批处理可调用的推理服务冷启动、并发瓶颈监控迭代日志、漂移检测、回滚监控看板上线即失联这张表是我自己项目里反复用的骨架。你会发现它和很多教程的区别在于数据工程和实验管理占了前两位。很多从零项目一上来就讲模型结构但真实项目里模型结构往往是最不花时间的部分前面两步才是决定项目成败的地方。2.2 技术选型背后的取舍逻辑选型这件事新手最容易犯的错是追新。看到某个新框架火了就换结果每个都只懂皮毛。我在这个项目里坚持一个原则每一层只选一个主流且稳定的方案把精力放在链路打通上而不是工具对比上。具体来说语言层面用 Python这个没什么争议。深度学习框架用 PyTorch理由是它的动态图调试体验对新手友好报错信息也相对直观。数据处理用 pandas 加 datasets 库前者处理表格数据后者处理大规模文本或图像数据集。实验管理我强烈建议用 MLflow 或 Weights Biases 这类工具哪怕只是本地跑也要养成记录习惯。服务化用 FastAPI轻量、异步支持好、文档自动生成。容器化用 Docker这个几乎是现代 AI 工程的标配。为什么不用更高级的方案比如直接用某个云平台的托管训练因为从零项目的目的是建立掌控感。你用托管服务出问题只能看平台日志学不到东西。自己搭一遍哪怕简陋每个报错都是你的。等你把链路跑通了再去用托管服务提效那时候你是选择用它而不是只能用它。还有一个取舍是关于数据规模的。很多人一上来就想搞个大模型、大语料结果卡在数据下载和显存上热情三天就没了。我的建议是先用一个能在单机跑通的小数据集把链路走完比如几万条文本分类数据或者一个小型图像数据集。链路通了再换大数据集这时候你遇到的只是规模问题而不是整个流程都不会的问题。2.3 目录结构工程化的第一道门槛我见过太多项目所有代码堆在一个 notebook 里或者根目录下十几个test.py、test2.py、test_final.py。这种结构在 demo 阶段没问题但一旦要迭代就是灾难。ai-engineering-from-scratch 这类项目必须从一开始就建立清晰的目录约定。我常用的结构是这样的project/ ├── configs/ # 所有配置文件按实验分组 │ ├── base.yaml │ └── exp001.yaml ├── data/ │ ├── raw/ # 原始数据只读 │ ├── interim/ # 中间处理结果 │ └── processed/ # 最终训练用数据 ├── src/ │ ├── data/ # 数据加载与处理 │ ├── models/ # 模型定义 │ ├── train/ # 训练逻辑 │ ├── eval/ # 评估逻辑 │ └── serve/ # 服务化代码 ├── notebooks/ # 探索性分析不参与生产 ├── tests/ # 单元测试 ├── scripts/ # 一键脚本 ├── artifacts/ # 模型权重、日志等产物 └── README.md这个结构的关键在于数据分层和代码分层。raw目录只读任何处理都写到interim或processed这样你永远能回到原始数据重跑。src下按功能分模块训练和服务代码分离避免服务端不小心 import 了训练依赖。configs独立出来是为了让实验可复现——改配置不改代码这是工程化的基本素养。提示artifacts目录一定要加进.gitignore。模型权重动辄几百 MB提交到 Git 会把仓库撑爆。用对象存储或者本地路径管理代码里只存路径引用。3. 核心细节解析与实操要点每个环节的坑在哪3.1 数据工程80% 的时间花在这里不冤数据工程是整个链路里最不性感、但最决定成败的部分。我统计过自己做过的项目数据处理和清洗的时间通常占整个项目的 50% 到 70%。新手最容易低估这块觉得读进来、分个 train/test 就完事了结果模型效果上不去回头一看是数据泄漏或者标签噪声。先说数据切分。很多人用train_test_split随手一分但忽略了几个关键点。第一如果数据有时间属性必须按时间切分不能随机切否则你会用未来的数据预测过去线下指标虚高。第二如果同一条数据有多个样本比如同一用户的多次行为要按实体切分避免同一实体同时出现在训练和测试集。第三切分比例不是固定的 8:1:1小数据集可能要 6:2:2大数据集 98:1:1 也正常。再说数据泄漏。这是最隐蔽的坑。举个真实例子我做文本分类时把整个数据集先做了 TF-IDF 向量化再切分训练测试集。结果词表里包含了测试集的词汇信息线下准确率 95%线上一塌糊涂。正确做法是任何依赖全局统计的预处理都只能在训练集上 fit然后 transform 到测试集。这个原则适用于标准化、编码、特征选择等所有环节。数据版本化也常被忽略。你改了清洗逻辑重跑一遍但旧模型是用旧数据训的这时候你根本分不清效果变化是来自数据还是模型。我的做法是用 DVC 或者简单的哈希标记每次数据处理生成一个版本号训练配置里记录用的是哪个版本。这样任何一次实验都能追溯到确切的数据快照。import hashlib import pandas as pd def data_version(df: pd.DataFrame) - str: 基于数据内容生成版本号内容变则版本变 content pd.util.hash_pandas_object(df, indexTrue).values return hashlib.md5(content.tobytes()).hexdigest()[:12] # 使用示例 df pd.read_csv(data/processed/train.csv) print(f当前数据版本: {data_version(df)})这段代码很简单但作用很大。它让你在实验记录里写下一个版本号就能精确对应到某一份数据。别小看这个习惯等你做了几十次实验回头想复现某个好结果时会感谢自己。3.2 实验管理让每次尝试都留下痕迹实验管理的核心目标是可复现和可对比。我见过太多人跑了一堆实验最后只记得好像有个参数效果不错具体是多少、用的什么数据、什么代码版本全忘了。这不是记忆力问题是流程问题。最低成本的实验管理是把所有超参数写进配置文件每次实验生成一个独立目录里面存配置、日志、指标、模型。进阶一点用 MLflow 这类工具它能自动记录参数、指标、产物还能起一个 Web 界面做对比。我建议哪怕项目再小也要养成配置驱动的习惯。配置驱动的好处是你的代码里不应该出现硬编码的超参数。学习率、batch size、模型层数全部从配置读。这样改实验只需要改 YAML不用动代码也避免了改了代码忘了改回来的尴尬。# configs/exp001.yaml data: train_path: data/processed/train.csv val_path: data/processed/val.csv max_length: 128 model: name: bert-base-chinese num_labels: 5 dropout: 0.1 train: batch_size: 32 learning_rate: 2e-5 epochs: 5 warmup_ratio: 0.1 seed: 42 output: dir: artifacts/exp001这个配置文件里seed是我特别想强调的。深度学习里有大量随机性权重初始化、数据打乱、dropout。如果不固定随机种子同样的配置跑两次结果可能差好几个点你根本没法判断是配置变了还是随机性。固定种子是实验可复现的底线。还有一个细节是指标记录。不要只记最终准确率要记训练过程中的 loss 曲线、学习率变化、每个 epoch 的验证指标。这些曲线能告诉你很多信息loss 震荡说明学习率太大验证 loss 上升说明过拟合loss 不降说明模型或数据有问题。我习惯用 TensorBoard 或 WB 实时看曲线比看数字直观得多。3.3 训练循环看似简单细节全是坑训练循环的代码看起来就那么几行但每个细节都可能出问题。我按顺序说几个关键点。混合精度训练。现在显卡基本都支持 fp16 或 bf16用混合精度能省显存、提速但要注意梯度缩放。PyTorch 的torch.cuda.amp已经封装好了用起来很简单但新手常犯的错是忘了在验证时也切换精度或者梯度累积时缩放没处理好。梯度累积。显存不够时用小 batch 累积几步再更新等效于大 batch。但要注意BatchNorm 这类依赖 batch 统计的层累积时行为会变。如果模型里有 BatchNorm梯度累积要谨慎或者换成 LayerNorm。检查点与早停。不要只存最后一个 epoch 的模型要存验证指标最好的那个。早停的 patience 一般设 3 到 5太小容易错过后面的提升太大浪费算力。我一般还会存一个最后状态包含优化器状态方便中断后继续训练。import torch from torch.cuda.amp import autocast, GradScaler scaler GradScaler() best_val_loss float(inf) patience_counter 0 patience 3 for epoch in range(num_epochs): model.train() for batch in train_loader: optimizer.zero_grad() with autocast(): outputs model(**batch) loss outputs.loss scaler.scale(loss).backward() scaler.step(optimizer) scaler.update() val_loss evaluate(model, val_loader) if val_loss best_val_loss: best_val_loss val_loss torch.save(model.state_dict(), f{output_dir}/best.pt) patience_counter 0 else: patience_counter 1 if patience_counter patience: print(f早停于 epoch {epoch}) break这段代码是训练循环的骨架。注意autocast只包住前向传播反向传播由scaler处理。验证时不需要autocast或者用torch.no_grad()包住。这些细节看起来琐碎但错一个就可能导致训练不稳定或者显存泄漏。注意torch.save(model.state_dict())存的是权重加载时需要先实例化模型结构。如果想连结构一起存用torch.save(model)但这样加载依赖代码定义跨项目迁移不方便。我一般存 state_dict配合配置文件重建模型。3.4 评估验证线下指标好看不等于线上能用评估这块新手最容易犯的错是只看一个总体指标。准确率 90% 听起来不错但如果你的数据里 90% 是负样本那模型全预测负样本也有 90% 准确率毫无意义。所以评估一定要看多个维度精确率、召回率、F1、混淆矩阵分类任务还要看每个类别的表现。更重要的是错误分析。把模型预测错的样本捞出来人工看几十条你会发现问题往往很集中某一类样本特别难分或者某些样本标签本身就有问题。这一步是提升效果最有效的手段比调参有用得多。我一般会写个小脚本把错误样本按置信度排序优先看那些模型很自信但错了的样本这些往往揭示了系统性问题。还有一个常被忽略的点是评估集的选择。如果你的评估集和训练集同分布指标会偏乐观。真实场景里线上数据分布往往和训练数据有差异。所以有条件的话要留一个分布外的测试集或者至少做交叉验证看看模型在不同子集上的稳定性。评估维度关注指标常见问题整体性能准确率、F1类别不平衡时失真分类别性能每类 P/R/F1少数类被忽略置信度校准ECE、可靠性图模型过度自信鲁棒性扰动后指标对输入变化敏感效率延迟、吞吐线上无法满足 SLA这张表是我做评估时的检查清单。特别是置信度校准很多模型输出的概率不能直接当置信度用需要温度缩放等后处理。如果你的业务要根据置信度做决策比如低置信度转人工这一环不能省。4. 实操过程与核心环节实现从空目录到可调用服务4.1 环境准备与依赖管理动手第一步是环境。我强烈建议用虚拟环境conda 或 venv 都行别在系统 Python 里装一堆包。依赖管理用requirements.txt或者更好的pyproject.toml把版本号锁死。AI 项目的依赖版本敏感度很高PyTorch 差一个小版本可能就有 API 变化锁版本能省很多事。# 创建虚拟环境 python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate # 安装核心依赖 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 pip install transformers datasets fastapi uvicorn mlflow pandas scikit-learn这里--index-url指定了 CUDA 版本对应的源装之前先确认自己的显卡驱动支持的 CUDA 版本。装完用torch.cuda.is_available()验证一下返回 False 就说明环境没配好别急着往下走。依赖装好后先跑一个最小验证加载一个预训练模型做一次前向传播。这一步能排除掉大部分环境问题。我见过有人写了半天训练代码一跑发现 CUDA 不可用白忙活。4.2 数据管道搭建数据管道我习惯分三步加载、处理、封装成 Dataset。加载阶段把原始数据读进来处理阶段做清洗和特征工程封装阶段转成 PyTorch 的 Dataset 和 DataLoader。处理阶段有几个参数要仔细调。文本任务里max_length直接影响显存和效果。太短会截断信息太长浪费算力。我的经验是先统计训练集长度的分布取覆盖 95% 样本的长度作为max_length。图像任务里分辨率同理不要盲目用 224根据任务难度和数据量调整。from torch.utils.data import Dataset, DataLoader from transformers import AutoTokenizer class TextDataset(Dataset): def __init__(self, texts, labels, tokenizer, max_length128): self.encodings tokenizer( texts, truncationTrue, paddingmax_length, max_lengthmax_length, return_tensorspt ) self.labels labels def __len__(self): return len(self.labels) def __getitem__(self, idx): item {k: v[idx] for k, v in self.encodings.items()} item[labels] torch.tensor(self.labels[idx]) return item tokenizer AutoTokenizer.from_pretrained(bert-base-chinese) train_dataset TextDataset(train_texts, train_labels, tokenizer) train_loader DataLoader(train_dataset, batch_size32, shuffleTrue, num_workers4)num_workers这个参数值得说一句。它控制数据加载的并行进程数设太小数据加载会成为瓶颈设太大可能吃满内存。一般设成 CPU 核心数的一半到全部具体看机器。Windows 上num_workers大于 0 有时会有问题遇到奇怪的报错可以先设成 0 排查。4.3 训练与评估的完整流程把前面的模块串起来一个完整的训练脚本大概长这样读配置、建数据管道、初始化模型和优化器、训练循环、评估、保存产物。我习惯把训练和评估写成函数主脚本只负责编排这样每个部分都能单独测试。优化器的选择上Transformer 类模型用 AdamW学习率一般 1e-5 到 5e-5配合 warmup。warmup 的作用是训练初期慢慢把学习率升上去避免一开始就把预训练权重破坏掉。warmup 比例一般设总步数的 10%。学习率调度用线性衰减或余弦衰减看任务而定。评估函数要独立于训练输入模型和数据加载器输出指标字典。这样训练中途可以调用训练完也可以单独跑。评估时记得model.eval()和torch.no_grad()前者切换 dropout 和 batchnorm 的行为后者省显存。def evaluate(model, dataloader, device): model.eval() all_preds, all_labels [], [] with torch.no_grad(): for batch in dataloader: batch {k: v.to(device) for k, v in batch.items()} outputs model(**batch) preds outputs.logits.argmax(dim-1) all_preds.extend(preds.cpu().numpy()) all_labels.extend(batch[labels].cpu().numpy()) from sklearn.metrics import classification_report report classification_report(all_labels, all_preds, output_dictTrue) return reportclassification_report会给出每个类别的精确率、召回率、F1比单一准确率信息量大得多。我一般还会把混淆矩阵画出来看看错误集中在哪些类别之间。4.4 服务化把模型变成能调用的 API模型训好了最后一步是服务化。用 FastAPI 起一个推理服务加载模型暴露一个 POST 接口。这里有几个工程细节要注意。第一模型加载只做一次放在应用启动时不要每次请求都加载。第二推理要加锁或者用队列因为 PyTorch 模型不是线程安全的并发请求直接调可能出问题。第三输入要做校验和预处理输出要格式化别把原始 tensor 直接返回。from fastapi import FastAPI from pydantic import BaseModel import torch app FastAPI() model None tokenizer None app.on_event(startup) def load_model(): global model, tokenizer tokenizer AutoTokenizer.from_pretrained(bert-base-chinese) model AutoModelForSequenceClassification.from_pretrained(artifacts/exp001/best) model.eval() class Request(BaseModel): text: str app.post(/predict) def predict(req: Request): inputs tokenizer(req.text, return_tensorspt, truncationTrue, max_length128) with torch.no_grad(): logits model(**inputs).logits probs torch.softmax(logits, dim-1) pred probs.argmax().item() return {label: pred, confidence: probs[0][pred].item()}启动命令是uvicorn src.serve.app:app --host 0.0.0.0 --port 8000。启动后访问/docs能看到自动生成的接口文档直接在里面测试。这个服务很简陋但链路是通的。生产环境还要加日志、限流、健康检查、模型版本管理但那是下一步的事。提示服务化时把模型推理封装成单独的函数不要和 FastAPI 的路由逻辑耦合。这样以后换 Web 框架或者改成批处理任务推理逻辑都能复用。5. 常见问题与排查技巧实录5.1 训练不收敛的排查顺序训练 loss 不降是最常见也最让人抓狂的问题。我的排查顺序是这样的先看数据再看模型最后看超参数。数据层面检查标签是否正确对齐有没有全 0 或全 1 的异常样本输入和标签是不是错位了。我遇到过一次数据加载时 shuffle 了特征但没 shuffle 标签模型怎么训都是随机水平。模型层面检查输出维度对不对损失函数选得对不对比如多分类用了二分类的损失。超参数层面学习率太大导致震荡太小导致不降先试几个数量级。还有一个隐蔽的原因是梯度消失或爆炸。打印每层的梯度范数如果大部分接近 0说明梯度消失可能需要加残差连接或换激活函数如果数值巨大说明梯度爆炸需要梯度裁剪。梯度裁剪在 Transformer 训练里几乎是标配torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm1.0)一行搞定。5.2 显存溢出的几种解法显存溢出OOM是另一个高频问题。解法按代价从低到高排减小 batch size、减小序列长度或图像分辨率、用梯度累积模拟大 batch、用混合精度、用梯度检查点、换更小的模型、用模型并行。一般前三个就能解决大部分情况。梯度检查点gradient checkpointing值得单独说。它用计算换显存前向传播时不存中间激活反向时重新算一遍。显存能省 50% 以上代价是训练慢 20% 左右。Transformer 模型基本都支持一行配置就能开。# 开启梯度检查点 model.gradient_checkpointing_enable() # 或者训练时用 from torch.utils.checkpoint import checkpoint如果这些都试了还是 OOM那可能是代码里有显存泄漏。常见原因是把 tensor 存进了 list 但没 detach或者验证时忘了torch.no_grad()。用torch.cuda.memory_summary()能看到显存分配详情定位泄漏点。5.3 线下好线上差的典型原因模型线下指标漂亮上线就拉胯这个落差几乎每个 AI 工程师都经历过。原因通常有几类数据分布不一致、特征处理不一致、评估指标和业务目标不一致、服务端有 bug。数据分布不一致最常见。训练数据是历史积累的线上是实时产生的两者分布可能差很远。解法是持续监控线上数据分布发现漂移就补充训练数据。特征处理不一致也很隐蔽比如训练时用了某个归一化参数服务端忘了用或者用了不同的参数。解法是把预处理逻辑封装成共享模块训练和服务都调同一份代码。评估指标和业务目标不一致这个更本质。线下用准确率线上业务关心的是转化率两者不一定正相关。解法是在项目早期就和业务方对齐指标最好能做一个线上的 A/B 测试框架用真实业务指标验证模型价值。问题现象可能原因排查方法线下高线上低数据分布漂移对比线上线下特征分布预测结果不稳定预处理不一致检查服务端预处理代码延迟过高模型太大或批处理不当profile 推理耗时部分请求报错输入边界情况加输入校验和日志效果随时间下降概念漂移监控指标趋势定期重训这张表可以贴在手边出问题时按图索骥。我自己的经验是线上问题里真正是模型本身的不到三成大部分是工程链路的问题。5.4 几个我踩过的坑说几个具体的。第一个是随机种子没固定全。PyTorch、NumPy、Python 内置 random 各有各的种子只固定一个不够。而且 DataLoader 的worker_init_fn也要设否则多进程加载数据时随机性还是不可控。完整的种子固定要覆盖所有这些。第二个是配置文件路径写死。本地跑没问题换台机器或者进容器就找不到文件。解法是用相对路径加项目根目录定位或者用环境变量传路径。我一般会在代码开头把项目根目录加到sys.path所有路径基于根目录拼。第三个是忘了关训练模式。评估时忘了model.eval()dropout 还在起作用指标忽高忽低。这个错误很隐蔽因为不会报错只是结果不稳定。养成习惯训练前model.train()评估前model.eval()形成肌肉记忆。第四个是日志级别没调。transformers 库默认会打一堆 warning把关键信息淹没了。用transformers.logging.set_verbosity_error()调高日志级别只留错误。自己的日志用 logging 模块分级别输出别用 print。6. 从跑通到跑好工程能力的进阶方向链路跑通只是起点。真正拉开工程师差距的是跑通之后的优化和扩展。我按投入产出比排几个方向。第一是自动化。把数据处理、训练、评估、部署串成一条流水线用 Makefile 或者简单的 shell 脚本一条命令跑完。更进一步用 CI/CD代码提交自动跑测试和训练。自动化省下的时间是你做更多实验的本钱。第二是监控和可观测性。服务上线不是终点要能看到它的运行状态请求量、延迟、错误率、预测分布。预测分布尤其重要如果线上预测的类别分布突然变了往往意味着数据漂移要触发重训。这块用 Prometheus 加 Grafana 是常见组合。第三是成本优化。AI 服务的成本主要在算力。推理侧可以用量化、蒸馏、批处理来降本。量化把 fp32 降到 int8模型小一半速度快两三倍精度损失通常可接受。蒸馏用大模型教小模型适合对延迟敏感的场景。这些技术不难难的是知道什么时候用、用哪个。第四是持续学习。线上数据是源源不断的模型要定期用新数据更新。但全量重训成本高可以用增量学习或者定期微调。关键是要有一套评估机制确保新模型确实比旧模型好再上线替换。我个人在实际操作中的体会是从零搭一套 AI 工程链路最难的不是某个技术点而是把整条链路串起来并保持可复现。单个环节的教程网上到处都是但把它们组合成一个能持续迭代的系统需要的是工程思维和纪律。这个项目标题指向的能力本质上就是这种把散点连成线的能力。你跑通一遍再跑通第二遍第三遍的时候就会发现很多当初觉得难的东西已经变成肌肉记忆了。最后分享一个小技巧每完成一个阶段写一份简短的 README记录这个阶段做了什么、遇到什么问题、怎么解决的。这份文档在几周后你自己回头看时价值远超你的想象。工程能力很多时候不是学出来的是记录和复盘出来的。