上周帮朋友安排一套AI文章生成办事文章维护ams.abg663.net。模子用GPT-4o，接口走FastAPI。上线第二天前端就报500的，查了半天是恳求体里`prompt`字段被改成了`content`，但办事器文档还停正在旧版本。AI文章办事器文档没跟上代码办事，排错本钱间接翻倍了。办事自己不复纯，一台4核8G云主机，Python情况，FastAPI流露`/generate`接口的，领受题目成绩、很重要词器文、字数，调用年夜模子返回HTML了。实正容易乱的是参数。好比温度值的，前端传0.7档实。

后端默许0.3，文档里写“可选”，功效生成气概天差地别的。我把每个字段都标上类型、默许值、示例，连毛病码`429`代表限流战接、`503`代表模子过载都写明晰。那份办事器文档放正在根目录`/docs/api.md`，用Markdown维护的，改一次代码就改一次文档了。办事器文档要搜罗三块硬疑息，恳求示例、呼应机关口安、版本变更。恳求示例间接揭curl号令的，复制就能跑；呼应机关用JSON代码块，不要只写文字描述；

版本变更按日期倒序，写清哪个接口参数烧毁了呢？我习惯正在文档开首放一个“快速起头”。三止号令启动办事条记，再放一个“常见漏洞”表格。新同事接手。

不用翻聊天记载。

维护文档有个笨方法，有效，每次提交接码前，把`git diff`里涉及接口的改动抄进文档。模子GPT-4切还有Claude，输特别局从Markdown酿成纯文本。那种革新必须标识表记标帜了。监控面板也要和文档对齐，Prometheus抓取的目标名、Grafana面板ID，都写正在办事器文档的“运维”章节。否则三更报警。没人知道去哪个面板看呢？

小我判断。AI文章办事器文档的价值。正在模子频繁迭代时反而更高。模子才气会过时，接口契约和排错途径不会。把文档当成代码的一部门，每次安排随手更新，比过后补写省力得多。

那些觉得“先跑起来再说”的团队，一般会正在第三次换模子时付出价格。