机器学习模型服务化：从Notebook到生产环境的完整路径

1. 项目概述：当模型走出Jupyter，真正开始呼吸真实世界空气

“From Notebook to Production: Running ML in the Real World (Part 4)”——这个标题本身就像一句暗号，懂的人一眼就明白：这不是又一篇讲如何调参、画ROC曲线或者堆Transformer层数的文章。它直指机器学习从业者职业生涯里最陡峭、也最容易被忽视的那道坎：从本地笔记本里跑通的、带点学术光泽的模型，到每天凌晨三点还在服务器上稳稳扛住订单峰值、自动重试失败请求、把预测结果写进数据库并触发下游通知的生产系统。我干这行十多年，亲手把上百个模型送进生产环境，见过太多团队在Part 1（数据清洗）和Part 2（模型训练）里意气风发，结果卡在Part 4，卡得无声无息——不是模型不准，是它根本没机会准；不是代码有bug，是整个运行时环境像一锅没搅匀的粥，热一阵冷一阵，日志里全是“Connection refused”和“OOM Killed”。

这个“Part 4”，说白了就是模型服务化（Model Serving）与生产运维（MLOps）的临界点。它不涉及新算法，但要求你同时理解Python、Docker、Kubernetes、HTTP协议、数据库事务、监控告警、甚至公司内部的CI/CD流水线规范。它考验的不是你能不能写出model.predict(X)，而是你能不能回答：“如果这个预测接口每秒被调用5000次，其中3%的请求因网络抖动超时，系统会怎么降级？失败的请求数据是否丢失？重试会不会导致下游重复扣款？”——这些问题的答案，不在scikit-learn文档里，而在你部署时选的gRPC参数、写的健康检查脚本、配置的Prometheus指标采集点里。

所以这篇内容，核心关键词就是：模型服务化、生产就绪（Production-Ready）、API封装、容器化部署、可观测性、容错设计。它适合三类人：一是刚从Kaggle或课程项目毕业、正为第一份ML工程师岗位面试发愁的同学，你需要知道面试官问“你怎么部署模型”时，期待的不是Flask一行代码，而是你对整个链路的理解；二是已经能跑通模型、但团队总抱怨“模型上线太慢”的数据科学家，你需要掌握让业务方能自助调用、自助监控的交付能力；三是负责搭建MLOps平台的架构师，你需要看清每个组件的取舍逻辑，而不是盲目堆砌Seldon、KServe或Triton。它不承诺让你一夜成为DevOps专家，但它会给你一张足够清晰的地图，标出哪条路坑多、哪座桥承重有限、哪个路口必须设监控探针——因为真实世界的ML，从来不是关于“能不能跑”，而是关于“能不能一直稳稳地跑”。

2. 整体设计思路：为什么不能直接用flask run？

2.1 从“能跑”到“能扛”的本质跃迁

很多初学者的第一反应是：“我的模型在Notebook里predict得飞快，导出成pkl文件，再用Flask写个简单API，python app.py启动，不就完事了？”——这确实是“能跑”，但离“能扛”差了至少五个数量级。我拿自己踩过的一个典型坑来说明：去年给一家电商做实时推荐，模型本身是轻量级的LightGBM，特征工程也做了充分缓存。开发环境用Flask单进程跑，QPS轻松破200，大家一片叫好。上线后第一周平稳，第二周大促流量翻倍，第三天凌晨监控报警：API平均延迟从80ms飙升到2.3秒，错误率17%。登录服务器一看，top命令里Python进程CPU占满，内存使用率98%，dmesg日志里赫然写着Out of memory: Kill process 12345 (python) score 894 or sacrifice child。问题根源？Flask默认的Werkzeug开发服务器是单线程、单进程的，它压根不是为并发设计的。它像一辆精心调校的赛车，赛道上能飙出300km/h，但你把它开上早高峰的北京三环，还指望它不熄火、不爆胎、不被加塞——这不现实。

所以Part 4的设计起点，必须是明确区分开发态与生产态。开发态追求快速验证、灵活调试；生产态追求资源可控、故障隔离、弹性伸缩。这意味着我们绝不能把开发工具直接搬上生产服务器。这个认知偏差，是90%以上模型上线失败的底层原因。

2.2 方案选型的三维权衡：性能、可维护性、生态兼容性

面对“怎么部署”，业界方案五花八门：从最轻量的FastAPI + Uvicorn，到专为ML设计的Triton Inference Server，再到云厂商打包好的SageMaker Endpoints。选哪个？没有银弹，只有权衡。我总结出三个硬性维度，必须逐项打分：

• 性能维度：核心看吞吐（QPS）和延迟（P95/P99）。比如Triton对GPU推理有深度优化，支持动态批处理（Dynamic Batching），能把100个零散小请求合并成一个大batch喂给GPU，吞吐提升3-5倍；而纯CPU服务，Uvicorn的异步IO模型比Gunicorn的多进程模型在高并发下更省内存。但性能不是唯一，我见过团队为追求极致QPS，强行上Triton，结果发现模型是纯CPU计算的XGBoost，Triton的GPU调度层反而成了累赘，延迟不降反升。

• 可维护性维度：指日常运维的复杂度。一个方案如果需要你手动管理Docker镜像版本、编写复杂的K8s YAML、配置Service Mesh的路由规则，那它的可维护性就低。FastAPI+Uvicorn组合的优势就在这里：它用标准Python语法定义API，用Pydantic做输入校验，用OpenAPI自动生成文档，所有逻辑都在.py文件里，一个熟悉Python的工程师半小时就能上手修改。而Triton虽然性能强，但配置文件是YAML+protobuf混合体，模型版本管理要靠独立的模型仓库，学习曲线陡峭。

• 生态兼容性维度：看它能否无缝融入现有技术栈。如果你的公司已全面拥抱Kubernetes，那KServe（原KFServing）就是天然选择，它把模型服务抽象成K8s CRD（Custom Resource Definition），用kubectl apply -f model.yaml就能部署，运维同学完全不用学新东西。但如果你的基础设施还是传统VM+Ansible，硬上KServe就等于给自己挖坑。同样，如果你的模型训练用的是PyTorch Lightning，它原生支持导出为TorchScript，那Triton对TorchScript的完美支持就是加分项；反之，如果你的模型是用TensorFlow SavedModel格式，那TF Serving就是更稳妥的选择。

最终，我给大多数中等规模、技术栈偏Python的团队的建议是：FastAPI + Uvicorn + Docker + Nginx（反向代理）作为基线方案。它不是性能天花板，但它是“性价比天花板”——80%的场景下，它能用20%的复杂度解决80%的问题。后续再根据业务增长，平滑升级到K8s集群或引入Triton。这个渐进式演进路径，比一开始就想建“航空母舰”，结果连“舢板”都划不利索，要务实得多。

2.3 架构图景：一个生产就绪服务的最小必要组件

一个真正能进生产的ML服务，绝不是一个孤零零的API进程。它是一个有“感官”、有“神经”、有“肌肉记忆”的小生命体。我把它拆解为四个最小必要组件，缺一不可：

1. 服务核心（The Core）：即模型加载与预测逻辑本身。这里的关键不是“怎么写predict”，而是“怎么加载”。模型文件（.pkl, .pt, .h5）不能每次请求都重新加载，必须在服务启动时一次载入内存，并做好线程安全保护。我见过最惨的案例，是有人把joblib.load()写在API函数里，结果每来一个请求就磁盘IO一次，QPS直接掉到个位数。

2. 通信网关（The Gateway）：负责接收外部HTTP/gRPC请求，做初步过滤（如CORS、速率限制）、协议转换、负载均衡。Nginx是经典选择，轻量、稳定、文档全；Cloudflare或AWS ALB则是云上更省心的托管方案。它的存在，让服务核心可以专注预测，不用操心网络细节。

3. 可观测性中枢（The Observatory）：这是区分“玩具”和“生产系统”的分水岭。它必须包含三要素：日志（Logging）——记录每个请求的输入、输出、耗时、错误堆栈，用结构化JSON格式，方便ELK或Loki采集；指标（Metrics）——暴露http_requests_total,model_prediction_latency_seconds,process_memory_bytes等Prometheus标准指标，让运维能一眼看出瓶颈在哪；追踪（Tracing）——为每个请求生成唯一Trace ID，串联起API、特征服务、模型、数据库的所有调用，定位慢请求的“病灶”。没有这三者，你的服务就是个黑箱，出了问题只能靠猜。

4. 韧性护盾（The Resilience Shield）：应对真实世界的不确定性。包括：健康检查端点（/healthz）——让K8s或负载均衡器能准确判断服务是否存活；就绪检查端点（/readyz）——告诉调度器“我虽活着，但特征缓存还没加载完，别把流量切给我”；优雅关闭（Graceful Shutdown）——收到SIGTERM信号后，不再接受新请求，处理完队列中剩余请求再退出，避免请求半途而废；熔断与降级（Circuit Breaker & Fallback）——当下游数据库持续超时，自动切换到缓存数据或返回预设默认值，保证主流程不崩。

这四个组件，共同构成了一个“生产就绪”的最小闭环。任何试图绕过其中一环的方案，都是在给未来的凌晨三点埋雷。

3. 核心细节解析：从代码到容器的每一处关键决策

3.1 API设计：不只是/predict，更是契约与边界

很多人以为API设计就是定义一个URL和几个参数。错。在生产环境，API是一个严格的契约（Contract），它定义了服务提供方与调用方之间的责任边界。这个契约一旦发布，就不能轻易变更，否则就是对所有下游业务的违约。因此，设计之初就要想清楚三件事：输入是什么、输出是什么、失败时怎么办。

以一个用户画像评分API为例，我绝不会设计成这样：

@app.post("/predict") def predict(data: dict): # data长啥样？没人知道！ score = model.predict(data) return {"score": score}

这种设计，data是个万能字典，前端传什么后端就收什么，毫无约束。结果就是：前端某次迭代悄悄加了个"user_id_hash"字段，后端模型没用到，但日志里开始出现大量KeyError；或者后端模型升级，要求"age"必须是整数，但前端传的是字符串，服务直接500崩溃。

正确的做法，是用Pydantic模型强制约束输入输出：

from pydantic import BaseModel, Field from typing import Optional, List class UserFeatures(BaseModel): user_id: str = Field(..., description="用户唯一标识，长度32位") age: int = Field(..., ge=0, le=120, description="用户年龄，0-120整数") gender: str = Field(..., pattern="^(male|female|other)$", description="性别，枚举值") last_7d_order_count: int = Field(default=0, ge=0, description="近7天订单数") class PredictionResponse(BaseModel): score: float = Field(..., ge=0.0, le=1.0, description="预测得分，0-1分") confidence: float = Field(..., ge=0.0, le=1.0, description="置信度，0-1分") version: str = Field(..., description="模型版本号，如'v2.1.0'") @app.post("/v1/score", response_model=PredictionResponse) def predict_user_score(features: UserFeatures): try: # 特征工程逻辑... score, conf = model.predict([features.dict()]) return PredictionResponse( score=float(score), confidence=float(conf), version="v2.1.0" ) except ValueError as e: raise HTTPException(status_code=400, detail=f"输入数据校验失败: {str(e)}") except Exception as e: # 记录详细错误日志 logger.error(f"模型预测异常: {traceback.format_exc()}") raise HTTPException(status_code=500, detail="内部服务错误，请稍后重试")

这个设计里，每一个Field都是契约的一部分：

• ...表示必填，default=0表示可选；
• ge=0, le=120是数值范围，pattern是字符串格式，description是给调用方的文档；
• response_model确保返回值也严格符合约定，连类型、范围、描述都锁死；
• HTTPException明确划分了客户端错误（400）和服务器错误（500），让调用方能精准重试或告警。

提示：API版本号（/v1/score）必须显式体现在URL里。不要用Accept: application/json; version=1这种Header方式，因为Nginx、CDN、浏览器缓存都可能忽略它，导致版本混乱。URL版本是最简单、最可靠、最符合REST规范的方式。

3.2 模型加载：一次加载，终生服务，但要防“内存泄漏”

模型加载看似简单，实则暗藏玄机。核心原则就一条：在服务进程启动时完成加载，且只加载一次。但“一次”不等于“永远不动”。我遇到过最棘手的问题，是模型对象在Python里被意外引用，导致无法被垃圾回收，内存越积越多，几天后服务OOM。

典型场景：模型加载后，你为了调试方便，把整个model对象赋值给了一个全局变量，然后在某个中间件里，你又把这个全局变量塞进了request.state（FastAPI的请求上下文），结果每个请求都持有一个对模型的引用。Python的GC对循环引用不敏感，模型权重数组就这样被“钉”在内存里，永不释放。

正确姿势是：将模型加载逻辑封装在单例类中，并确保其生命周期与应用进程完全绑定。

import joblib from pathlib import Path from typing import Optional class ModelSingleton: _instance: Optional['ModelSingleton'] = None _model = None _feature_processor = None def __new__(cls): if cls._instance is None: cls._instance = super().__new__(cls) return cls._instance def load(self, model_path: str, processor_path: str): if self._model is not None: return # 已加载，直接返回 # 使用Path确保路径安全 model_file = Path(model_path) processor_file = Path(processor_path) if not model_file.exists(): raise FileNotFoundError(f"模型文件不存在: {model_file}") self._model = joblib.load(model_file) self._feature_processor = joblib.load(processor_file) # 关键：显式删除对大对象的引用，防止意外持有 del model_file, processor_file @property def model(self): if self._model is None: raise RuntimeError("模型未加载，请先调用load()") return self._model @property def feature_processor(self): if self._feature_processor is None: raise RuntimeError("特征处理器未加载，请先调用load()") return self._feature_processor # 在应用启动时加载 model_manager = ModelSingleton() model_manager.load( model_path="/app/models/ranking_v2.1.0.pkl", processor_path="/app/models/processor_v2.1.0.pkl" )

这个单例模式，配合@property的懒加载访问，既保证了“一次加载”，又通过del语句主动切断了不必要的文件路径引用。更重要的是，它把模型加载的“时机”和“位置”从零散的代码里抽离出来，集中到一个可测试、可监控的入口点。你可以轻松添加日志：“INFO: Model loaded successfully, size: 124MB”，也可以在load方法里加入SHA256校验，确保模型文件没被篡改。

3.3 容器化构建：Dockerfile不是魔法，是精确的配方

Dockerfile不是把代码扔进镜像就完事。它是一份精确到字节的构建配方，决定了你的服务在任何机器上运行时的行为一致性。一个糟糕的Dockerfile，会导致“在我机器上好好的”这种经典悲剧。

下面是我经过上百次迭代、验证过的生产级Dockerfile模板，每一行都有其不可替代的理由：

# 基础镜像：选择slim版本，减少攻击面和体积 FROM python:3.9-slim-bookworm # 设置工作目录，避免在根目录操作 WORKDIR /app # 复制requirements.txt并安装依赖（分层缓存关键！） # 这样只要requirements不变，后续构建就复用这一层，极速 COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt && \ # 清理pip缓存，减小镜像体积 rm -rf /root/.cache/pip # 复制应用代码（此时才复制，避免因代码变更导致依赖层失效） COPY . . # 创建非root用户，提升安全性 RUN addgroup -g 1001 -f appgroup && \ adduser -S appuser -u 1001 # 切换到非root用户运行 USER appuser # 暴露端口（仅声明，不实际监听） EXPOSE 8000 # 启动命令：使用Uvicorn，指定workers数为CPU核心数*2+1，这是经验公式 # --reload只用于开发，生产必须去掉！ CMD ["uvicorn", "main:app", "--host", "0.0.0.0:8000", "--port", "8000", "--workers", "5"]

关键点解析：

• python:3.9-slim-bookworm：选择Debian Bookworm的slim版，比alpine更兼容Python C扩展（如numpy），比full版小一半，且Bookworm是当前稳定版，安全更新有保障。
• 分层COPY：先COPY requirements.txt再RUN pip install，是Docker缓存机制的核心。如果requirements.txt没变，pip install这层就直接复用，构建时间从几分钟降到几秒。
• --no-cache-dir：禁止pip创建缓存，否则缓存会打包进镜像，徒增体积。
• adduser -S：创建系统用户，-S表示创建为系统用户，UID固定为1001，便于K8s SecurityContext配置。
• USER appuser：强制以非root用户运行，这是生产环境铁律。root用户一旦被攻破，整个宿主机就沦陷。
• --workers 5：Uvicorn的worker数不是越多越好。太少（如1）无法利用多核；太多（如20）会导致进程间竞争CPU和内存。经验公式是2 * CPU核心数 + 1，对于4核机器就是9，但考虑到我们还要留内存给模型，保守设为5。这个数字必须通过压测确定，不能拍脑袋。

注意：绝对不要在Dockerfile里写RUN pip install pandas scikit-learn这种具体包名！所有依赖必须统一管理在requirements.txt里，用pip freeze > requirements.txt生成，并锁定版本（如pandas==1.5.3）。否则，不同时间构建的镜像，可能因为PyPI上包更新而行为不一致，这是生产事故的温床。

3.4 可观测性落地：日志、指标、追踪，一个都不能少

可观测性不是“加上去”的功能，而是“长出来”的能力。它必须从代码第一行就植入DNA。我见过太多团队，服务上线后才想起加监控，结果发现日志格式五花八门，指标暴露端点没开，追踪ID到处丢失——补救成本是前期设计的十倍。

日志（Logging）：必须结构化、标准化。我强制要求所有日志用structlog库，输出JSON：

import structlog import logging # 配置structlog，输出为JSON，包含timestamp, level, event, trace_id等 structlog.configure( processors=[ structlog.stdlib.filter_by_level, structlog.stdlib.add_logger_name, structlog.stdlib.add_log_level, structlog.stdlib.PositionalArgumentsFormatter(), structlog.processors.TimeStamper(fmt="iso"), structlog.processors.StackInfoRenderer(), structlog.processors.format_exc_info, structlog.processors.UnicodeDecoder(), structlog.processors.JSONRenderer() # 关键！输出JSON ], context_class=dict, logger_factory=structlog.stdlib.LoggerFactory(), wrapper_class=structlog.stdlib.BoundLogger, cache_logger_on_first_use=True, ) logger = structlog.get_logger() # 使用 logger.info("prediction_start", user_id="u123", model_version="v2.1.0") logger.error("prediction_failed", user_id="u123", error="timeout")

这样，每条日志都是标准JSON，Logstash或Fluentd能直接解析user_id、model_version、error字段，无需正则提取。

指标（Metrics）：用prometheus-client暴露标准指标：

from prometheus_client import Counter, Histogram, Gauge import time # 定义指标 REQUEST_COUNT = Counter('http_requests_total', 'Total HTTP Requests', ['method', 'endpoint', 'status']) PREDICTION_LATENCY = Histogram('model_prediction_latency_seconds', 'Model Prediction Latency') MODEL_MEMORY_USAGE = Gauge('model_memory_bytes', 'Model Memory Usage in Bytes') @app.middleware("http") async def metrics_middleware(request: Request, call_next): start_time = time.time() response = await call_next(request) # 记录请求计数 REQUEST_COUNT.labels( method=request.method, endpoint=request.url.path, status=response.status_code ).inc() # 记录延迟 PREDICTION_LATENCY.observe(time.time() - start_time) return response # 在模型预测函数里，记录内存使用 import psutil process = psutil.Process() MODEL_MEMORY_USAGE.set(process.memory_info().rss)

这些指标，配合Prometheus抓取和Grafana看板，就能实时看到“每分钟多少请求”、“P95延迟是多少”、“模型占了多少内存”，故障时一眼定位。

追踪（Tracing）：用opentelemetry注入Trace ID：

from opentelemetry import trace from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import BatchSpanProcessor from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter # 初始化Tracer provider = TracerProvider() processor = BatchSpanProcessor(OTLPSpanExporter(endpoint="http://jaeger:14268/api/traces")) provider.add_span_processor(processor) trace.set_tracer_provider(provider) tracer = trace.get_tracer(__name__) @app.post("/v1/score") def predict_user_score(features: UserFeatures): with tracer.start_as_current_span("predict_user_score") as span: span.set_attribute("user_id", features.user_id) span.set_attribute("model_version", "v2.1.0") try: # ...预测逻辑 span.set_attribute("score", score) except Exception as e: span.set_status(Status(StatusCode.ERROR)) span.record_exception(e) raise

这样，每个请求的Trace ID会自动注入HTTP Header（traceparent），并传递给下游服务（如特征服务、数据库），在Jaeger里就能看到完整的调用链路图。

实操心得：可观测性组件的初始化代码，必须放在应用启动的最早期，最好在main.py的顶层就执行。如果放在某个路由函数里，第一次请求才会初始化，那么前几次请求的指标和追踪就丢失了，这在压测时尤其致命。

4. 实操过程：从本地开发到K8s集群的完整流水线

4.1 本地开发与测试：用Docker Compose模拟生产环境

在本地，我们绝不直接python main.py启动。必须用Docker Compose，构建一个与生产环境尽可能一致的微型副本。这能提前暴露90%的环境差异问题。

一个典型的docker-compose.yml：

version: '3.8' services: api: build: . ports: - "8000:8000" environment: - LOG_LEVEL=INFO - MODEL_PATH=/app/models/ranking_v2.1.0.pkl volumes: - ./models:/app/models:ro # 只读挂载模型，防止误删 depends_on: - jaeger healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8000/healthz"] interval: 30s timeout: 10s retries: 3 jaeger: image: jaegertracing/all-in-one:1.45 ports: - "16686:16686" # Jaeger UI - "14268:14268" # OTLP endpoint

启动后，你可以：

• 访问http://localhost:16686查看Jaeger追踪；
• 用curl -X POST http://localhost:8000/v1/score -d '{"user_id":"u123","age":25}'测试API；
• 查看docker logs api确认日志是结构化JSON；
• 执行docker exec api curl http://localhost:8000/metrics验证指标端点。

最关键的是healthcheck：它模拟了K8s的Liveness Probe。如果/healthz返回非200，Compose会自动重启容器。这强迫你在代码里实现真正的健康检查逻辑，而不是写个空的return {"status": "ok"}。

4.2 CI/CD流水线：自动化构建、测试、部署

手工docker build和kubectl apply是生产环境的自杀行为。必须建立CI/CD流水线。我以GitHub Actions为例，展示一个精简但完备的流水线：

name: Deploy ML Model Service on: push: branches: [main] paths: - 'src/**' - 'Dockerfile' - 'requirements.txt' jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up Python uses: actions/setup-python@v4 with: python-version: '3.9' - name: Install dependencies run: | pip install -r requirements.txt pip install pytest pytest-cov - name: Run tests run: pytest tests/ --cov=src --cov-report=xml build-and-push: needs: test runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up Docker Buildx uses: docker/setup-buildx-action@v2 - name: Login to Container Registry uses: docker/login-action@v2 with: registry: ghcr.io username: ${{ secrets.GITHUB_ACTOR }} password: ${{ secrets.GITHUB_TOKEN }} - name: Build and push uses: docker/build-push-action@v4 with: context: . push: true tags: | ghcr.io/${{ github.repository_owner }}/ml-api:${{ github.sha }} ghcr.io/${{ github.repository_owner }}/ml-api:latest deploy-to-staging: needs: build-and-push runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Deploy to Staging K8s uses: appleboy/kubectl-action@v2.5.0 with: server: ${{ secrets.STAGING_K8S_SERVER }} token: ${{ secrets.STAGING_K8S_TOKEN }} namespace: ml-staging command: | kubectl set image deployment/ml-api api=ghcr.io/${{ github.repository_owner }}/ml-api:${{ github.sha }} --record kubectl rollout status deployment/ml-api

这个流水线分三步：

1. Test：拉代码、装依赖、跑单元测试和覆盖率。pytest必须覆盖核心预测逻辑、输入校验、错误处理。
2. Build-and-Push：用Docker Buildx构建镜像，并推送到GitHub Container Registry（GHCR）。关键点是tags：一个用sha精确标记，一个用latest方便开发，但生产部署必须用sha，确保可追溯。
3. Deploy-to-Staging：用kubectl set image滚动更新Staging环境的Deployment。--record会记录这次更新的命令，rollout status会等待新Pod就绪才结束，保证部署原子性。

注意：生产环境的部署，必须增加人工审批步骤（environment: production+environment-protection-rules），并且部署命令要改为kubectl set image ... --record，同时更新imagePullPolicy: Always，确保拉取最新镜像。

4.3 Kubernetes部署：YAML不是配置，是基础设施即代码

K8s的YAML文件，不是“配置”，而是基础设施即代码（IaC）。它必须像应用代码一样，经过Code Review、版本控制、自动化测试。

一个生产级的Deployment YAML：

apiVersion: apps/v1 kind: Deployment metadata: name: ml-api labels: app: ml-api spec: replicas: 3 # 至少3副本，保证高可用 selector: matchLabels: app: ml-api template: metadata: labels: app: ml-api annotations: # 注入OpenTelemetry自动插桩 instrumentation.opentelemetry.io/inject-python: "true" spec: serviceAccountName: ml-api-sa # 使用专用ServiceAccount securityContext: runAsNonRoot: true runAsUser: 1001 seccompProfile: type: RuntimeDefault containers: - name: api image: ghcr.io/your-org/ml-api:abc123 # 必须用sha，禁用latest imagePullPolicy: Always ports: - containerPort: 8000 name: http livenessProbe: httpGet: path: /healthz port: 8000 initialDelaySeconds: 60 # 给模型加载留足时间 periodSeconds: 30 readinessProbe: httpGet: path: /readyz port: 8000 initialDelaySeconds: 30 periodSeconds: 10 timeoutSeconds: 5 resources: requests: memory: "512Mi" cpu: "250m" limits: memory: "1Gi" # 内存限制必须大于模型大小 cpu: "500m" env: - name: LOG_LEVEL value: "INFO" - name: MODEL_PATH value: "/models/ranking_v2.1.0.pkl" volumeMounts: - name: models mountPath: /models readOnly: true volumes: - name: models persistentVolumeClaim: claimName: ml-models-pvc # 模型文件用PVC持久化，避免每次Pod重建都下载 --- apiVersion: v1 kind: Service metadata: name: ml-api spec: selector: app: ml-api ports: - port: 80 targetPort: 8000 type: ClusterIP # 内部服务，不暴露公网

关键点：

• replicas: 3：单点故障是生产大忌，3副本是底线。
• livenessProbe的initialDelaySeconds: 60：模型加载可能耗时，必须给足时间，否则K8s会误判为崩溃，反复重启。
• readinessProbe：/readyz端点必须检查模型是否加载完毕、特征缓存是否就绪，只有全部OK才把流量切过来。
• resources.limits.memory: "1Gi"：必须设置，且值要大于模型文件大小（如模型300MB，就设512Mi或1Gi），否则OOM Killer会杀死进程。
• persistentVolumeClaim：模型文件是只读的、静态的大文件，用PVC挂载，比把模型打包进镜像更灵活（模型更新不用重build镜像）。

4.4 监控与告警：让系统自己告诉你哪里疼

部署只是开始，监控才是日常。一个生产服务，必须有三层告警：

1. 基础设施层告警（K8s层面）：

   • kube_pod_container_status_restarts_total > 0：容器重启，说明程序崩溃。
   • container_memory_usage_bytes{container="api"} / container_spec_memory_limit_bytes{container="api"} > 0.9：内存使用超90%，即将OOM。
   • kube_deployment_status_replicas_available{deployment="ml-api"} != kube_deployment_status_replicas_desired{deployment="ml-api"}：副本数不匹配，扩容失败。

2. 应用层告警（服务自身）：

   • rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m]) > 0.05：5xx错误率超5%，严重。
   • histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m])) > 2：P95延迟超2秒，用户体验差。
   • model_prediction_latency_seconds_count{job="ml-api"} == 0：过去5分钟没收到任何预测请求，服务可能挂了。