从Demo到生产环境TinyFish Cookbook项目的7个最佳实践——Token效率、限流与隐身抓取【免费下载链接】tinyfish-cookbookA collection of sample apps and recipes built with the TinyFish web agent. Open-source examples for you to learn build!项目地址: https://gitcode.com/gh_mirrors/ti/tinyfish-cookbookTinyFish Cookbook 是一个基于 TinyFish 网页智能体Web Agent构建的开源示例应用合集收录了实时抓取、并行浏览器自动化、AI 研究助手等数十个可运行的项目。对新手来说这个仓库最大的价值不是看 Demo而是从这些真实项目里学到生产级网页抓取的 7 个最佳实践如何用 Token 效率设计降低 LLM 成本、如何控制限流与并发、以及利用内置的隐身抓取能力稳定运行在真实网站上。TinyFish 的四个端点先选对工具再谈优化在动手之前必须理解 TinyFish 的四层端点体系。这是所有最佳实践的地基详见 README.md端点做什么速度成本Search结构化网页搜索为 LLM 设计的 JSON 结果 0.5s免费Fetch任意 URL → 干净 Markdown / JSON几秒免费AgentURL 自然语言目标自动操作浏览器返回 JSON~10s 起按量计费Browser租用托管云浏览器接入自己的 Playwright 脚本实时按量计费实践一从最轻端点开始逐级升级Token 效率第一原则官方 Agent Skill skills/use-tinyfish/SKILL.md 给出了一条清晰的升级路径search → fetch → agent → browser 最轻 最重用户需要网页信息但没有 URL先search再对最佳结果fetch已有 URL且只要内容直接fetch需要点击、填表、动态交互升级到agentAgent 都搞不定的复杂多步流程最后才用browser核心思想能用搜索解决的绝不启动浏览器。一次 Agent 运行的成本可能是一次 Search 的数百倍。官方 Skill 还披露了一个数据相比原始 MCP 方案按此策略可减少约 87% 的 Token见 CHANGELOG.md。实践二永远用 Fetch 的干净 Markdown别把原始 HTML 喂给 LLM这是 Token 效率最直接的杠杆。TinyFish Fetch 使用真实浏览器渲染页面后自动剥离导航栏、脚本、Cookie 横幅等垃圾内容只返回正文。tinyskills 项目是最好的示范它批量抓取文档、GitHub、博客页面后统一请求format: markdown让text字段可以直接喂给合成模型。相关逻辑见 tinyskills/app/api/scrape-sources/route.ts。对比感受一下差距一个典型网页的原始 HTML 可能是正文的 5~10 倍体积其中大部分是 LLM 根本用不上的标签噪声。生产环境里这一步省下的 Token 就是真金白银。实践三批量 并行请求把限流花在刀刃上Search 和 Fetch 虽然免费但有限流额度rate limits。正确姿势是合并批量、控制并发而不是一个 URL 一次请求。tinyskills 的做法值得抄作业批量上限每次 Fetch 最多携带10 个 URL常量FETCH_BATCH_SIZE 10见 scrape-sources/route.ts8 个来源就是一次网络往返批次并行超过 10 个 URL 分成多批用Promise.all并行执行总耗时接近一轮最慢请求而非顺序 N 次跨类型去重URL 归一化后去重绝不重复抓同一页16 个 URL → 2 批10 6→ Promise.all 并行 → 总耗时 ≈ 一轮实践四并发 Agent 用 allSettled超时预算要显式声明当必须动用 Agent 端点真正的浏览器自动化时限流与稳定性问题会更突出。viet-bike-scout 是一个真实案例一次搜索要同时向 5~6 家越南摩托租车网站发射并行浏览器 Agent。两个关键生产技巧都在 viet-bike-scout/src/app/api/search/route.ts 中Promise.allSettled而非Promise.all5 个 Agent 里有 1 个卡死或失败其余 4 个的结果照常返回前端流式展示已完成的店铺不必等待最慢的那个显式超时预算API 路由头部声明export const maxDuration 800明确告诉托管平台这个接口是长任务避免被默认超时切断另外官方 Skill 还强调了一条易错点多个独立网站要拆成多个并行调用不要合并进一个 goal——合并后既慢又不可靠见 SKILL.md。实践五隐身抓取是内置能力不是外挂很多团队为如何绕过反爬头疼而在 TinyFish 体系里隐身stealth是平台内置、零额外成本的默认能力内置隐身Browser 端点自带轮换代理和隐身浏览器配置无需自己搭代理池见 README.md出口地区可控use-tinyfish SKILL.md 展示了浏览器会话支持--proxy-country DE选德国出口 IP或接入自己的代理甚至--no-proxy直连整个会话 IP 一致默认流量经同一代理 IP 出口避免每换一个 IP 就重新触发风控的问题对新手的关键启示是不要在应用层自己写反检测代码把隐身交给平台你的精力应花在数据结构化和业务逻辑上。实践六把失败免费写进你的容错设计生产环境和 Demo 的最大区别目标网站会挂、会改版、会限流。TinyFish 在两个层面帮你兜底平台层失败的 Fetch 请求免费。官方定价策略明确Failed URLs are freeREADME.md——批量抓取 10 个 URL坏 2 个不扣费重试成本极低。应用层错误按 URL 隔离。tinyskills 的抓取路由会把 Fetch 返回的errors数组逐条映射为source_error事件单个来源失败不会导致整批任务崩溃见 tinyskills/README.md 与 scrape-sources/route.ts 的 SSE 错误事件设计。配合实践四的allSettled模式你的系统就变成了部分成功 全部失败的韧性架构。实践七可观测性——SSE 流 doctor 自检问题定位不再靠猜上生产之前问自己两个问题Agent 现在卡在哪一步和为什么突然 401 了第一步让运行过程可见。viet-bike-scout 利用EventType.STREAMING_URL事件把每个 Agent 的实时浏览器画面以 iframe 形式推到前端用户在 UI 上能直接看见抓取过程结果则通过 SSE 流在每家店铺完成时即时推送架构图见 viet-bike-scout/README.md。第二步给环境装体检工具。TinyFish CLI 内置doctor命令一条命令完成认证、MCP 注册、连通性检查还能--fix自动修复见 INSTALL.md 与 tinyfish-doctor SKILL.md。生产排障时先跑doctor再谈其他。快速上手从 Demo 到你的第一个生产项目拿 Key注册后一个 Key 打通 Search / Fetch / Agent / Browser 全部端点Search 和 Fetch 免费照抄架构本仓库每个项目都是独立文件夹、自带 README建议先跑 viet-bike-scout并行 Agent 流和 tinyskills批量 Fetch 流这两个模板环境变量隔离viet-bike-scout 的 env.ts 展示了好习惯——Key 缺失时显式抛 500 并说明原因而不是让请求默默失败渐进升级先 search fetch 跑通业务成本不够再看是否需要 agent总结把 7 个实践浓缩成一张清单#实践解决的问题1最轻端点优先逐级升级Token 成本失控2Fetch 返回干净 MarkdownLLM 为 HTML 噪声付费3批量 10 URL 批次并行限流额度浪费、速度慢4allSettled 显式超时单点卡死拖垮整批任务5依赖平台内置隐身自建代理池的高成本6失败免费 错误按 URL 隔离目标站挂掉导致全线崩溃7SSE 流 doctor 自检线上问题无从排查这些模式来自 AABW_Vietnam_Hackathon_Samples、fast-qa、game-buying-guide 等数十个真实项目的共同沉淀。下一个版本建议直接打开对应项目源码对照本文逐条验证——从 Demo 到生产只差一次认真的代码走读。【免费下载链接】tinyfish-cookbookA collection of sample apps and recipes built with the TinyFish web agent. Open-source examples for you to learn build!项目地址: https://gitcode.com/gh_mirrors/ti/tinyfish-cookbook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考