OmniRoute 联网搜索完整指南：/v1/search 端点与免费 DuckDuckGo 兜底策略-酒店常州论坛

OmniRoute 联网搜索完整指南：/v1/search 端点与免费 DuckDuckGo 兜底策略

【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 350 providers (90+ free), 1200+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 450+ contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute

OmniRoute 是一个免费 MIT 协议的 AI 网关，其联网搜索功能让大模型一次 POST 到/v1/search端点即可完成网页搜索。即使你不配置任何付费搜索密钥，它也会自动启用免费 DuckDuckGo 搜索兜底，开箱即用，零成本、零配置。

🎯 OmniRoute 联网搜索是什么？

OmniRoute 把“联网搜索”做成了 AI 网关的一等公民能力：

能力	说明
统一端点	一个`POST /v1/search`接口，背后可切换 20 余种搜索服务商
免费兜底	未配置任何密钥时，自动降级到免费的 DuckDuckGo lite 搜索
配额感知	服务商被限流时自动 failover 到下一家，不中断请求
结果缓存	相同查询 5 分钟 TTL 缓存，重复搜索不产生额外费用
成本记账	每次搜索按服务商单价计入 API Key 预算（免费源为 0）

核心实现分布在src/app/api/v1/search/route.ts（端点入口）与open-sse/config/searchRegistry.ts（搜索服务商注册表，约 530 行，是所有搜索能力的"单一事实来源"）。

📡 /v1/search 端点怎么用？

端点提供两个方向：

1. 列出可用搜索服务商（GET）

GET /v1/search返回当前所有可用的搜索服务商列表（id、名称、支持的搜索类型），会自动剔除被安全策略屏蔽的条目。适合客户端先"发现"再"调用"。

2. 执行网页搜索（POST）

请求体核心字段：

字段	说明
`query`	搜索关键词（必填）
`provider`	可选。指定服务商（如`serper-search`、`duckduckgo-free`），不传则自动选择
`search_type`	`web`（网页）或`news`（新闻）
`max_results`	返回条数，会被自动钳制到该服务商的上限（如 DuckDuckGo 上限 25 条）
`country`/`language`	地域与语言偏好
`filters`	域名包含/排除过滤（`include_domains`/`exclude_domains`）
`time_range`	时间范围过滤
`content`	是否附带正文摘要

响应为标准 JSON，包含results（标题、URL、摘要、相关度分）、cached（是否命中缓存）与usage（本次消耗查询数与美元成本，缓存命中时为 0）。

🦆 免费 DuckDuckGo 兜底策略：为什么零配置也能搜？

这是 OmniRoute 联网搜索最有新手友好度的一处设计。注册表中 DuckDuckGo 服务商被标记为fallbackOnly: true（见open-sse/config/searchRegistry.ts第 320 行附近的duckduckgo-free条目）：

无需任何 API Key：authType: "none"，直接抓取 DuckDuckGo lite 页面的 HTML 结果，月配额设为 999999（实际不限，仅受对端频率限制）
永远不会抢占付费源：自动选择逻辑按单次查询成本从低到高排序，但会跳过所有fallbackOnly服务商，所以配置了 Serper（$0.001/次）等付费源时，DuckDuckGo 不会被误选
最后兜底才登场：仅当"没有任何服务商可用/被限流"或"主服务商执行失败"时，才把它提升为主选或备胎（failover），保证裸机部署的 OmniRoute 联网搜索永远有结果返回
专属 HTML 解析路径：它不走通用 JSON 适配器，而是由open-sse/handlers/search.ts中专用的 HTML 解析分支处理

这套"last-resort 兜底"策略在src/app/api/v1/search/route.ts的自动选择逻辑中有两段对应代码：先遍历已配置服务商按成本择优，再进入"Last resort"分支提升duckduckgo-free——无论是首次选主还是为失败准备备胎，都会走到它。

⚖️ 内置搜索服务商一览

除 DuckDuckGo 外，注册表内置的常用服务商（部分）：

服务商	单次成本	免费月配额	支持类型
Serper Search	$0.001	2500 次	web / news
Brave Search	$0.005	1000 次	web / news
Jina Search	$0.002	1000 次	web
Tavily Search	$0.008	1000 次	web / news
Exa Search	$0.007	1000 次	web / news
SearXNG（自建）	免费	不限	web / news
Context7（文档）	免费	不限	web
DuckDuckGo（免费）	免费	不限	web

在仪表盘的/dashboard/providers页面填入任意一家密钥即可启用对应服务商；GET /api/search/providers会实时推导每家服务商的状态（configured / missing / rate_limited）。

🛠️ 搜索工具工作室：可视化玩转 /v1/search

不必手写 curl——OmniRoute 提供了Search Tools Studio（路由/dashboard/search-tools），三个标签页覆盖全部场景：

Search 标签：查询 → 结果（标题/URL/摘要/相关度），支持选择重排（Rerank）模型用 LLM 重排结果
Scrape 标签：调用姊妹端点POST /v1/web/fetch抓取整页内容，输出 Markdown / 文本 / HTML，超 256 KB 自动截断提示
Compare 标签：同一查询并行打到最多 4 家服务商，并排对比延迟、成本、结果数与 URL 重合度

侧边配置面板可实时查看每家服务商的成本、配额与健康状态；"Export Code" 还能一键导出 curl / Python / TypeScript 调用片段。完整设计文档见 docs/frameworks/SEARCH_TOOLS_STUDIO.md。

❓ 常见问题（FAQ）

Q：没配任何搜索密钥，搜索会报错吗？不会。自动选择链路最终会落到duckduckgo-free（免费、无 Key），这是刻意的"零配置可用"设计。

Q：为什么我配了 Serper，却还是走 DuckDuckGo？正常情况下不会。只有当 Serper 的所有凭据处于限流冷却中时才会降级；可在 Search Tools 侧边栏或/api/search/providers查看实时状态。

Q：搜索有缓存吗？有。相同查询 + 服务商 + 参数组合 5 分钟内命中缓存，响应带cached: true，且不计入成本（usage.search_cost_usd为 0）。

Q：能限制只用免费源吗？可以。在设置中通过"服务商屏蔽"（blockedProviders）策略禁用付费源，/v1/search的 GET 与 POST 都会自动尊重该策略。

✅ 小结

OmniRoute 的联网搜索把"一个端点 + 多服务商 + 免费兜底"做得非常彻底：/v1/search屏蔽了 20 多家搜索服务商的差异，成本感知的自动选择 + 限流 failover 保证可用性，而免费 DuckDuckGo 兜底让任何新手克隆下来立刻就能搜到互联网。配合 Search Tools Studio 的可视化调试，从"零配置尝鲜"到"多服务商对比调优"都是一条顺滑的路径。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析