model-deployment

用途

model-deployment 用于把训练好的机器学习模型部署到生产环境，并提供正确的服务方式与监控手段。它围绕 FastAPI、Docker 和 Kubernetes 展开，适用于服务预测、容器化、监控、漂移检测，或遇到延迟问题的场景。

主要能力

部署方式对照

文档给出四种部署方式的适用场景与延迟特征（REST API、Batch、Streaming、Edge），但未提供各方式的完整实现细节。

FastAPI 模型服务

提供基于 FastAPI 的模型服务代码：加载 joblib 模型，定义 PredictionRequest 与 PredictionResponse，并实现 /health 与 /predict 接口。

Docker 部署

提供 Dockerfile 示例（python:3.12-slim 基础镜像，复制 requirements.txt、model.pkl、app.py，暴露 8000 端口，使用 uvicorn 启动）。

模型监控

提供 ModelMonitor 类框架，用于记录预测输入、预测结果与时延，并声明 detect_drift 方法用于与参考分布比较（实现留空）。

部署检查清单

文档列出部署前需确认的事项：模型已在测试集验证、API 端点有文档、健康检查端点、认证配置、日志与监控配置、模型版本管理、回滚流程文档。

六步快速开始

文档给出快速部署步骤：保存模型（joblib.dump）、创建 FastAPI 应用、创建 Dockerfile、本地构建与测试、推送镜像到仓库、部署到 Kubernetes。

使用方式

FastAPI 服务示例

from fastapi import FastAPI
from pydantic import BaseModel
import joblib
import numpy as np

app = FastAPI()
model = joblib.load('model.pkl')

class PredictionRequest(BaseModel):
    features: list[float]

class PredictionResponse(BaseModel):
    prediction: float
    probability: float

@app.get('/health')
def health():
    return {'status': 'healthy'}

@app.post('/predict', response_model=PredictionResponse)
def predict(request: PredictionRequest):
    features = np.array(request.features).reshape(1, -1)
    prediction = model.predict(features)[0]
    probability = model.predict_proba(features)[0].max()
    return PredictionResponse(prediction=prediction, probability=probability)

Dockerfile 示例

FROM python:3.12-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY model.pkl .
COPY app.py .

EXPOSE 8000
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

六步部署命令

# 1. 保存训练模型
import joblib
joblib.dump(model, 'model.pkl')

# 2. 创建 FastAPI 应用（见 references/fastapi-production-server.md）
# app.py 包含 /predict 和 /health 端点

# 3. 创建 Dockerfile
cat > Dockerfile << 'EOF'
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app.py model.pkl ./
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]
EOF

# 4. 本地构建与测试
docker build -t model-api:v1.0.0 .
docker run -p 8000:8000 model-api:v1.0.0

# 5. 推送至镜像仓库
docker tag model-api:v1.0.0 registry.example.com/model-api:v1.0.0
docker push registry.example.com/model-api:v1.0.0

# 6. 部署到 Kubernetes
kubectl apply -f deployment.yaml
kubectl rollout status deployment/model-api

已知问题与预防

文档列出八类常见问题及解决方案：

缺少健康检查导致停机：实现 liveness 与 readiness 探针（/health 与 /ready），并在 deployment.yaml 配置 livenessProbe 和 readinessProbe。
容器中找不到模型文件：确保 Dockerfile 正确复制模型文件且路径一致，可用 ENV MODEL_PATH 与 os.getenv 统一路径。
未处理输入校验导致 500 错误：使用 Pydantic 的 Field 与 validator 做自动校验，FastAPI 对非法请求返回 422。
无漂移监控导致静默退化：实现漂移检测并在应重训时通过 alert_manager 发送告警。
缺少资源限制导致 OOM Kill：设置 requests 与 limits（内存、CPU），并用 kubectl top pods 监控实际用量。
无回滚方案导致卡在错误部署：用版本标签部署，出现问题时用 kubectl rollout undo 或指定先前版本回滚。
同步预测导致批处理缓慢：实现 /predict/batch 端点，使用向量化一次性处理。
无 CI/CD 校验导致部署坏模型：在 CI 流水线中执行模型验证脚本（如 --min-accuracy 0.85 低于阈值则失败）。

适用场景

适用于需要将机器学习模型以 REST API 方式提供服务、进行容器化打包、部署到 Kubernetes、并希望加入监控与漂移检测的工程场景；也适用于排查部署中的延迟问题、容器启动失败、资源不足、回滚困难等问题。

限制

文档未提供具体收费、价格、平台限制或效果承诺信息，暂未提供。部分能力（如 detect_drift 的具体实现、各部署方式的完整实现）在文档中仅为框架或指向参考文件，未展开完整代码。