北京
上周，一位朋友花费整整六个小时调试 Stripe Connect 集成。他用的工具是 Cursor，调用的模型是 Claude 3.5 Sonnet，面对的更是业界公认文档质量上乘的 Stripe API。然而，模型持续在他的验证逻辑中塞入一个名为 X-Stripe-Connect-Signature 的 Webhook 头。他复制了那段代码，做了测试，又反复翻阅官方文档，甚至让模型“再核对一遍官方文档”。模型每次都自信地继续生成那个头。
那个头根本不存在。Stripe 验证 Connect webhook 用的其实是 Stripe-Signature，跟它其他地方用的是同一个头。那个带“Connect”字样的版本，是模型在微调过程中悄然编造出来的，并且他工具链里的每一个智能体都在随后重现这个错误，且带着十足的把握。这位朋友并非初级工程师，他已经推出过六家创业公司的产品。他只是犯了当下几乎所有使用 AI 编码助手的团队都在犯的同一个错误——以为问题出在文档上。
随便走进哪个 AI 工程领域的即时通讯频道，你都会反复听到同样的对话：“我们的智能体总是幻觉出我们的 API，得把文档做得更好。”于是团队开始改进文档，重写接口说明，添加代码示例，优化 Markdown 排版，迁移到更花哨的文档框架，发布 Notion、OpenAPI 甚至 llms.txt。可幻觉依然不断发生。诊断从一开始就错了。API 被幻想出来，不是写作水平的问题，不是语气问题，甚至也不是“文档不够完整”的问题。
这是个结构问题。文档在网络上被组织起来的方式，从根本上就排斥模型实际的阅读方式。下次你再让 AI 编码助手抓取某款真实产品的文档时，打开网络面板看看。你会看到，模型被要求回答一个极其精确的、模式级别的问题——“我用哪个头来验证这个 webhook？”——然而它眼前只有一堆写给人类看的散文，而且预设读者是从头到尾通读页面，通过版式、侧边栏和语气来理解上下文的。模型获取不到版式，也拿不到侧边栏，更谈不上捕捉语气。它接收到的只是一包被压扁的段落，绝大多数的结构信号都被剥离掉了。
于是，模型开始自行填空。它做了所有语言模型一贯会做的事：生成一个听起来像 Stripe 头的字段，因为它的训练数据里到处都在说头是存在的，而且名字得照着某种样式起。这就是幻觉。不是创意失灵，而是结构失灵。想象一下，你想教一个刚入行的初级工程师调用你的 API。你不会让他去读四百页 Markdown，再自行判断哪一页是权威信息。可我们今天对 AI 智能体采用的，恰恰就是后一种做法。
说起“改进文档”，人们通常的理解是写出更好的叙述——加一段更清晰的导语，把警告提示往上挪一挪，增补一些解释性说明。然而真正需要的不是更流畅的语句，而是能让模型直接提取到权威参数、头信息、请求体结构的方式。这种错位还在持续，而每一次幻觉，其实都是那位朋友经历的重演：团队把问题归咎于文档不够好，却没有发现，模型只在那堆给人类编排的页面里搜寻一个它永远找不到的确定性答案。
特别声明：以上内容(如有图片或视频亦包括在内)为自媒体平台“网易号”用户上传并发布，本平台仅提供信息存储服务。
Notice: The content above (including the pictures and videos if any) is uploaded and posted by a user of NetEase Hao, which is a social media platform and only provides information storage services.
