章节主旨
在 Agentic 工作流里接入第三方 API 时,不要让模型自己上网去”读”文档——那样又慢、又容易踩错、还烧 context。本章讲更高效的做法:把文档手动粘进上下文一次到位,并识别那些已经为 AI 优化过的 API。
核心论点
- 让模型自己搜 API 文档是最大的隐性成本——它约一半时间在查文档、一半在踩错。(→ 详解1)
- JS 渲染的文档页模型根本抓不到,只能瞎猜端点,既不准又持续吃 context。(→ 详解2)
- 直接复制粘贴文档 = 一次给全,省掉”搜索”这个会复合错误概率的额外步骤。(→ 详解3)
- 越来越多 API 主动为 AI 优化(copy for LLM 按钮 / markdown 版),token 高效、AI 原生可读。(→ 详解4)
- 会连 API 就能承接自由职业市场上大量一次性对接需求,这是可交付的实操能力。(→ 详解5)
知识点详解
1. 让模型自己查文档的双重损耗 4:04:11
当你只丢一个文档链接给模型、让它自己去读时,它会花掉大约一半时间在查阅 API 文档、另一半时间在撞各种错误上。表面看只是”帮我读一下”,实际是把最不确定的一步交给了概率系统。
它拿到链接的第一反应是用 web search 工具去访问。但页面一旦返回不完整,模型就会反复兜圈子:再搜一次、再猜一次,始终拿不到确切的 endpoint schema、限流规则或代码示例。
2. JS 渲染文档页:抓不到就开始瞎猜 4:05:04
关键坑在于:有些 API 文档页只通过 JavaScript 加载。模型的抓取工具看到的是渲染前的空壳,端点根本不在 HTML 里,于是它只能开始”猜” JSON 结构、转头去翻别人的文档和博客帖子。
这一路的代价是可量化的:Nick 现场敲 /context 查看,还没干正事,message 上下文已经涨到 1.4%;若任其自己循环三十秒,轻松爬到 3%–5% 甚至更多。搜索这一步不但慢,还在持续侵蚀有限的上下文预算。
3. 手动粘贴文档:一次给全,避免复合错误 4:06:49
Nick 的做法是:自己打开需要的那几页文档(比如 open、get、URL 校验这些端点页),把内容整段复制粘贴进对话,直接告诉模型”这些是该服务的 API 文档,给我列出端点”。
这么做的逻辑是——让模型自己搜,是一个额外步骤,而额外步骤会复合(compound)错误概率。你把资料一次喂全,它第一次就能拿对,不再来回猜端点。要它照着写一段调用 POST 端点的 Python,它立刻就能给出完整正确的代码。
这正是概率系统 vs 确定性工作思路的落地:凡是能提前确定的输入,就别留给模型现场概率化处理。
4. 为 AI 优化的 API:copy for LLM 与 markdown 4:07:40
有些 API 已经直接为大模型和 agentic 工作流做了适配。Nick 举的例子是 Apify 这类服务:文档页顶部带有 copy for LLM 按钮,还能一键 view as markdown、直接在 ChatGPT / Claude / Perplexity 里打开。
拷出来的其实就是整页内容的 markdown 版本。因为是 markdown,它天然更紧凑、更 token 高效,模型也原生就懂怎么遍历这种结构。把这段 markdown 粘给模型,它访问一次就能抓全并快速给出总览,后续追问端点也答得很顺。
背后的信号是:API 提供方正在预判 agentic 工作流会大规模到来,于是主动把文档做成对 AI 友好的 token 高效格式。遇到这类 API,直接用它的 LLM 版本即可。
5. 会连 API = 可变现的实操能力 4:08:57
剥离推销话术后,这里有一条站得住的操作认知:自由职业平台上有大量”一次性 API 对接”需求——某企业在用 X 平台,但 X 没有一键 Zapier 集成,他们不知道怎么连它的 API,觉得又难又吓人。
而如今你甚至不必精通如何手写对接,只需能把”我想连这个 API、发一条测试查询 XYZ”清楚地传达给模型,它就能替你完成。掌握这套读文档 + 粘文档 + 让模型调用的流程,就能接下这类常见、明确、可快速交付的对接活。
术语
- API documentation(API 文档,描述某服务可用端点、请求/响应结构与用法的说明页)
- endpoint schema(端点结构,某个 API 端点的入参/返回字段定义)
- JS-rendered docs(JS 渲染文档,页面内容靠 JavaScript 动态生成、静态抓取拿不到)
- copy for LLM(为大模型准备的一键复制按钮,输出 token 高效的 markdown 版文档)
- context budget(上下文预算,模型对话可容纳的有限 token 空间)
自检问题
- 为什么”让模型自己上网读 API 文档”往往是低效且不可靠的? 答案:它约一半时间耗在查文档、一半时间在踩错;遇到 JS 渲染的页面还抓不到端点,只能瞎猜并反复搜索,既不准又持续吃掉上下文预算。见详解1、2。4:04:11
- Nick 推荐的替代做法是什么?为什么它更可靠? 答案:自己打开所需文档页、整段复制粘贴进对话,让模型一次拿全资料。因为”让模型自己搜”是会复合错误概率的额外步骤,直接给全就能第一次做对、不再来回猜端点。见详解3。4:06:49
- 怎样识别一个”为 AI 优化过”的 API 文档?这样的文档好在哪? 答案:看它是否提供 copy for LLM 按钮或 markdown 版(可直接在 ChatGPT/Claude/Perplexity 打开)。markdown 更紧凑、token 高效,模型原生就懂遍历,访问一次即可抓全。见详解4。4:07:40