实验八：模型部署与接口开发

实验目的：

- 掌握将机器学习预测模型封装为可访问的服务接口的方法，学习使用Web框架（如Flask或FastAPI）部署模型为RESTful API服务。理解接口设计的要点，包括请求方法、输入输出格式(JSON)、状态返回等，能够为模型功能提供标准化的对外接口。

- 了解基本的部署流程和要点：如在服务器环境运行服务、前后端分离调用、接口文档编写等[13]。培养学生将模型推向实际应用的工程能力，以及团队协作意识（接口是团队分工的契合点，需要清晰定义）。

- 在部署测试中考察接口的正确性与性能。通过对API发送请求获取响应，验证预测结果一致性和响应延迟，确保服务达到可用标准。

- 综合运用所学，实现从模型训练到上线服务的完整闭环。强调研究到应用的落地，使学生体验将科研成果转化为实际产品原型的全过程。

实验资源要求：

- 数据： 用于接口测试的输入（与实验七相同或类似），以及相应真实值用于结果校验。测试工具如Postman可用来构造HTTP请求数据。

- 软件环境： Python 3.x，Flask或FastAPI框架，搭建简单的Web服务。需要安装相关依赖库。浏览器或Postman用于发送HTTP请求测试。

- 计算环境： 一台可运行长期服务的计算机或服务器（可本地即可）。要求网络环境允许HTTP通信（本地可用localhost），确保服务启动后能够接受请求。

实验时长： 約3小时

实验内容： 最终实验将模型真正“上线”——通过开发Web接口，将乘员舱瞬态降温预测模型部署为可远程调用的服务。这是项目在软件层面的最后集成，使模型能够被前端UI或其它系统模块便捷访问。本实验具备很强的工程实践意义，将课堂所学算法与实际软件开发连接起来。

首先，选择Web框架并设计API规范。本项目规模较小且接口功能单一（提供温度预测），可使用轻量的Flask框架来实现REST接口。接口设计包括：URL路径（例如/predict）、HTTP方法（使用POST发送输入数据）、输入数据格式（采用JSON，包含必要的环境参数和可选的历史序列）、输出数据格式（JSON，返回预测温度序列或特定时刻温度）。需要考虑接口易用性和遵循RESTful风格：路径命名清晰，方法语义正确（预测操作用POST），输入输出字段命名规范、使用JSON结构。还应定义当请求不当时返回何种错误码和信息，以便前端了解情况。

图1 2xx 请求时延直方图

接下来，学生将在Flask框架下编写代码：

- 启动服务：创建Flask应用实例，编写路由/predict对应的处理函数。在该函数内获取客户端发送的JSON数据（Flask提供request.get_json()方法），并对其进行验证（检查必要字段是否存在、类型是否正确）。

- 调用预测模块： 利用实验七开发的CabinCoolingPredictor对象，将解析出的输入数据传入其predict方法，得到预测结果。注意此处CabinCoolingPredictor应该在Flask应用启动时就创建并加载模型至内存（避免每次请求重复加载）。可将其作为全局对象或应用属性，这样每次请求处理只需执行快速的推理。

- 返回响应： 将模型预测结果组织为JSON格式，如：{"predicted_temps": [列表], "unit": "degC"}，然后通过Flask的jsonify返回。确保HTTP响应状态码为200成功，并设置适当的响应头（如Content-Type: application/json）。

图2 逐请求时延时间线（含SLO=300ms参考线）

为了确保接口安全和稳定，函数中应对异常情况进行处理：如果predict过程中抛出错误（例如输入数据格式不对导致无法计算），捕获异常并返回HTTP 400错误，携带说明信息（如“Invalid input data”）。可以利用Flask的错误处理机制或手动try-except返回。

完成编码后，运行Flask应用（开发阶段可直接用app.run()本地启动）。接下来使用Postman或curl命令对接口进行功能测试：

- 发送一个正确格式的请求，包含合理的数据（可以是与实验七相同的JSON输入）。检查返回是否成功，状态码是否200，内容是否为预测温度数组JSON，并与直接调用CabinCoolingPredictor的结果一致。

- 尝试发送错误格式请求，如缺少字段或类型错误，观察是否返回了自定义的错误信息和400状态。

- 在命令行观察Flask日志，确认每次请求模型都在预期时间内返回，没有报错信息。

一旦功能正确，进一步测试性能：可以编写一个简单脚本循环调用该HTTP接口100次，测量总时间计算平均每次响应时间。如果有并发需求，可用工具模拟并发请求，评估吞吐量。但本课程实验以演示为主，不必深度压测。一般来说，只要模型推理本身足够快，在Flask这层的开销是微小的，预计响应在几十毫秒到几百毫秒量级，可满足实时要求。若发现性能瓶颈，可以考虑部署时采用更高级的WSGI服务器（如Gunicorn）并发处理请求，甚至启用多线程/进程。但这些超出本实验范围，可在报告中提及。

图3 负载相关性：Payload 字节数 vs 时延散点

最后，让学生编写简单的前端调用示例（可选）：例如一个HTML页面，用JavaScript发送Ajax请求到该/predict接口并将返回结果可视化（这部分如时间有限可只做概念说明）。根据项目合同要求，实际系统会由甲方开发UI界面，乙方提供接口。学生可在报告中描述接口如何供前端使用，如前端通过HTTP库（Axios等）请求预测并将曲线绘制，这与项目要求保持一致。

至此，模型预测服务已成功部署在模拟的云端环境，可以通过标准接口获取预测结果。这标志着完整的乘员舱瞬态降温预测软件功能闭环打通——从数据到模型，从模型到服务接口。学生通过实验八不仅巩固了模型部署技能，也真正体会了科研成果在工程上的落地过程，为今后独立承担类似任务奠定了基础。

实验步骤：

1. 设计API接口规范

目标： 在实现前冻结接口契约（URL、方法、载荷、错误模型、版本策略、幂等性与速率限制），确保前后端/第三方一致协作。

设计要点

  • 版本策略与路径：采用前缀版本 /api/v1/predict（预留 /v2 扩展）；所有 breaking change 升主版本；兼容扩展以字段可选+默认值实现。

  • 方法与语义：POST /api/v1/predict 用于推理；另定义

    • GET /api/v1/healthz（存活）、GET /api/v1/readyz（依赖加载就绪）；

    • GET /api/v1/schema（返回 JSON Schema / OpenAPI 片段，便于前端校验与 Mock）。

  • 输入 JSON（建议 Schema，字段单位/范围/形状明确）：

{
"meta": {
"request_id": "uuid",
"ts": "ISO8601Z",
"sampling_hz": 1,
"window_seconds": 60
},
"features": {
"ext_temp": [34.8, ...], // °C, 长度=window_seconds*sampling_hz
"sunlight": [0..1200], // W/m²或归一化，无负值
"speed": [km/h, ≥0],
"vent_temps": [[...],[...],...], // 每个出风口一条序列；或简化为加权平均
"vent_speeds": [[...],[...],...],
"init_cabin_temp": 45.0 // °C，亦可冗余为序列首值
}
}

  • 一致性约束：所有时序字段长度一致；时间单调不减；数值域校验（如温度[−40, 80]）。

  • 允许的最小输入：若仅提供聚合风量与风温，明确计算规则（如加权平均/最大/中位）。

  • 输出 JSON（含诊断与可追踪字段）：

{
"predicted_curve": [28.0, ...], // °C，未来 H 个步长
"horizon_seconds": 30,
"time_step": 1,
"unit": "degC",
"diagnostics": {
"latency_ms": 142,
"device": "cpu",
"alerts": [], // 截断/修复/越界等告警
"model_semver": "1.3.0",
"data_semver": "2025.07",
"fusion": {"type": "alpha", "value": 0.52}
}
}

  • 错误模型（统一错误体 + 可机读错误码）：

  • { "error": { "code":"E1001_FEATURE_MISSING", "message":"'ext_temp' missing", "hint":"see schema at /schema" } }

    • 400（校验失败/越界）、429（限流）、415（媒体类型错误）、500（内部错误）等。

  • 安全与速率限制（实验态即可声明，不必全部实现）：

    • 仅内网访问；CSRF 不适用；CORS 限定来源；

    • 临时 Token 或调用白名单；

    • X-Request-ID 透传，便于端到端追踪。

Gate（验收门槛）：JSON Schema/ OpenAPI 片段通过校验；示例请求/响应可被 ajv/pydantic 成功验证；错误码/HTTP 状态一一对应。 Artifacts：openapi.yaml、request.schema.json、response.schema.json、error.schema.json、api_contract.md。

2. 实现Flask服务

目标： 在 Flask 下实现契约遵循、高内聚低耦合的路由与请求生命周期；CabinCoolingPredictor 常驻内存。

实现要点

  • 应用结构：

app/
__init__.py # create_app() 工厂 + 注册蓝图/限流/日志中间件
routes.py # /predict /healthz /readyz /schema
predictor.py # CabinCoolingPredictor 封装（来自实验七）
validators.py # 输入校验（pydantic/marshmallow）
errors.py # 全局异常钩子 -> 统一错误体
config.py # env/config 读取（端口、日志级别、限流阈值）

  • 创建全局预测器（一次加载）：在 create_app() 中实例化 CabinCoolingPredictor 并挂到 app.state；设 model.eval()，禁止梯度；预热一次空推理做就绪检测。

  • 输入校验与类型转换：

    • Content-Type 必须为 application/json；

    • 使用 pydantic/marshmallow 将 features 转为 np.ndarray 并校验维度/范围；

    • 对末端短缺失应用插值修复并记录告警。

  • 异常与日志：

    • 统一捕获到 @app.errorhandler，映射为上述错误模型；

    • 结构化日志（JSON 行），字段至少包含：ts, level, path, status, latency_ms, request_id, alerts, model_semver。

  • 伪代码（简化）：

@bp.route("/api/v1/predict", methods=["POST"])
def predict():
tic = time.time()
rid = request.headers.get("X-Request-ID", str(uuid4()))
try:
payload = request.get_json(force=True, silent=False)
data = RequestModel(**payload) # pydantic 校验
x = to_model_input(data) # 对齐形状 (1, T, F)
out = current_app.state.predictor.predict(x) # 常驻实例
resp = normalize_response(out, rid)
status = 200
except ValidationError as e:
resp, status = make_err("E1000_SCHEMA", str(e)), 400
except FeatureMissing as e:
resp, status = make_err("E1001_FEATURE_MISSING", str(e)), 400
except Exception as e:
resp, status = make_err("E9000_INTERNAL", "internal error"), 500
finally:
log_json(rid, path="/predict", status=status, latency_ms=ms(tic))
return jsonify(resp), status

Gate：冷启动<1s；首次请求 p95<350ms（本地开发态）；错误不抛裸栈到客户端；结构化日志包含 request_id。 Artifacts：app/ 源码、gunicorn.conf.py（先占位）、logs/example.jsonl、schema_dump.json。

3. 运行服务测试

目标： 完成功能联调与契约一致性回归：端到端结果与离线流水线严格对齐（给定容差）。

测试要点

  • 契约测试（contract test）：用 schemathesis/prance 从 openapi.yaml 生成正/负样例，自动验证 2xx/4xx/5xx 的结构与类型。

  • Golden 样本回放：选择离线评估用过的样本，构造请求体，核对：

    • 预处理对齐：输入张量统计（均值/方差）与离线一致±ε；

    • 推理输出与融合输出一致±ε（禁用随机性）；

    • 逆标准化/校准后最终曲线 MAE 与离线差值<1e−6（浮点容差）。

  • 可复现脚本：

curl -s -H "Content-Type: application/json" \
-H "X-Request-ID: 0001-golden" \
-d @tests/golden_request.json \
http://127.0.0.1:5000/api/v1/predict | jq '.' > out.json
python tests/compare_golden.py out.json tests/golden_response.json # 断言误差阈值

Gate：Golden 对齐通过；OpenAPI 驱动的 contract 测试 100% 通过；日志中无 ERROR。 Artifacts：tests/golden_request.json、tests/golden_response.json、test_contract_report.md、true_vs_pred_overlay.png（对齐可视化）。

4. 异常情况测试

目标： 验证鲁棒性与错误语义：所有非法请求都被明确拒绝并返回一致的错误体与可用提示。

测试矩阵（示例）

  • 缺字段：移除 ext_temp/vent_speeds；

  • 维度错配：sunlight 长度≠window_seconds*sampling_hz；

  • 类型错误：温度传字符串 "hot"；

  • 越界：负光照、温度<-40 或 >80；

  • 时间戳异常：乱序/重复（若模型不使用时间戳，可要求仍单调）。

  • 媒体类型：Content-Type: text/plain。

  • 速率限制：模拟频繁调用触发 429（若接入 Flask-Limiter）。

断言规范

  • 400/415/429/500 状态码正确；错误体含 {code, message, hint}；服务器不返回栈；日志包含 request_id 与 alerts。

  • 对“末端短缺失”这类可修复问题：返回 200，但 diagnostics.alerts 记录 “IMPUTE_TAIL_N=2”。

Gate：异常用例≥20项，覆盖率>95%；错误响应体结构一致性=100%；无非预期 500。 Artifacts：tests/negative_cases.jsonl、error_matrix.csv、sample_error_responses/*.json。

5. 性能测试

目标： 在本地/仿真环境评估端到端时延与吞吐，定位瓶颈并给出优化建议。

基线/压力策略

  • 单线程回环：requests 连续 50/100/1000 次；统计 p50/p95/p99；剔除冷启动；绘制时延直方图/CDF。

  • 并发试验（了解即可）：

    • 开发服务器为单线程，作为对比基线；

    • 可用 ab / wrk/hey 对 /predict 做 1、2、4、8、16 并发短压，观察退化曲线；

    • 若采用 Gunicorn（见第 8 步），采用 workers = 2*CPU+1 的经验法则（可先占位不实现）。

  • 阶段耗时拆解：在服务端记录 preprocess/infer/postprocess 的均值±标准差；抓取长尾请求（>p99）输入摘要以便排障。

  • 请求大小影响：改变 payload 规模（序列长度/通道数），测“载荷—时延”关系，评估前端是否需要压缩/裁剪。

SLO 建议（实验态）：本地 p95 < 300 ms、p99 < 500 ms；吞吐≥20 QPS（取决于预测窗口与特征数，仅作教学指标）。 优化路线（如需）：常驻加载、复用张量/缓冲区、批量多步预测、简化/蒸馏模型、WSGI/多进程并行、keep-alive、Nagle 关闭等。 Artifacts：perf_summary.json、latency_hist.png、latency_cdf.png、qps_vs_latency.png、stage_breakdown.csv、payload_vs_latency.png。

6. 接口文档完善

目标： 生成交付级文档，既能指导前端调用，又能支持运维与验收。

文档清单

  • API 概览：目的、版本策略、环境（dev/staging/prod）、Base URL、认证方式（实验阶段可空）。

  • 端点说明：/predict（POST）、/healthz、/readyz、/schema；每个包含请求/响应示例、字段释义、单位/范围、错误码与示例。

  • 契约附件：openapi.yaml、JSON Schema；字段变更历史（CHANGELOG）。

  • SLO & 限制：最大窗口长度、最大并发、节流策略、容错（末端插值）。

  • 安全与合规（实验态说明）：仅内网、记录脱敏日志、TTL 与日志留存策略；数据以 JSON 传输[13]。

  • 调用示例：curl、Python（requests）、JS（fetch/axios）。

  • FAQ/Runbook：常见错误与定位步骤、健康检查项、紧急回滚流程。

Gate：由未参与实现的同学依据文档独立发起 POST /predict 成功调用；所有示例通过 Schema 校验。 Artifacts：API_usage.md、openapi.yaml、examples/*.json、CHANGELOG.md、RUNBOOK.md。

7. 前端调用演示（可选）

目标： 以最小可用前端演示“人机交互闭环”。

实现要点

  • 静态页 + JS：

    • 一个 HTML 页（含输入参数表单/粘贴 JSON 区）；

    • fetch('/api/v1/predict') 发送 POST；

    • 用 Chart.js/ECharts 绘制 predicted_curve；

    • 处理 4xx/5xx 错误体，展示 error.code/message。

  • CORS/同源策略：若前端在不同端口，服务端需设置 CORS 白名单；仅允许 POST 与必要头。

  • 可用性：节流（防止重复点击）、加载态/错误提示、请求超时（如 2s）。

  • 可追踪：在请求头加入 X-Request-ID 并同步显示，便于与服务端日志对照。

Gate：样例数据可在浏览器中一键绘制预测曲线；错误提示可读；移动端视口下布局不崩。

Artifacts：demo/index.html、demo/script.js、demo/style.css、demo/demo_screenshot.png。

8. 部署注意事项

目标：形成可迁移、可维护、可回滚的上线方案（实验报告层面给出具体条目）。

部署要点

  • 运行时与依赖：固定 Python 版本；依赖锁定（poetry.lock/requirements.txt + 哈希）；禁用隐式升级。

  • 容器化（可选）：

    • 基础镜像（slim + 安全基线）；

    • multi-stage build 生成最小镜像；

    • 只读根文件系统、非 root 运行、最小权限。

  • 进程模型（WSGI）：

    • gunicorn app:create_app() -w 2*CPU+1 -k sync --timeout 30 --preload；

    • 健康检查 /healthz 与就绪 /readyz；

    • 反向代理（Nginx）启用 TLS（内网可自签），限速/限连接数。

  • 配置与密钥：12-factor：通过环境变量/挂载只读配置；密钥不入镜像。

  • 可观测性：

    • 指标（延迟/错误率/吞吐）导出到采集系统；

    • 结构化日志集中收集；

    • 告警阈值：错误率>1%、p95>目标阈值持续5min。

  • 弹性与扩缩：HPA 策略（CPU/延迟）；灰度发布/金丝雀；蓝绿切换。

  • SRE 基线：宕机自动拉起（systemd/容器编排）、无状态实例、滚动重启；备份 integration.yaml/权重/校准参数。

  • 安全：仅内网暴露；IP 白名单；最小化开放端口；请求体大小上限；基本鉴权（Token）与速率限制（429）。

  • 回滚策略：前一稳定镜像留存；一键回滚脚本；失败时自动降级到只读模式，保留日志。

Gate：部署清单齐全；预生产环境以 Gunicorn 跑通健康检查与契约测试；回滚演练通过。

Artifacts：Dockerfile、gunicorn.conf.py、deploy_checklist.md、k8s_manifests/*.yaml（可选）、rollback_playbook.md。

上一页实验七：模型系统集成与验证

最后更新于