零成本自建AI代理搜索引擎：基于SearXNG与Redis缓存的实战方案

1. 项目概述：零成本自建AI代理搜索引擎

如果你正在开发一个需要联网搜索功能的AI应用，比如智能客服、研究助手或者一个能自动获取最新信息的聊天机器人，那么你一定对搜索API的成本感到头疼。市面上的主流方案，无论是Brave、Tavily还是Google Custom Search，价格基本都在每千次搜索5美元左右。对于一个日活用户上千的应用来说，这笔开销会迅速累积，成为一笔不小的运营负担。我自己在搭建SuperClawHub平台时就深有体会，当用户量起来后，搜索成本几乎成了每月账单里最刺眼的一项。

这个项目就是为了解决这个问题而生的。它不是一个简单的想法，而是一个已经在生产环境（SuperClawHub.com）中经过实战检验的完整解决方案。核心思路很简单：与其依赖昂贵的第三方API，不如自己搭建一个。我们利用开源的元搜索引擎SearXNG作为搜索后端，它能够聚合Google、Bing、DuckDuckGo等多个搜索引擎的结果，且完全免费。然后，我们在这个基础上，构建了一个包含缓存、用户配额管理和API代理层的生产级应用栈。最终效果是，你的AI代理可以获得稳定、高质量的网页搜索结果，而你的成本，从按次付费变成了固定且极低的服务器开销——每月大约5到10美元。

简单来说，这个项目提供了一套开箱即用的代码和配置，让你能在自己的服务器上，快速部署一个专为AI代理设计的、带缓存和配额管理的免费搜索引擎。无论你用的是OpenClaw、LangChain、CrewAI还是其他任何AI框架，都能轻松集成。

2. 核心架构与设计思路拆解

2.1 为什么选择SearXNG作为搜索核心？

在决定自建搜索服务时，后端引擎的选择是关键。我们评估过直接爬取、使用单个搜索引擎的未公开API等多种方案，但最终选择了SearXNG，主要基于以下几点考量：

首先是成本与可持续性。直接使用各大搜索引擎的官方API固然稳定，但成本高昂且有调用限制。而像直接爬取Google这样的方式，不仅违反服务条款，还极易因反爬策略导致IP被封，维护成本极高。SearXNG采取了一种巧妙的“中间层”策略：它模拟普通浏览器的行为向各大搜索引擎发起请求，然后解析返回的HTML页面来提取搜索结果。这种方式不依赖任何付费API，实现了真正的零按次付费。虽然搜索引擎可能会对高频请求进行限制，但SearXNG通过轮询多个引擎、使用随机User-Agent等策略，极大地提高了可用性和抗封禁能力。

其次是结果质量与多样性。单一的搜索引擎结果可能存在偏见或不够全面。SearXNG作为元搜索引擎，可以同时向Google、Bing、DuckDuckGo、Brave等发起查询，并将结果去重、排序后聚合返回。这意味着一次搜索就能获得多角度的信息，对于需要高准确性和全面性的AI应用来说，价值巨大。例如，搜索一个科技新闻，你可能会同时得到来自主流媒体（Google/Bing）和注重隐私的独立媒体（DuckDuckGo）的报道，信息维度更丰富。

最后是开源与可定制性。SearXNG是AGPL-3.0协议下的开源项目，这意味着我们可以完全掌控它。我们可以自定义启用的搜索引擎、调整结果排序算法、修改前端界面，甚至根据业务需求深度定制。项目中的searxng/settings.yml文件就是我们对SearXNG的定制配置，已经预先优化好了用于AI代理的引擎组合（Web搜索+Wikipedia+新闻）。

注意：使用SearXNG需要对其工作原理有正确认识。它提供的是一种“公平使用”的访问方式，适用于中小流量场景。如果你的应用预期会产生极其巨大的搜索量（例如日均超数万次），可能需要考虑部署多个SearXNG实例进行负载均衡，并严格遵守robots.txt，以避免对上游搜索引擎造成过大压力。

2.2 生产级增强层：缓存与配额管理

直接使用裸奔的SearXNG实例给AI代理调用，在生产环境中是行不通的。这主要会带来三个问题：1) 性能瓶颈，每次搜索都进行完整的网络请求和解析，延迟高；2) 成本风险，无限制的调用可能导致上游搜索引擎限制你的IP；3) 商业逻辑缺失，无法区分付费用户和免费用户。因此，我们在SearXNG之上构建了两个核心增强层。

Redis缓存层。这是提升性能和降低上游压力的关键。想象一下，你的100个用户在同一分钟内搜索了“今天天气怎么样”，如果没有缓存，SearXNG会向Google等引擎发起100次相同的查询。而有了缓存，只有第一次查询会真正到达SearXNG和上游引擎，随后的99次都会从Redis中毫秒级返回结果。我们采用的策略是对查询关键词进行规范化（如转为小写、去除多余空格）后计算SHA-256哈希值作为缓存键，并设置30分钟的过期时间（TTL）。这个时间长度对于新闻、实时信息可能略长，但对于大多数知识性、百科类查询已经足够，能在性能和数据新鲜度之间取得很好的平衡。代码中的src/redis-client.ts还实现了优雅降级：即使Redis服务暂时不可用，搜索功能依然能正常工作，只是没有缓存效果，保证了系统的鲁棒性。

用户配额管理系统。这是将免费服务转化为可控商业服务的基础。我们在src/search-proxy.ts中实现了基于用户订阅等级的每日搜索次数限制。例如，试用用户每天只能搜索20次，而高级付费用户可能拥有1000次。这个计数是通过Redis实现的：为每个用户（通过用户ID标识）创建一个计数器键，并设置25小时的TTL。选择25小时而非24小时，是为了避免在午夜重置时出现临界时间点的竞争条件。每次用户发起搜索，系统会先检查其当日已用额度，如果未超限，则执行搜索并增加计数；如果超限，则直接返回额度已用尽的错误。这套机制简单有效，并且能无缝集成到你现有的用户认证系统（如JWT）中。

2.3 整体数据流与组件职责

理解整个系统如何协同工作，有助于你在调试和扩展时胸有成竹。整个数据流是一个清晰的管道：

1. 请求发起：你的AI代理（例如一个OpenClaw助手）决定需要搜索“最新的深度学习框架”，于是调用其内置的web_search工具。
2. 代理层接收：工具调用被路由到你后端部署的src/search-route.ts提供的API端点（例如POST /api/search）。该端点会进行请求验证、用户身份鉴权（通过Authorization头）和基础速率限制。
3. 业务逻辑处理：请求被转发到src/search-proxy.ts中的核心search函数。该函数依次执行以下逻辑：
   • 配额检查：根据用户ID，查询Redis中该用户当日的搜索计数，判断是否超出其套餐限制。
   • 缓存查询：将用户查询语句规范化并哈希，用此哈希值作为键去Redis中查询是否有缓存结果。
   • 缓存命中：如果找到缓存，立即返回缓存的结果，并在响应中标记"cached": true。注意，缓存命中通常不会消耗用户配额，这是为了提升付费用户体验的常见设计，具体逻辑可根据业务调整。
   • 缓存未命中：如果缓存中没有，则准备调用SearXNG。首先，更新用户的搜索计数（+1）。然后，构造请求调用SearXNG实例的JSON API接口。
4. 搜索执行：SearXNG服务（运行在Docker容器内）收到请求。它根据settings.yml配置，同时向已启用的多个搜索引擎（如Google, Bing）发起异步请求。
5. 结果聚合：SearXNG收集所有引擎的返回结果，进行去重、排序和格式化，最终生成一个结构化的JSON数组，包含标题、链接、摘要等信息。
6. 结果返回与缓存：SearXNG的结果返回到search函数。函数首先将这些结果存入Redis（键为查询哈希，值为结果JSON，TTL为30分钟）。然后，将结果返回给API路由。
7. 响应最终用户：API路由将最终结果包装成标准格式，返回给AI代理。AI代理收到结构化的搜索结果，可以将其作为上下文信息，生成更准确、信息更丰富的回复。

这个流程确保了每一次搜索都经过了配额控制、缓存优化，并且最终获得的是多引擎聚合的高质量结果。

3. 从零开始的详细部署与集成指南

3.1 本地开发环境搭建（Docker Compose）

对于开发和测试，使用Docker Compose是最快、最干净的方式。它能确保你的本地环境与生产环境高度一致。

首先，克隆项目仓库并进入目录：

git clone https://github.com/HeavenFYouMissed/free-ai-search.git cd free-ai-search

在启动之前，我强烈建议你先花一分钟浏览一下docker-compose.yml文件。你会看到它定义了两个服务：searxng和redis。SearXNG服务使用了官方镜像，并将本地的searxng目录（内含定制的settings.yml）挂载到容器内以覆盖默认配置。Redis服务则使用官方镜像并提供持久化存储。

现在，一键启动所有服务：

docker compose up -d

-d参数代表在后台运行。执行后，Docker会拉取镜像（如果本地没有）并启动容器。你可以使用docker compose ps来查看服务状态，确认两者都是“Up”状态。

接下来进行功能验证。我们通过curl直接测试SearXNG实例是否工作：

curl "http://localhost:8080/search?q=openai+latest+news&format=json" | jq '.results[0:2]'

这个命令向本地的SearXNG发起一个搜索“openai latest news”的请求，并要求返回JSON格式。jq是一个命令行JSON处理工具，.results[0:2]表示只提取结果数组的前两项。如果一切正常，你将看到包含标题、链接和摘要的JSON输出。如果没有安装jq，可以去掉| jq ‘.results[0:2]’部分，你会看到完整的JSON响应。

实操心得：第一次启动时，SearXNG可能需要几秒钟来初始化。如果curl返回连接拒绝错误，请稍等片刻再重试。你也可以直接打开浏览器访问http://localhost:8080，可以看到SearXNG的搜索界面，进行手动搜索测试，这能更直观地确认服务正常。

3.2 将搜索代理集成到你的后端应用

本地服务跑通后，下一步就是把搜索功能集成到你自己的AI应用后端中。项目src/目录下的三个文件是核心。

第一步：复制文件。将src/search-proxy.ts、src/redis-client.ts和src/search-route.ts复制到你现有Node.js/TypeScript后端项目的相应目录（例如src/services/search/）。

第二步：配置环境变量。在你的后端项目根目录创建或修改.env文件，添加以下配置：

# 指向你运行的SearXNG实例地址 SEARXNG_BASE_URL=http://localhost:8080 # 指向你运行的Redis实例地址 REDIS_URL=redis://localhost:6379 # 可选：设置默认的搜索结果数量上限 DEFAULT_MAX_RESULTS=10

REDIS_URL的格式是标准的Redis连接字符串。如果你的Redis有密码，格式应为redis://:password@hostname:port。

第三步：安装依赖。确保你的项目已安装必要的npm包：

npm install redis axios # 如果使用TypeScript，还需要对应的类型定义 npm install --save-dev @types/redis @types/node

第四步：在业务逻辑中调用。现在，你可以在处理AI代理工具调用的地方，引入并使用搜索函数了。假设你有一个处理“web_search”工具的处理器：

// 在你的工具处理文件中，例如 tool-handler.ts import { search } from './services/search/search-proxy'; // 根据你的实际路径调整 async function handleWebSearchTool(query: string, userId: string) { try { // 调用搜索代理，传入查询词、用户ID和想要的最大结果数 const searchResult = await search(query, userId, 5); if (!searchResult.success) { // 处理失败情况，例如配额不足、网络错误等 return `搜索失败: ${searchResult.error}`; } // 将搜索结果格式化为AI代理易于理解的文本 let formattedResults = `关于"${searchResult.query}"，我找到了以下信息：\n`; searchResult.results.forEach((result, index) => { formattedResults += `\n${index + 1}. **${result.title}**\n`; formattedResults += ` 链接: ${result.url}\n`; formattedResults += ` 摘要: ${result.snippet}\n`; }); if (searchResult.cached) { formattedResults += `\n（注：本次结果来自缓存）`; } return formattedResults; } catch (error) { console.error('搜索处理异常:', error); return '抱歉，搜索服务暂时不可用。'; } }

这个示例展示了如何将结构化的搜索结果转换为一段富含信息的文本，供AI模型生成最终回复。searchResult.cached标志位在调试和监控时非常有用。

3.3 生产环境部署（以Railway为例）

本地测试完成后，就可以部署到生产环境了。这里以Railway为例，因为它对Docker和微服务架构的支持非常友好，且部署流程简单。其他平台（如Fly.io、Render或你自己的VPS）步骤也类似。

1. 准备你的后端应用：确保你的后端应用代码已经在一个Git仓库中（例如GitHub），并且包含了我们集成的搜索代理代码。

2. 在Railway中创建项目并关联仓库：登录Railway，点击“New Project”，选择“Deploy from GitHub repo”，关联你的代码仓库。

3. 添加Redis服务：在Railway项目仪表板，点击“+ New”，选择“Database”，然后添加一个“Redis”数据库。Railway会自动为你创建并注入REDIS_URL环境变量到你的主服务中。记下这个变量名。

4. 部署SearXNG服务：我们需要为SearXNG单独部署一个服务。在同一个Railway项目中，再次点击“+ New”，这次选择“Empty Service”。在新建的服务中，你需要：

• 在“Settings”页签下，将“Build Command”留空，将“Start Command”设置为docker run -p 8080:8080 -e "INSTANCE_NAME=MySearch" searxng/searxng:latest。这告诉Railway直接运行SearXNG的官方Docker镜像。
• 在“Variables”页签下，添加一个环境变量PORT=8080。
• 在“Networking”页签下，添加一个自定义域名，或者记下Railway为这个服务生成的默认域名（如https://searxng-production.up.railway.app）。这个域名就是你的SEARXNG_BASE_URL。

5. 配置后端应用环境变量：回到你主后端应用服务的“Variables”页签，设置以下变量：

SEARXNG_BASE_URL=https://searxng-production.up.railway.app # 替换为你的SearXNG服务域名 REDIS_URL=redis://... # Railway会自动添加这个变量，无需手动修改 NODE_ENV=production

6. 触发部署：Railway会在你每次推送代码到Git仓库时自动部署主服务。对于SearXNG服务，由于我们是直接运行镜像，无需代码，在完成上述配置后，Railway会自动启动该服务。你需要等待SearXNG服务状态变为“Deployed”。

7. 验证生产环境：部署完成后，你可以通过一个简单的脚本来测试生产环境的搜索API是否正常工作。在你的本地终端运行：

curl -X POST https://your-backend-production.up.railway.app/api/search \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_TEST_USER_TOKEN" \ -d '{"query": "test the search", "maxResults": 1}'

请将URL和Token替换为你的实际值。如果返回了JSON格式的搜索结果，恭喜你，生产环境部署成功！

注意事项：在Railway上，SearXNG服务是无状态的，这意味着重启后配置会重置。如果你需要永久修改SearXNG配置（例如更改默认语言、禁用某些引擎），需要将自定义的settings.yml文件通过Dockerfile或卷挂载的方式注入，这需要更复杂的Docker部署设置。对于大多数情况，使用默认配置加上项目提供的settings.yml核心设置已经足够。

4. 与主流AI框架的深度集成方案

4.1 与OpenClaw无缝集成

如果你的AI应用基于OpenClaw构建，那么集成将变得异常简单。从OpenClaw v2026.4.1版本开始，官方已经内置了SearXNG插件支持。这意味着你无需手动处理HTTP API调用，OpenClaw核心会替你完成。

配置步骤如下：

1. 确保环境变量正确：在你的OpenClaw应用运行环境中，设置SEARXNG_BASE_URL变量，指向你部署好的SearXNG实例地址，例如https://search.yourdomain.com。

2. 修改OpenClaw配置文件：在你的openclaw.json（或类似配置文件）中，找到工具配置部分，添加或修改web搜索工具的提供商为searxng。

   { "tools": { "web": { "search": { "provider": "searxng", "maxResults": 5 // 可选：指定每次搜索返回的最大结果数 } } } }

3. 重启应用：重启你的OpenClaw应用，使其加载新的配置。

完成以上步骤后，你的OpenClaw助手在需要使用web_search工具时，会自动向你配置的SearXNG实例发起请求。但是，请注意：这种直接集成方式绕过了我们项目中构建的缓存和配额管理层。OpenClaw插件会直接调用SearXNG。因此，为了获得完整的生产级功能（缓存、配额），推荐的架构是：OpenClaw -> 你的后端搜索代理API -> SearXNG。你可以在OpenClaw中自定义工具的实现，将其指向你自己的/api/search端点，而不是直接使用内置的searxng提供商。

4.2 为LangChain、CrewAI、AutoGen等框架创建自定义工具

对于其他流行的AI框架，它们通常允许你定义“自定义工具”（Custom Tools）。我们可以将我们的搜索代理API包装成符合框架要求的工具函数。

以LangChain为例，创建一个自定义工具：

// searchTool.ts import { DynamicTool } from "@langchain/core/tools"; import axios from 'axios'; // 你的搜索代理API的端点 const SEARCH_API_URL = process.env.SEARCH_API_URL || 'https://your-backend.com/api/search'; const API_TOKEN = process.env.SEARCH_API_TOKEN; // 用于鉴权的Bearer Token export const webSearchTool = new DynamicTool({ name: "web_search", description: "A tool to search the web for current information. Input should be a detailed search query string.", func: async (input: string): Promise<string> => { try { const response = await axios.post( SEARCH_API_URL, { query: input, maxResults: 5, // 可根据需要调整 }, { headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${API_TOKEN}`, }, } ); const data = response.data; if (!data.results || data.results.length === 0) { return "没有找到相关的网络信息。"; } // 将结果格式化为字符串 let formatted = `根据对"${data.query}"的搜索，找到以下信息：\n`; data.results.slice(0, 3).forEach((result: any, idx: number) => { // 取前3条 formatted += `\n${idx + 1}. **${result.title}**\n`; formatted += ` 链接: ${result.url}\n`; formatted += ` 摘要: ${result.snippet}\n`; }); if (data.cached) { formatted += `\n（信息来自缓存）`; } return formatted; } catch (error: any) { console.error('搜索工具调用失败:', error); return `搜索过程出错: ${error.response?.data?.error || error.message}`; } }, }); // 然后在你的链（Chain）或代理（Agent）初始化时，将此工具加入工具列表

对于CrewAI，其工具定义类似，你需要创建一个继承自BaseTool的类。对于AutoGen，你需要定义一个符合其function调用规范的工具。核心逻辑都是相同的：封装一个异步函数，内部调用你的搜索代理API，处理响应并格式化为字符串。

关键点在于身份传递：在AI代理调用工具时，你需要能够获取当前会话或用户的身份标识（如userID），并将这个标识通过HTTP请求头（如X-User-ID）或请求体传递给你的搜索代理API，以便代理层进行配额校验。这通常需要你在AI框架的会话管理或工具调用上下文中进行拦截和注入。

5. 性能调优、监控与故障排查

5.1 缓存策略优化与性能指标

默认的30分钟缓存对于大多数场景是合理的起点，但你可以根据业务特点进行优化。

• 热点数据缓存：对于频繁搜索的通用关键词（如“天气”、“新闻”），可以考虑设置更长的缓存时间（例如1小时），甚至使用永久缓存并手动刷新。这需要你在search-proxy.ts的缓存逻辑中增加更复杂的规则判断。
• 缓存键设计：目前的缓存键是查询语句的哈希。但有时，语义相同但表述不同的查询（如“AI最新进展”和“人工智能近期发展”）无法命中同一缓存。对于高阶场景，可以考虑引入轻量级的文本嵌入模型，计算查询的语义向量，对向量相似度高的查询返回同一缓存结果。但这会显著增加系统复杂度。
• 内存优化：Redis是内存数据库，需要监控内存使用情况。搜索结果的JSON字符串可能不小。建议在存储前对结果进行压缩（例如使用pako库进行gzip压缩再存入Redis），虽然会增加少量CPU开销，但能显著节约内存。同时，确保为Redis实例设置合理的maxmemory-policy（如allkeys-lru），防止内存耗尽。

监控指标：在生产环境中，务必监控以下几个关键指标：

1. 缓存命中率：(缓存命中次数 / 总搜索请求次数) * 100%。这是衡量缓存效益的核心指标。健康的命中率应在60%以上。你可以在每次搜索时，将cached字段记录到日志或时序数据库（如Prometheus）中进行计算。
2. 搜索延迟：分别记录缓存命中和未命中的请求延迟。缓存命中延迟应低于10毫秒，而未命中（需要调用SearXNG）的延迟可能在500毫秒到2秒之间，取决于上游引擎的响应速度。
3. 配额使用分布：监控不同用户等级的平均每日搜索用量，这有助于你调整套餐设置，使其更符合用户实际需求。
4. SearXNG实例健康度：监控SearXNG实例的HTTP错误率（如429 Too Many Requests, 503 Service Unavailable），这可能是上游引擎开始限制你的信号。

5.2 常见问题与解决方案速查表

在实际运营中，你可能会遇到以下典型问题。这里提供一个快速排查指南。

5.3 安全与合规性考量

自建服务意味着你需要承担更多的运维和安全责任。

• API端点保护：你的/api/search端点暴露在公网，必须实施严格的认证和速率限制。项目中的search-route.ts提供了基础的Bearer Token认证框架，你需要将其与你现有的用户认证系统（如OAuth2、JWT）集成。此外，应在网关层或应用层实施全局速率限制（例如使用express-rate-limit），防止恶意刷接口。
• SearXNG实例访问控制：你的SearXNG实例（通常运行在8080端口）不应该直接对外暴露。最佳实践是只允许你的后端服务器（即运行搜索代理的那个服务）通过内部网络访问它。在Railway或Docker Compose中，这通常意味着SearXNG服务不绑定公共端口，或者只绑定到内部网络。你的后端服务通过服务发现（如Docker服务名）来访问它。
• 日志与审计：记录所有搜索请求的日志，至少包括时间戳、用户ID（或匿名会话ID）、查询关键词和结果数量。这不仅是故障排查的需要，也能帮助你了解用户兴趣、发现潜在滥用行为。确保日志中不记录个人敏感信息（PII）。
• 尊重robots.txt：SearXNG默认会遵守上游网站的robots.txt协议。你应该保持这一默认设置。虽然这可能会限制抓取某些内容，但这是做一个负责任网络公民的基本要求，也能减少你的IP被屏蔽的风险。

最后，关于法律合规性，项目README中的FAQ已经说明，SearXNG本身是合法的开源软件。你的使用方式应集中于为你的用户提供信息聚合服务，而不是大规模爬取、复制或创建与原始搜索引擎竞争的服务。保持适度的请求频率，利用好缓存，这个架构完全能够支撑起一个中小型AI产品的搜索需求，同时将成本控制在极低的范围。