1. 这不是“搭个LLM API”——AI工程从零开始的真实战场

很多人看到“AI Engineering from Scratch”第一反应是：不就是调个OpenAI API，写个Flask后端，再套个React前端？点几下Hugging Face Model Hub，拖个Streamlit组件，发个推特说“我做了个AI应用”，完事。
但真正做过AI工程落地的人知道，这标题背后根本不是“Hello World”级别的玩具项目，而是一场覆盖数据、模型、服务、监控、迭代闭环的系统性攻坚。它不考你会不会写model.generate()，而是考你能不能在没有现成MLOps平台、没有专职SRE支持、甚至没有GPU集群调度权限的情况下，让一个能处理真实业务请求的AI服务，在生产环境里连续跑满72小时不OOM、不超时、不返回乱码、不把用户query喂进错误的tokenizer。

我去年带团队重构一个金融文档摘要系统时，就卡死在这个“from scratch”的起点上：我们手头只有3台A10服务器，没有Kubeflow，没有MLflow，连Prometheus都得自己编译；原始PDF解析用的是开源PyMuPDF，结果发现它对扫描件OCR后的文本排版丢失严重；微调用的LoRA权重加载后显存暴涨40%，但监控日志里只显示“CUDA out of memory”，没告诉你到底是KV Cache没清、还是LoRA adapter层的grad缓存没释放、抑或是tokenizer的padding策略把512 token的batch硬撑到1024。这些坑，API封装层根本不会暴露给你——它只负责抛错，不负责解释错在哪。

所以这篇不是教程，是战地笔记。它不教你怎么“快速上线”，而是带你回到那个最原始的状态：没有SDK包装、没有云厂商兜底、没有预置pipeline，只有Linux命令行、Python源码、CUDA驱动日志和一份模糊的业务需求文档。关键词不是“AI”或“Engineering”，而是可验证、可回滚、可归因、可计量——这才是“from scratch”的真正门槛。适合三类人：刚脱离Kaggle套路想进工业界的算法同学、被业务方催着“快上个AI功能”的后端工程师、以及正在评估是否该自建AI基建的技术负责人。你不需要会写CUDA kernel，但必须清楚torch.compile()在什么场景下会让推理延迟翻倍；你不用懂Transformer数学推导，但得明白为什么把attention_mask传错shape会导致整个batch输出全为<unk>。

2. 从“能跑”到“敢上生产”：四个不可跳过的底层验证层

很多团队把模型跑通就叫“完成工程化”，结果上线后发现：测试集准确率92%，线上bad case率却高达37%；QPS标称200，实际压测到80就触发重试风暴；模型版本更新后，老用户历史对话突然变味。问题不在模型本身，而在验证环节被压缩成了“跑个eval.py”。真正的AI工程验证必须分层穿透，每一层都得有明确的准入阈值和失败熔断机制。

2.1 数据管道的原子性校验：别让脏数据毁掉整个链路

多数人以为数据清洗是预处理脚本的事，但工程化中最大的隐患恰恰藏在数据流的衔接处。举个真实案例：我们接入的PDF解析服务返回JSON，字段名是"text_content"，而下游微调脚本读取的是"content"。开发环境用mock数据测试时一切正常，因为mock里两个字段都存在；但生产环境PDF解析偶尔返回空text_content，脚本却默认填充了空字符串，导致训练数据里混入大量纯空行——模型学到了“空输入→空输出”的强关联，上线后遇到合法空query（如用户只点了发送按钮没输文字），直接返回空响应，被判定为服务不可用。

解决方案不是加try-except，而是建立Schema契约校验层：

• 在数据进入pipeline前，强制校验JSON Schema，字段名、类型、非空约束全部定义在YAML里；
• 使用jsonschema库做实时校验，失败时打点告警并路由到隔离队列，绝不让脏数据流入下游；
• 关键字段（如text_content）增加语义校验：长度>10且中文字符占比>30%，否则标记为low_quality并触发人工复核。

提示：不要依赖上游文档承诺的字段名。我们曾发现同一PDF解析服务在v2.1和v2.2版本间，page_number字段从int变成了string，没做类型校验直接导致排序逻辑崩溃。现在所有外部数据接入，第一行代码永远是assert isinstance(data['page_number'], int)。

2.2 模型服务的确定性沙箱：为什么你的本地推理和线上结果不一致

同一个.pt文件，在开发机上model(input_ids)输出正确，在服务器上却返回全零向量。查了一天发现是服务器CUDA版本（11.8）比开发机（12.1）低，而模型里用了torch.nn.functional.scaled_dot_product_attention——这个算子在11.8里默认回退到朴素实现，但回退路径有个未公开的bug：当attn_mask是bool类型且batch_size>1时，会错误地mask掉所有token。问题根源不是模型代码，而是CUDA驱动与PyTorch ABI的隐式耦合。

因此，“from scratch”的模型服务必须构建确定性沙箱：

• 环境锁定：Dockerfile里明确指定CUDA_VERSION=12.1.1,PYTORCH_VERSION=2.2.1+cu121，用pip install torch==2.2.1+cu121 --extra-index-url https://download.pytorch.org/whl/cu121而非pip install torch；
• 算子白名单：禁用所有torch.nn.functional里的非稳定算子，改用torch.nn.MultiheadAttention等经过充分测试的模块；
• 输入指纹校验：对每次推理的input_ids、attention_mask、position_ids做SHA256哈希，记录到日志，当线上结果异常时，可精确比对开发环境同指纹输入的输出差异。

实测下来，这套沙箱让模型服务层的“环境相关故障”下降91%。最值钱的不是技术，而是把“为什么结果不一样”这个问题，从玄学排查变成可复现的二进制对比。

2.3 推理服务的资源边界控制：OOM不是内存不够，是资源没封顶

A10显存24GB，理论上能跑batch_size=8的7B模型，但实际部署时经常OOM。查nvidia-smi发现显存占用忽高忽低，最高冲到23.8GB，但torch.cuda.memory_allocated()只显示18GB——差的那5GB去哪了？答案是CUDA Context的碎片化内存和未释放的梯度缓存。PyTorch默认不主动释放显存，尤其在动态batch场景下，不同长度的sequence会留下大量小块显存，最终无法分配新tensor。

解决方案是三级资源封顶机制：

1. 进程级显存硬限制：启动服务时加CUDA_VISIBLE_DEVICES=0,1,2+--gpus '"device=0,1,2"'，再用nvidia-docker run --memory=32g --memory-swap=32g限制宿主机内存；
2. 框架级显存回收：在推理函数末尾强制执行torch.cuda.empty_cache()，并在每个request处理完后调用gc.collect()；
3. 模型级显存预估：用transformers的estimate_memory_usage工具，对不同max_length和batch_size组合生成显存占用热力图，选择安全区间的配置组合。

我们最终确定A10单卡安全运行7B模型的上限是：batch_size=4,max_length=1024,kv_cache=True。超过任一参数，OOM概率从5%飙升至67%。这个数字不是理论值，是压测2000次后统计出的生存边界。

2.4 服务可观测性的最小可行集：没有Metrics的AI服务等于盲飞

很多团队只监控HTTP状态码和CPU使用率，但AI服务的健康指标完全不同：p99_latency可能正常，但p99_output_length暴跌，说明模型开始胡言乱语；error_rate很低，但empty_response_rate持续上升，意味着tokenizer或post-processing逻辑失效。真正的可观测性必须包含三个维度：

特别强调output_entropy_mean：我们曾发现金融问答模型在回答“利率下调影响”时熵值突降至0.3，细查发现模型把所有政策类query都映射到固定模板，丧失了泛化能力。这个指标在准确率、F1等传统指标上完全无体现，却是模型退化的最早信号。

这套最小可观测集，用Prometheus+Grafana实现，总代码量不到200行，但让故障平均定位时间从47分钟缩短到6分钟。

3. 模型微调的工程真相：LoRA不是银弹，而是新的负债中心

“用LoRA微调，省显存又快！”——这是LoRA宣传中最误导人的说法。真实情况是：LoRA降低了单次训练的显存需求，但大幅增加了工程负债。我们用LoRA微调一个7B模型，训练过程顺利，但上线后遭遇三个致命问题：

3.1 权重加载的隐式耦合：LoRA adapter和base model必须版本严格匹配

LoRA权重文件里存的是lora_A和lora_B矩阵，但加载时需要知道base model的hidden_size、num_attention_heads等参数。如果base model从transformers==4.36升级到4.37，内部LlamaAttention类的__init__方法签名变了，LoRA加载器就会报AttributeError: 'LlamaAttention' object has no attribute 'q_proj'。更糟的是，这个错误只在特定batch size下触发，导致问题在灰度发布时才暴露。

解决方案是LoRA权重绑定base model hash：

• 训练完成后，用git rev-parse HEAD获取transformers库的commit hash；
• 将hash写入LoRA权重文件的config.json里，字段名为base_model_transformers_hash；
• 服务启动时校验当前环境transformers的hash是否匹配，不匹配则拒绝加载并告警。

我们因此建立了一个LoRA仓库，每个权重包都附带requirements.txt和model_card.md，明确标注适配的PyTorch/CUDA/Transformers版本组合。现在团队新增LoRA任务，第一件事不是写训练脚本，而是更新这个版本矩阵。

3.2 推理时的LoRA融合陷阱：你以为的“融合”其实是计算开销转移

文档说“LoRA可以merge到base model节省推理显存”，但没人告诉你merge操作本身要消耗多少资源。我们尝试merge一个7B模型的LoRA权重，发现：

• merge耗时127秒，期间GPU显存占用峰值达22GB；
• merge后模型体积增大37%，从13GB变成17.8GB；
• 最关键的是，merge后的模型在A10上推理速度反而下降18%，因为LoRA原本利用了A10的Tensor Core加速稀疏计算，而merge后变成全dense计算，失去了硬件优化。

结论：LoRA不merge才是生产环境常态。我们改为在线LoRA加载，但做了两件事：

• 预热阶段提前加载所有LoRA adapter到GPU，避免runtime加载抖动；
• 用torch.compile()对LoRA forward路径做图优化，将lora_A @ lora_B融合为单个kernel，实测提速23%。

注意：torch.compile()对LoRA的优化效果高度依赖CUDA版本。我们在CUDA 12.1上获得23%提速，在11.8上反而慢5%。所以版本锁定不仅是模型兼容性问题，更是性能基线问题。

3.3 LoRA的版本漂移：微调不是“一次训练，永久有效”

LoRA权重不是静态资产。我们发现同一份训练数据，用transformers==4.36训练的LoRA，在4.37上加载后，相同输入的输出KL散度达0.42（>0.3即视为显著偏移）。原因在于4.37修复了RoPE位置编码的一个边界bug，导致attention score分布变化，LoRA微调的补偿方向随之失效。

因此，LoRA必须像数据库migration一样管理：

• 每次LoRA训练，生成migration.sql式描述文件，记录base_model_version、training_data_version、transformers_version、rope_theta等关键参数；
• 线上服务根据当前base model的参数，自动选择匹配的LoRA版本；
• 当base model升级时，触发LoRA重训流水线，而非简单替换权重。

这套机制让我们避免了三次因LoRA版本错配导致的线上语义漂移事故。代价是运维复杂度上升，但换来的是模型行为的可预测性——这才是AI工程的核心诉求。

4. 构建可演进的AI服务骨架：拒绝“一次性脚本”思维

很多AI项目止步于app.py——一个500行Flask应用，包含数据加载、模型加载、推理逻辑、结果返回。它能跑，但无法维护。真正的“from scratch”骨架必须解决三个本质问题：配置可分离、逻辑可插拔、状态可追溯。

4.1 配置即代码：用Pydantic V2重构所有硬编码参数

旧代码里充斥着这样的片段：

MAX_LENGTH = 1024 TEMPERATURE = 0.7 TOP_P = 0.9 MODEL_PATH = "/models/llama-7b-v2"

问题在于：这些值分散在各处，修改时需全局搜索；没有类型校验，TEMPERATURE=1.5这种非法值直到运行时报错；无法区分环境配置（dev/staging/prod）。

新骨架采用Pydantic Settings分层配置：

class ModelConfig(BaseSettings): path: str = Field(default="/models/llama-7b-v2") max_length: int = Field(default=1024, ge=128, le=2048) temperature: float = Field(default=0.7, ge=0.0, le=1.0) class ServiceConfig(BaseSettings): host: str = "0.0.0.0" port: int = Field(default=8000, ge=1024, le=65535) workers: int = 4 class Config(BaseSettings): model: ModelConfig = ModelConfig() service: ServiceConfig = ServiceConfig() class Config: env_file = ".env" env_file_encoding = "utf-8"

启动时加载：

config = Config() # 自动校验：temperature>1.0会抛ValidationError # 自动注入：从.env读取MODEL_PATH，覆盖默认值 # 自动转换：port字符串转int

这套配置体系让参数变更从“改代码”变成“改.env文件”，且所有非法值在服务启动时就被拦截，而不是等到用户请求时才崩溃。

4.2 逻辑插件化：用Protocol定义AI能力契约

传统写法把prompt engineering、post-processing、rate limiting全塞进一个generate()函数里。当业务要求“对金融类query启用专业术语校验”时，不得不在函数里加if-else分支，很快变成意大利面条代码。

新骨架用Protocol定义能力契约：

from typing import Protocol, Optional class TextProcessor(Protocol): def process(self, text: str) -> str: ... class PromptEngineer(Protocol): def build_prompt(self, query: str, history: list) -> str: ... class OutputValidator(Protocol): def validate(self, output: str) -> Optional[str]: # 返回None表示通过

然后实现具体插件：

class FinanceTermValidator: def __init__(self, terms: set): self.terms = terms def validate(self, output: str) -> Optional[str]: if not any(term in output for term in self.terms): return "输出未包含必要金融术语" return None # 注册插件 validator = FinanceTermValidator({"LPR", "MLF", "SLF"})

服务核心逻辑变成：

def generate(query: str, validator: OutputValidator): prompt = prompt_engineer.build_prompt(query) raw_output = model.generate(prompt) error = validator.validate(raw_output) if error: raise ValidationError(error) return post_processor.process(raw_output)

这样，新增一个“法律条款校验插件”，只需实现OutputValidator协议，无需改动主流程。我们已积累12个可插拔插件，覆盖金融、医疗、法律等垂直领域，复用率83%。

4.3 请求全链路追踪：从“用户说了一句什么”到“模型为什么这么答”

没有追踪的AI服务就像黑盒。当用户投诉“为什么回答错误”，你只能看日志里的{"input": "...", "output": "..."}，但不知道中间发生了什么：是prompt拼错了？是tokenizer截断了关键信息？是LoRA权重加载失败回退到base model？还是cache命中了错误的历史？

我们构建了轻量级全链路追踪骨架：

• 每个request生成唯一trace_id，贯穿数据加载、prompt构建、tokenization、model forward、post-processing全流程；
• 关键节点打点：tokenize_start,tokenize_end,forward_start,forward_end,validate_start,validate_end；
• 每个打点记录timestamp,duration_ms,input_shape,output_shape,error（如有）；
• 所有trace数据序列化为JSON，写入单独的traces.log文件，按小时切割。

当问题发生时，用grep trace_id traces.log就能还原完整链路：

[2024-05-20T14:22:31.123] tokenize_start {"input_len": 247} [2024-05-20T14:22:31.128] tokenize_end {"output_len": 256, "truncated": false} [2024-05-20T14:22:31.129] forward_start {"batch_size": 1, "max_length": 1024} [2024-05-20T14:22:32.891] forward_end {"kv_cache_used": true, "latency_ms": 1762} [2024-05-20T14:22:32.892] validate_start {} [2024-05-20T14:22:32.893] validate_end {"error": "输出未包含必要金融术语"}

这个骨架不依赖Jaeger或Zipkin，纯Python实现，增加的延迟<2ms，却让90%的线上问题能在5分钟内定位根因。

5. 工程化不是终点，而是迭代循环的起点

做完以上所有，你得到的不是一个“完成”的AI服务，而是一个可迭代的最小可行产品（MVP）。真正的AI工程价值，体现在这个MVP如何支撑持续迭代——不是靠“加新模型”，而是靠“加固反馈闭环”。

我们上线第一个版本后，建立了三个自动化反馈通道：

5.1 用户显式反馈的结构化沉淀

用户点击“回答有误”按钮，旧做法是记录一行日志{"user_id": "...", "feedback": "wrong"}。新做法是：

• 弹出结构化问卷：“错误类型”（事实错误/逻辑错误/格式错误/无关回答）、“影响程度”（轻微/中等/严重）、“期望答案关键词”；
• 将结构化数据存入专用feedback.db，字段包括trace_id,error_type,severity,expected_keywords；
• 每日凌晨跑ETL任务，提取error_type="fact_error"且severity="severe"的样本，自动加入下一轮微调数据集。

三个月后，事实错误率从12.7%降至3.2%，因为每一条严重事实错误都被转化成了精准的监督信号。

5.2 模型输出的隐式质量评估

不是所有错误用户都会反馈。我们部署了无监督输出质量探针：

• 对每个输出，用轻量级分类器判断是否包含“免责声明”（如“仅供参考”、“不构成投资建议”）；
• 计算输出与标准术语库的Jaccard相似度；
• 检测输出中是否存在矛盾陈述（如同时出现“上涨”和“下跌”）；
• 当三项指标同时低于阈值时，标记为low_confidence_output，自动触发人工审核。

这个探针每天捕获237条潜在bad case，其中68%经审核确认为真实问题，远超用户主动反馈量。

5.3 服务指标驱动的模型轮换机制

我们不再手动决定何时更新模型。而是设定自动化轮换规则：

• 当p99_latency连续2小时>1500ms，且kv_cache_hit_rate<70%，触发模型降级（切换到更小的3B模型）；
• 当empty_response_rate连续1小时>8%，且output_entropy_mean<0.8，触发LoRA重训；
• 当feedback_severity_high_count周环比增长>50%，触发全量数据重采样。

这套机制让模型迭代从“人盯报表”变成“规则驱动”，平均迭代周期从14天缩短到3.2天。

最后分享一个血泪教训：我们曾以为“工程化完成”意味着可以松口气，结果上线两周后发现，所有优化都抵不过一个bug——tokenizer.pad_token_id在不同transformers版本中默认值不同，导致padding位置的attention mask全为0，模型把padding token当成了有效输入。这个bug在单元测试里完全覆盖不到，因为它只在batch_size>1且sequence长度不等时触发。

所以真正的AI工程从零开始，从来不是搭建一个完美系统，而是建立一套让错误快速暴露、快速定位、快速修复的肌肉记忆。当你能把一个CUDA OOM错误，从“重启服务”推进到“定位到某行PyTorch源码的内存泄漏”，你就真正踏入了AI Engineering的大门。这条路没有银弹，只有日拱一卒的确定性——而这，正是“from scratch”最珍贵的馈赠。