从零构建AI工程：数据契约、服务契约与最小可行实验追踪

1. 为什么“从零构建AI工程”不是写个模型就完事了

“AI Engineering from Scratch”——这个标题乍看像极了某本技术书的副标题，或者某个开源项目的README第一行。但如果你真照着字面意思去干，十有八九会在第三天凌晨两点盯着GPU显存溢出报错、数据管道卡死、线上服务503、监控面板一片红的时候，默默关掉终端，打开外卖APP点一份热汤面。我带过七支跨职能AI团队，亲手交付过12个落地项目，其中8个是从“一张白纸+一个需求文档”开始的。所谓“from scratch”，从来不是指从import torch开始，而是从没有训练集群、没有标注规范、没有数据版本控制、没有模型注册中心、甚至没有统一日志格式的状态下，把整套AI生产链路一砖一瓦垒出来。

这背后真正要解决的，是三个被严重低估的断层：数据断层（原始业务数据→可训练样本）、能力断层（研究级代码→工业级服务）、协作断层（算法工程师→后端/运维/产品）。关键词“ai-engineering”和“from-scratch”连在一起，本质是在说：我们不接API、不调微调接口、不依赖现成平台，而是用Python脚本、Dockerfile、Kubernetes YAML和大量手写SQL，把AI变成一种可重复、可审计、可回滚、可交接的工程产物。它不追求SOTA指标，但必须保证周一早上9点上线的模型，在周五下午4点还能准确识别出客户上传的模糊发票上的金额数字；它不强调参数量，但要求每次模型更新前，能自动完成数据漂移检测、特征一致性校验、A/B测试流量分配和灰度发布熔断。

你可能会问：现在不是有MLflow、Weights & Biases、Vertex AI、SageMaker这些工具吗？当然有。但它们解决的是“已有基础设施后的效率问题”，而“from scratch”面对的是“连基础设施该长什么样都得自己画草图”的阶段。就像盖楼，别人在讨论电梯调度算法优化，你得先决定地基打多深、钢筋型号选什么、混凝土标号怎么配——而且施工队只给你三个人、一台笔记本和三个月工期。这不是炫技，而是生存必需。接下来我会拆解四个真实踩坑最深、复现率最高的核心模块：数据流水线的原子化设计、模型服务的轻量级契约治理、实验追踪的最小可行范式、以及最关键的——如何让非算法背景的同事也能看懂你的模型到底在干什么。

2. 数据流水线：别再用Jupyter写ETL，从第一行SQL开始建契约

绝大多数“from scratch”项目崩塌的第一步，不是模型训不出来，而是数据根本喂不进去。我见过最典型的场景：算法同学在本地Jupyter里跑通了一个清洗脚本，处理了2000条样本，效果不错；他把代码发给后端，后端按逻辑改写成Java服务，上线后发现每天处理10万条订单数据时，内存暴涨到32GB，CPU持续100%，下游服务全部超时。问题出在哪？不是语言差异，而是缺乏数据契约（Data Contract）——没人定义过“订单表中amount字段的取值范围、空值含义、单位精度”，也没人约定“清洗后cleaned_amount必须是decimal(10,2)且非负”。Jupyter里的df.dropna()在生产环境就是定时炸弹。

真正的“from scratch”数据流水线，必须从SQL开始建立不可绕过的契约层。我们团队的标准做法是：所有原始数据接入点（MySQL binlog、Kafka topic、S3 bucket）都对应一个只读视图（Read-Only View），该视图强制执行三类约束：

1. 类型契约：amount DECIMAL(15,2)而非VARCHAR，避免后续计算中出现字符串拼接；
2. 业务契约：WHERE status IN ('paid', 'refunded')，过滤掉测试订单和无效状态；
3. 时效契约：WHERE event_time >= CURRENT_DATE - INTERVAL '7 days'，明确数据新鲜度边界。

提示：视图本身不存储数据，只定义查询逻辑。它像一份法律合同，告诉所有人“从此处读取的数据，必须满足以上三条”。任何试图绕过视图直接查基表的行为，都会触发DBA设置的审计告警。

在此基础上，我们构建三层流水线：

• Raw Layer（原始层）：仅做格式转换（JSON→Parquet）、分区归档（按日期/业务域），不做任何清洗。保留所有原始痕迹，包括脏数据、重复记录、缺失字段。这是我们的“数据黑匣子”，用于事后溯源。
• Cleansed Layer（清洗层）：基于视图执行标准化清洗。关键动作不是fillna()，而是显式标记：新增amount_is_null_reason STRING字段，填入'missing_from_source'或'invalid_format'；对异常值不直接剔除，而是生成amount_outlier_flag BOOLEAN。清洗逻辑全部封装为SQL UDF（用户自定义函数），通过Airflow调度，每次运行生成唯一run_id，写入元数据表。
• Feature Layer（特征层）：这才是算法同学真正使用的数据源。它由Cleansed Layer通过确定性SQL聚合生成，例如SELECT user_id, AVG(amount) AS avg_order_value_30d FROM cleansed_orders WHERE event_time >= CURRENT_DATE - INTERVAL '30 days' GROUP BY user_id。所有特征必须附带血缘标签（如feature_origin: 'sql_aggregation_v1.2'）和稳定性指标（如null_rate < 0.001,std_dev_ratio < 1.5）。

实操中最大的教训是：永远不要在Python里做JOIN操作。我们曾用Pandas合并用户行为日志和商品目录，本地跑得飞快；上生产后，因日志表每天10亿行、目录表500万行，单次JOIN耗时从2分钟飙升到47分钟，且OOM频发。解决方案是：所有关联逻辑下沉到Spark SQL或Trino，利用列式存储和谓词下推。Python只负责调用SQL、校验结果Schema、触发下游任务——它只是流水线的“指挥官”，不是“搬运工”。

另一个血泪经验：数据质量检查必须嵌入流水线每个环节，而非最后补测。我们在Cleansed Layer后插入一个Quality Gate节点，自动执行：

• 字段完整性检查（COUNT(*) vs COUNT(non_nullable_column)）
• 分布偏移检测（KS检验对比上周同周期分布）
• 业务规则验证（SUM(amount) > 0，否则触发人工审核）

这些检查失败不阻断流水线，但会生成quality_score并写入监控系统。当分数低于阈值（如0.85），自动邮件通知数据Owner，并暂停Feature Layer的更新。这比等模型上线后才发现预测全错，早救了三天。

3. 模型服务：用Flask+Docker搞定的不是API，而是可验证的服务契约

很多团队以为“模型服务化”就是把model.predict()包进一个Flask接口，返回JSON。这确实能跑通Demo，但在真实业务中，它会迅速演变成一场灾难：前端传来的图片base64编码长度超限、后端没做输入校验导致模型崩溃、不同版本模型共用同一端点引发混淆、错误码全是500掩盖了真实问题。真正的“from scratch”模型服务，核心不是部署，而是定义服务契约（Service Contract）——就像REST API需要OpenAPI规范，AI服务也需要明确的输入/输出契约、版本策略、健康检查标准。

我们坚持用最简技术栈：Flask + Docker + Nginx，拒绝任何“AI平台”抽象层。原因很实在：当服务器硬盘故障需要紧急恢复时，你能用U盘拷贝一个Docker镜像，在新机器上docker run -p 5000:5000 model:v1.2立刻恢复服务；而依赖Kubeflow或Seldon的方案，光重装Operator就得两小时。

服务契约的具体实现，体现在三个文件中：

3.1contract.yaml：机器可读的契约声明

name: "invoice-amount-extractor" version: "v1.2.0" input_schema: type: "object" properties: image_base64: type: "string" description: "PNG/JPEG image, max 5MB, base64 encoded" maxLength: 5242880 ocr_confidence_threshold: type: "number" default: 0.7 minimum: 0.1 maximum: 0.99 output_schema: type: "object" properties: amount: type: "number" multipleOf: 0.01 currency: type: "string" enum: ["CNY", "USD", "EUR"] confidence: type: "number" minimum: 0.0 maximum: 1.0 health_check: path: "/healthz" timeout_ms: 2000 success_criteria: "status == 200 and response.time < 100ms"

这个YAML文件不是文档，而是服务启动时的校验依据。Flask应用加载时，会解析它并动态生成输入校验中间件（用jsonschema库）、设置路由、配置健康检查响应。任何违反契约的请求（如ocr_confidence_threshold=1.5）在进入模型前就被拦截，返回清晰的400错误和具体字段名。

3.2Dockerfile：契约的物理载体

FROM python:3.9-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt # 关键：将contract.yaml和模型权重一起打包，确保契约与二进制强绑定 COPY contract.yaml model.pth . COPY app.py . # 暴露契约定义的端口 EXPOSE 5000 CMD ["gunicorn", "--bind", "0.0.0.0:5000", "--workers", "4", "app:app"]

镜像构建完成那一刻，“服务契约”就固化在镜像ID里。model:v1.2.0不只是一个标签，而是contract.yaml内容、model.pth哈希值、requirements.txt依赖树的联合指纹。升级时，必须同时更新契约和模型，否则CI/CD流水线会拒绝构建。

3.3nginx.conf：契约的网关守门员

upstream model_backend { server 127.0.0.1:5000; } server { listen 80; location /predict { # 强制JSON Content-Type if ($content_type != "application/json") { return 400 "Content-Type must be application/json"; } # 请求体大小限制（防DoS） client_max_body_size 6m; proxy_pass http://model_backend; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } location /healthz { proxy_pass http://model_backend; # 健康检查超时独立配置 proxy_read_timeout 2; } }

Nginx在这里不是性能优化器，而是契约执行器。它拦截所有非法请求头、超大请求体、非JSON格式，确保到达Flask的请求100%符合contract.yaml定义。我们甚至用Nginx日志统计各字段的取值分布，反向验证契约是否合理——比如发现99%的请求ocr_confidence_threshold=0.8，就说明默认值0.7可能偏低，需调整契约。

最后一条铁律：所有模型服务必须提供/explain端点。不是SHAP或LIME那种复杂解释，而是最朴素的“决策路径追溯”。例如，对于发票金额提取，/explain返回：

{ "input_hash": "a1b2c3...", "model_version": "v1.2.0", "steps": [ {"stage": "preprocess", "time_ms": 12, "output_shape": [3, 1024, 768]}, {"stage": "ocr", "time_ms": 85, "detected_text": ["¥1,234.56", "TOTAL"]}, {"stage": "regex_match", "time_ms": 3, "matched": "1234.56"}, {"stage": "postprocess", "time_ms": 2, "final_amount": 1234.56} ], "confidence": 0.92 }

这个端点让运维能快速定位瓶颈（是OCR慢还是正则慢），让产品能理解模型为何失败（没匹配到文本还是正则写错了），让法务能审计决策过程。它成本极低（日志埋点即可），价值极高——把黑盒变成了透明流水线。

4. 实验追踪：放弃MLflow，用CSV+Git管理你的每一次尝试

当团队说“我们要做实验追踪”时，90%的人第一反应是装MLflow或Weights & Biases。这没错，但违背了“from scratch”的初衷：你连Kubernetes集群都没搭好，就先搞起分布式跟踪服务？更现实的起点，是用最原始的工具——CSV文件和Git版本控制——建立最小可行实验追踪系统（Minimal Viable Experiment Tracking, MVET）。

我们的MVET系统只有三个核心组件：

4.1experiments.csv：人类可读的实验总账

id,timestamp,model_name,dataset_version,hyperparams_hash,train_acc,val_acc,test_acc,git_commit,notes exp_001,2024-05-10T08:22:15,resnet18,v2.1,abc123,0.921,0.893,0.887,feat/invoice-v1,"baseline, no augmentation" exp_002,2024-05-10T14:15:33,resnet18,v2.1,def456,0.935,0.901,0.892,feat/invoice-v1,"+ random rotation" exp_003,2024-05-11T09:03:47,efficientnet_b0,v2.1,ghi789,0.942,0.915,0.908,feat/invoice-v1,"switch to EfficientNet, lr=1e-3"

这个CSV不是数据库，而是每日同步到共享NAS的Excel文件。算法同学每次训练完，手动（或用一行Python脚本）追加一行。关键设计在于：

• hyperparams_hash：不是完整参数，而是hashlib.md5(json.dumps(sorted(hyperparams.items()))).hexdigest()，确保相同参数必有相同哈希，便于去重；
• git_commit：指向训练代码的精确提交，保证可复现；
• notes：强制要求写清“为什么改这个参数”，而非“调参结果”。

注意：CSV用逗号分隔，但notes字段含逗号时，必须用双引号包裹。我们用Pandas的to_csv(..., quoting=csv.QUOTE_ALL)生成，避免解析错误。这看似原始，却杜绝了“参数存在数据库里但找不到对应代码”的经典困境。

4.2artifacts/目录：模型与数据的物理存档

每个实验ID对应一个子目录：

artifacts/ ├── exp_001/ │ ├── model.pth # PyTorch权重 │ ├── config.yaml # 训练时的完整超参 │ ├── metrics.json # 各指标详细报告 │ └── train_log.txt # 控制台完整日志 ├── exp_002/ │ ├── model.pth │ ├── config.yaml │ └── ...

目录结构简单粗暴，但保证了一次实验的所有产出物物理共存。model.pth和config.yaml必须同目录，避免权重文件丢了配置、或配置文件丢了权重。我们用rsync -av --delete每日同步到备份服务器，比数据库备份更可靠。

4.3 Git Commit Message：实验的上下文锚点

每次提交代码，Commit Message必须包含实验ID：

feat(invoice): improve OCR accuracy [exp_003] - switch to EfficientNet-B0 backbone - add geometric augmentation (rotate, scale) - tune learning rate to 1e-3 - val_acc +1.4%, test_acc +1.1%

这样，git log --grep="exp_003"就能瞬间拉出所有相关代码变更。Git成为实验的“时间机器”，而CSV是它的索引目录。当有人质疑“为什么用EfficientNet”，直接git show feat/invoice-v1看diff，比翻MLflow UI快十倍。

这套MVET的威力，在于它把实验管理从“技术问题”降维成“协作习惯”。不需要学习新工具，不增加运维负担，所有成员（包括实习生）都能立刻上手。我们曾用它支撑了37个并发实验，直到团队规模扩大到15人、日均实验超50次时，才平滑迁移到自建的轻量版MLflow（仅用PostgreSQL+MinIO，不碰K8s）。迁移时，所有历史CSV数据一键导入，因为MVET的schema就是MLflow的底层表结构。

最深刻的体会是：实验追踪的本质不是记录数据，而是建立责任归属。当exp_003的test_acc突然下降0.5%，git blame能立刻定位到是谁改了数据预处理逻辑，experiments.csv的notes字段写着“为提升速度删除了图像归一化”，这就是根因。工具越简单，责任越清晰。

5. 模型可解释性：不用SHAP，用业务规则反向校验你的神经网络

“可解释AI”常被当成高深技术，动辄SHAP、LIME、Attention可视化。但在“from scratch”的实战中，最有效、最低成本的可解释性，是用业务规则反向校验模型输出——不是告诉用户“模型为什么这么预测”，而是确保“模型的预测一定符合业务常识”。这听起来像回归测试，但它解决了AI落地中最致命的信任危机：当模型给出一个反直觉结果时，你是该信模型，还是信业务专家？

我们的方法叫Rule-Based Sanity Check（RBSC），它不修改模型，只在预测后加一层轻量级校验。以发票金额提取为例，业务规则明确：

• 金额必须为正数（amount > 0）；
• 金额小数位不超过2位（amount == round(amount, 2)）；
• 若发票含税，则amount应接近subtotal + tax（允许±5%误差）；
• 同一发票的amount与total字段应一致（若OCR识别出多个金额字段）。

RBSC的实现，是一个独立于模型的Python模块：

def validate_invoice_amount(prediction: dict, ocr_raw: dict) -> dict: """输入模型预测和原始OCR结果，返回校验报告""" report = {"valid": True, "issues": []} # 规则1：正数检查 if prediction["amount"] <= 0: report["valid"] = False report["issues"].append("amount_must_be_positive") # 规则2：小数位检查 if prediction["amount"] != round(prediction["amount"], 2): report["valid"] = False report["issues"].append("amount_decimal_precision") # 规则3：税额一致性（需OCR提供subtotal/tax字段） if "subtotal" in ocr_raw and "tax" in ocr_raw: expected = ocr_raw["subtotal"] + ocr_raw["tax"] if abs(prediction["amount"] - expected) > expected * 0.05: report["issues"].append("amount_vs_tax_inconsistency") return report

这个模块被集成在服务的/predict端点末尾：

@app.route("/predict", methods=["POST"]) def predict(): data = request.get_json() prediction = model.predict(data["image_base64"]) validation = validate_invoice_amount(prediction, data.get("ocr_raw", {})) # 关键：校验失败不直接报错，而是降级处理 if not validation["valid"]: # 记录告警，但返回预测结果 + 校验报告 logger.warning(f"RBSC failed for {data['id']}: {validation['issues']}") prediction["rb_sc_report"] = validation return jsonify(prediction)

RBSC的价值远超“过滤错误结果”：

• 它是模型的实时压力测试：当amount_must_be_positive频繁触发，说明模型在训练数据中见过太多负数样本（如退款单），需重新清洗数据；
• 它是业务知识的沉淀载体：每条规则都来自财务部门的SOP，把隐性知识编码为可执行逻辑；
• 它是人机协作的桥梁：前端收到rb_sc_report后，可自动高亮可疑字段，提示审核员：“模型预测¥123.45，但OCR识别出subtotal¥100 + tax¥25，建议复核”。

我们甚至用RBSC驱动模型迭代：每月统计各规则的失败率，失败率最高的规则对应的问题，就是下个迭代周期的优化重点。例如，当amount_vs_tax_inconsistency失败率达12%，我们就知道OCR的subtotal识别准确率不足，优先投入资源优化OCR模块，而非盲目调参。

最后一点经验：RBSC规则必须版本化、可配置。我们把规则集存为YAML：

version: "v1.3" rules: - name: "amount_must_be_positive" enabled: true severity: "error" - name: "amount_decimal_precision" enabled: true severity: "warning" - name: "amount_vs_tax_inconsistency" enabled: true severity: "error" tolerance: 0.05

服务启动时加载此文件，支持运行时热更新（通过Redis Pub/Sub广播新规则）。这样，业务部门提出新规则（如“含折扣券的发票，amount应等于subtotal减去discount”），无需重启服务，只需更新YAML并推送，10秒内生效。可解释性，从此不再是技术团队的独角戏，而是业务与技术共同维护的活文档。

我在实际交付中发现，客户最常问的不是“模型准确率多少”，而是“如果模型错了，你们怎么知道？”——RBSC就是那个掷地有声的回答。它不追求学术上的可解释性深度，但确保每一次预测都经得起业务逻辑的拷问。这才是“from scratch”工程化的终极体现：用最朴实的代码，构建最坚实的信任。