1. 为什么 AI Agent 开发者需要一份靠谱的免费 API 清单做 AI Agent 的人都有一个共同的痛点模型能力再强工具链跟不上也是白搭。一个能跑起来的 Agent背后往往需要代码托管、文件解析、模型推理、数据抓取、消息推送等一大堆外部能力支撑。而这些能力如果全部走商业 API一个月下来账单能吓死人。我自己搭过几个 Agent 项目从最开始的无脑买服务到后来慢慢摸索出一套免费 API 组合拳中间踩的坑足够写一本小册子。这份清单里的 10 个免费 API是我在实际项目中反复验证过、目前仍在稳定使用的。覆盖了代码仓库加速下载、大模型推理、文档解析、搜索增强等 Agent 最常用的场景。其中 GitHub/Gitee/GitLab 的下载加速方案能让你在 5GB/月的免费额度内基本够用对于个人开发者和中小团队来说这个量级足以支撑日常的 Agent 开发和调试。适合谁看如果你正在搭建 AI Agent或者打算给现有 Agent 增加工具调用能力又不想在 API 成本上投入太多这份清单就是为你准备的。不管你是用 Python 还是 Rust不管你的 Agent 架构是 ReAct 还是 Plan-and-Execute这些 API 都能直接集成进去。2. 代码托管平台加速下载 API 的选型与实操2.1 为什么 Agent 项目特别依赖代码仓库加速AI Agent 项目有一个很显著的特点依赖多、更新快、体积大。一个典型的 Agent 项目可能同时依赖 LangChain、Transformers、各种向量数据库客户端再加上模型权重文件动辄几个 GB。如果每次部署都从 GitHub 原始地址拉取速度慢不说还经常断连。更麻烦的是很多 Agent 框架的安装脚本里写死了 GitHub 的 raw 地址你没法简单替换。我试过在 CI/CD 流程里直接跑pip install结果因为 GitHub 连接超时导致整个构建失败。后来改成先用加速服务把依赖包拉到本地缓存再走本地安装构建成功率直接从 60% 提升到了接近 100%。这个经验告诉我代码仓库加速不是锦上添花而是 Agent 工程化的基础设施。2.2 GitHub 加速的三种主流方案对比目前市面上针对 GitHub 的加速方案主要有三类各有适用场景方案类型原理优点缺点适用场景镜像站替换将 github.com 替换为镜像域名配置简单无需额外工具镜像站稳定性参差不齐临时下载单个文件代理缓存通过中间层缓存仓库内容速度快支持 release 下载需要配置 git 全局替换日常开发拉取本地缓存首次拉取后本地留存完全离线可用首次拉取仍需加速CI/CD 构建我个人的做法是组合使用日常开发用代理缓存方案CI 环境用本地缓存方案。具体操作上可以通过修改 git 的insteadOf配置来实现自动替换git config --global url.https://加速域名/.insteadOf https://github.com/这条命令的意思是当你执行git clone https://github.com/user/repo.git时git 会自动把https://github.com/替换成加速域名。实测下来克隆速度能从几十 KB/s 提升到几 MB/s。需要注意的是不同加速服务的域名格式可能不一样有的需要保留后面的路径有的需要额外加参数配置前最好先看服务方的说明。注意使用insteadOf配置后git 的 remote 地址显示仍然是原始地址但实际请求走的是加速域名。如果某天加速服务挂了记得用git config --global --unset url.https://加速域名/.insteadOf取消配置。2.3 Gitee 作为国内镜像仓库的实操要点Gitee 在国内的访问速度确实有优势但直接用它做 GitHub 的镜像有几个坑要注意。首先是仓库同步的延迟问题Gitee 的导入功能不是实时同步的你 push 到 GitHub 之后Gitee 那边可能需要手动触发或者等待定时同步。其次是开源许可证的选择如果你打算把项目同时放在 GitHub 和 Gitee许可证要选两边都认可的MIT 和 Apache 2.0 是最稳妥的选择。从 Gitee 拉取项目到 IDEA 的流程和 GitHub 基本一致但有一个细节Gitee 的 SSH 密钥配置和 GitHub 是分开的。你需要单独生成一对密钥然后在 Gitee 的个人设置里添加公钥。我见过不少人直接把 GitHub 的密钥复制过去结果一直提示权限错误。正确的做法是ssh-keygen -t ed25519 -C your_emailexample.com -f ~/.ssh/gitee_ed25519然后在~/.ssh/config里配置Host gitee.com HostName gitee.com User git IdentityFile ~/.ssh/gitee_ed25519这样配置之后GitHub 和 Gitee 的密钥互不干扰切换平台时不会出现认证冲突。2.4 GitLab 自建与 CLI 工具链的配合GitLab 的情况比较特殊很多团队是自建 GitLab 实例。自建的好处是内网速度快但坏处是版本更新和安全补丁需要自己维护。我经历过一次 GitLab 高危漏洞修复当时官方发布了安全补丁但我们的实例版本比较老升级路径不是直接的需要先升到中间版本再升到目标版本。这个过程花了整整一个周末。GitLab CLI 的安装相对简单在 macOS 上可以用 Homebrewbrew install glab安装完成后需要配置个人访问令牌。这里有个细节GitLab 的个人访问令牌权限粒度比 GitHub 细创建令牌时要根据实际需要勾选 scope。如果只是拉取代码read_repository就够了如果需要提交代码要加上write_repository。令牌创建后只显示一次务必立即保存。提示GitLab 14.0 之前的版本在 IDEA 中登录会提示版本不支持。如果你在用老版本要么升级 GitLab要么改用令牌方式认证不要用账号密码登录。3. 大模型推理 API 的免费额度挖掘与调用技巧3.1 免费大模型 API 的现状与选择逻辑AI Agent 的核心是推理能力而推理 API 的成本往往是整个项目里最高的。目前市面上提供免费额度的大模型 API 主要有几类一是国内厂商的推广期免费额度比如 DeepSeek、智谱等二是海外厂商的试用额度三是开源模型的自部署方案。选择免费 API 时我主要看三个指标免费额度的有效期、模型的上下文长度、以及 API 的稳定性。有些平台虽然免费额度大但限制并发数Agent 一跑起来就排队体验很差。还有些平台免费额度只有几天有效期适合短期测试但不适合长期项目。DeepSeek 的 API 调用方式兼容 OpenAI 的接口格式这意味着你可以直接用 OpenAI 的 SDK 来调用只需要改一下 base_url 和 api_keyfrom openai import OpenAI client OpenAI( api_keyyour_deepseek_api_key, base_urlhttps://api.deepseek.com/v1 ) response client.chat.completions.create( modeldeepseek-chat, messages[ {role: system, content: 你是一个有用的助手}, {role: user, content: 帮我写一个快速排序} ] )这种兼容性设计对 Agent 开发者非常友好因为大部分 Agent 框架都默认支持 OpenAI 接口切换模型只需要改配置不需要改代码。3.2 上下文长度限制的应对策略免费 API 通常有上下文长度限制比如 1048576 tokens 这种。虽然看起来很大但 Agent 场景下很容易超。一个典型的 Agent 对话可能包含系统提示、历史对话、工具调用结果、检索到的文档片段加起来轻松超过几万 tokens。我的应对策略是分层管理上下文系统提示和工具定义放在最前面这部分是固定的历史对话做滑动窗口只保留最近 N 轮检索结果做摘要压缩只保留最相关的片段。具体实现上可以用 tiktoken 来计算 token 数import tiktoken def count_tokens(text, modelgpt-4): encoding tiktoken.encoding_for_model(model) return len(encoding.encode(text))然后在组装请求前检查总 token 数超过阈值就触发压缩逻辑。这个做法虽然增加了代码复杂度但能有效避免因为超长导致的 400 错误。3.3 多模型路由与降级方案Agent 项目不建议只依赖一个模型 API。我的做法是配置多个模型提供商按优先级路由。主模型用能力强的备用模型用免费额度大的。当主模型返回错误或者超时自动切换到备用模型。实现上可以用一个简单的路由层class ModelRouter: def __init__(self, providers): self.providers providers def chat(self, messages, **kwargs): for provider in self.providers: try: return provider.chat(messages, **kwargs) except Exception as e: print(fProvider {provider.name} failed: {e}) continue raise Exception(All providers failed)这个模式在实际运行中救过我很多次。有一次主模型 API 临时维护因为配置了备用模型Agent 服务没有中断用户完全无感知。注意不同模型的输出格式可能有差异特别是工具调用的格式。做多模型路由时要在路由层做格式归一化否则 Agent 的工具解析逻辑会出错。4. 文档解析与数据获取 API 的集成方案4.1 MinerU 等文档解析 API 的使用场景Agent 经常需要处理 PDF、Word、PPT 等文档。这些文档的解析如果自己写工作量巨大而且效果很难保证。MinerU 这类文档解析 API 能把 PDF 转成结构化的 Markdown保留标题、表格、公式等元素非常适合喂给大模型。我试过用 MinerU 解析一份 50 页的技术文档输出质量比 PyPDF2 好很多表格没有错乱公式也保留了 LaTeX 格式。调用方式一般是先上传文件然后轮询解析结果import requests import time def parse_document(file_path, api_key): # 上传文件 with open(file_path, rb) as f: upload_resp requests.post( https://api.mineru.example/upload, headers{Authorization: fBearer {api_key}}, files{file: f} ) task_id upload_resp.json()[task_id] # 轮询结果 while True: result requests.get( fhttps://api.mineru.example/result/{task_id}, headers{Authorization: fBearer {api_key}} ).json() if result[status] completed: return result[markdown] time.sleep(2)这个轮询模式在文档解析 API 里很常见因为解析大文件需要时间。实际使用时要注意设置超时和重试避免无限等待。4.2 搜索增强 API 的接入与结果过滤Agent 做事实性回答时需要搜索 API 来获取最新信息。免费搜索 API 的选择不多但有一些开源方案可以自建比如 SearXNG。自建的好处是可控坏处是需要维护。如果不想自建也可以用一些平台提供的免费搜索额度。接入方式和普通 REST API 一样关键是结果过滤。搜索引擎返回的结果往往包含大量噪音直接喂给大模型会浪费 token 还影响效果。我的做法是先用规则过滤掉低质量结果比如域名黑名单、标题长度过短、摘要为空等然后再用大模型做相关性排序。def filter_search_results(results, min_score0.5): filtered [] for r in results: if len(r.get(title, )) 5: continue if not r.get(snippet): continue if r.get(score, 0) min_score: continue filtered.append(r) return filtered[:5]这个过滤逻辑看起来简单但实际效果很明显。过滤后的搜索结果喂给大模型回答准确率能提升不少。4.3 数据抓取 API 的合规使用边界Agent 做数据抓取时合规是底线。我的原则是只抓公开数据遵守 robots.txt控制请求频率不绕过任何反爬机制。有些平台提供官方 API优先用官方 API哪怕额度少一点也比抓页面稳定。拼多多等电商平台的 API 有严格的调用限制和权限要求个人开发者能拿到的权限有限。如果 Agent 需要电商数据建议先用官方开放平台提供的接口不要尝试非官方渠道。这不仅是合规问题也是稳定性问题——非官方渠道随时可能失效。5. 免费 API 组合在 Agent 项目中的实战集成5.1 一个完整的 Agent 工具链配置示例把上面这些 API 组合起来一个典型的 Agent 工具链配置大概是这样的agent: model: primary: deepseek-chat fallback: zhipu-glm tools: - name: code_search api: github_accelerated - name: doc_parse api: mineru - name: web_search api: searxng_selfhosted - name: repo_clone api: gitee_mirror context: max_tokens: 32000 compression: sliding_window这个配置覆盖了 Agent 最常用的几类工具。实际运行时模型路由层负责切换模型工具层负责调用各个 API上下文管理层负责控制 token 数。5.2 并发控制与限流处理免费 API 通常有并发限制Agent 如果同时发起多个工具调用很容易触发限流。我的做法是在工具调用层加一个信号量控制同时进行的请求数import asyncio class RateLimiter: def __init__(self, max_concurrent3): self.semaphore asyncio.Semaphore(max_concurrent) async def call(self, func, *args, **kwargs): async with self.semaphore: return await func(*args, **kwargs)这个简单的信号量能有效避免因为并发过高导致的 429 错误。实测下来把并发控制在 3 以内免费 API 基本不会触发限流。5.3 缓存策略降低 API 消耗Agent 运行过程中有很多重复请求比如同一个文档被多次解析、同一个搜索词被多次查询。加一层缓存能显著降低 API 消耗。我用的是本地文件缓存加内存缓存的双层结构import hashlib import json import os class APICache: def __init__(self, cache_dir./cache): self.cache_dir cache_dir os.makedirs(cache_dir, exist_okTrue) self.memory {} def _key(self, params): return hashlib.md5(json.dumps(params, sort_keysTrue).encode()).hexdigest() def get(self, params): key self._key(params) if key in self.memory: return self.memory[key] path os.path.join(self.cache_dir, key) if os.path.exists(path): with open(path) as f: result json.load(f) self.memory[key] result return result return None def set(self, params, result): key self._key(params) self.memory[key] result path os.path.join(self.cache_dir, key) with open(path, w) as f: json.dump(result, f)这个缓存层让我的 API 调用量减少了大约 40%对于免费额度有限的场景来说效果非常明显。6. 常见问题与排查技巧实录6.1 API 调用失败的典型原因与排查路径免费 API 调用失败的原因五花八门我整理了一个排查顺序按这个顺序查基本能定位到问题排查步骤检查内容常见问题1API Key 是否有效过期、额度用完、复制时多了空格2请求格式是否正确JSON 格式错误、字段名拼写错误3网络是否可达DNS 解析失败、连接超时4是否触发限流返回 429、并发过高5参数是否超限上下文超长、文件过大6服务端是否正常查看服务状态页、社区反馈这个顺序是从客户端到服务端从简单到复杂。大部分问题在前三步就能解决。6.2 免费额度用尽后的应对方案免费额度用尽是迟早的事关键是要有预案。我的做法是设置额度监控当剩余额度低于 20% 时触发告警然后自动切换到备用方案。备用方案可以是另一个免费 API也可以是本地部署的小模型。本地部署小模型作为兜底是个不错的选择。用 Ollama 跑一个 7B 的模型虽然能力不如大模型但处理简单任务足够了。切换逻辑可以做成配置项通过环境变量控制import os MODEL_PROVIDER os.getenv(MODEL_PROVIDER, deepseek) if MODEL_PROVIDER deepseek: from providers.deepseek import DeepSeekProvider provider DeepSeekProvider() elif MODEL_PROVIDER ollama: from providers.ollama import OllamaProvider provider OllamaProvider()这样切换只需要改环境变量不需要改代码。6.3 我踩过的三个坑与避坑建议第一个坑是 API Key 硬编码在代码里。有一次我把代码推到公开仓库结果 API Key 泄露被人刷了几百块的额度。后来我改用环境变量加.env文件并且把.env加入.gitignore。这个教训很深刻建议大家从一开始就养成好习惯。第二个坑是没做超时设置。免费 API 有时候响应很慢如果不设超时Agent 会一直卡在那里。我现在所有 API 调用都设 30 秒超时超时后自动重试或降级。第三个坑是忽略了 API 的版本变化。有些免费 API 会不定期调整接口格式如果不关注更新日志某天突然就调不通了。我的做法是订阅服务方的公告并且在代码里做好版本兼容。提示建议给每个 API 调用都加上日志记录包括请求参数、响应状态、耗时。出问题时这些日志就是最好的排查依据。7. 关于 API 组合策略的一些个人体会这套免费 API 组合我用了大半年整体稳定性还不错。最大的感受是免费 API 的关键不在于单个 API 有多强而在于组合策略是否合理。一个 API 挂了另一个能顶上一个额度用完了另一个能接替。这种冗余设计比追求单个 API 的极致性能更重要。另外免费 API 的额度是有限的但 Agent 的创造力是无限的。与其纠结额度不够不如想想怎么用更少的调用做更多的事。缓存、压缩、批处理这些优化手段的效果往往比换一个额度更大的 API 更明显。最后分享一个小技巧很多免费 API 的额度是按自然月重置的如果你在月底把额度用完了可以先把非紧急的任务攒到月初再跑。这个策略听起来简单但实际用起来能省下不少额度。