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

系统提示词（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 并非确定性系统。

你的客服智能体稳定运行了三个月。一次例行模型更新在周二悄然上线。到周三下午，三个下游服务已在静默地解析智能体响应中的错误字段——JSON 键值发生了微妙变化，但没有任何报错。到周四，你追溯到订单完成率下降，原因是某个 JSON 字段从 "status" 被重命名为 "current_state"。模型更新了，智能体版本号仍是 v2.1.0，没有人收到告警。

这正是传统 API 设计从未需要解决的版本管理空白。语义化版本控制（Semver）在能够从规范中确定性地复现输出时才有效。AI 智能体无法做出这种承诺。然而下游服务对其行为的依赖程度，与对任何微服务 API 的依赖一样关键。"我们打了一个发布标签"与"下游消费者受到了保护"之间的鸿沟，从未如此之大。

你的文档说 /summarize 端点会返回一个简明扼要的摘要。这没错。但它每次返回的摘要都不一样，有时会遗漏关键点，偶尔在你忘记在提示词（prompt）中指定格式时返回结构化的 JSON，并在你毫不知情的模型更新后发生无声的性能退化。而这些都没有出现在文档中。

传统的 API 文档记录的是契约：给定输入 X，预期输出 Y。而 AI 驱动的功能从根本上打破了这一模式。这里没有稳定的契约可供记录。同样的提示词、同样的模型、同样的参数 —— 却会产生不同的输出。然而，团队在发布这些功能时，使用的文档风格仍与编写数据库查询文档时如出一辙：一个函数签名、一个返回类型，或许还有一句关于错误代码的说明。

你的文档所描述的内容与功能的实际表现之间的鸿沟，正是开发者信任消亡的地方。

你的 AI agent 在推理、规划和生成自然语言方面表现出色。然后你把它指向企业的 SAP 端点，它接下来花了 4,000 个 token 试图理解一个 SOAP 信封。欢迎来到阻抗失配的世界——这个隐性税收把每一次企业 AI 集成都变成了 token 的焚烧炉。

这种失配不仅仅是 XML 与 JSON 的问题。它是 LLM 思维方式（自然语言、扁平的键值结构、简洁的上下文）与企业系统通信方式（深层嵌套的 schema、特定于实现的命名、分页游标以及数十年积累的协议约定）之间的根本冲突。与人类开发者只需阅读一次 WSDL 文档就可以继续工作不同，你的 agent 在每次调用时都要重新解析这种复杂性。

2023 年，斯坦福大学和加州大学伯克利分校的研究团队做了一项受控实验：他们在 3 月和 6 月分别向 GPT-4 提交了完全相同的提示词，任务非常基础——判断一个数字是否为质数。3 月时，GPT-4 的准确率为 84%。到了 6 月，使用完全相同的 API 端点和完全相同的模型别名，准确率已跌至 51%。没有变更日志，没有通知，没有传统意义上的破坏性变更。

这项实验清晰地揭示了一个在多服务架构中部署 LLM 的团队迟早都会遇到的问题：模型别名不是稳定的契约。当你的下游支付处理器、推荐引擎或合规系统依赖 LLM 生成的结构化 JSON 时，你就建立了一个隐式的 API 契约——而隐式契约会悄无声息地崩溃。

在 2024 年，自动化机器流量在互联网上首次超过了人类流量。Gartner 预测，到 2026 年，超过 30% 的新 API 需求将来自 AI Agent 和 LLM 工具。然而，只有 24% 的组织在设计 API 时明确考虑了 AI 客户端。

这一差距正是生产系统崩溃的地方。并不是因为 LLM 本身表现不佳，而是因为为人类开发者构建的 API 包含了一些默认假设，当调用者是自主 Agent 时，这些假设会悄无声息地失效。Agent 无法请求澄清，无法阅读文档网站，也无法自行判断 422 错误是指“修改你的请求”还是“几秒钟后重试”。

这篇文章是写给那些刚刚发现自己的服务正被 AI Agent 调用，或者即将构建此类服务的后端工程师的。