# 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+，无需安装任何包。在仓库根目录：

```bash
python3 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`。

## 手动操作

终端一启动服务：

```bash
python3 examples/02_model_service/service.py --port 8008
```

终端二发送请求（macOS/Linux 的 curl；Windows 可用 `curl.exe`）：

```bash
curl 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 文档](https://docs.python.org/3/library/http.server.html) 明确不建议把该模块用于生产。本例没有 TLS、用户认证、限流、外部可观测平台、持久化队列、容器隔离或灾备。线程数也没有设上限，所以保持 localhost 绑定，不能直接放到公网。

下一步由目标 JD 决定：使用适合部署的服务框架，加入请求 ID 和结构化指标、模型版本切换、资源上限、过载行为、超时取消、权限控制与真实负载测试。每加入一项，就写一个可观察的验收，不堆工具名称。

## 简历与面试（教学模拟）

可写：“基于既有教学分类器实现本地批量 HTTP 推理接口；定义输入边界与错误码，完成 14 项真实 HTTP 验收，记录 40 次回环延迟及测试条件；个人新增【具体改动】。”

不能写：“上线高并发 AI 平台，支撑上万用户。”本例没有上线或用户证据。

准备回答：模型版本怎么追踪？部分批次错误为什么拒绝整批？同步 CPU 任务会怎样阻塞？p95 取哪种定义？并发20次通过为什么不能说明容量？读取超时与推理超时有何区别？公开部署前最先补哪两件事？

## 许可与归属

代码 MIT，基线由 AI 辅助新写并实际执行；模型输入来自本项目 CC0 合成数据。使用时列明上游出处、自己修改的代码/测试、AI 辅助部分与人工验收，不将已有实现写为个人原创商业系统。
