02|把模型交给一个真实 HTTP 接口
作者:AI酋长Andy · 星觉科技 · 北京 · 微信号:AIPMAndy 版本:2026-11-13。教学模拟,只监听本机,不是线上生产服务。
要证明的能力
模型离开训练脚本后,要有明确的输入输出、可追溯产物、失败行为和可复现的检查。本案例把 01 的 JSON 模型放进标准库 HTTP 服务,发送真实请求并检查响应。适合 AI 工程 / MLE / 后端转 AI 工程的入门证据。
重点是工程判断,不是调用次数或“做了一个 API”这句话。模型质量仍受前一个案例的合成数据和小词表限制。
完整输入与接口契约
依赖的唯一模型文件:../01_ml_experiment/reports/model.json。必须先运行 01;服务启动时计算模型文件 SHA-256 的前 12 位,作为 model_id 返回,便于核对“运行的是哪份产物”。这不是数字签名或安全校验机制。
| 项目 | 约定 |
|---|---|
| 地址 | 127.0.0.1,默认端口 8008,仅本机可访问 |
| 健康检查 | GET /health |
| 预测 | POST /predict,Content-Type: application/json |
| 请求 | 恰好一个字段 texts,列表长度 1–16 |
| 单条文本 | 非空字符串,最多 1,000 个字符 |
| 请求体 | 1–16,384 字节,需 Content-Length |
| 不支持输入 | 数字、布尔值、未知字段、空白、无已知词的文本会被拒绝 |
| 返回 | 保持输入顺序;model_id、count、predictions |
known_token_count == 0 时拒绝整个批次,避免把纯先验预测伪装成正常结果。有已知词也不代表输入在训练分布内,仍可能误判。
最快运行与验收
Python 3.10+,无需安装任何包。在仓库根目录:
bashpython3 examples/01_ml_experiment/run.py
python3 examples/02_model_service/verify.py
验证器在系统分配的本机随机端口启动真实服务,发 HTTP 请求,完成后自动关闭。预期输出类似:
json{"project":"02_model_service","passed_checks":14,"benchmark":{"n":40,"p50_ms":0.714,"p95_ms":0.938}}
passed_checks 应为 14,延迟会随机器和负载变化,示例数值不能当验收门槛。最新实测值与 40 次原始耗时见 reports/verification.json。
手动操作
终端一启动服务:
bashpython3 examples/02_model_service/service.py --port 8008
终端二发送请求(macOS/Linux 的 curl;Windows 可用 curl.exe):
bashcurl http://127.0.0.1:8008/health
curl -X POST http://127.0.0.1:8008/predict -H 'Content-Type: application/json' -d '{"texts":["reset my password","refund the payment","application crashes"]}'
三条预测标签应依次为 access、billing、technical。响应带未校准的类别分数,不能宣传为“83% 概率正确”。终端一按 Ctrl+C 退出。
如果系统没有 curl,可直接运行 verify.py,它已用 Python 的 HTTP 客户端完成同样的实际请求。
验收到底检查什么
14 项包括:健康检查、批次顺序、破损 JSON、空批次、非字符串、空白文本、未知字段、超过批次上限、文本过长、全词表外输入、错误媒体类型、请求体过大、未知路径,以及 4 个客户端线程发送 20 次请求。
| 情况 | 预期状态码 |
|---|---|
| 有效请求 | 200 |
| JSON 破损 | 400 |
| 路径不存在 | 404 |
| 请求体过大 | 413 |
| Content-Type 不支持 | 415 |
| JSON 结构或内容无效 | 422 |
实现另有缺失 Content-Length 返回 411、读取请求体超时返回 408 的分支;当前自动验收未覆盖这两个分支,不能写成“所有异常均测试通过”。3 秒读取超时也不是模型推理取消机制。
风险测试另外验证:数字/布尔值不能冒充文本、未知字段被拒绝、批次顺序不变、模型 JSON 往返序列化不改变预测。
如何测延迟,如何避免乱写性能
验证器先暖机 5 次,再发送 40 个串行请求,使用单调高精度计时器测端到端本地耗时,计算最近秩定义的 p50/p95,并记录所有原始样本。数字包含 Python 客户端、回环网络与服务处理开销。
这是“本机+小模型+极短输入+单进程+低负载”的测量。不能据此声称支持几千 QPS,也不能把串行吞吐数字推广到云端、互联网或大模型。4 线程 20 次请求检查的是一致性,不是负载极限。
错误排查
| 现象 | 原因与处理 |
|---|---|
model missing | 先运行 01;不要从未知来源拿 pickle 替代 JSON |
Address already in use | 手动服务换 --port 8009;自动验证使用随机端口 |
| 连接被拒绝 | 确认服务仍在运行、端口一致;验证器结束会关闭服务 |
422 no known tokens | 输入超出小英文词表,例如纯中文;此模型不适合该输入 |
| 环境禁止回环 socket | 记录具体权限错误;在允许本地网络的 Python 环境重跑,不记为通过 |
| 延迟与文档不同 | 属正常环境差异;先比较请求大小、机器、并发与暖机条件 |
实际限制与下一步
Python 官方 http.server 文档 明确不建议把该模块用于生产。本例没有 TLS、用户认证、限流、外部可观测平台、持久化队列、容器隔离或灾备。线程数也没有设上限,所以保持 localhost 绑定,不能直接放到公网。
下一步由目标 JD 决定:使用适合部署的服务框架,加入请求 ID 和结构化指标、模型版本切换、资源上限、过载行为、超时取消、权限控制与真实负载测试。每加入一项,就写一个可观察的验收,不堆工具名称。
简历与面试(教学模拟)
可写:“基于既有教学分类器实现本地批量 HTTP 推理接口;定义输入边界与错误码,完成 14 项真实 HTTP 验收,记录 40 次回环延迟及测试条件;个人新增【具体改动】。”
不能写:“上线高并发 AI 平台,支撑上万用户。”本例没有上线或用户证据。
准备回答:模型版本怎么追踪?部分批次错误为什么拒绝整批?同步 CPU 任务会怎样阻塞?p95 取哪种定义?并发20次通过为什么不能说明容量?读取超时与推理超时有何区别?公开部署前最先补哪两件事?
许可与归属
代码 MIT,基线由 AI 辅助新写并实际执行;模型输入来自本项目 CC0 合成数据。使用时列明上游出处、自己修改的代码/测试、AI 辅助部分与人工验收,不将已有实现写为个人原创商业系统。