1. 项目概述一个免费、可自部署的Web搜索技能最近在折腾AI Agent和智能助手发现一个挺普遍的需求让AI能联网搜索。市面上方案不少但要么收费要么限制多要么就是得自己从零开始搭一套复杂的爬虫和解析系统对个人开发者或小团队来说门槛不低。直到我发现了这个叫roryyu/websearch-free-skill的项目眼前一亮。这本质上是一个为AI Agent特别是基于composio或类似框架的Agent设计的、开箱即用的Web搜索技能Skill。简单来说它帮你封装好了从发起搜索请求到获取搜索结果再到解析网页内容这一整套流程。你不需要去研究各个搜索引擎的API很多已经收费或限制严格也不用头疼怎么从杂乱无章的HTML里提取出干净、结构化的文本。这个技能包直接提供了一个标准化的“搜索”动作你的Agent调用它它返回整理好的信息Agent再基于这些信息进行思考或回答。最吸引人的是它标榜“免费”和“可自部署”这意味着你可以完全掌控数据流和成本不用担心额度问题也能根据自己需求进行定制。这个项目非常适合那些正在构建个人AI助手、自动化研究工具、信息聚合Bot或者任何需要让AI获取实时信息的开发者。如果你厌倦了为搜索API付费或者担心现成服务的稳定性和隐私问题那么自己部署一个这样的技能会是一个既经济又安心的选择。接下来我就结合自己的部署和调试经验把这个项目的里里外外、关键细节和踩过的坑给大家完整拆解一遍。2. 核心架构与工作原理拆解在动手部署之前我们先得搞清楚websearch-free-skill到底是怎么工作的。它不是魔法其核心是巧妙地组合了几项成熟的开源技术并将它们封装成一个统一的接口。2.1 技术栈构成与选型理由这个项目主要依赖于以下几个核心组件SearXNG 这是整个技能的“搜索引擎心脏”。SearXNG是一个开源的元搜索引擎它本身不爬取网页而是将用户的查询同时发送给Google、Bing、DuckDuckGo、Wikipedia等数十个公开的搜索引擎然后聚合、去重、排序返回结果。它的关键优势在于隐私友好默认不记录用户IP、搜索历史也不使用追踪器。无商业广告返回结果纯净。可自托管这是实现“免费”和“可控”的基石。你部署自己的SearXNG实例就拥有了一个私有的、无查询限制的搜索入口。API支持提供了简洁的JSON API方便程序调用。Firecrawl 这是技能的“内容抓取与解析器”。SearXNG返回的只是包含标题、链接和摘要的搜索结果列表。要获取链接指向的网页的详细内容就需要爬取和解析。Firecrawl或其开源版本是一个专门为LLM应用设计的爬虫框架它能智能解析不是简单地下载HTML而是能识别并提取出文章的主体内容过滤掉导航栏、广告、侧边栏等噪音。结构化输出可以将网页内容转换成干净的Markdown或纯文本格式非常适合后续交给AI模型处理。处理JavaScript对于现代动态网页如用React、Vue.js构建的它能通过无头浏览器如Playwright渲染后抓取确保拿到完整内容。Composio或类似Agent框架的Skill SDK 这是技能的“标准化外壳”。websearch-free-skill项目是按照Composio这个AI Agent工具平台的规范编写的。Skill SDK定义了一个技能应该有哪些元数据名称、描述、需要哪些输入参数比如搜索关键词、结果数量、会输出什么格式的数据。这样任何兼容Composio的Agent都能像调用本地函数一样轻松地调用这个搜索技能而不必关心背后的SearXNG和Firecrawl是如何协作的。为什么是这样一个组合这个选型非常务实。直接调用商业搜索引擎API如Google Custom Search JSON API有严格的每日免费限额超出后费用不菲。而利用开源的SearXNG作为代理本质上是利用了各大搜索引擎对普通浏览器访问的宽容策略绕开了API限制实现了“免费”。Firecrawl则解决了从“链接”到“可用内容”这个最棘手的环节。最后通过Skill SDK封装极大降低了集成复杂度让开发者能聚焦在Agent的逻辑本身。2.2 工作流程与数据流转一次完整的搜索调用其内部流程是这样的接收指令你的AI Agent决定需要进行一次Web搜索于是它按照Skill的规范构造一个请求包含query搜索词、num_results需要几条结果等参数调用websearch-free-skill。发起搜索Skill接收到请求后首先向你自己部署的SearXNG实例的API端点发送搜索请求。聚合结果SearXNG实例将查询分发给其配置的后端搜索引擎如Google, Bing收集它们的返回结果经过排序和去重后将前N条结果的标题、链接、摘要封装成JSON返回给Skill。抓取内容Skill拿到结果链接列表并不是直接返回给Agent。为了提供更丰富的信息它会选取前几条例如前3条最相关的链接调用Firecrawl服务去分别抓取这些链接对应网页的详细内容。解析与格式化Firecrawl访问目标网页执行渲染如果需要然后运用其解析算法提取核心正文并将其转换为干净的文本或Markdown。整合返回Skill将SearXNG返回的原始结果列表包含所有结果的链接和摘要和Firecrawl抓取到的详细内容针对部分结果整合在一起结构化地返回给调用它的AI Agent。Agent处理AI Agent收到这份结构化的搜索报告里面既有概括性的结果列表也有具体网页的深度内容它便可以综合这些信息生成更准确、更全面的回答。注意步骤4和5即调用Firecrawl进行深度抓取通常是可配置的。如果只是为了快速获取链接列表或者目标网站反爬严重可以关闭这个功能只返回SearXNG的聚合结果这样速度更快但对Agent的信息支持会弱一些。3. 从零开始部署环境准备与配置详解理解了原理我们就可以动手搭建自己的“免费搜索技能”了。整个过程可以分为三个主要部分部署SearXNG、部署Firecrawl、以及配置和运行websearch-free-skill本身。3.1 部署私有SearXNG搜索引擎SearXNG的部署方式很多这里推荐使用Docker最为简单快捷。1. 安装Docker与Docker Compose确保你的服务器或本地开发机已经安装了Docker和Docker Compose。你可以通过运行docker --version和docker-compose --version来检查。2. 创建SearXNG配置目录mkdir searxng cd searxng3. 获取官方Docker Compose配置SearXNG官方提供了示例的docker-compose.yaml文件。我们基于此进行修改。# 下载官方示例文件 curl -o docker-compose.yaml https://raw.githubusercontent.com/searxng/searxng-docker/master/docker-compose.yaml # 下载环境变量示例文件 curl -o .env https://raw.githubusercontent.com/searxng/searxng-docker/master/.env4. 关键配置修改编辑.env文件有几个关键设置需要关注# 设置一个安全的密钥用于会话加密等。可以用 openssl rand -hex 32 生成。 SEARXNG_SECRET_KEY你的32位十六进制密钥 # 将SearXNG设置为公开可用如果你希望从外网访问或者仅限本地。 SEARXNG_BASE_URLhttp://你的服务器IP:8080/ # 非常重要启用JSON格式的搜索API这是Skill调用的基础。 SEARXNG_SETTINGS{ search: { formats: [html, json] } }编辑docker-compose.yaml确保端口映射正确比如将容器内的8080端口映射到主机的8080端口。5. 启动SearXNGdocker-compose up -d等待片刻访问http://你的服务器IP:8080你应该能看到SearXNG的搜索界面。尝试搜索一下确认功能正常。6. 获取API访问地址Skill调用的是SearXNG的JSON API端点。其地址格式为http://你的服务器IP:8080/search?q关键词formatjson。你可以直接在浏览器中测试这个链接看看返回的JSON数据是否正常。实操心得在云服务器上部署时务必在安全组或防火墙中开放你映射的端口如8080。另外SearXNG的默认配置可能访问某些搜索引擎不稳定你可以在其管理界面/preferences的“引擎”选项卡中禁用一些不常用或经常超时的引擎只保留Google、Bing、DuckDuckGo等核心引擎能提升搜索速度和稳定性。3.2 部署Firecrawl爬虫服务Firecrawl提供了多种部署方式包括云服务付费和自托管开源版本。websearch-free-skill通常对接其开源版本。1. 克隆Firecrawl开源仓库git clone https://github.com/mendableai/firecrawl cd firecrawl2. 使用Docker Compose启动Firecrawl项目也提供了docker-compose.yml文件使得部署非常方便。# 直接使用docker-compose启动所有服务包括API服务器、爬虫worker、Redis队列等 docker-compose up -d这个过程会拉取多个镜像包括Playwright用于渲染JS网页所以首次启动可能需要一些时间。3. 验证Firecrawl服务默认情况下Firecrawl的API服务器运行在3002端口。你可以通过一个简单的cURL命令测试它是否工作curl -X POST http://localhost:3002/v1/scrape \ -H Content-Type: application/json \ -d {urls: [https://example.com]}如果返回了包含网页内容和元数据的JSON说明Firecrawl服务部署成功。4. 关键配置说明Firecrawl的配置主要在docker-compose.yml和其环境变量中。对于基础使用默认配置通常足够。但如果你需要处理大量请求或特定网站可能需要调整WORKER_CONCURRENCY: 控制同时爬取的worker数量。PLAYWRIGHT_HEADLESS: 是否以无头模式运行浏览器一般设为true。你可以在docker-compose.yml中映射自己的配置文件来设置请求头、超时时间、代理等高级选项以应对反爬策略。注意事项Firecrawl自托管版本需要处理网页渲染对服务器CPU和内存有一定要求。对于简单的静态网页负载很轻但如果频繁抓取复杂的单页应用SPA资源消耗会显著上升。建议在配置不低于2核4G的服务器上运行。3.3 配置与运行websearch-free-skill前两步是搭建基础设施现在我们来安装和配置技能本身。1. 获取技能代码git clone https://github.com/roryyu/websearch-free-skill.git cd websearch-free-skill2. 安装Python依赖项目根目录下会有requirements.txt文件。pip install -r requirements.txt3. 配置环境变量这是连接技能与SearXNG、Firecrawl的关键。你需要创建一个.env文件或者直接导出环境变量。# 复制示例环境文件如果项目提供 cp .env.example .env # 编辑 .env 文件填入你的服务地址 SEARXNG_BASE_URLhttp://你的服务器IP:8080 # 你的SearXNG实例地址 FIRECRAWL_API_URLhttp://你的服务器IP:3002 # 你的Firecrawl API地址 # 如果Firecrawl需要API密钥云服务版在这里设置 # FIRECRAWL_API_KEYyour_firecrawl_api_keySEARXNG_BASE_URL 指向你刚刚部署的SearXNG实例。技能会向{SEARXNG_BASE_URL}/search?formatjson发送请求。FIRECRAWL_API_URL 指向你部署的Firecrawl服务的API地址。技能会向{FIRECRAWL_API_URL}/v1/scrape发送抓取请求。4. 理解技能代码结构通常一个Composio Skill的核心是一个skill.py文件里面定义了class WebSearchFreeSkill: 技能主类。action装饰器 标记一个可被调用的动作比如search。schema: 定义动作的输入参数如query: str,num_results: int和输出格式。 你需要检查代码确认它如何读取环境变量、如何调用SearXNG和Firecrawl的API。5. 本地测试技能在运行Agent之前最好先单独测试一下技能是否正常工作。你可以写一个简单的Python脚本import asyncio import os from skill import WebSearchFreeSkill # 根据实际文件导入 async def test(): skill WebSearchFreeSkill() # 调用技能的search动作 result await skill.actions.search(query什么是大型语言模型, num_results3) print(result) if __name__ __main__: asyncio.run(test())运行这个脚本观察输出。它应该会打印出包含搜索结果和抓取内容的字典。如果报错根据错误信息检查环境变量配置、网络连通性技能能否访问到SearXNG和Firecrawl服务以及依赖包版本。4. 集成到AI Agent以Composio为例技能部署测试成功后下一步就是把它“装配”到你的AI Agent上。这里以Composio框架为例展示集成过程。4.1 在Composio平台注册技能Composio作为一个中心化的技能市场和管理平台简化了集成。创建Toolset 登录Composio平台创建一个新的Toolset工具集给它起个名字比如my-websearch-tools。添加本地技能 在Toolset中选择添加技能。由于websearch-free-skill是一个本地/自定义技能你需要通过“Custom Skill”或“Git Repo”的方式添加。方式一推荐 如果你的技能代码已经在GitHub等公开仓库可以直接提供仓库URL。Composio可以拉取代码并识别其中的Skill定义。方式二 如果代码在本地你需要按照Composio的CLI工具指引将技能打包并推送到平台。通常需要安装composio-cli在技能目录下运行composio push等命令。配置连接器 添加技能后你需要为这个技能配置一个“连接器”Connector。对于自托管的技能连接器通常是一个运行在你本地的守护进程composio-local它负责在Composio云平台和你的本地技能服务之间建立安全隧道。你需要按照指引下载并运行这个本地连接器并让它与你刚创建的Toolset关联。获取API密钥 集成完成后Composio会为这个Toolset生成一个API密钥。你的Agent代码将使用这个密钥来调用Toolset里的所有技能。4.2 在Agent代码中调用搜索技能假设你使用OpenAI的Assistant API或LangChain来构建Agent集成Composio技能非常直观。示例使用Composio Python SDKimport os from composio import Composio from composio.openai import ComposioToolSet # 1. 初始化Composio客户端使用你的API密钥 COMPOSIO_API_KEY os.getenv(COMPOSIO_API_KEY) composio Composio(api_keyCOMPOSIO_API_KEY) # 2. 获取你创建的Toolset toolset composio.get_toolset(my-websearch-tools) # 替换为你的Toolset名称 # 3. 将Toolset中的工具即我们的websearch技能注册到你的AI框架 # 这里以LangChain为例 from langchain.agents import initialize_agent, AgentType from langchain_openai import ChatOpenAI llm ChatOpenAI(modelgpt-4, temperature0) # 通过ComposioToolSet将工具转换为LangChain可用的格式 lc_tools ComposioToolSet(toolsettoolset).get_langchain_tools() # 4. 创建并运行Agent agent initialize_agent( toolslc_tools, llmllm, agentAgentType.STRUCTURED_CHAT_ZERO_SHOT_REACT_DESCRIPTION, verboseTrue ) # 5. 现在Agent在思考过程中如果需要搜索就会自动调用我们的websearch技能了 response agent.run(帮我搜索一下今天关于AI芯片的最新新闻并总结要点。) print(response)当Agent执行到需要信息的步骤时它会自动触发websearch-free-skill的search动作。Composio的本地连接器会收到请求转发给你本地运行的技能服务技能服务执行搜索和抓取再将结果通过连接器返回给Composio平台最终送达你的Agent。整个过程对开发者几乎是透明的你只需要关注Agent的逻辑本身。5. 高级配置、优化与故障排查基础部署完成后为了获得更稳定、更高效的搜索体验还需要进行一些优化和问题处理。5.1 性能与稳定性调优SearXNG优化引擎选择 在SearXNG管理界面 (/preferences) 的“引擎”页只启用google,bing,duckduckgo等少数稳定、快速的引擎。禁用不必要或响应慢的引擎可以大幅减少搜索延迟和超时。超时设置 在SearXNG的配置文件 (settings.yml) 中可以调整server.limiter和引擎的timeout设置避免因个别引擎无响应而拖慢整个搜索请求。使用缓存 启用SearXNG的结果缓存对于热门查询可以显著提速。Firecrawl优化并发控制 在docker-compose.yml中调整WORKER_CONCURRENCY环境变量。不要设置过高以免爬虫行为过于激进导致IP被目标网站封禁。通常2-4个并发worker对于个人使用足够了。请求速率限制 Firecrawl支持设置全局或针对特定域名的请求延迟 (delay)。在配置文件中添加适当的延迟如1000毫秒是遵守网站robots.txt、体现良好网络公民行为的关键也能避免被封。超时与重试 配置合理的请求超时时间和重试策略以应对网络波动或网站暂时不可用的情况。技能层优化异步处理 确保websearch-free-skill的代码是异步的使用async/await这样在等待网络I/O搜索、抓取时不会阻塞。结果缓存 可以考虑在技能层面为相同的搜索查询添加一个短期缓存例如使用functools.lru_cache或Redis在几分钟内重复的查询直接返回缓存结果减少对后端服务的压力。限制抓取深度 在技能代码中严格控制调用Firecrawl抓取详细内容的页面数量。默认抓取前3条结果的内容通常是合理的平衡点。抓取全部结果会非常慢且消耗资源。5.2 常见问题与解决方案实录在实际部署和使用中我遇到了不少问题这里总结一下问题1SearXNG搜索返回空结果或速度极慢。排查 首先直接在浏览器访问你的SearXNG实例进行相同关键词搜索看网页版是否正常。如果不正常问题在SearXNG本身。可能原因与解决网络问题 你的服务器可能无法访问某些搜索引擎如Google。尝试在SearXNG后台切换使用不同的搜索引擎或者检查服务器网络。引擎失效 某些SearXNG内置的引擎可能已经失效。进入SearXNG的“引擎”设置禁用所有引擎然后只重新启用google,bing,duckduckgo等核心引擎进行测试。被屏蔽 如果你的服务器IP发送的搜索请求过于频繁可能被搜索引擎临时屏蔽。尝试为SearXNG配置代理在settings.yml中设置outgoing.proxy。问题2Firecrawl抓取失败返回超时或空内容。排查 直接用cURL调用Firecrawl API尝试抓取一个简单网站如https://example.com和一个复杂网站如一个新闻站。可能原因与解决Playwright问题 Firecrawl依赖Playwright来渲染JS。确保Docker镜像正确包含了Playwright和浏览器。可以进入Firecrawl的容器内手动运行Playwright命令测试。网站反爬 目标网站可能检测到无头浏览器或来自数据中心的流量。尝试在Firecrawl配置中设置更真实的User-Agent头或者启用stealth模式如果Firecrawl支持。资源不足 抓取复杂JS网页非常消耗内存和CPU。检查服务器资源使用情况必要时升级配置或减少并发worker数。超时设置太短 对于加载慢的页面增加Firecrawl请求的超时时间。问题3技能运行时抛出依赖错误或模块找不到。排查 仔细查看错误堆栈确认是哪个Python包缺失或版本冲突。解决确保在正确的Python虚拟环境中安装依赖。检查requirements.txt中的包版本有时需要根据你的Python版本进行微调。可以尝试先安装基础版本pip install composio-sdk requests aiohttp再根据报错信息逐个解决。问题4Agent调用技能时超时或无响应。排查 这是一个链条问题。需要分段排查。测试技能本身 用第3.3节的测试脚本直接运行看是否正常。测试Composio本地连接器 检查连接器进程是否在运行日志是否有报错。尝试通过Composio平台的测试功能手动触发一次技能调用。检查网络 确保运行Agent的机器能访问到SearXNG和Firecrawl的服务地址和端口。防火墙或安全组规则是常见阻碍。解决 根据分段测试的结果定位问题环节。最常见的是网络连通性问题或Composio连接器配置错误。5.3 扩展可能性超越基础搜索websearch-free-skill提供了一个很好的起点但你完全可以基于它进行扩展结果后处理 在技能返回结果给Agent之前可以添加一个后处理步骤。例如使用一个轻量级的文本摘要模型如BART对Firecrawl抓取的长文进行摘要只把核心摘要发给Agent节省上下文窗口。多模态搜索 修改技能使其不仅能搜索网页文本还能通过SearXNG的“图像搜索”或“视频搜索”功能获取图片或视频信息并整合到返回结果中。垂直领域增强 如果你专注于某个领域如学术、电商可以配置SearXNG优先使用该领域的垂直搜索引擎如Google Scholar并在Firecrawl的解析规则中针对该领域常见网站如arXiv, Amazon编写特定的内容提取规则获得更精准的信息。与知识库结合 将搜索技能与本地知识库如用ChromaDB、Pinecone存储的向量数据库结合。Agent可以先在本地知识库中检索如果找不到或信息过时再触发Web搜索并将搜索得到的新知识存入知识库实现信息的持续更新和积累。部署和调试这样一个系统确实需要一些耐心尤其是当SearXNG或Firecrawl的某个环节出问题时。但一旦跑通你就拥有了一个完全受控、免费、强大的AI信息获取渠道。这种将开源工具链组合起来解决实际问题的过程本身也是极佳的学习和锻炼。