1 篇博文 含有标签「documentation」

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

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

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