去年有个项目让我印象特别深模型在Notebook里跑得漂漂亮亮准确率、召回率都拿得出手一进生产环境就原形毕露——预处理和训练时对不上、并发一上来接口就超时、Docker镜像大到拉不动、模型版本是哪个也说不清。我花了两个通宵才把线上服务救回来。那次之后我彻底明白了一个道理做AI和做AI工程是两件完全不同的事。算法模型只是AI系统里的一小部分真正决定一个项目能不能落地、能不能长久维护的是数据管线、训练流程、服务化、版本管理、监控这一整套工程体系。ai-engineering-from-scratch 这个项目就是我当时决定把整套东西从头到尾重新跑一遍的产物。目标很朴素用一个足够小、足够聚焦的场景从原始数据一路做到线上API再把模型监控和实验管理补上形成一条完整可复现的AI工程闭环。这篇文章把这条路径完整复盘一遍——包括每一步为什么这么做、中间踩了哪些坑、哪些决策回头看值得坚持希望对正准备从“会跑通模型”走向“能交付系统”的你有点帮助。1. 项目整体设计为什么“从零”比“从算法”更重要1.1 算法能力、AI工程能力是有本质区别的先说个我观察到的普遍现象。很多人学AI的第一反应是扎进算法堆里今天看Transformer论文明天调一个扩散模型后天在Kaggle榜单里挣扎。算法能力当然重要但对多数企业场景来说模型训练只占整个AI系统的一小部分。你真正需要处理的往往是这些事训练数据从哪里来、怎么清洗、怎么做标签、怎么划分才能保证模型评估结果可信训练环境能不能复现换一台机器、隔三个月再训练还能不能跑出一致的结果模型怎么对外提供服务延迟和吞吐怎么权衡并发上来了怎么处理模型上线后效果会不会下降数据分布变了有没有感知出了问题时能不能快速定位是代码问题、数据问题还是模型问题。这些问题一个堆满了算法理论的简历不一定答得上来。AI工程的核心关注点不是“精度再高一个点”而是稳定、可控、可交付、可维护。这也是我在项目里反复强调的思维方式先保证系统转得起来再谈优化。1.2 学习路径怎么定先做完整闭环再回头补理论从零开始做AI工程最容易犯的错误是想把所有知识都学完了再动手。我一开始也吃过这个亏——光环境搭建的资料就存了一百多个书签越看越觉得没准备好。这个项目采用了截然相反的路径先立一个最小可用的完整系统跑通全链路然后围绕这个系统逐个环节往深挖。我选的切入场景是文本情感分析数据集规模可控、标注相对成熟、模型可大可小、对算力要求不高。这不是拍脑袋选的。选首战场景有几个判断标准数据量不需要天量级一台普通机器能处理模型训练时间不能超过一小时否则迭代成本太高要能自然引出服务化、部署、监控这些工程环节业务价值要直观一看就明白这东西能用在哪。情感分析恰好满足全部条件。整个项目按照“数据 → 训练 → 评估 → 服务化 → 部署 → 监控”的流程跑通完整走完了AI系统落地的全部环节。1.3 技能地图规划好六块必修内容下这个项目之前我先给自己画了一张技能地图算是在校友里对项目边界的确认。圈定了六个大的模块也是后续一步步逐一拆下来的模块核心职责对应工具选型示例基础编程与工程代码质量、依赖管理、环境隔离Python、uv / conda、Git数据工程数据获取、清洗、验证、版本化Pandas、DVC、Great Expectations模型开发特征处理、模型训练、离线评估PyTorch、Transformers、Scikit-learn模型服务化API封装、推理优化、并发控制FastAPI、ONNX Runtime、Batching部署与交付环境一致性、弹性伸缩、CI/CDDocker、Kubernetes备选、GitHub Actions监控与运维延迟/吞吐监控、数据漂移、告警Prometheus、Evidently AI、日志系统这个技能地图不是静态的随着项目推进我不断调整权重。一开始花了很多时间在模型调优上后来发现服务化环节的坑更多更隐蔽又把重心转移到部署和监控上。想表达的核心观点是很多项目在书架项目或实验室跑得很顺利恰恰是在“最后一公里”坏掉的那扇门不是模型精度能够打开的。2. 基础设施准备环境与工具链是第一个大坑2.1 Python环境管理不要再global pip install了开始写任何代码之前先解决环境问题。这里我绕了很多路一开始直接在系统Python里pip install各种包用了一段时间就出现了灾难性后果一个项目需要pandas 1.5另一个项目锁定了pandas 2.0系统里各种版本互相打架最后连Python本身都被我搞坏过一次。后来老老实实用虚拟环境试了venv、conda、pipenv最后锁定了两个工具的组合uv日常新建虚拟环境、安装依赖特别快替代pip和pipenvconda处理一些底层库比如带CUDA的PyTorch或者非Python依赖时保留备用。每次开新项目我都会做这样一套动作uv venv .venv source .venv/bin/activate uv pip install -r requirements.txtrequirements.txt必须锁版本。不用pandas2.0这种宽泛写法而是pandas2.2.2这种精确锁定。AI项目最痛苦的就是“训练的时候好好的过两个月重跑依赖库一升级结果对不上了”。把版本锁住是环境可复现的第一步。注意锁版本不是锁住就完事了requirements.txt本身要进Git。我见过不少人环境弄好了但requirements.txt是后补的到底装了什么全靠猜这等于没锁。2.2 容器化训练和推理环境不再“在我机器上好好的”环境隔离是第一步还是不够。因为你的模型最终要部署到服务器上服务器环境跟你本机大概率不一样。为了彻底解决“在我机器上好好的”这个问题项目从第一天就引入了Docker。训练阶段其实可以不急着容器化但推理服务我是一上来就写了Dockerfile的。这个决策回头看来极其明智——正因为早写后面部署到测试服务器时几乎没有折腾。项目里的推理服务Dockerfile比较简单FROM python:3.10-slim WORKDIR /app RUN apt-get update apt-get install -y --no-install-recommends \ build-essential \ rm -rf /var/lib/apt/lists/* COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY src/ ./src/ COPY models/ ./models/ EXPOSE 8000 CMD [uvicorn, src.app:app, --host, 0.0.0.0, --port, 8000]几点取舍和大家说一下。基础镜像用的是slim版本没选择alpine原因是alpine的musl库在某些科学计算库上容易出兼容问题没必要为了省几十MB去冒这个险。模型文件直接打进镜像里对当前项目阶段是合理的——模型不大版本和代码天然绑定部署也更简单。如果模型到了几个GB甚至更大才会考虑挂载外部存储或走对象存储。GPU环境的坑值得单独提容器里要用GPU光装Docker不够还得装NVIDIA Container Toolkit并在运行时加--gpus all参数。第一次跑训练容器报了CUDA错误时别慌大概率不是代码问题而是宿主机的GPU驱动没有正确透传进容器。2.3 目录结构不给以后的自己留坑基础设施最后一块是约定一个清晰的目录结构。项目初期不重视这个后面文件满天飞数据、脚本、模型、日志全都混在一起复盘时根本找不到东西。这个项目从头就确定了标准布局后来我所有AI项目都沿用这套ai-engineering-from-scratch/ ├── data/ │ ├── raw/ # 原始数据只读 │ ├── processed/ # 清洗后的数据 │ └── labels/ # 标注结果 ├── models/ # 模型权重输出目录 ├── src/ │ ├── data/ # 数据处理代码 │ ├── train/ # 训练代码 │ ├── serve/ # 推理服务代码 │ └── monitor/ # 监控脚本 ├── tests/ # 单元测试 ├── Dockerfile ├── requirements.txt └── README.md这套结构的核心思路是让数据流动方向一目了然从raw到processed到labels层层加工每一步都清晰可控。AI项目最大的问题往往是数据链路混乱同一个数据文件在不同地方存了三个版本。有一份清晰的目录约定能省掉后面大量的心智负担。3. 核心实操完整跑通一个文本情感分析API3.1 项目选型为什么是“情感分析”前面提到了选型标准这里再展开说说。文本情感分析作为AI工程的首个项目有几个天然优势第一数据相对容易准备。电商评论、电影评论、社交言论都有现成语料不需要复杂的采集和标注过程。我项目里用的是一份公开的评论数据二分类正面/负面量级控制在几万条以内单机完全可以处理。第二模型可复杂度弹性变化。可以用经典的TF-IDF逻辑回归也可以微调一个预训练语言模型同一个数据集能对比不同技术路线的差距工程上又不需要多卡训练。第三业务价值直观。产品评论的情感分析是很多公司真实的需求做成API后能被业务方直接调用这比那些自嗨式的demo有说服力得多。选定情感分析后整个项目的边界就清晰了输入是一段文本输出是情感极性正面/负面和对应的置信度。所有后续工程环节都围绕这个输入输出契约展开。3.2 数据准备的几个关键动作数据部分容易被人轻视实际它是整条链路里最费时也最容易出错的环节。具体做了四件事**第一探查数据分布。**拿到数据先别急着清洗先看看类别是否均衡、文本长度分布怎么样、有没有大量重复或近似重复的样本。我当时发现数据集里“好评”明显多于“差评”比例大约7:3如果不处理模型会学偏大概率把所有内容都预测成好评。**第二清洗与规范化。**去HTML标签、处理URL和特殊符号、统一标点、过滤过短文本比如长度小于5个字符的口水评论。这里有个原则清洗规则越少越好每一条清洗规则都可能在推理阶段成为必须复现的预处理步骤规则越多越容易在服务化时漏掉一条导致线上推理和离线训练不一致。**第三划分数据集。**用train_test_split按70% / 15% / 15%划分训练、验证、测试集并且固定随机种子。这一步的作用是保证每次实验的可比性——如果你每次划分都不一样那比较两个模型的指标就没意义了。**第四写数据校验测试。**这里引入了一个小程序来检查数据完整性类别分布是否符合预期、是否没有空文本、标签值是否只有0和1。别小看这几条测试后面所有代码重构都要回归跑一遍能拦住大量低级错误。我踩过的一个坑清洗规则写在训练代码里了但推理API重新实现预处理时漏掉了“去除连续标点”这步。结果线上推理的文本分布和训练时不一致模型准确率直接掉了快5个点。这段经历让我后来养成了一个习惯——所有预处理逻辑必须抽象成独立的模块训练和推理共用同一份代码不允许各自实现。3.3 模型训练与评估不要只盯着准确率训练环节我试了两条路线恰好对比出工程思维和算法思维的区别。第一条路线TF-IDF 逻辑回归。训练一分钟召回率和F1分数已经不错而且部署极其轻量。第二条路线微调一个小型预训练语言模型类似BERT-base的中文版本训练大概二十分钟精度确实更高但模型体积、推理延迟、部署成本也是成倍上升。最终线上版本我选了第二种但那是基于业务对精度有硬要求的情况。这个对比如果你想在本地验证完全可以先跑轻量模型建立基线再决定要不要上重模型。评估指标上强烈建议不要只看准确率。在类别不均衡的数据集上准确率是有迷惑性的。这个项目里我同时看Precision、Recall、F1-Score并打印分类报告和混淆矩阵。这里浮现一个很常见的工程事故就是评估时数据泄漏清洗、归一化如果误把整个数据集的统计信息带进了训练集会把测试指标撑得很虚。所谓“预处理里用了全量数据的均值/方差/词表”就是一个经典的泄漏案例。为了防止这类问题我给项目定了一条死规矩一切会从数据集中统计出来的信息只能在训练集上计算然后应用到验证集和测试集。这条规矩后面救了我好几次。3.4 模型服务化把模型变成能用的API模型训练完才真正进入AI工程的地界。我用了FastAPI来封装推理服务主要考虑是性能好、自动生成API文档、生态成熟写起来很直观。服务的核心代码大致长这样from fastapi import FastAPI from pydantic import BaseModel import torch app FastAPI() class PredictRequest(BaseModel): text: str class PredictResponse(BaseModel): label: int label_name: str confidence: float app.post(/predict, response_modelPredictResponse) def predict(req: PredictRequest): inputs tokenizer( req.text, max_length128, truncationTrue, paddingmax_length, return_tensorspt ) with torch.no_grad(): logits model(**inputs).logits probs torch.softmax(logits, dim-1) pred int(torch.argmax(probs, dim-1)) return PredictResponse( labelpred, label_namepositive if pred 1 else negative, confidencefloat(probs.max()) )服务化阶段有三个容易被忽视的点**推理延迟与吞吐的平衡。**模型第一次推理时要把参数加载到显存里之后就是纯推理。为了降低单次请求延迟我做了两件事一是模型加载后不再一帧帧重复转GPU而是提前把模型放在model.eval()状态二是在推理里用了fp16半精度速度提升明显精度损失可以忽略。之前也提过如果你对延迟敏感ONNX Runtime能比PyTorch原生的eager模式再快不少。**请求体的输入校验。**用Pydantic做参数声明这样接口文档自动生成非法输入会被自动拦截不用在业务代码里手写一堆if判断。**并发与批量推理。**高并发场景下逐条推理效率很低。常见的做法是排队批量处理。FastAPI配合异步队列可以把多个请求攒在一起做成一个batch输入模型。这个优化能把吞吐提升好几倍不过第一次做时要注意控制batch大小不然显存容易爆。3.5 部署上线与监控基础模型服务代码写好后配合前面写的Dockerfile走上线流程就顺理成章了docker build -t sentiment-api:1.0.0 . docker run -d --name sentiment-api -p 8000:8000 sentiment-api:1.0.0执行完这两行一个可用的模型API就跑起来了。但这只是第一步。上线之后真正要紧的是观测系统状态。我在项目里加了三个基础观测项健康检查给服务加一个/health端点返回服务存活状态和模型加载状态供容器编排系统做探针结构化日志每个请求都记录处理耗时、输入长度、预测结果、置信度方便排查问题基础指标采集记录请求数、平均延迟、P99延迟、错误率发给Prometheus这类监控系统。没有这些观测手段AI服务就是一坨黑盒出了问题只能靠用户反馈完全没法主动发现。这是工程化落地中非常关键的一环。4. 延伸到MLOps从“模型跑起来”到“系统能维护”如果说完成一个推理API还只是AI工程的入门那MLOps相关的环节就是决定这个系统能不能长期转下去的关键。这块内容我在项目里是一步步补上的只做了一部分但每一条都有明确的收益。4.1 实验追踪你的训练记录还能复现吗问题是这个调参十几次模型文件存了一排最后连哪个模型对应哪组参数都分不清。为此我把MLflow引入了项目。用法是每次训练前记录参数和指标import mlflow with mlflow.start_run(): mlflow.log_param(learning_rate, 3e-5) mlflow.log_param(batch_size, 16) mlflow.log_param(model_name, bert-base-xxx) mlflow.log_metric(val_f1, val_f1) mlflow.log_metric(val_precision, val_precision) mlflow.pytorch.log_model(model, model)这个工具体验很直观跑完几十次实验之后打开MLflow UI每次跑的参数、指标、产物一目了然。哪个模型效果最好、用了什么参数谁都能看明白。对多人协作的项目来说这几乎是刚需。否则一个同学实验是跑完了但是问他“你这个0.92的模型怎么得来的”他多半报不全参数。4.2 数据版本管理光有代码复现还不够模型的可复现性除了代码、参数、环境还绕不开数据。训练数据换了一版模型效果可能完全不一样。但日常工作里最容易被忽略的就是数据版本控制。我在项目里用DVC管理训练数据集。用一个比喻来解释DVC它不存数据本身而是像一支写满注释的指挥棒一样记录数据的版本和下载位置。Git里放的是一串元信息真正的数据放在远端存储。切换分支时数据也跟着切到对应版本。dvc add data/processed/train.csv git add data/processed/train.csv.dvc git commit -m update training data这套流程给我的体验是数据和代码能对齐了再也不存在“旧代码配新数据”这种说不清的状态。4.3 模型监控上线后最容易被忽视的一层模型部署上线只是开头真正严峻的挑战是不久之后模型开始“慢慢变傻”。线下验证时候的分布不代表线上永远的分布。用户行为在变化、语料表达在变化模型精度会悄无声息地掉。项目里我实现了三层监控**第一层服务质量监控。**延迟、吞吐、错误率这些标准指标的告警确保服务本身没有故障。**第二层数据漂移检测。**定期统计线上请求的文本长度分布、关键词频率、特证值分布跟训练集的分布做对比。最轻量的方案是用Evidently AI里现成的漂移检测模块输出直观的报告。**第三层反馈循环。**人工抽样审查预测结果或者在有业务反馈的情况下把纠正后的样本收集起来作为下轮训练的增量数据。这三层做到什么程度取决于项目资源但至少要有“线上模型效果可能下降”的意识。很多AI项目死掉不是模型本身不行而是没人注意到它在变蠢直到业务方反馈时才抓瞎。5. 常见问题排查与避坑实录整条链路走下来踩的坑比预想的多。给你整理一张高频问题速查表都是我实际遇到过的问题现象可能原因解决思路训练时CUDA Out of Memory批量太大或显存碎片化调小batch size、清理GPU缓存、降精度容器里看不到GPU未装NVIDIA Container Toolkit安装工具包并用--gpus all运行线上预测结果和训练时不一致预处理代码不统一把预处理抽象成公共模块强制共用并发一高接口就超时单条推理无batching加入请求排队和批量推理模型文件找不到了没有版本管理和梳理目录规约用MLflow管理模型产物指标虚高但线上效果差评估时数据泄漏只在训练集上拟合统计信息一段时间后准确率明显下降数据漂移上线监控监控分布变化并定期重训练再补充三个训练和部署过程里容易犯的细节问题**GPU内存泄漏。**如果你在循环里反复创建模型、加载权重而不显式释放显存会慢慢被吃光。推理循环里要确保每次请求不新加载模型权重如果确实需要多模型切换要显式del并torch.cuda.empty_cache()。**依赖版本不一致。**这是“我本地能跑”的经典来源。解决办法是不仅锁requirements还要定期在干净环境里重新安装并跑一遍全部测试。我在项目里把环境重建做成了脚本保证重建后能完整复现训练和服务流程。**模型文件与代码版本不匹配。**模型参数和加载代码的结构如果版本对不上轻则报错重则在某些预测上悄悄出错。应对思路是把模型训练时所用的代码版本号、tokenizer版本、数据版本一并写进模型目录下的manifest文件部署时先校验。6. 如果我重新做一遍会先做这几件事这个项目做到了“完整跑通全链路”之后再回头看整个过程如果让我重新来一遍我会省掉一些不必要的折腾把力气花在更值得的地方。首先会把数据版本管理提前到第一天。项目早期我用的是“数据放固定目录手动备份”这种方式后来引入DVC时发现历史数据版本已经乱了。如果从一开始就规范数据版本后面所有实验的可复盘性都会好很多。其次会更早引入负载压测。服务上线前我只做了基本的API调用测试结果用脚本连续压了几百个请求之后才发现内存占用节节攀升。早点用压测工具跑一轮能少在生产上丢人。最后就是增强服务端观测的颗粒度。监控的作用不只是服务出问题后快速定位更重要的是它提供了优化方向的线索。我现在看任何AI系统第一反应都是先看监控面板因为系统运行的真实信号都藏在那里。这个项目做完后我最大的收获不是拿到了一个情感分析API而是建立了一套可以复用到其他AI项目的方法论先定边界再选最小闭环然后全链路跑通最后在关键环节加深。这条路本身就是ai-engineering从零到一的核心意义。 
长河君 · 2026/10/3 11:12:49 · 阅读 1.2k 从模型到系统：AI工程化落地全链路实战指南
去年有个项目让我印象特别深模型在Notebook里跑得漂漂亮亮准确率、召回率都拿得出手一进生产环境就原形毕露——预处理和训练时对不上、并发一上来接口就超时、Docker镜像大到拉不动、模型版本是哪个也说不清。我花了两个通宵才把线上服务救回来。那次之后我彻底明白了一个道理做AI和做AI工程是两件完全不同的事。算法模型只是AI系统里的一小部分真正决定一个项目能不能落地、能不能长久维护的是数据管线、训练流程、服务化、版本管理、监控这一整套工程体系。ai-engineering-from-scratch 这个项目就是我当时决定把整套东西从头到尾重新跑一遍的产物。目标很朴素用一个足够小、足够聚焦的场景从原始数据一路做到线上API再把模型监控和实验管理补上形成一条完整可复现的AI工程闭环。这篇文章把这条路径完整复盘一遍——包括每一步为什么这么做、中间踩了哪些坑、哪些决策回头看值得坚持希望对正准备从“会跑通模型”走向“能交付系统”的你有点帮助。1. 项目整体设计为什么“从零”比“从算法”更重要1.1 算法能力、AI工程能力是有本质区别的先说个我观察到的普遍现象。很多人学AI的第一反应是扎进算法堆里今天看Transformer论文明天调一个扩散模型后天在Kaggle榜单里挣扎。算法能力当然重要但对多数企业场景来说模型训练只占整个AI系统的一小部分。你真正需要处理的往往是这些事训练数据从哪里来、怎么清洗、怎么做标签、怎么划分才能保证模型评估结果可信训练环境能不能复现换一台机器、隔三个月再训练还能不能跑出一致的结果模型怎么对外提供服务延迟和吞吐怎么权衡并发上来了怎么处理模型上线后效果会不会下降数据分布变了有没有感知出了问题时能不能快速定位是代码问题、数据问题还是模型问题。这些问题一个堆满了算法理论的简历不一定答得上来。AI工程的核心关注点不是“精度再高一个点”而是稳定、可控、可交付、可维护。这也是我在项目里反复强调的思维方式先保证系统转得起来再谈优化。1.2 学习路径怎么定先做完整闭环再回头补理论从零开始做AI工程最容易犯的错误是想把所有知识都学完了再动手。我一开始也吃过这个亏——光环境搭建的资料就存了一百多个书签越看越觉得没准备好。这个项目采用了截然相反的路径先立一个最小可用的完整系统跑通全链路然后围绕这个系统逐个环节往深挖。我选的切入场景是文本情感分析数据集规模可控、标注相对成熟、模型可大可小、对算力要求不高。这不是拍脑袋选的。选首战场景有几个判断标准数据量不需要天量级一台普通机器能处理模型训练时间不能超过一小时否则迭代成本太高要能自然引出服务化、部署、监控这些工程环节业务价值要直观一看就明白这东西能用在哪。情感分析恰好满足全部条件。整个项目按照“数据 → 训练 → 评估 → 服务化 → 部署 → 监控”的流程跑通完整走完了AI系统落地的全部环节。1.3 技能地图规划好六块必修内容下这个项目之前我先给自己画了一张技能地图算是在校友里对项目边界的确认。圈定了六个大的模块也是后续一步步逐一拆下来的模块核心职责对应工具选型示例基础编程与工程代码质量、依赖管理、环境隔离Python、uv / conda、Git数据工程数据获取、清洗、验证、版本化Pandas、DVC、Great Expectations模型开发特征处理、模型训练、离线评估PyTorch、Transformers、Scikit-learn模型服务化API封装、推理优化、并发控制FastAPI、ONNX Runtime、Batching部署与交付环境一致性、弹性伸缩、CI/CDDocker、Kubernetes备选、GitHub Actions监控与运维延迟/吞吐监控、数据漂移、告警Prometheus、Evidently AI、日志系统这个技能地图不是静态的随着项目推进我不断调整权重。一开始花了很多时间在模型调优上后来发现服务化环节的坑更多更隐蔽又把重心转移到部署和监控上。想表达的核心观点是很多项目在书架项目或实验室跑得很顺利恰恰是在“最后一公里”坏掉的那扇门不是模型精度能够打开的。2. 基础设施准备环境与工具链是第一个大坑2.1 Python环境管理不要再global pip install了开始写任何代码之前先解决环境问题。这里我绕了很多路一开始直接在系统Python里pip install各种包用了一段时间就出现了灾难性后果一个项目需要pandas 1.5另一个项目锁定了pandas 2.0系统里各种版本互相打架最后连Python本身都被我搞坏过一次。后来老老实实用虚拟环境试了venv、conda、pipenv最后锁定了两个工具的组合uv日常新建虚拟环境、安装依赖特别快替代pip和pipenvconda处理一些底层库比如带CUDA的PyTorch或者非Python依赖时保留备用。每次开新项目我都会做这样一套动作uv venv .venv source .venv/bin/activate uv pip install -r requirements.txtrequirements.txt必须锁版本。不用pandas2.0这种宽泛写法而是pandas2.2.2这种精确锁定。AI项目最痛苦的就是“训练的时候好好的过两个月重跑依赖库一升级结果对不上了”。把版本锁住是环境可复现的第一步。注意锁版本不是锁住就完事了requirements.txt本身要进Git。我见过不少人环境弄好了但requirements.txt是后补的到底装了什么全靠猜这等于没锁。2.2 容器化训练和推理环境不再“在我机器上好好的”环境隔离是第一步还是不够。因为你的模型最终要部署到服务器上服务器环境跟你本机大概率不一样。为了彻底解决“在我机器上好好的”这个问题项目从第一天就引入了Docker。训练阶段其实可以不急着容器化但推理服务我是一上来就写了Dockerfile的。这个决策回头看来极其明智——正因为早写后面部署到测试服务器时几乎没有折腾。项目里的推理服务Dockerfile比较简单FROM python:3.10-slim WORKDIR /app RUN apt-get update apt-get install -y --no-install-recommends \ build-essential \ rm -rf /var/lib/apt/lists/* COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY src/ ./src/ COPY models/ ./models/ EXPOSE 8000 CMD [uvicorn, src.app:app, --host, 0.0.0.0, --port, 8000]几点取舍和大家说一下。基础镜像用的是slim版本没选择alpine原因是alpine的musl库在某些科学计算库上容易出兼容问题没必要为了省几十MB去冒这个险。模型文件直接打进镜像里对当前项目阶段是合理的——模型不大版本和代码天然绑定部署也更简单。如果模型到了几个GB甚至更大才会考虑挂载外部存储或走对象存储。GPU环境的坑值得单独提容器里要用GPU光装Docker不够还得装NVIDIA Container Toolkit并在运行时加--gpus all参数。第一次跑训练容器报了CUDA错误时别慌大概率不是代码问题而是宿主机的GPU驱动没有正确透传进容器。2.3 目录结构不给以后的自己留坑基础设施最后一块是约定一个清晰的目录结构。项目初期不重视这个后面文件满天飞数据、脚本、模型、日志全都混在一起复盘时根本找不到东西。这个项目从头就确定了标准布局后来我所有AI项目都沿用这套ai-engineering-from-scratch/ ├── data/ │ ├── raw/ # 原始数据只读 │ ├── processed/ # 清洗后的数据 │ └── labels/ # 标注结果 ├── models/ # 模型权重输出目录 ├── src/ │ ├── data/ # 数据处理代码 │ ├── train/ # 训练代码 │ ├── serve/ # 推理服务代码 │ └── monitor/ # 监控脚本 ├── tests/ # 单元测试 ├── Dockerfile ├── requirements.txt └── README.md这套结构的核心思路是让数据流动方向一目了然从raw到processed到labels层层加工每一步都清晰可控。AI项目最大的问题往往是数据链路混乱同一个数据文件在不同地方存了三个版本。有一份清晰的目录约定能省掉后面大量的心智负担。3. 核心实操完整跑通一个文本情感分析API3.1 项目选型为什么是“情感分析”前面提到了选型标准这里再展开说说。文本情感分析作为AI工程的首个项目有几个天然优势第一数据相对容易准备。电商评论、电影评论、社交言论都有现成语料不需要复杂的采集和标注过程。我项目里用的是一份公开的评论数据二分类正面/负面量级控制在几万条以内单机完全可以处理。第二模型可复杂度弹性变化。可以用经典的TF-IDF逻辑回归也可以微调一个预训练语言模型同一个数据集能对比不同技术路线的差距工程上又不需要多卡训练。第三业务价值直观。产品评论的情感分析是很多公司真实的需求做成API后能被业务方直接调用这比那些自嗨式的demo有说服力得多。选定情感分析后整个项目的边界就清晰了输入是一段文本输出是情感极性正面/负面和对应的置信度。所有后续工程环节都围绕这个输入输出契约展开。3.2 数据准备的几个关键动作数据部分容易被人轻视实际它是整条链路里最费时也最容易出错的环节。具体做了四件事**第一探查数据分布。**拿到数据先别急着清洗先看看类别是否均衡、文本长度分布怎么样、有没有大量重复或近似重复的样本。我当时发现数据集里“好评”明显多于“差评”比例大约7:3如果不处理模型会学偏大概率把所有内容都预测成好评。**第二清洗与规范化。**去HTML标签、处理URL和特殊符号、统一标点、过滤过短文本比如长度小于5个字符的口水评论。这里有个原则清洗规则越少越好每一条清洗规则都可能在推理阶段成为必须复现的预处理步骤规则越多越容易在服务化时漏掉一条导致线上推理和离线训练不一致。**第三划分数据集。**用train_test_split按70% / 15% / 15%划分训练、验证、测试集并且固定随机种子。这一步的作用是保证每次实验的可比性——如果你每次划分都不一样那比较两个模型的指标就没意义了。**第四写数据校验测试。**这里引入了一个小程序来检查数据完整性类别分布是否符合预期、是否没有空文本、标签值是否只有0和1。别小看这几条测试后面所有代码重构都要回归跑一遍能拦住大量低级错误。我踩过的一个坑清洗规则写在训练代码里了但推理API重新实现预处理时漏掉了“去除连续标点”这步。结果线上推理的文本分布和训练时不一致模型准确率直接掉了快5个点。这段经历让我后来养成了一个习惯——所有预处理逻辑必须抽象成独立的模块训练和推理共用同一份代码不允许各自实现。3.3 模型训练与评估不要只盯着准确率训练环节我试了两条路线恰好对比出工程思维和算法思维的区别。第一条路线TF-IDF 逻辑回归。训练一分钟召回率和F1分数已经不错而且部署极其轻量。第二条路线微调一个小型预训练语言模型类似BERT-base的中文版本训练大概二十分钟精度确实更高但模型体积、推理延迟、部署成本也是成倍上升。最终线上版本我选了第二种但那是基于业务对精度有硬要求的情况。这个对比如果你想在本地验证完全可以先跑轻量模型建立基线再决定要不要上重模型。评估指标上强烈建议不要只看准确率。在类别不均衡的数据集上准确率是有迷惑性的。这个项目里我同时看Precision、Recall、F1-Score并打印分类报告和混淆矩阵。这里浮现一个很常见的工程事故就是评估时数据泄漏清洗、归一化如果误把整个数据集的统计信息带进了训练集会把测试指标撑得很虚。所谓“预处理里用了全量数据的均值/方差/词表”就是一个经典的泄漏案例。为了防止这类问题我给项目定了一条死规矩一切会从数据集中统计出来的信息只能在训练集上计算然后应用到验证集和测试集。这条规矩后面救了我好几次。3.4 模型服务化把模型变成能用的API模型训练完才真正进入AI工程的地界。我用了FastAPI来封装推理服务主要考虑是性能好、自动生成API文档、生态成熟写起来很直观。服务的核心代码大致长这样from fastapi import FastAPI from pydantic import BaseModel import torch app FastAPI() class PredictRequest(BaseModel): text: str class PredictResponse(BaseModel): label: int label_name: str confidence: float app.post(/predict, response_modelPredictResponse) def predict(req: PredictRequest): inputs tokenizer( req.text, max_length128, truncationTrue, paddingmax_length, return_tensorspt ) with torch.no_grad(): logits model(**inputs).logits probs torch.softmax(logits, dim-1) pred int(torch.argmax(probs, dim-1)) return PredictResponse( labelpred, label_namepositive if pred 1 else negative, confidencefloat(probs.max()) )服务化阶段有三个容易被忽视的点**推理延迟与吞吐的平衡。**模型第一次推理时要把参数加载到显存里之后就是纯推理。为了降低单次请求延迟我做了两件事一是模型加载后不再一帧帧重复转GPU而是提前把模型放在model.eval()状态二是在推理里用了fp16半精度速度提升明显精度损失可以忽略。之前也提过如果你对延迟敏感ONNX Runtime能比PyTorch原生的eager模式再快不少。**请求体的输入校验。**用Pydantic做参数声明这样接口文档自动生成非法输入会被自动拦截不用在业务代码里手写一堆if判断。**并发与批量推理。**高并发场景下逐条推理效率很低。常见的做法是排队批量处理。FastAPI配合异步队列可以把多个请求攒在一起做成一个batch输入模型。这个优化能把吞吐提升好几倍不过第一次做时要注意控制batch大小不然显存容易爆。3.5 部署上线与监控基础模型服务代码写好后配合前面写的Dockerfile走上线流程就顺理成章了docker build -t sentiment-api:1.0.0 . docker run -d --name sentiment-api -p 8000:8000 sentiment-api:1.0.0执行完这两行一个可用的模型API就跑起来了。但这只是第一步。上线之后真正要紧的是观测系统状态。我在项目里加了三个基础观测项健康检查给服务加一个/health端点返回服务存活状态和模型加载状态供容器编排系统做探针结构化日志每个请求都记录处理耗时、输入长度、预测结果、置信度方便排查问题基础指标采集记录请求数、平均延迟、P99延迟、错误率发给Prometheus这类监控系统。没有这些观测手段AI服务就是一坨黑盒出了问题只能靠用户反馈完全没法主动发现。这是工程化落地中非常关键的一环。4. 延伸到MLOps从“模型跑起来”到“系统能维护”如果说完成一个推理API还只是AI工程的入门那MLOps相关的环节就是决定这个系统能不能长期转下去的关键。这块内容我在项目里是一步步补上的只做了一部分但每一条都有明确的收益。4.1 实验追踪你的训练记录还能复现吗问题是这个调参十几次模型文件存了一排最后连哪个模型对应哪组参数都分不清。为此我把MLflow引入了项目。用法是每次训练前记录参数和指标import mlflow with mlflow.start_run(): mlflow.log_param(learning_rate, 3e-5) mlflow.log_param(batch_size, 16) mlflow.log_param(model_name, bert-base-xxx) mlflow.log_metric(val_f1, val_f1) mlflow.log_metric(val_precision, val_precision) mlflow.pytorch.log_model(model, model)这个工具体验很直观跑完几十次实验之后打开MLflow UI每次跑的参数、指标、产物一目了然。哪个模型效果最好、用了什么参数谁都能看明白。对多人协作的项目来说这几乎是刚需。否则一个同学实验是跑完了但是问他“你这个0.92的模型怎么得来的”他多半报不全参数。4.2 数据版本管理光有代码复现还不够模型的可复现性除了代码、参数、环境还绕不开数据。训练数据换了一版模型效果可能完全不一样。但日常工作里最容易被忽略的就是数据版本控制。我在项目里用DVC管理训练数据集。用一个比喻来解释DVC它不存数据本身而是像一支写满注释的指挥棒一样记录数据的版本和下载位置。Git里放的是一串元信息真正的数据放在远端存储。切换分支时数据也跟着切到对应版本。dvc add data/processed/train.csv git add data/processed/train.csv.dvc git commit -m update training data这套流程给我的体验是数据和代码能对齐了再也不存在“旧代码配新数据”这种说不清的状态。4.3 模型监控上线后最容易被忽视的一层模型部署上线只是开头真正严峻的挑战是不久之后模型开始“慢慢变傻”。线下验证时候的分布不代表线上永远的分布。用户行为在变化、语料表达在变化模型精度会悄无声息地掉。项目里我实现了三层监控**第一层服务质量监控。**延迟、吞吐、错误率这些标准指标的告警确保服务本身没有故障。**第二层数据漂移检测。**定期统计线上请求的文本长度分布、关键词频率、特证值分布跟训练集的分布做对比。最轻量的方案是用Evidently AI里现成的漂移检测模块输出直观的报告。**第三层反馈循环。**人工抽样审查预测结果或者在有业务反馈的情况下把纠正后的样本收集起来作为下轮训练的增量数据。这三层做到什么程度取决于项目资源但至少要有“线上模型效果可能下降”的意识。很多AI项目死掉不是模型本身不行而是没人注意到它在变蠢直到业务方反馈时才抓瞎。5. 常见问题排查与避坑实录整条链路走下来踩的坑比预想的多。给你整理一张高频问题速查表都是我实际遇到过的问题现象可能原因解决思路训练时CUDA Out of Memory批量太大或显存碎片化调小batch size、清理GPU缓存、降精度容器里看不到GPU未装NVIDIA Container Toolkit安装工具包并用--gpus all运行线上预测结果和训练时不一致预处理代码不统一把预处理抽象成公共模块强制共用并发一高接口就超时单条推理无batching加入请求排队和批量推理模型文件找不到了没有版本管理和梳理目录规约用MLflow管理模型产物指标虚高但线上效果差评估时数据泄漏只在训练集上拟合统计信息一段时间后准确率明显下降数据漂移上线监控监控分布变化并定期重训练再补充三个训练和部署过程里容易犯的细节问题**GPU内存泄漏。**如果你在循环里反复创建模型、加载权重而不显式释放显存会慢慢被吃光。推理循环里要确保每次请求不新加载模型权重如果确实需要多模型切换要显式del并torch.cuda.empty_cache()。**依赖版本不一致。**这是“我本地能跑”的经典来源。解决办法是不仅锁requirements还要定期在干净环境里重新安装并跑一遍全部测试。我在项目里把环境重建做成了脚本保证重建后能完整复现训练和服务流程。**模型文件与代码版本不匹配。**模型参数和加载代码的结构如果版本对不上轻则报错重则在某些预测上悄悄出错。应对思路是把模型训练时所用的代码版本号、tokenizer版本、数据版本一并写进模型目录下的manifest文件部署时先校验。6. 如果我重新做一遍会先做这几件事这个项目做到了“完整跑通全链路”之后再回头看整个过程如果让我重新来一遍我会省掉一些不必要的折腾把力气花在更值得的地方。首先会把数据版本管理提前到第一天。项目早期我用的是“数据放固定目录手动备份”这种方式后来引入DVC时发现历史数据版本已经乱了。如果从一开始就规范数据版本后面所有实验的可复盘性都会好很多。其次会更早引入负载压测。服务上线前我只做了基本的API调用测试结果用脚本连续压了几百个请求之后才发现内存占用节节攀升。早点用压测工具跑一轮能少在生产上丢人。最后就是增强服务端观测的颗粒度。监控的作用不只是服务出问题后快速定位更重要的是它提供了优化方向的线索。我现在看任何AI系统第一反应都是先看监控面板因为系统运行的真实信号都藏在那里。这个项目做完后我最大的收获不是拿到了一个情感分析API而是建立了一套可以复用到其他AI项目的方法论先定边界再选最小闭环然后全链路跑通最后在关键环节加深。这条路本身就是ai-engineering从零到一的核心意义。