AI 服务的 HTTP API 契约

AI 功能首先是一个网络服务。稳定的请求契约比 Prompt 技巧更早决定系统能否维护。

必须掌握

• 用输入模型限制长度、枚举、格式与可空字段。
• 使用 4xx 表示调用方问题，5xx 表示服务故障；不要把所有失败包装成 200。
• 为每次请求生成 request_id，并贯穿日志、模型调用和工具调用。
• 设置连接、读取和总耗时上限；取消请求时停止下游任务。
• 写操作带幂等键，流式输出使用 SSE 或明确的分块协议。

最小练习

建立 POST /questions：先返回固定结果，再替换成模型服务。覆盖空输入、超长输入、上游超时、限流和重复幂等键五条测试。路由只负责协议，业务逻辑进入 service 层。

验收清单

项目	合格标准
契约	OpenAPI 能表达所有字段和错误
超时	上游卡住时请求能在预算内结束
日志	可用 request_id 找到完整链路
安全	密钥不进入响应和仓库

官方资料

FastAPI Tutorial 覆盖输入模型、依赖、安全、错误处理、SSE 与后台任务。