17 篇博文 含有标签「api-design」

一个团队从前沿模型升级到了其更快的后继版本。评估套件（eval suite）全绿。最终答案一致。工具调用的 Schema 完全相同。结构化输出通过了与以往一样的 JSON Schema 验证。他们发布了。不到一天，支持票据就堆积如山：“助手感觉太匆忙了”，“它不再真正思考了”，“感觉不对劲”。产品经理调取了遥测数据，发现任务完成率没有变化。工程团队反复检查了评估和 Schema，没发现任何问题。投诉是真实的，但团队定义的契约——就如团队所定义的那样——依然完好无损。

改变的是流的纹理（texture）。旧模型在调用工具前会停顿 800 毫秒，发出一句“让我查一下……”的前导词，并以每秒约 35 个 Token 的速度输出，在子句边界处有自然的节奏。新模型以每秒 90 个 Token 的速度输出，从不停顿，且完全跳过了前导词。这些都没有出现在任何文档记录的契约中。但所有这些都是不可或缺的“承重”部分。

这就是海勒姆定律（Hyrum's Law），而流式传输（streaming）让它的表面积变得巨大。系统的任何可观察行为都会被某人所依赖——而流式 AI 界面暴露的可观察行为远比团队意识到的要多。

大多数工程团队将 API 文档视为开发者体验关注点——一种为了减少支持工单和入职时间而进行的改进。当你的主要消费者是在浏览器中阅读文档的人类时，这种思维方式是有道理的。但现在，这已经不再足够。

当 AI 智能体通过工具调用访问你的 API 时，你的文档就不再仅仅是指南，而是变成了运行时行为。模糊的参数描述不再是 UX 上的不便，而是对模型产生幻觉值的直接指令。缺失的错误代码不再是参考文档中的空白，而是一个模糊信号，可能导致智能体陷入没有退出条件的重试循环。你三年前为人类读者编写的文档，现在正被一个无状态的语言模型解析，无论它是否理解正确，都会自信地执行。

2025 年，自动化互联网流量同比增长了 23.5%，是人类流量增速的八倍。其中，agent 驱动的交互增长了 7851%。如果你的产品处理了相当体量的 API 流量，那你的最重度"用户"很可能根本不是人类。而令人不安的事实是：你的产品分析系统对此几乎一无所知。

这不是一个机器人检测问题，而是一个埋点架构问题。当 AI agent 预订差旅、提交费用报告、查询数据库或调用你的支付 API 时，它留下的行为特征与人类完全不同——而你的会话漏斗、NPS 问卷和队列留存图，正在悄悄对你撒谎。

你的 REST API 运行良好。文档齐全，错误码一致，每一个经过测试的人工编写客户端都能正常使用。然后你的团队接入了一个 AI 智能体，不到一小时，它就通过不断重试一个不存在的端点的各种变体生成了 2,000 次失败请求——bulk_search_users、search_all_users、bulk_user_search——每次尝试都触发了真实的下游处理。

这不是提示词工程的失败，而是 API 设计的失败。

REST API 是为能够解析文档、遵守契约、严格调用规范的客户端而构建的。AI 智能体则不同：它们根据名称和描述推断端点可能做什么，在不追踪状态的情况下重试，并将错误信息视为指令而非诊断代码。为智能体调用方设计 API，需要重新审视大多数后端工程师从未质疑过的基本假设。

你交付了一个工具，让你的 Agent 可以获取用户个人资料。描述中写道：“通过用户 ID 检索用户信息。”六周后，后端团队将 user_id 重命名为 customer_uuid 并添加了一个必填的 tenant_id 字段。没有人更新工具的 Schema。你的 Agent 继续调用旧的签名，收到 400 错误，将空结果解释为“未找到用户”，并“热心地”创建了一个重复记录。

日志中没有错误。没有触发任何报警。Agent 全程都非常自信。

这就是工具文档问题：Schema 漂移将陈旧的描述变成了隐性故障向量。这可能是当今生产环境 AI 系统中最被低估的可靠性风险，而且你的 Agent 运行的时间越长，情况就越严重。

系统提示词（system prompt）上一个四个词的修改——用 "respond using clean JSON"（使用干净的 JSON 响应）替换 "output strictly valid JSON"（输出严格有效的 JSON）——在评估（eval）中一度没有引起任何波动。它在周四发布，却在周五凌晨 4 点被回滚，因为结构化输出的错误率从 0.3% 飙升到了 11%。提示词并没有变糟。它只是变得“不同”了，而下游解析器在无人察觉的情况下，已经固化（pinned）在了 "strictly valid" 这个词组上。

这是大多数提示词工程（prompt-engineering）团队尚未建立工具来应对的失效模式：提示词被视为作者拥有的文本，而实际上它是与作者从未见过的消费者之间的一份合约。这些消费者中，有些是逐字引用原句的其他提示词；有些是 JSON 模式（JSON schema）字段锚定在特定形容词上的工具描述；有些是其评分标准（rubrics）要求裁判（judge）检查“严格有效格式”的评估（evals）；还有一些是解析器——最脆弱的一类——其正则表达式是根据模型输出的精确前导语（preamble）进行校准的。

一次“小小的措辞清理”会悄无声息地破坏解析器、导致裁判校准偏移，并使数周的评估运行失效。这些失败都不会在 PR（拉取请求）中显示出来，而是在一周后作为“偏移”（drift）出现在仪表盘上。

你两年前发布的 API 是为单一类别的调用者设计的：浏览器或移动客户端背后的人，点击一次，然后等待响应。现在，大约一半的关键端点上，这个假设都是错误的。另一半流量是智能体（Agents）——你自己的、你客户的，或者是将你的端点作为工具使用的第三方集成——它们具有不同的运行逻辑。它们会产生爆发式流量。它们会无限重试。它们会并行处理。它们会逐字解析错误字符串。它们代表人类行事，而当出现问题时，人类无法即时提供意图说明。

今年出现在复盘报告（postmortems）中的大多数生产环境异常，都可以追溯到一个架构错误：将这两类调用者视为同一种类别。为人类步调设置的频率限制（Rate limits）会被智能体的并行扇出瞬间击穿。为人类可读而设计的错误消息，会被一个在 400 错误上无限重试的智能体解析错误。人类默认会满足的幂等性假设，在智能体从恢复的检查点重试相同的负载时会被打破。身份验证日志失去了区分“用户执行了此操作”与“用户的智能体代表用户执行了此操作”的能力。

解决方法不是更智能的 WAF 或更大的频率限制桶。而是一种深思熟虑的 API 设计，它定义了两类调用者，将它们的流量视为不同的形态，并记录委托链，以便在间接层级中保持可追溯性。

大多数多轮 LLM 应用将对话历史存储为消息数组。这在演示（demo）中表现良好。但在生产环境中，它会以需要数天才能诊断出的方式崩溃，因为这些故障看起来更像是模型的问题，而非基础设施的问题。

用户在对话中途断开连接，并重新连接到不同的服务器实例——会话消失了。智能体（agent）在处理复杂任务时进入第 47 轮，载荷悄无声息地超过了上下文窗口——没有报错，只有错误的回答。产品经理问道：“我们可以让用户从第 3 步开始尝试不同的方法吗？”——而工程侧的回答是“不，按照我们的构建方式不行”。这些都不是极端情况，而是将对话状态视为瞬态数组（transient array）而非一等资源（first-class resource）的必然结果。

大多数构建 AI Agent 的团队都在花数周时间调整 Prompt 和评估（evals）、基准测试模型选择以及微调 Temperature —— 而他们真正的瓶颈其实在更深的一层：那个为人类开发者而非 Agent 设计的数据访问层。

这种失配并非细微。像 Hibernate、SQLAlchemy 和 Prisma 这样的 ORM，结合返回分页、单实体响应的 REST API，产生的数据访问模式对自主 AI Agent 来说完全是错误的。其结果是 Token 浪费、速率限制失败、级联的 N+1 数据库查询，以及 Agent 因为无法负担加载所需上下文的成本而产生幻觉。

本文将探讨这一结构性问题，以及一个针对 Agent 优化的数据层究竟是什么样的。

大多数后端工程师能够背诵 REST 契约：客户端发送请求，服务器处理请求，服务器返回状态码和响应体。200 表示成功，4xx 表示客户端出了问题，5xx 表示服务器出了故障。响应是确定性的，超时是可预测的，幂等键保证了安全重试。

而 LLM 后端违背了上述所有假设。一个返回 200 OK 的请求，可能意味着模型对整个响应产生了幻觉。一次成功的请求可能需要十二分钟，而不是十二毫秒。两次参数完全相同的请求会返回不同的结果。如果服务器在推理过程中超时，你根本不知道模型究竟是否已完成。

把 LLM 硬塞进传统 REST API 的团队，最终往往面对一堆补丁：超时杀死了正在运行的 Agent 任务，客户端把带幻觉的 200 当成成功，重试逻辑因为幂等键没有针对概率性操作设计而三次扣了用户的信用卡。本文将梳理这些不匹配最致命的地方，以及真正在生产环境中能站得住脚的接口模式。

你的 /v1/summarize 端点在 18 个月里运行得非常完美。然后你升级了底层模型。输出格式没变，JSON schema 完全一致。但你的下游消费者开始提交 bug：摘要“太随意了”，要点“详细得诡异”，边界情况下的拒绝响应“变得不同”。从传统意义上讲，一切都没坏；但在 AI 的语境下，一切都坏了。

这是 REST 和 GraphQL 从未被设计用来解决的版本控制问题。传统的 API 合约假设确定性：相同的输入总是产生相同的输出。而 AI 端点的合约是概率性的——它包括语气、推理风格、输出长度分布以及拒绝阈值，当你更换或更新底层模型时，所有这些都可能发生漂移。对于以数据库为支撑的 API 有效的技术，对于以 AI 为支撑的 API 是必要但不充分的。

你的支付服务拥有 99.9% 的可用性 SLA。请求要么成功，要么以文档记录的错误代码失败。当出现故障时，你清楚地知道哪里出了问题。

现在，想象你发布了一个封装了 LLM 的智能发票解析 API。在一个周一早晨，你最大的客户打来电话：“你们的 API 返回了一个有效的 JSON 对象，但在涉及外币的发票中，total_amount 字段的值差了十倍。” 你的服务返回了 HTTP 200。你的可用性仪表板显示绿色。根据每一个传统的 SLA 指标，你都没有违反任何规定。但你确实搞砸了——而且在契约语言中，你甚至找不到词汇来描述到底哪里出了错。

这就是当今大多数 AI API 部署的核心鸿沟。管理你的 API 承诺 的契约为确定性系统而写，而 LLM 并非确定性系统。