1. 项目概述：这不是“跑通模型”，而是让模型在真实世界里活下来

“From Notebook to Production: Running ML in the Real World (Part 4)”——这个标题本身就像一句行话暗号，老手一眼就懂：前面三篇已经蹚过了数据清洗、特征工程、模型训练和验证的浅水区，而这一part，是真正把脚踩进泥里，开始面对生产环境那套冷酷又琐碎的生存法则。它不讲怎么调高0.5%的AUC，而是直击一个所有ML工程师最终都绕不开的硬核问题：你花三个月在Jupyter里调得闪闪发光的模型，一旦脱离本地GPU和干净数据集，放进每天要处理百万级请求、数据格式随时漂移、上游服务可能凌晨两点挂掉的线上系统里，它还能不能呼吸？会不会直接窒息？会不会反向污染整个业务链路？这才是Part 4的核心战场。

我做过不下二十个从实验室走向产线的模型项目，最深的体会是：模型上线那一刻，不是终点，而是运维噩梦的起点。Part 4讲的，就是如何把那个在Notebook里被宠坏的“模型宝宝”，训练成能扛住流量洪峰、能读懂脏数据、能自己报错求救、甚至能在出问题时优雅降级的“生产老兵”。它涉及的远不止是模型本身，而是整个MLOps流水线的肌肉记忆——从模型打包封装的细节选择，到API服务的并发压测策略；从特征服务的缓存穿透防护，到线上监控告警的阈值设定逻辑；从模型版本灰度发布的节奏把控，到A/B测试结果的统计显著性陷阱。这些内容，在Kaggle排行榜上永远看不到，但在真实业务中，任何一个环节的疏忽，都可能让价值百万的模型项目在上线首周就因一次未捕获的NaN输入而全线崩溃。所以，这篇内容不是给只想跑通demo的新手看的，它是写给那些已经把模型训出来、正站在生产环境门口、手里攥着部署脚本却迟迟不敢按回车键的实战派工程师的生存指南。如果你的日常是和Docker日志、Prometheus图表、Kubernetes事件、以及凌晨三点的告警电话打交道，那么Part 4的每一段文字，都是你明天早上开会时能直接甩出来的解决方案。

2. 核心设计思路拆解：为什么“封装-服务-监控”是铁三角，而不是可选项

2.1 封装：从Python对象到可交付制品，中间隔着一堵墙

很多人以为模型封装就是joblib.dump(model, 'model.pkl')，然后扔进一个Flask路由里returnmodel.predict()。这是最危险的认知误区。真正的封装，核心目标是隔离与契约。隔离的是开发环境与运行环境的差异（Python版本、依赖库冲突、CUDA驱动兼容性），契约的是模型输入输出的严格定义（schema）。我见过太多项目因为没做这一步，上线后第一周就栽在numpy版本不一致导致的array形状错乱上。

我们团队现在强制采用双层封装策略。第一层是模型本身的序列化，我们弃用了pickle，改用ONNX作为标准交换格式。原因很实在：pickle是Python专属，且存在安全风险；而ONNX是跨语言、跨框架的开放标准，一个PyTorch训练的模型导出为ONNX后，可以用C++、Java甚至JavaScript原生加载推理，为未来可能的边缘计算或移动端集成埋下伏笔。导出时，我们必做三件事：一是固定opset_version（我们统一用15），避免不同ONNX Runtime版本解析差异；二是用torch.onnx.export的dynamic_axes参数明确定义哪些维度是动态的（比如batch size），否则服务端无法处理变长请求；三是导出后必须用onnx.checker.check_model()做校验，这步看似多余，但曾帮我们提前发现过一个因torch.nn.functional.interpolate算子在特定插值模式下生成非法ONNX图的致命bug。

第二层是服务容器的封装。我们不用裸Flask，而是基于FastAPI构建最小服务骨架，再用Docker打包。关键在于Dockerfile的设计哲学：多阶段构建 + 最小基础镜像。构建阶段用python:3.9-slim安装所有训练和转换依赖（torch,onnx,scikit-learn）；运行阶段则切换到更轻量的python:3.9-slim-bullseye，只COPY编译好的ONNX模型文件和精简后的requirements.txt（里面剔除了所有-dev包和jupyter等开发工具）。这样最终镜像大小能从1.2GB压到380MB，启动时间从12秒降到3.5秒。别小看这几秒——在K8s集群里，Pod频繁重启时，这决定了你的服务能否在流量高峰前完成冷启动。

提示：ONNX模型导出后，务必用onnxruntime在目标环境（如CPU服务器）上做一次inference实测。我们曾在一个金融风控模型上发现，PyTorch导出的ONNX在onnxruntimeCPU版上，对torch.nn.Softmax的处理逻辑与GPU版有微小数值差异，虽不影响分类结果，但会导致后续规则引擎的阈值判断失效。这个坑，只能靠实测填。

2.2 服务：API不是“能返回结果”就行，而是要经得起压测和混沌

服务层是模型与世界的接口，它的健壮性直接决定了用户体验。很多团队把API当做一个简单的函数包装器，忽略了它在生产环境中的多重角色：流量网关、错误熔断器、性能缓冲池、安全过滤器。

我们现在的API服务骨架，核心围绕三个原则设计：

第一，输入强校验，拒绝一切模糊地带。FastAPI的Pydantic模型不是摆设。我们为每个预测接口定义严格的InputSchema，不仅校验字段类型（float/str），更校验业务逻辑约束。例如，一个用户年龄字段，Pydantic模型会定义age: conint(ge=0, le=120)，如果传入-5或150，FastAPI会在进入预测函数前就返回422错误，并附带清晰的错误信息"age must be greater than or equal to 0"。这比在模型里抛出ValueError再被全局异常处理器捕获，要快一个数量级，也更友好。更重要的是，它把数据质量检查的关口前移到了最外层，避免了脏数据一路渗透到模型内部，引发不可预知的崩溃。

第二，并发与资源隔离是生命线。默认的uvicorn单进程模型在高并发下是灾难。我们的标准配置是：--workers 4 --threads 2 --limit-concurrency 100。workers数设为CPU核心数，确保GIL不成为瓶颈；threads控制每个worker内的线程数，用于处理I/O密集型任务（如数据库查询）；而--limit-concurrency是关键，它限制了同时处理的请求数，防止一个慢查询拖垮整个worker。我们还为模型推理本身加了asyncio锁，确保同一时刻只有一个协程在执行ort_session.run()（ONNX Runtime的Session.run是线程安全的，但某些自定义后处理逻辑不是）。这个锁的粒度我们反复权衡过：锁整个predict函数太重，锁单个ONNX Session又太细，最终选择锁在“加载模型+执行推理”这个原子操作上，实测下来在QPS 800时，P99延迟稳定在120ms以内。

第三，健康检查与就绪探针是K8s的“心跳”。K8s的livenessProbe和readinessProbe不是可选项。我们的/healthz端点，不仅检查uvicorn进程是否存活，更会执行一次轻量级的“模型心跳”：加载一个预存的、极小的测试样本（1行数据），调用ort_session.run()并验证输出是否为有效数组。如果这个心跳失败，K8s会立即杀死Pod并重建。而/readyz则更进一步，它还会检查下游依赖（如Redis特征缓存、PostgreSQL元数据库）的连接状态。只有当所有依赖都健康时，/readyz才返回200，K8s才会将流量导入该Pod。这个设计让我们在一次Redis集群升级期间，成功避免了所有服务请求被路由到尚未连上新Redis的Pod上，实现了零感知的平滑过渡。

2.3 监控：没有监控的服务，等于在黑暗中开车

监控不是事后诸葛亮，而是实时导航仪。Part 4的监控体系，我们坚持“三层漏斗”原则：基础设施层 → 服务层 → 业务层。每一层的指标，都对应着不同的故障域和响应人。

基础设施层（Infra Metrics）由Prometheus抓取，核心是node_exporter和cAdvisor。我们重点关注三个黄金信号：container_cpu_usage_seconds_total（CPU使用率突增往往预示内存泄漏）、container_memory_working_set_bytes（工作集内存，比RSS更能反映真实压力）、container_network_receive_bytes_total（网络接收字节数，异常飙升可能是DDoS或上游数据泵异常）。这些指标的告警阈值不是拍脑袋定的，而是基于历史基线。我们用Prometheus的rate()函数计算5分钟平均速率，再用stddev_over_time()计算过去7天的标准差，告警阈值设为avg_over_time() + 3 * stddev_over_time()。这套方法让我们在一次因上游ETL任务配置错误导致每秒涌入10倍正常数据的事故中，提前17分钟收到了CPU告警，抢在服务雪崩前手动扩容了Pod副本数。

服务层（Service Metrics）是我们自研的fastapi-metrics中间件注入的。它自动记录每个API端点的http_request_total（按status_code、method、path标签）、http_request_duration_seconds_bucket（P50/P90/P99延迟）、http_request_size_bytes_sum（请求体大小）。这里有个关键经验：延迟指标必须分桶（histogram），不能只看平均值。平均延迟50ms毫无意义，如果其中90%的请求是10ms，10%是500ms，平均值还是50ms，但那10%的用户已经体验到了卡顿。我们配置了从10ms到5000ms共12个分桶，这样就能清晰看到P99是否稳定在200ms内。有一次，我们发现P99突然从180ms跳到320ms，但P50几乎没变。排查后发现，是某个新上线的特征计算逻辑里，对一个稀疏ID做了全表扫描，导致尾部请求严重拖慢。这个细节，只有分桶延迟才能暴露。

业务层（Business Metrics）是最容易被忽视，也最有价值的一层。它不关心技术指标，只关心模型是否在正确地做事。我们定义了三个核心业务指标：model_prediction_count_total（总预测次数）、model_prediction_error_rate（预测失败率，非HTTP错误，而是模型内部逻辑错误，如输出NaN）、model_data_drift_score（通过KS检验计算的输入特征分布偏移得分）。最后一个指标尤其关键。我们每天定时用线上最新1小时的数据，与模型训练时的基准数据集做KS检验，计算每个数值型特征的p-value。如果任意一个特征的p-value < 0.01，就触发data_drift_alert。这个机制在一次电商大促前救了我们：监测到“用户最近7天加购次数”这个关键特征的分布发生了显著右偏（p-value=0.003），我们立刻回溯发现，是上游推荐系统算法更新，导致加购行为激增。我们没有贸然上线新模型，而是先用新数据重新训练，避免了模型在大促期间因特征失真而做出错误的转化率预测。

3. 实操过程详解：从ONNX导出到K8s部署的完整流水线

3.1 模型导出与验证：一次不能出错的精密手术

导出ONNX模型，绝不是一行代码的事。它是一个需要精确控制每一步的精密流程。以下是我们团队标准化的export_onnx.py脚本核心逻辑，它已被封装进CI/CD流水线，每次模型训练完成后自动触发：

import torch import onnx from onnx import checker, shape_inference from pathlib import Path def export_model_to_onnx( model: torch.nn.Module, dummy_input: torch.Tensor, output_path: str, opset_version: int = 15, dynamic_axes: dict = None ): """ 导出PyTorch模型为ONNX格式，并进行完整性校验 :param model: 训练好的PyTorch模型 :param dummy_input: 用于trace的示例输入张量 :param output_path: 输出ONNX文件路径 :param opset_version: ONNX算子集版本 :param dynamic_axes: 动态轴字典，如 {'input': {0: 'batch'}, 'output': {0: 'batch'}} """ # 确保模型处于eval模式，关闭dropout和bn的training行为 model.eval() # 关闭梯度计算，节省内存 with torch.no_grad(): # 执行一次前向传播，确保模型能跑通 _ = model(dummy_input) # 导出ONNX torch.onnx.export( model=model, args=dummy_input, f=output_path, export_params=True, # 存储训练好的参数 opset_version=opset_version, do_constant_folding=True, # 优化常量折叠 input_names=['input'], # 输入名称 output_names=['output'], # 输出名称 dynamic_axes=dynamic_axes if dynamic_axes else {} ) # 步骤1：校验ONNX模型语法 try: onnx_model = onnx.load(output_path) checker.check_model(onnx_model) print(f"✅ ONNX模型语法校验通过: {output_path}") except Exception as e: raise RuntimeError(f"❌ ONNX语法校验失败: {e}") # 步骤2：执行shape inference，推断输出张量形状 try: onnx_model = shape_inference.infer_shapes(onnx_model) onnx.save(onnx_model, output_path) print(f"✅ ONNX Shape Inference完成") except Exception as e: raise RuntimeError(f"❌ ONNX Shape Inference失败: {e}") # 步骤3：用ONNX Runtime进行端到端推理验证 import onnxruntime as ort try: # 创建ORT session ort_session = ort.InferenceSession(output_path, providers=['CPUExecutionProvider']) # 准备输入数据（注意：ORT要求numpy array） ort_inputs = {ort_session.get_inputs()[0].name: dummy_input.numpy()} # 执行推理 ort_outputs = ort_session.run(None, ort_inputs) # 验证输出形状和基本数值（非零、非NaN） assert len(ort_outputs) == 1, "ONNX模型应只有一个输出" assert not any([np.isnan(x).any() for x in ort_outputs]), "ONNX输出包含NaN" assert not any([np.isinf(x).any() for x in ort_outputs]), "ONNX输出包含Inf" print(f"✅ ONNX Runtime端到端推理验证通过") except Exception as e: raise RuntimeError(f"❌ ONNX Runtime推理验证失败: {e}") # 使用示例 if __name__ == "__main__": # 假设model是已加载的PyTorch模型 # dummy_input是符合模型输入要求的Tensor，例如: torch.randn(1, 3, 224, 224) export_model_to_onnx( model=model, dummy_input=dummy_input, output_path="models/resnet50_v1.onnx", dynamic_axes={'input': {0: 'batch'}, 'output': {0: 'batch'}} )

这个脚本的关键在于三重验证闭环：语法校验（checker）确保ONNX图结构合法；Shape Inference确保模型能被正确解析；ORT Runtime验证确保它能在目标硬件上真正跑起来。我们曾在一个NLP模型上，因为torch.nn.Embedding层的padding_idx参数在导出时未被正确处理，导致ONNX图语法校验通过，但ORT Runtime在加载时直接崩溃。这个崩溃在shape_inference步骤就会被onnx.shape_inference.InferenceError捕获，从而在CI阶段就阻断了错误模型的发布。

注意：dummy_input的构造极其重要。它必须是模型实际能接受的最小合法输入。对于图像模型，我们用torch.randn(1, 3, 224, 224)；对于文本模型，我们用torch.randint(0, 1000, (1, 128))（128是最大序列长度）。这个dummy_input的shape，直接决定了ONNX模型的输入签名，后续所有服务端的输入校验都以此为依据。我们有一个专门的input_schema.json文件，与ONNX模型同目录存放，里面明确记录了input_shape: [1, 3, 224, 224]和input_dtype: "float32"，供服务端开发者查阅。

3.2 FastAPI服务骨架：不只是API，更是模型的“管家”

我们的main.py服务骨架，已经进化成一个高度定制化的模型管家。它不仅仅提供/predict，还内置了模型热重载、特征预处理管道、以及面向运维的深度诊断能力。以下是核心代码片段：

from fastapi import FastAPI, HTTPException, Depends, status from pydantic import BaseModel, conint, confloat, validator from typing import List, Dict, Any, Optional import numpy as np import onnxruntime as ort import logging import time from contextlib import contextmanager # 初始化日志 logging.basicConfig(level=logging.INFO) logger = logging.getLogger(__name__) # 全局ONNX Runtime Session，单例模式 ort_session = None class PredictionInput(BaseModel): """预测输入Schema，强校验""" user_id: conint(gt=0) # 必须是正整数 age: conint(ge=0, le=120) # 年龄范围校验 income: confloat(ge=0.0) # 收入非负 features: List[confloat()] # 特征向量，必须是浮点数列表 @validator('features') def features_length_must_be_128(cls, v): if len(v) != 128: raise ValueError('features length must be 128') return v class PredictionOutput(BaseModel): """预测输出Schema""" prediction: float confidence: float model_version: str app = FastAPI(title="ML Model Serving API", version="1.0.0") @app.on_event("startup") async def startup_event(): """应用启动时加载ONNX模型""" global ort_session try: # 加载ONNX模型，指定CPU provider ort_session = ort.InferenceSession( "models/resnet50_v1.onnx", providers=['CPUExecutionProvider'] ) logger.info("✅ ONNX模型加载成功") except Exception as e: logger.error(f"❌ ONNX模型加载失败: {e}") raise @app.on_event("shutdown") async def shutdown_event(): """应用关闭时清理资源""" global ort_session if ort_session is not None: ort_session = None logger.info("ONNX模型Session已释放") @app.get("/healthz") async def health_check(): """健康检查端点，检查模型是否可推理""" if ort_session is None: raise HTTPException(status_code=503, detail="Model not loaded") try: # 执行一次轻量级推理 dummy_input = np.random.randn(1, 3, 224, 224).astype(np.float32) ort_inputs = {ort_session.get_inputs()[0].name: dummy_input} _ = ort_session.run(None, ort_inputs) return {"status": "ok", "model": "resnet50_v1"} except Exception as e: logger.error(f"Health check failed: {e}") raise HTTPException(status_code=503, detail=f"Model inference failed: {e}") @app.post("/predict", response_model=PredictionOutput) async def predict(input_data: PredictionInput): """主预测端点""" start_time = time.time() try: # 1. 特征预处理（这里可以加入归一化、编码等逻辑） # 例如：将输入的features list转为numpy array，并reshape input_array = np.array(input_data.features, dtype=np.float32).reshape(1, -1) # 2. 执行ONNX推理 ort_inputs = {ort_session.get_inputs()[0].name: input_array} ort_outputs = ort_session.run(None, ort_inputs) # 3. 解析输出（假设输出是[batch, 2]的logits） logits = ort_outputs[0][0] # 取第一个样本的输出 probs = np.exp(logits) / np.sum(np.exp(logits)) # softmax prediction = int(np.argmax(probs)) confidence = float(np.max(probs)) # 4. 构建响应 response = PredictionOutput( prediction=prediction, confidence=confidence, model_version="resnet50_v1" ) # 5. 记录耗时（用于监控） latency_ms = (time.time() - start_time) * 1000 logger.info(f"Predict success | user_id={input_data.user_id} | latency={latency_ms:.2f}ms") return response except ValueError as ve: # Pydantic校验失败，返回422 raise HTTPException(status_code=422, detail=str(ve)) except Exception as e: # 其他所有异常，记录详细日志，返回500 logger.error(f"Predict error | user_id={input_data.user_id} | error={str(e)} | traceback={e.__traceback__}") raise HTTPException(status_code=500, detail="Internal server error") # 新增：深度诊断端点，仅限内部使用 @app.get("/diagnose/model_info") async def get_model_info(): """获取模型元信息，用于调试""" if ort_session is None: raise HTTPException(status_code=503, detail="Model not loaded") inputs = ort_session.get_inputs() outputs = ort_session.get_outputs() return { "input_names": [inp.name for inp in inputs], "input_shapes": [inp.shape for inp in inputs], "output_names": [out.name for out in outputs], "output_shapes": [out.shape for out in outputs], "providers": ort_session.get_providers() }

这个骨架的亮点在于可观察性。/diagnose/model_info端点是运维人员的救命稻草。当线上出现“预测结果全为0”的诡异问题时，他们不需要登录服务器去翻代码，只需要curl一下这个端点，就能立刻看到ONNX模型的输入输出shape是否与预期一致，从而快速锁定是数据管道问题还是模型本身问题。我们还为/predict添加了详细的结构化日志，每条日志都包含user_id和latency，这使得在ELK日志系统中，可以轻松地按用户ID追踪某次失败请求的完整链路，或者绘制出延迟随时间变化的热力图。

3.3 Dockerfile与K8s部署：让服务像乐高一样可组合、可替换

我们的Dockerfile遵循“多阶段构建”和“最小化”原则，是经过数十次生产环境迭代打磨出的稳定版本：

# 构建阶段 FROM python:3.9-slim-bullseye AS builder # 安装构建依赖 RUN apt-get update && apt-get install -y \ build-essential \ && rm -rf /var/lib/apt/lists/* # 复制requirements.txt并安装构建时依赖 COPY requirements-build.txt . RUN pip install --no-cache-dir -r requirements-build.txt # 复制源码 COPY . /app WORKDIR /app # 运行阶段 FROM python:3.9-slim-bullseye # 创建非root用户，提升安全性 RUN addgroup -g 1001 -f appgroup && adduser -S appuser -u 1001 # 复制构建阶段安装的依赖和源码 COPY --from=builder /usr/local/lib/python3.9/site-packages /usr/local/lib/python3.9/site-packages COPY --from=builder /usr/local/bin /usr/local/bin COPY --from=builder /app /app # 复制ONNX模型文件（从CI/CD流水线生成） COPY models/resnet50_v1.onnx /app/models/resnet50_v1.onnx # 设置工作目录和用户 WORKDIR /app USER appuser # 暴露端口 EXPOSE 8000 # 启动命令 CMD ["uvicorn", "main:app", "--host", "0.0.0.0:8000", "--port", "8000", "--workers", "4", "--threads", "2", "--limit-concurrency", "100"]

对应的requirements-build.txt只包含构建时必需的包：

torch==1.12.1+cpu onnx==1.12.0 onnxruntime==1.12.0

而运行时的requirements.txt则极度精简：

fastapi==0.85.0 uvicorn[standard]==0.19.0 onnxruntime==1.12.0 pydantic==1.10.12

这个设计让最终镜像体积稳定在380MB左右，且完全不包含任何torch的编译工具链，极大降低了安全扫描的风险。

K8s的deployment.yaml则体现了我们对弹性和可观测性的极致追求：

apiVersion: apps/v1 kind: Deployment metadata: name: ml-model-serving spec: replicas: 3 selector: matchLabels: app: ml-model-serving template: metadata: labels: app: ml-model-serving spec: # 强制使用非root用户 securityContext: runAsNonRoot: true runAsUser: 1001 containers: - name: api-server image: your-registry/ml-model-serving:v1.0.0 ports: - containerPort: 8000 name: http # 资源限制，防止单个Pod吃光节点资源 resources: requests: memory: "512Mi" cpu: "500m" limits: memory: "1Gi" cpu: "1000m" # 健康检查 livenessProbe: httpGet: path: /healthz port: 8000 initialDelaySeconds: 30 periodSeconds: 10 timeoutSeconds: 5 failureThreshold: 3 readinessProbe: httpGet: path: /readyz port: 8000 initialDelaySeconds: 10 periodSeconds: 5 timeoutSeconds: 3 failureThreshold: 2 # 自定义指标，用于HPA env: - name: POD_NAME valueFrom: fieldRef: fieldPath: metadata.name # 服务网格Sidecar（如Istio） serviceAccountName: ml-model-serving-sa --- apiVersion: v1 kind: Service metadata: name: ml-model-serving spec: selector: app: ml-model-serving ports: - port: 80 targetPort: 8000 protocol: TCP type: ClusterIP --- # Horizontal Pod Autoscaler，基于CPU和自定义指标 apiVersion: autoscaling/v2 kind: HorizontalPodAutoscaler metadata: name: ml-model-serving-hpa spec: scaleTargetRef: apiVersion: apps/v1 kind: Deployment name: ml-model-serving minReplicas: 2 maxReplicas: 10 metrics: - type: Resource resource: name: cpu target: type: Utilization averageUtilization: 70 - type: Pods pods: metric: name: http_requests_total target: type: AverageValue averageValue: 200

这个YAML文件的关键点在于双重HPA：它既根据CPU利用率（70%）进行扩缩容，也根据http_requests_total这个自定义指标（平均每Pod每秒200个请求）进行扩缩容。后者更为精准，因为它直接反映了业务负载，而不是间接的CPU消耗。我们曾在一个视频分析服务上，因为模型推理本身是CPU密集型，但数据预处理（FFmpeg解码）是I/O密集型，导致CPU利用率一直很低，但服务却因I/O瓶颈而延迟飙升。引入基于http_requests_total的HPA后，系统能准确识别出这种“CPU不忙但请求堆积”的场景，及时扩容，将P99延迟从2.1秒稳定在800ms以内。

4. 常见问题与排查技巧实录：那些文档里不会写的血泪教训

4.1 “模型预测结果全是NaN”：一场深夜的溯源之旅

现象：上线后第二天，监控面板上model_prediction_error_rate曲线突然飙升至15%，日志里大量出现"Predict error | error=... NaN encountered in output"。

排查思路：这是一个典型的“数据漂移+模型脆弱性”双重问题。我们没有直接去看模型代码，而是按照“数据流”倒推：

1. 查日志：首先在/predict的日志中，筛选出报错的user_id，发现它们都集中在某个新上线的APP版本（v3.2.0）的用户。
2. 查数据：立刻拉取v3.2.0版本用户在过去1小时的原始特征数据，用pandas.describe()查看各列统计量。果然，screen_width_px和screen_height_px这两个特征，出现了大量-1值（APP SDK在获取屏幕尺寸失败时的默认占位符）。
3. 查模型：回到模型训练代码，发现特征工程Pipeline里，对-1的处理方式是fillna(0)，而0这个值，在归一化（MinMaxScaler）后，被映射到了一个极小的负数，最终在模型的某一层ReLU激活函数后，由于数值下溢，变成了-inf，再经过后续计算，最终输出NaN。

解决方案：这是一个经典的“缺失值处理不当”案例。我们立刻发布了热修复：

• 在FastAPI的PredictionInputSchema中，为screen_width_px和screen_height_px添加了conint(gt=0)校验，直接拦截-1。
• 在特征预处理Pipeline中，将-1视为真正的缺失值，改用median()填充，而非0。
• 同时，我们在ONNX模型的输出后，增加了一行防御性代码：if np.isnan(prediction).any(): raise ValueError("NaN detected in model output")，确保任何NaN都能被及时捕获并上报。

实操心得：永远不要相信上游数据。在生产环境中，-1、999、"NULL"、空字符串，都是常见的“伪缺失值”。最好的防御，是在数据进入模型前的最外层（API Schema）就将其拒之门外。我们后来建立了一个“伪缺失值词典”，收录了所有业务方历史上用过的各种占位符，并在CI/CD流水线中，对每个新模型的训练数据做一次扫描，如果发现词典中的值占比超过0.1%，就自动阻断发布。

4.2 “P99延迟从100ms飙升到2500ms”：一次被忽略的锁竞争

现象：服务平稳运行一周后，某天下午3点，http_request_duration_seconds_bucket的P99延迟曲线毫无征兆地从100ms垂直拉升至2500ms，并持续了15分钟，期间QPS下降了40%。

排查思路：延迟飙升，第一反应是CPU或内存瓶颈。但我们检查了Prometheus的container_cpu_usage_seconds_total和container_memory_working_set_bytes，发现它们都平稳如初。这说明问题不在基础设施层，而在应用层内部。

我们立刻登录到一台Pod，用py-spy record -p <pid> -o profile.svg生成火焰图。打开SVG后，一个意料之外的函数占据了90%的采样时间：threading.Lock.acquire。这指向了严重的锁竞争。

根因定位：我们回顾了main.py的代码，发现为了实现模型热重载（/reload_model端点），我们在全局加了一个threading.RLock()，并在/predict函数入口处acquire()，出口处release()。这个设计在低并发下毫无问题，但当QPS从200瞬间涨到800时，所有请求都在争抢同一个锁，形成了“锁队列”，导致大量请求在等待锁时被阻塞，P99延迟自然飙升。

解决方案：我们彻底重构了热重载机制，放弃了全局锁，改为无锁的原子指针替换：

import threading from typing import Optional # 全局模型引用，使用threading.local保证线程安全 _local = threading.local() def get_current_model(): """线程局部获取当前模型""" if not hasattr(_local, 'model'): _local.model = ort_session # 初始化为全局session return _local.model @app.post("/reload_model") async def reload_model(): """热重载模型，无锁""" global ort_session # 在后台线程中加载新模型 new_session = ort.InferenceSession("models/new_model.onnx") # 原子性地替换全局引用 ort_session = new_session # 清理旧模型（可选） # old_session = ...