亚马逊把API文档改了个写法，工业AI准确率翻了3倍

2024年12月，一位工厂操作员用西班牙语问AI："厂里设备有新情况吗？"系统秒回：3台设备状态分级，2台危急、1台警告，还点名建议优先检修涡轮EQ-003。全程无人工介入。

这场景来自亚马逊云科技（AWS）最新落地的工业AI助手项目。项目负责人发现，同样的底层模型，API文档写法一改，故障预判准确率从"能用"跳到"敢用"。

从"我不懂你在说什么"到"建议立即检修"

项目缘起很典型：一位工程师向同事吐槽，之前用的聊天机器人只会重复"抱歉，我没听懂"。工厂里传感器24小时吐数据，仪表盘铺满屏幕，最后还得靠老师傅肉眼判读。

亚马逊Bedrock智能体（Bedrock Agents）的解法，是把"文档即界面"推到极致。传统API文档长这样：GET /sensors/temp，summary写"获取温度"，200返回"成功"。AI拿到这种描述，像新入职的程序员面对零注释祖传代码——能跑，但全靠猜。

改写后的版本把端点命名为/equipment/{id}/health，description里塞满业务语境："评估设备综合状态，对比当前指标与历史区间，识别异常模式，返回健康评分及维护建议。"

模型不需要更聪明，只需要更懂上下文。

实测对比残酷：同一套工业API，传统文档让AI频繁调用错误端点，把温度传感器数据当成振动分析用； enriched文档把多步推理压缩成一次精准请求。开发者反馈，调试时间从数小时压到分钟级。

RESTful已死？不，是读者变了

项目作者有个尖锐观察：我们设计API时默认读者是人类程序员，现在读者池里多了大语言模型。后者没有"常识"，不会"显然如此"——你把字段叫temp，它不会自动联想到temperature；你写"获取数据"，它不知道要拿来干嘛。

亚马逊的应对是强制结构化：每个端点必须声明业务意图、输入输出语义、异常场景处理。文档从"参考手册"变成"对话脚本"，AI能预判调用链：查健康状态→发现异常→调取历史曲线→生成维修工单。

工业场景成了试金石。工厂设备故障的代价按分钟算钱，AI幻觉一次可能停产半天。Bedrock智能体在这里跑通，意味着文档驱动设计（Documentation-Driven Design）从最佳实践变成硬性门槛。

一个细节值得玩味：演示里的操作员说西班牙语，系统无缝响应。多语言不是额外功能，是文档语义足够丰富后，模型自然解锁的副产物——它理解的是"涡轮机临界状态"，而非硬编码的英文关键词。

API设计的下一个十年

这个项目没发新模型，没堆算力，只改了一件事：把"给人看"的文档改成"给AI读"的文档。效果却像从拨号上网切到宽带——同一根电话线，编码方式变了，带宽天差地别。

亚马逊内部有个说法正在流传：未来评估API成熟度，不看QPS，看"AI一次调用成功率"。人类开发者能容忍翻文档、试参数、读报错；AI没这个耐心，错一次就链式崩溃。

那位最初吐槽的工程师，现在每天收到AI生成的设备简报。他说了句被团队记进文档的话：「以前是我追着数据跑，现在是数据追着我跑。」

当你的API文档需要同时服务人类和AI，你会先改哪一端？