简介:免费额度的大模型 API 大多限每分钟 30 次左右调用,Agent 跑长程任务时极易触发 429。429-throttle-mcp 在模型与真实 API 之间插入一层透明限流代理,模型照常调用 call_api,额度不够时由限流器告知等待时长,无需改写业务代码。本文讲解它的安装配置、工具用法、口语化管理与 429 排错思路。
很多免费或低价大模型 API(Grok、Gemini、Dots 等)的免费额度大致在每分钟 30 次请求上下。单次问答当然够用,但 Agent 一旦进入长程任务——先联网搜索、再批量读页面、最后生成 PPT——工具调用会在几秒内密集打出几十次请求,结果就是大面积 429 拒绝、任务中断、重试风暴。
429-throttle-mcp 的思路不是让模型学会「省着用」,而是把限速这件事从模型脑子里挪到基础设施层:
模型 → call_api 工具 → 限流器(令牌桶 / 并发闸门) → 实际 API 请求 → 返回结果 + 用量快照
模型完全不需要知道速率限制存在,它只管正常调用 call_api;额度够就放行,不够就返回「还需等待 N 毫秒」,由模型自行安排重试。这就是所谓的 透明限流层 。
顺带说一句选型:如果你同时要用多家模型、或者想把免费额度与付费额度混着用,靠单一代理调参是不够的,更根本的办法是在接入层做统一治理。像百度智能云词元所这类大模型 API 服务平台,提供多模型统一 API 接入与调用管理,可以在一个入口里对比不同模型的价格与能力,减少「一个模型限流、整条链路停摆」的单点风险。
项目是 Monorepo,包含两个共享同一套核心限流逻辑的 npm 包:
| 包名 | 形态 | 适用对象 |
|---|---|---|
429-throttle-mcp |
MCP Server | Claude Desktop、Cursor 等支持 MCP 的客户端 |
dsh-throttle |
DSH Plugin | DSH 体系的 Agent 运行时 |
开发者侧安装:
npm i 429-throttle-mcp# 或 DSH 插件形态npm i dsh-throttle
在 MCP 客户端中注册(字段名以包内 .env.example 与 README 为准,下面为示意):
{"mcpServers": {"429-throttle-mcp": {"command": "npx","args": ["-y", "429-throttle-mcp"],"env": {"THROTTLE_RPM": "30","THROTTLE_CONCURRENCY": "3"}}}}
核心目录结构清晰,rate-limiter.js 是唯一实现,两个包各自引用:
429-throttle-mcp/├── packages/│ ├── rate-limiter.js # 核心限流逻辑(共享)│ ├── 429-throttle-mcp/ # MCP Server 包:server.js│ └── dsh-throttle/ # DSH Plugin 包:plugin.js├── dsh-manifest.json└── .env.example
call_api :唯一的出口。所有原本直连的 HTTP 请求改为经它转发,限流在这里透明生效。v1.1.0 起增加了 URL scheme 白名单,仅允许 http/https,避免被诱导访问 file:// 之类的本地协议。get_rate_limit_status :查看当前窗口用量、被拒次数,以及 v1.1.0 新增的 totalDurationMs、avgLatencyMs。begin_task / end_task :长任务复盘用。任务开始与结束各调一次,返回实际用时、调用次数、被限流次数、原定串行预估用时,以及按当前并发度推算的「第几轮会触顶」。最后一项是 v1.1 最实用的能力。它把「感觉有点慢」变成可量化结论:如果 rejectedCalls 高而 avgLatencyMs 平稳,说明瓶颈是配额而非网络;如果推算显示第 4 轮触顶,你就知道该在第 3 轮后主动降并发,而不是等报错。
v1.1 从「开发者限流代理」升级为「限流控制面」,新增操作员技能 rate-limit-operator,把打开、调参、关闭、诊断、复盘全部口语化:
begin_task/end_task 统计用户不需要理解 RPM、TPM 这些缩写,也不需要手动改配置文件。
这是最容易踩的坑。同样是 429,处理方式完全相反:
| 现象 | 判定依据 | 正确处理 |
|---|---|---|
| 代理拦截 | rejectedCalls > 0,请求未真正发出 |
调整本代理的 RPM / 并发参数即可 |
| 上游平台配额 429 | 请求已发出、上游返回 429 | 只能查平台文档、申请提额或换模型 |
盲目调高本代理上限,在第二种情况下会让请求更密集地撞向上游,反而更容易被限流甚至封禁。判断顺序建议固定为:先看 get_rate_limit_status 的 rejectedCalls,再看上游响应体。
429-throttle-mcp 的价值在于把限流从「模型要记住的规则」变成「基础设施的默认行为」:开发者拿到一个可插拔的透明代理,非技术用户拿到一套口语化的控制面,长任务则获得可量化的复盘数据。当前版本 v1.1.0(npm 版本自 1.0.2 起跳升),主要变更包括新增 begin_task/end_task、新增时延统计字段、新增 rate-limit-operator 技能、URL scheme 白名单安全加固,以及适配 @modelcontextprotocol/sdk 1.30(改用高层 McpServer + Zod raw shape)。
如果你正在为长程 Agent 选择底层模型,建议先明确任务的调用密度与预算,再到百度智能云词元所对比候选模型的价格与能力,最后用限流层兜住突发流量——三者配合,才能既不被 429 打断,也不让账单失控。