前几年大家聊 AI聊的还是某个模型准确率多高、炼丹多炫。但真正把一个模型放到业务里、扛住流量、持续迭代你会发现大部分工作量根本不在模型本身而在模型外围那一大圈工程化的东西。这就是我理解的 ai-engineering也是ai-engineering-from-scratch这个项目最想解决的事不是教你调参而是教你从零开始把一个模型项目当成一个软件系统工程来做。这篇文章写给谁两类人。一类是算法工程师你训练模型很熟练但一说到部署、监控、CICD就头皮发麻另一类是后端或者全栈工程师你想往 AI 方向靠但是被梯度、损失函数这些概念劝退过。这篇文章会用一套完整的项目实践把从数据准备到模型上线的全过程拆开讲清楚所有代码都是可以在自己电脑上跑通的级别不是那种只讲概念的空中楼阁。我会按我自己从零搭这套体系时的踩坑顺序来写尽量把为什么这么做也说透。1. AI 工程全景先搞懂你要搭的是什么1.1 AI 工程和算法研究的本质区别先说个最容易被搞混的点AI 工程不是算法研究。研究的目标是在公开数据集上刷出更高的准确率工程的目标是让模型稳定地、可维护地、有成本效益地服务真实业务。这两个目标经常是冲突的。我见过太多团队把大量时间花在优化模型结构上最后发现线上瓶颈是推理延迟太高、或者是特征管线不稳定、再或者是模型版本根本没法回滚。用个生活化的类比算法研究是研发一道新菜你只需要在厨房里把这道菜做到好吃AI 工程是把这道菜变成连锁餐厅的标准菜品你得设计中央厨房的流程、培训厨师、控制食材成本、保证每家分店口味一致。后者其实更难而且大部分难度不在做菜本身。ai-engineering-from-scratch这个项目的核心思路是先建立一个完整的工程视角一个 AI 系统不只是模型还包括数据管线、训练平台、模型仓库、推理服务、监控告警这五个部分。缺任何一个系统都不算真正完成。1.2 从零到一五阶段的路线图设计我给自己设计的学习路径是这样拆分的每一步都对应一类独立的技能而且顺序不能乱阶段一基础工具链。Python 工程化写法、虚拟环境管理、版本控制、Docker 容器化。这叫先把房子地基打好。阶段二数据处理与特征工程。从原始数据到模型能吃的格式包括清洗、切分、标准化、数据版本管理。阶段三训练与评估。模型代码结构设计、超参数管理、实验记录、评估指标选择。阶段四部署上线。把训练好的模型包装成 API 服务处理并发、延迟、资源占用。阶段五监控与迭代。线上数据漂移检测、模型回滚、A/B 测试、定期重训机制。这个顺序的合理性在于每个阶段都为下一个阶段提供支撑。比如你不提前把 Docker 学会部署阶段就会被环境问题折磨到怀疑人生你不提前把数据版本管好后面想复现一个实验结果都会抓狂。2. 环境搭建与工具链选型这里偷懒后面全是坑2.1 Python 环境管理为什么不用系统自带 Python环境搭建是第一道坎我见过太多人在这上面浪费几天时间。核心痛点是 Python 包依赖冲突项目 A 需要numpy1.21项目 B 需要numpy1.24装在一起就会互相打架。系统自带的 Python 还牵扯系统级工具比如yum、apt你一旦用 root 权限往系统 Python 里塞了包后面出问题真的会让人崩溃。我自己目前的标准配置是用pyenv管理 Python 版本用venv创建项目虚拟环境用uv或者poetry管理依赖。具体到ai-engineering-from-scratch项目里我的操作是# 安装指定 Python 版本 pyenv install 3.11.5 # 在当前项目目录创建虚拟环境 python -m venv .venv # 激活环境 source .venv/bin/activate # 用 uv 管理依赖并锁定版本 uv pip install -r requirements.txt为什么强调锁定版本AI 生态的依赖更新极快你今天装了torch2.0.1跑得好好的三个月后重新安装变成了torch2.2.0API 行为变了代码可能直接报错。版本锁定是最廉价的可复现性保障。2.2 GPU 环境CUDA 版本匹配是真正的拦路虎做深度学习绕不开 GPU而 GPU 环境配置是新手遇到的第一座大山。核心要理解三者的关系NVIDIA 驱动程序是底层的CUDA Toolkit 是中间层PyTorch 等框架是上层应用。驱动必须兼容 CUDACUDA 必须兼容 PyTorch版本错位就会报CUDA driver version is insufficient之类的错。我的经验是如果你只是用 PyTorch 跑模型根本不需要手动装完整的 CUDA Toolkit。PyTorch 安装包自带 CUDA runtime你只需要保证显卡驱动版本够新就行。验证是否可用的最简命令# 检查驱动 nvidia-smi # 检查 PyTorch 是否能用 GPU python -c import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))如果torch.cuda.is_available()返回True就算环境通了。这里最容易踩的坑是为了装 CUDA 去改系统库路径结果把系统搞坏。记住驱动没问题就直接装对应版本的 PyTorch别碰 CUDA Toolkit。下面是 PyTorch 与 CUDA 版本的对应关系速查表以常见组合为例PyTorch 版本对应 CUDA 版本建议驱动版本2.0.xCUDA 11.7 / 11.8 5152.1.xCUDA 11.8 / 12.1 5302.2.xCUDA 11.8 / 12.1 5352.3.xCUDA 11.8 / 12.1 545注意在 Linux 服务器上配置环境先跑nvidia-smi看右上角的 CUDA 版本这个数字是驱动支持的最大版本号。只要它大于等于你安装 PyTorch 需求的版本就行。2.3 Docker把环境变成代码为什么 AI 工程必须用 Docker三个字可复现。你本地跑通的一套环境交给同事或者部署到服务器大概率跑不起来因为操作系统、系统库、环境变量、GPU 驱动配置都不一样。Docker 把整个环境打包成镜像镜像就是环境本身。我的标准做法是写一个Dockerfile把训练和推理的环境都固化下来FROM nvidia/cuda:12.1.1-cudnn8-runtime-ubuntu22.04 # 设置工作目录 WORKDIR /app # 先拷贝依赖文件利用 Docker 层缓存 COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt # 再拷贝代码 COPY . . # 声明暴露的端口 EXPOSE 8000 # 启动命令 CMD [uvicorn, app.main:app, --host, 0.0.0.0, --port, 8000]注意一个细节COPY requirements.txt和COPY .分开写是因为 Docker 的构建缓存机制。只要你requirements.txt没变后面每次改代码重新构建时pip install这步都会命中缓存能省下大量时间。这是我被慢到令人发指的镜像构建毒打后的领悟。3. 端到端实操从原始数据到部署上线的完整案例3.1 项目背景与数据准备阶段空谈概念没用直接看我搭的一个具体项目。这里选一个常见的场景对用户评论做情感分类判断一条评论是正向还是负向。选择的依据是数据容易获取公开数据集、模型不复杂用预训练模型微调、业务价值清晰舆情分析、客服分流都是这个底子。数据准备的第一个动作是切分数据这是新手最容易忽略的。很多人拿到数据直接开训训完才发现没有留验证集根本没法评估模型效果。我的标准比例是训练集 80%、验证集 10%、测试集 10%三个集合必须互不重叠。验证集用来调参测试集用来做最终评估两个搞混会导致你对模型真实能力的判断是偏乐观的。预处理流程我写成了一套可复用的代码import pandas as pd from sklearn.model_selection import train_test_split # 读取原始数据 df pd.read_csv(data/raw/comments.csv) df df.dropna(subset[text, label]) # 标签文本转数值 label_map {negative: 0, positive: 1} df[label_id] df[label].map(label_map) # 划分数据集 train_df, temp_df train_test_split( df, test_size0.2, random_state42, stratifydf[label_id] ) valid_df, test_df train_test_split( temp_df, test_size0.5, random_state42, stratifytemp_df[label_id] ) print(f训练集大小: {len(train_df)}) print(f验证集大小: {len(valid_df)}) print(f测试集大小: {len(test_df)})这里两个关键点stratifydf[label_id]是分层抽样保证切分后正负样本比例和原始数据一致避免出现验证集全是负样本这种夭寿情况random_state42固定随机种子保证每次跑出来切分结果一致。要是你觉得随机种子无所谓等你复现实验发对不上结果的时刻就会回来给这段话点赞。3.2 模型训练如何设计一个清晰的训练脚本模型这块我不建议从零去写 Transformer直接用一个预训练中文语言模型来得实际比如bert-base-chinese。微调的本质是在已经懂语言规律的基础上加上一个小的分类头让模型学会完成你的任务。这种做法的好处是数据量需求小、收敛快、效果通常远好于从零训练。训练脚本的核心部分我拆给你看主要包含四个环节加载模型和分词器、构造数据集、定义训练循环、保存产物。from transformers import AutoTokenizer, AutoModelForSequenceClassification from datasets import Dataset from transformers import Trainer, TrainingArguments # 1. 加载预训练模型和分词器 model_name bert-base-chinese tokenizer AutoTokenizer.from_pretrained(model_name) model AutoModelForSequenceClassification.from_pretrained( model_name, num_labels2 ) # 2. 将 pandas DataFrame 转为 HuggingFace Dataset 格式 train_dataset Dataset.from_pandas(train_df[[text, label_id]]) train_dataset train_dataset.map( lambda x: tokenizer(x[text], truncationTrue, paddingmax_length, max_length128), batchedTrue, ) # 3. 设置训练参数 training_args TrainingArguments( output_dir./checkpoints, num_train_epochs3, per_device_train_batch_size16, per_device_eval_batch_size64, evaluation_strategyepoch, save_strategyepoch, logging_dir./logs, learning_rate2e-5, load_best_model_at_endTrue, metric_for_best_modelaccuracy, ) # 4. 训练并保存 trainer Trainer( modelmodel, argstraining_args, train_datasettrain_dataset, eval_datasetvalid_dataset, ) trainer.train() trainer.save_model(./models/bert_finetuned) tokenizer.save_pretrained(./models/bert_finetuned)几个参数我特别说一下因为它们是调参的命门。learning_rate2e-5是微调预训练模型的标准用法理论上你应该已经从地方听说过微调要用小学习率但为啥因为预训练模型已经收敛到了一个较好的局部最优点学习率太大一步就跨出去了直接把学到的语言知识破坏掉。batch_size16是在我这张显卡上能稳定跑动的值你显存小就调 8显存大就调 32batch size 变大往往能带来更平滑的梯度但要注意显存占用。evaluation_strategyepoch是每个训练轮次结束评估一次这样能观察到过拟合的轨迹。3.3 模型部署用 FastAPI 把模型包成服务训练完的模型是躺在磁盘上的一堆权重文件要把它变成可用的服务需要做两件事加载模型、通过 HTTP 接口对外提供预测能力。选 FastAPI 是因为它原生支持异步、自动生成接口文档、性能也不含糊是 Python 生态里做推理服务最省事的方案。下面是标准的推理服务代码import torch from fastapi import FastAPI from pydantic import BaseModel from transformers import AutoTokenizer, AutoModelForSequenceClassification # 启动时加载模型 device torch.device(cuda if torch.cuda.is_available() else cpu) tokenizer AutoTokenizer.from_pretrained(./models/bert_finetuned) model AutoModelForSequenceClassification.from_pretrained(./models/bert_finetuned) model.to(device) model.eval() app FastAPI() # 定义请求体格式 class Review(BaseModel): text: str app.post(/predict) def predict(review: Review): inputs tokenizer( review.text, truncationTrue, paddingmax_length, max_length128, return_tensorspt, ) inputs {k: v.to(device) for k, v in inputs.items()} with torch.no_grad(): outputs model(**inputs) probs torch.softmax(outputs.logits, dim-1) pred torch.argmax(probs, dim-1).item() return { prediction: positive if pred 1 else negative, confidence: float(probs.max().item()), }这里必须强调一个很多人踩过的坑model.eval()别漏。训练模式下的模型会启用 Dropout 和 BatchNorm 的训练行为预测的时候不关闭每次调接口的结果都会不一致而且这个不一致还不是随机的是模型结构导致的系统性错误。另一个细节是torch.no_grad()告诉 PyTorch 不需要计算梯度推理速度和内存占用都会大幅下降。我在不加这行的时候测过单次推理慢 30% 以上还多占显存。部署到服务器上跑用 uvicorn 启动uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 2--workers 2是开启两个进程可以同时处理两个请求。但注意如果你用 GPU 推理多进程同时申请显存容易 OOM这种情况下更推荐单进程内做异步并发。4. 工程化进阶实验管理、版本控制与 CI/CD4.1 实验记录别再手动拷贝实验结果模型训练的迭代过程本质上是无数个实验的堆积。你今天把学习率改成3e-5试了一把结果比2e-5好 0.5%但是你没有记录下来三天后你就忘了哪个配置跑的哪个结果只能靠模糊记忆这就是典型的实验不可复现困境。我在这个项目里引入了 MLflow 做实验追踪核心用法非常简单import mlflow # 开始一次实验追踪 with mlflow.start_run(run_namebert_lr3e5_batch16): mlflow.log_param(learning_rate, 3e-5) mlflow.log_param(batch_size, 16) mlflow.log_param(model_name, bert-base-chinese) # 训练完成后记录指标 mlflow.log_metric(val_accuracy, 0.912) mlflow.log_metric(val_f1, 0.897) # 保存模型产物 mlflow.pytorch.log_model(model, model)为什么要坚持这样做因为 AI 工程的本质是一连串决策的累积而这个累积需要一个信息系统来支撑。你手动记录不仅慢还很容易记错。MLflow 的 UI 能让你直观对比每次实验的学习率、batch size、准确率之间的关系这个能力在你回头分析到底哪个变更让效果变好时特别有用。关于实验记录我有三条笨但有效的建议每次实验记录 GPU 显存占用和训练耗时这会帮你在不同方案之间做成本选型时心里有数每次训练记录随机种子深度学习是有随机性的同样的参数两次跑结果可能不同不记种子等于无法复现不要只记数值要连同代码提交的 commit id 一起记录做到代码和实验结果一一对应。我自己吃过这个亏两周前一个实验效果好但代码改了好几版根本定位不到当时的代码状态。4.2 数据版本控制让数据和代码一样可以被追踪一说版本管理大家自然想到 Git但 Git 不适合管大文件一个数据集动辄几个 GB塞进 Git 仓库会导致克隆和提交都异常缓慢。数据版本控制要解决的核心问题是模型是由哪些数据和哪些代码训练出来的这个对应关系能不能随时复原轻量方案是直接用 DVCData Version Control管理数据它的工作方式和 Git 类似但把实际的数据文件存在本地路径或者云存储里Git 仓库里只需要跟踪一份小的元数据文件。基础操作# 初始化数据版本管理 dvc init # 把数据目录纳入版本管理 dvc add data/raw/comments.csv # 像 git 一样提交 git add data/raw/comments.csv.dvc git commit -m 加入评论原始数据集 v1等你改了数据重新训练得出更好的结果需要回退到旧数据跑一遍对比时dvc checkout就能把数据恢复到指定版本。这个能力在我自己复现实验结果时救了大命。刚接触的人最容易犯的错是原始数据被反复改动但不记录版本结果模型出了问题根本定位不到是数据变化还是代码变化引起的这是 AI 工程里最可怕的排查场景之一。4.3 轻量 CI/CD从训练到部署的自动化流转持续集成在传统软件工程里已经是标配但 AI 项目的 CI 有点不一样除了跑单元测试还得验证模型推理结果是否符合预期、镜像能不能正常构建、依赖有没有安全漏洞。我搭了一套最简单的流水线思路是代码推送到主干分支后自动触发构建、测试、打包镜像三个任务。训练代码的测试可能不像传统后端那样有明确的输入-输出断言但至少有三样必须测分词器与模型的兼容性加载后能不能正常执行前向传播、推理服务的接口响应结构是不是我们约定的 JSON schema、模型文件是否已经正确打包进镜像。这三个测试跑通部署的成功率能提高一大截。以下是一个精简的 GitHub Actions 工作流定义name: ci-pipeline on: push: branches: [main] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: 设置 Python uses: actions/setup-pythonv5 with: python-version: 3.11 - name: 安装依赖 run: | pip install -r requirements-dev.txt pip install -r requirements.txt - name: 跑基础测试 run: pytest tests/ - name: 构建 Docker 镜像 run: docker build -t my-ai-service:latest .不需要太复杂的配置重要的是建立自动化向前推进的意识。很多人习惯了在一个 Jupyter Notebook 里完成所有事情但工程化要求的是每一次代码变更都经过同样的验证流程而不是靠在我电脑上跑得通。5. 系统稳定性监控模型上线只是开始5.1 监控指标体系别只盯着模型准确率模型部署上线你以为完工了其实真正的挑战才刚开始。线上环境和训练环境最大的区别是数据分布一直在变。用户的表达习惯会变输入内容的形态会变模型的表现也会随之改变。如果没有任何监控这个劣化过程就像温水煮青蛙等你靠用户投诉发现问题时损失已经造成了。我建议至少从四个维度建立监控它们缺一不可服务健康度接口可用性、响应延迟 P99、错误率。这是最基础的保证服务活着。资源消耗GPU 利用率、显存占用、CPU 内存水位。这里反映成本也能帮你提前发现扩容需求。推理质量代理指标预测置信度分布、正负预测比例。不需要真实标签就能算非常有价值的早期预警信号。数据漂移输入文本长度分布、关键词频率分布、分词后 token 分布的变化。做一个可用的监控不需要一上来就上 Prometheus Grafana 全家桶。最简单的方式写一个定时脚本统计每小时的请求量、平均延迟、置信度均值和昨天同时段做对比。如果置信度均值突然从 0.9 掉到 0.7大概率是新来的输入模式和训练数据差得很远模型已经开始装懂了。5.2 模型回滚与版本切换机制线上模型出问题了怎么办最忌讳的是现场改代码、改模型。正确做法是提前准备好回滚机制。我实践中觉得最靠谱的方案把不同版本的模型都打成镜像或者放在统一的模型仓库里通过配置切换线上版本。简单说一下基于模型仓库的思路每次训完一个模型给它打上版本号并记录相关信息# 模型仓库结构 /models /sentiment v1.0.0/ v1.1.0/ v1.2.0/服务启动时读取一个配置文件config.yaml里的版本号决定加载哪个目录的模型。发现新版本效果不行改一行配置指向旧版本重启服务就完成了回滚。整个过程不需要改代码、不需要重新构建镜像能控制在几分钟内完成。没有这种机制的话线上出问题你会陷入一边挨骂一边手忙脚乱找备份的惨况。5.3 数据漂移检测一个朴素但高效的实现很多团队会告诉你用复杂的方法做漂移检测比如基于对抗网络或者贝叶斯方法。但在我的实践里一个简单的启发式方法就能覆盖大部分问题比较线上输入和训练集输入的分布差异。拿文本分类举例一个直观的漂移信号是 token 分布偏移。我把训练集中出现频率最高的 1000 个词当作基线上线后每天统计线上请求里这些词的占比占比显著下降意味着用户说话方式开始改变。再用一个很朴素的指标比如 Jaccard 相似度def token_set_similarity(tokens_a, tokens_b): set_a set(tokens_a) set_b set(tokens_b) intersection len(set_a set_b) union len(set_a | set_b) return intersection / union if union 0 else 0.0训练集高频词集和本周线上高频词集的相似度如果从 0.85 掉到 0.6就该考虑重新采集数据、补充训练了。这不是什么高深算法但它简单、计算快、容易解释。AI 工程里很多问题最有效的解法往往不是花哨的模型而是稳定可执行的简单规则。6. 常见问题排查与避坑心得6.1 环境类问题八成左右的报错都出在这里AI 工程几乎所有跑不起来的问题源头都是环境不一致。我把最常见的三种情况列在下面这也是网上求助频率最高的三类错误现象根本原因解决方案CUDA error: device-side assert triggered模型中标签数小于数据集中类别数用model.config.num_labels检查配置同时确认所有标签值在预期范围内ModuleNotFoundError: No module named torch虚拟环境没激活或依赖没装全先pip list确认包列表再看当前用的是哪个 Python 解释器本地跑得好好的服务器上就崩环境不一致没得说上 Docker把环境代码化这是一劳永逸的路我自己的血泪教训有一次线上服务偶发报错排查了一整天也没找到原因最后发现是同事在不知道的情况下升级了某个依赖包而 requirements 文件里没有锁版本。从那以后我定的规矩是所有依赖必须锁定到精确版本号每次代码变更必须经过 CI 流程环境问题靠流程来解决不靠人肉记忆。6.2 训练效果类问题先判断是欠拟合还是过拟合模型训练出来的效果不理想很多人第一反应是加数据或者换大模型但这其实是病急乱投医。正确的做法是先用训练集和验证集的表现对比判断当前处于什么状态。如果训练集上损失也降不下去、准确率也低那是欠拟合这时候加数据没用应该优化模型容量、降低学习率或者增加训练轮数。如果训练集上表现很好、验证集上很差这是过拟合这时优先考虑增加正则化、降低模型复杂度、增加数据增强而不是盲目堆参数。这里有一个非常实用的经验法则每次实验只改一个变量并且完整记录。我见过太多人同时改了三四个变量然后问为什么效果变好了这个问题根本无法回答。按我的习惯每个实验就是一个分支改一个参数跑一个结果记录一次。6.3 推理服务类问题性能与并发的心得刚写完推理服务的人最容易犯的错是在接口里使用同步调用模型一旦并发上来请求会排队延迟直接飙升。FastAPI 是异步框架但如果你在普通函数里跑model()前向传播这个操作在 GPU 上通常是同步阻塞的不会因为用了 FastAPI 就自动变成异步。一个可行方案是用run_in_executor把推理扔到线程池或者干脆用asyncio包一层。我当时改造后并发能力提升了差不多三倍。另一个细节是模型的加载时机。我见过有人把AutoModel.from_pretrained写在每个请求处理函数内部这种代码上线必炸。模型加载是对磁盘和内存的高消耗操作必须放在服务启动时只做一次。用通俗的话说模型是你餐厅的招牌菜应该提前做好放在保温柜里而不是客人点单时才开始蒸。6.4 排查思路方法论怎么高效定位问题最后分享一套我排查线上问题的方法论这套方法论本来是我在事故复盘时梳理出来的现在每次出问题我都会按这个顺序来先看监控面板确认是偶发还是持续是延迟高了还是报错多了。再看最近变更回顾最近一次代码发布、模型更新、数据调整是什么时候大概率问题就出在这里。复现问题链路用线上实际输入样本在测试环境复现能复现的问题就成功了一半。二分定位从请求入口到模型推理到响应返回每一步都加上时间戳和日志找到最耗时的环节或第一个报错的位置。这套方法的核心思路是不要靠猜。每一步都要有数据支撑每一层都要有日志可查。我特别建议在推理服务的每个关键路径上加上日志哪怕前期用最简单的print也行记录下输入长度、前向传播耗时、返回的置信度。这些日志在出问题时就是最珍贵的线索。最后再分享一个个人习惯每次项目做完我都会把整个搭建过程中的关键命令和踩坑记录整理成一份README放在项目根目录包括环境怎么搭、数据怎么跑、模型怎么部署、出问题了怎么回滚。这个文档一开始写觉得浪费时间但坚持下来发现三个月后自己回来看它比任何代码注释都有用。AI 工程领域新东西层出不穷但底层的这套方法论是稳的把数据处理当成工程来管把模型当成软件来写把部署当成运维来做从零开始也能搭出一套可靠的生产系统。