API 是程序之间的约定

建议用时：25 分钟（含练习）

学习目标

能够解释客户端、服务器、请求、响应和 HTTP 状态码在模型调用中的角色。

本节产出

一张模型请求往返图

核心知识：一次请求必须有明确的约定

术语

API（应用程序接口）

你在网页上点击“生成摘要”，背后通常是程序发出请求，另一个程序处理后返回结果。API（应用程序接口）规定双方怎样交互。它不是模型本身，也不专属于 AI。读取课程目录、查询天气和调用模型都可以使用 API，但每个接口的输入、权限和输出不同。

本课主要讨论基于 HTTP 的模型服务接口。一个请求可以拆成方法、地址、请求头和请求体；响应可以拆成状态码、响应头和响应体。客户端是发起这一轮请求的一方，服务端是接收并处理的一方。相同程序在另一条链路里也可能成为客户端，例如网站后端接收浏览器请求后，又向模型服务发起请求。

方法说明请求的操作语义，例如 GET 常用于获取资源，POST 常用于提交处理请求。地址决定访问哪个服务与资源。请求头传递认证、内容类型等元信息。请求体携带具体输入，模型调用常使用 JSON。不能只把输入文本写对，就忽略请求其余部分；任意一层不符合约定，都可能使调用失败。

图中的网站后端既是浏览器的服务端，又是模型服务的客户端。这个分工也解释了为什么服务端密钥不应直接写进公开网页：浏览器收到的代码和请求通常可以被使用者查看。正确的访问边界应由后端认证与授权实现，而不是把秘密藏在按钮后面。

看懂一份完整的教学报文

下面是虚构接口，只用于阅读，不要向这个保留示例域名发送真实凭证。它不代表某家厂商的实际请求格式。

POST /v1/summarize HTTP/1.1
Host: api.example.invalid
Authorization: Bearer EXAMPLE_ONLY_NOT_A_KEY
Content-Type: application/json

{"text":"周六开展图书交换活动。","maxSentences":1}

HTTP/1.1 200 OK
Content-Type: application/json

{"summary":"周六有图书交换活动。","requestId":"demo-001"}

阅读时先确定服务地址与方法，再看认证与内容类型，最后看业务字段。响应中的 requestId 是本例用于追踪请求的编号，不是用户密码，也不是所有接口都会采用的固定字段。真实服务可能通过响应头返回追踪编号，需要以文档为准。

成功响应不等于业务内容正确

HTTP 200 说明这一层请求处理成功，不代表摘要没有漏信息。接口返回了合法 JSON，也不代表字段含义符合你的业务要求。客户端至少应分别检查网络是否成功、状态码是否符合预期、响应格式能否解析，以及内容是否满足任务。

同理，网站首页能够打开，不代表模型接口配置正确。首页可能由一个服务提供，生成摘要可能经过另一条路径，需要不同的认证和权限。排错时应记录失败的是哪个实际请求，而不是笼统地说“网站坏了”或“模型不行”。

案例：按钮转圈，但不知道哪里出了问题

一个教学应用收到用户输入后调用摘要接口。前端只显示“生成失败”，没有进一步分类。你查看脱敏的请求记录，发现请求成功到达后端，但后端没有发送模型请求，因为输入字段名应为 text，客户端却发成了 content。

这不是换一个更强模型就能解决的问题。需要让前后端遵循同一个字段合同，并在输入校验失败时返回明确的可公开错误。不要为了调试把完整请求头、真实密钥和用户全文一起写进共享日志；通常记录字段是否存在、状态码、追踪编号和脱敏错误类型就足够定位这一类问题。

如果修复字段后收到摘要，再用两条样例检查：一条普通输入，一条空字符串。普通输入应得到合格输出；空输入应被明确拒绝或按文档定义处理。接口可靠性来自这些边界合同，而不仅是“成功调通一次”。

动手练习

1. 在上面的教学报文中标出方法、完整服务位置、认证头、内容类型、输入字段、状态码和输出字段。
2. 手工设计两种响应：输入缺少 text，以及服务暂时无法处理。为客户端分别写一条清楚但不泄露内部信息的提示。
3. 建立一张请求检查表，区分传输、协议、解析和业务验收。使用虚构报文即可，不需要购买服务或调用收费接口。

参考答案与推演

展开

完成检查

• 能画出客户端与服务端在两段请求链路里的角色。
• 能从完整报文定位输入和输出，而不是只看模型名。
• 知道成功状态、合法格式与正确业务内容是不同检查。
• 教学示例不包含真实密钥，日志设计遵循最少必要信息。

参考与来源

• MDN：Overview of HTTP：HTTP 请求与响应的基本结构。
• OpenAI：API Overview：一个实际模型服务的认证与请求追踪说明。