DeepSeek Web Search MCP
A stdio MCP server that gives clients live web search and citation-backed research through DeepSeek (optionally fused with other search providers).
web_search— search the live web and return normalized, citeable sources (structured results, no model answer).query(required, 1–400 chars);scope(auto/cn/global, defaultauto);freshness(any/day/week/month/year, defaultany);max_results(1–20, default 8);rerank(boolean, default false).
web_research— use DeepSeek native web search to research a question and return a written answer plus citeable sources with citations.query(required, 1–400 chars);freshness(same enum, defaultany);max_sources(1–20, default 5).
Under the hood: parallel recall across DeepSeek official Search API and external providers (AnySearch, SearXNG, Tavily), URL/language/cross-host deduplication, authority-aware cleaning and rank fusion, with optional OpenRouter reranking, docs-intent veto and semantic repost folding (all degrade gracefully, never failing the search).
README also documents multi-turn research sessions (
research_start/research_followup/research_close), but only the two tools above are exposed in this server schema.
Allows using a self-hosted SearXNG instance as a search provider for the web_search tool, including multi-provider retrieval and optional reranking.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@DeepSeek Web Search MCP search for the latest news on DeepSeek API updates"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
DeepSeek Web Search MCP
一个独立的 stdio MCP 服务器,向 Codex 等客户端暴露搜索、研究和多轮研究工具:
web_search:原生检索调用 DeepSeek 官方 Search API (POST /v1/tools/search),返回结构化来源、不含模型回答;也可与 AnySearch、 SearXNG、Tavily 外部源合并为同一候选池,再统一去重、融合和排序。旧的 Anthropic Messages 原生搜索路径(deepseek-native)保留兼容。web_research:通过 DeepSeek 官方 Anthropic 兼容 Messages API 调用web_search_20250305,返回回答、结构化来源和引用摘要(legacy 研究路径)。research_start/research_followup/research_close:带 TTL 和最大轮数的 内存研究 session,用于多轮追问。
v1.7.0 起可在 balanced / deep 路径上可选接入 OpenRouter 模型能力:重排分数标定
(默认启用)、docs-intent veto(默认关闭)和语义转载折叠(默认关闭)。三者互不
依赖:重排会随 quality 或缺少 key 自动跳过,决策与嵌入另有显式 off 开关;
未配置 OPENROUTER_API_KEY 时三者自动跳过,搜索退回纯检索行为(重排报告
applied: false)。
架构
架构图由 LaTeX/TikZ 绘制(源文件在 docs/diagrams),GitHub 直接显示 PNG。
分层架构
核心分层

LaTeX/TikZ 源文件:
docs/diagrams/architecture-core.tex
可选 OpenRouter 面板(核心图右侧扩展)

LaTeX/TikZ 源文件:
docs/diagrams/architecture-openrouter.tex
web_search 请求流程
主流程

LaTeX/TikZ 源文件:
docs/diagrams/request-flow-main.tex
可选分支(失败时降级)

LaTeX/TikZ 源文件:
docs/diagrams/request-flow-branches.tex
模块地图
层 | 主要文件 |
MCP 入口与工具 |
|
编排与缓存 |
|
检索 provider |
|
排序与质量 |
|
可选 OpenRouter |
|
配置与类型 |
|
评估 |
|
关键设计约束
先召回、后统一排序:所有 provider 的结果进入同一候选池,再做去重与 rank fusion,避免单家排序偏置。
增强能力默认不改变基础行为:rerank 在
fast、无 key 或失败时直接跳过;decisions 与 embedding 默认off;flags-off 的 fast 搜索与 v1.6.0 逐字节一致。失败只降级、不阻断:rerank 失败回到 provider 顺序,decisions 失败回到正则,embedding 失败回到词法去重,搜索本身不因 OpenRouter 故障失败。
校准与模型解耦:provider 只返回原始 rerank 分数,min-max/weak-signal 校准在 ranking 层完成,便于按模型选择
auto策略。共享客户端:rerank / decisions / embeddings 共用一个
OpenRouterClient,统一限流、并发与熔断,避免三个模块各自打爆配额。
Related MCP server: MCP Deep Search
DeepSeek 协议
DeepSeek 自 2026-10-17 起开放官方 Search & Fetch API。v1.6.0 起,web_search
新增官方 Search API 后端(deepseek-search),并成为默认 auto / hybrid 中
唯一的 DeepSeek 原生检索来源;旧的模型搜索保留为 legacy deepseek-native。
官方 Search API 直接返回结构化结果,不经过模型、不产生模型轮次:
POST https://api.deepseek.com/v1/tools/search需要模型撰写回答的场景仍走 Anthropic 兼容 Messages API:
POST https://api.deepseek.com/anthropic/v1/messages请求使用 web_search_20250305 服务端工具,返回模型回答、
web_search_tool_result 块和 citations。只有响应中存在
web_search_tool_result 才视为搜索成功;DSML、模型自述或普通文本都不能作为
搜索成功证据。web_research 与 research_start / research_followup 继续
使用这条路径;显式 backend: "deepseek-native" 也仍走它,用于兼容旧客户端。
Fetch 端点本项目不调用,也不注册为 MCP 工具。
路径 | 端点 | 使用场景 |
官方 Search API(推荐) |
|
|
Anthropic 兼容 Messages API(legacy) |
|
|
Responses API 现已支持 deepseek-v4-pro 的服务端 web_search_call,但本项目不
使用 Responses API;旧版 README 中"Responses API 会静默忽略 web_search"的说法
只描述当时状态,不再是当前事实。
Messages 路径的实现契约参考 DeepSeek 官方 Harness 的
@deepseek-ai/dsh-web-search-deepseek 包。
仓库不包含 API Key、服务器地址、用户名或私钥。所有凭据均从进程环境读取。
DeepSeek 官方 Search API
web_search(backend="deepseek-search") 直接调用官方 Search API,只做检索和结果
归一化,不产生模型回答。
请求与响应
端点:POST https://api.deepseek.com/v1/tools/search
请求头:
Authorization: Bearer <DEEPSEEK_API_KEY>
Content-Type: application/json请求示例:
{
"query": "site:api-docs.deepseek.com after:2026-01-01 DeepSeek search API",
"count": 5,
"need_content": false
}字段 | 类型 | 说明 |
| string,必填 | 1–128 个 Unicode 字符,不能全为空白,支持查询运算符 |
| integer | 返回条数,1–50,默认 10;不影响计费 |
| string | 可选,原始问题,1–128 个字符 |
| string | 可选,IP 形式的地域提示 |
| boolean | 默认 |
本项目当前只发送 query、count(由 max_results 与 quality 的每路候选
上限共同决定)和 need_content;
ori_question 与 localization 是官方 API 的可用字段,尚未暴露为工具参数。
当 DEEPSEEK_SEARCH_NEED_CONTENT=on 时,响应中的页面正文 content(Markdown,
保留换行)会原样映射为来源的 content 字段;响应体积可能明显变大,单价不变。
query 超过 128 字符时会被截断到上限;需要附加 freshness 的 after: 运算符时,
按包含运算符的总长度 128 字符截断。发生截断时返回的 warnings 会说明。
响应示例:
{
"results": [
{
"rerank_score": 2.31,
"title": "DeepSeek Search API",
"url": "https://api-docs.deepseek.com/guides/search",
"snippet": "…100–200 字符摘要…",
"summary": "…600–800 字符摘要…",
"content": "",
"site_name": "DeepSeek API Docs",
"site_icon": "https://api-docs.deepseek.com/favicon.ico",
"date": "2026-10-17T00:00:00Z",
"authority": 4
}
]
}rerank_score:0–3,>= 1.5视为高质量snippet约 100–200 字符,summary约 600–800 字符date:RFC3339 UTC 或nullauthority:0–4 的权威性分级;-1表示未知,>= 3视为高权威,该分级会 作为来源权威性信号参与 fast 清洗与 rank fusion;它只在聚合站/内容农场显式 名单之后生效,不会把名单内域名重新提升为权威来源results为空数组表示正常无匹配,不是错误
查询运算符
site:/-site::限定 / 排除站点-term:排除包含该词的页面"exact phrase"/-"exact phrase":精确短语及其排除lang:zh,en:限定语言after:2025/after:2025-01-01:起始时间before:2026/before:2026-06-01:结束时间
freshness 的 day / week / month / year 会翻译为服务端
after:YYYY-MM-DD 运算符。
计费
Search 与 Fetch 分别按 $0.75 / 1,000 次成功请求 计费。
只有 HTTP 200 且返回结果的请求计费;失败请求、空搜索结果和超时不计费。
count不影响单价。通过 DeepSeek Harness、Claude Code、Codex 等服务端工具发起的请求同样按成功 请求计费。
限流
账号级配额:Search 100 QPS、Fetch 25 QPS,两者额度独立;超限返回 429。
错误处理
错误响应使用 OpenAI 兼容格式。HTTP 状态码与建议处理:
状态 | 含义 | 处理 |
400 | 请求非法 | 修正请求,不重试 |
401 | API Key 缺失或无效 | 修正凭据,不重试 |
402 | 余额不足 | 充值后重试 |
403 | Fetch 安全策略拒绝 | 不重试 |
404 | Fetch 无法获取目标 | 不重试 |
408 | 读取请求体超时 | 等待后重试 |
413 | 响应体过大 | 不重试 |
429 | QPS 超限 | 等待后重试 |
500 | 内部错误 | 等待后重试 |
504 | 下游超时 | 等待后重试 |
处理原则:408 / 429 / 5xx 等待并退避重试;402 充值;其他 4xx 不要重试。本项目
不自动重试:单独使用 deepseek-search 时会直接返回该 provider 的错误,并保留
code、HTTP status 与 retryable 元数据;在 hybrid / auto 中单个
provider 失败不会丢掉其他 provider 的结果。成功但无匹配时返回 no_results,提示
No search results,而不是误报"所有 provider 失败"。本项目只集成 Search;403、
404、413 是 Fetch 端点的状态码,此处按官方统一错误码表列出,供参考。
构建
npm install
npm run build
npm test质量计划的离线 replay 使用无密钥 fixture,不会调用线上 provider:
npm run quality:fixture
npm run quality:replayfixture 生成 70 个分层 synthetic query(30 development / 40 held-out);结果写入
work/quality/baseline-report.json。
fixture 保存各 provider 的原始顺序、
状态、延迟、来源和可选 rerank 结果,用于比较当前 baseline 与 provider-aware RRF
shadow challenger;synthetic 数据只用于工程回归,不替代人工 relevance 标注,
shadow 结果不会改变 MCP 生产返回。
npm run quality:summary 打印各方法聚合指标和分类明细;npm run quality:diff
列出清洗后 nDCG@5 下降的具体 case;node scripts/quality-inspect.mjs <caseId>
打印单个 case 的输入、保留和被丢弃的来源。
除 official / current / ambiguous / exploratory 四类外,fixture 还包含两类
专门复现实测反馈的 held-out case:
syndication:同一篇文章的/it/、/ar/、/en/多语言副本 + 跨域转载aggregator-dominance:聚合站排在官方文档页之前,且 rerank 给出与线上实测 一致的低分(官方页 0.037 / 0.006)
需要采集真实四路原始运行时数据时执行:
npm run quality:capture -- "your query"结果写入被 .gitignore 排除的 work/quality/runtime/latest.json,不会把真实
provider 响应或凭据提交到仓库。
配置
复制 .env.example 中的变量到进程环境或 Windows 用户环境。至少需要:
DEEPSEEK_API_KEY:web_search(backend="deepseek-search")、web_search(backend="hybrid")的 DeepSeek 部分、web_search(backend="deepseek-native")、web_research和research_*。显式hybrid但未配置 key 时仍会返回外部 provider 结果,并给出deepseek-search缺少凭据的 warningWEB_SEARCH_BACKEND:web_search的默认后端,可选auto(默认)、external、deepseek-search、hybrid或deepseek-nativeFAST_CLEANING_MODE:fast 清洗模式,可选shadow(默认,只计算不改变结果)、on或offFAST_DOMAIN_CAP:fast 清洗的同域名保留上限,默认2DOCUMENTATION_QUERY_MODE:官方文档/API/source code 类 query 的质量路由, 默认fast,避免低分第三方页面被 deep rerank 压过;可设为deepopt-inSOURCE_IDENTITY_MODE:同一篇文章的重复来源折叠,默认on;设为off恢复 仅按精确 URL 去重的旧行为SOURCE_IDENTITY_CROSS_HOST:跨域转载检测,默认on;设为off时只折叠 同域的重复 URL 和多语言副本SOURCE_IDENTITY_VERBOSE:默认off;设为on时在sourceIdentity.groups中返回每个合并组的保留 URL、被合并 URL 和冲突标记FRESHNESS_INTENT_WARNING:默认on。检测到时效性 query 但调用方没有主动 使用strict时,返回一条建议性 warning(不改变本次请求行为)RESEARCH_SESSION_TTL_MS、RESEARCH_SESSION_MAX_SESSIONS、RESEARCH_SESSION_MAX_TURNS:研究 session 生命周期和容量ANYSEARCH_API_KEY:可选,匿名模式限额更低TAVILY_API_KEY:全球搜索OPENROUTER_API_KEY:可选;web_search的balanced/deep重排、 docs-intent veto 与语义转载折叠共用该 key,未配置时全部跳过SEARXNG_URL:自建实例地址
DeepSeek 官方 Search API 相关变量:
DEEPSEEK_SEARCH_API_BASE_URL:官方 Search API 的 base URL,默认https://api.deepseek.com/v1;provider 会自动追加/tools/search。DEEPSEEK_SEARCH_API_TIMEOUT_MS:Search API 请求超时,默认15000。DEEPSEEK_SEARCH_NEED_CONTENT:默认off。设为on时请求need_content: true,Search API 响应会包含页面正文(content),并原样映射为 来源的content字段(Markdown,保留换行),响应体更大,但单价不变(仍按成功 请求计费)。
legacy Anthropic Messages 路径相关变量,仅用于 web_research、research_* 和
显式 backend: "deepseek-native":
DEEPSEEK_SEARCH_BASE_URL:Anthropic SDK 的 base URL,SDK 会自动追加/v1/messages。默认值是https://api.deepseek.com/anthropic。DEEPSEEK_SEARCH_MODEL:默认deepseek-flash。deepseek-flash是当前 V4.1-Flash 的别名;deepseek-v4-flash目前临时路由到同一模型。DEEPSEEK_SEARCH_MAX_USES:服务端搜索工具的最大调用次数,默认5。DEEPSEEK_SEARCH_MAX_TOKENS:回答最大 token 数,默认4096。DEEPSEEK_SEARCH_TIMEOUT_MS:Messages 请求超时,默认150000,仅 legacy 路径使用。
v1.7.0 OpenRouter 模型相关变量(均为可选;未配置 OPENROUTER_API_KEY 时
功能跳过、搜索不受影响):
重排:
OPENROUTER_RERANK_MODEL(默认nvidia/nemotron-3.5-rerank-8b:free)、OPENROUTER_RERANK_MODEL_BALANCED(默认旧...vl-1b-v2:free)、OPENROUTER_RERANK_MODEL_DEEP(留空继承 base)、OPENROUTER_RERANK_FALLBACK_MODEL(可选)、OPENROUTER_RERANK_TIMEOUT_MS(留空/0 = 按模型 profile:旧 5000 / 新 12000)、RERANK_NORMALIZATION(auto/raw/minmax)、RERANK_CONFIDENCE_FLOOR(0.35)、RERANK_TOP1_MIN(0.85)、RERANK_CANDIDATE_LIMIT(30,上限 30)、RERANK_INPUT_CHARS(800)docs-intent veto:
WEB_SEARCH_DECISIONS_MODE(off;别名DECISIONS_MODE)、OPENROUTER_DECISIONS_MODEL(parallel/decisions-fast:free)、OPENROUTER_DECISIONS_THRESHOLD(0.30,仅报告字段)、OPENROUTER_DECISIONS_TIMEOUT_MS(4000)、OPENROUTER_DECISIONS_CACHE_TTL_MS(86400000)、OPENROUTER_DECISIONS_CACHE_MAX_ENTRIES(500)、WEB_SEARCH_DECISIONS_MAX_CALLS_PER_MINUTE(4)、WEB_SEARCH_DECISIONS_CIRCUIT_COOLDOWN_MS(300000)语义转载折叠:
EMBEDDING_MODE(off)、EMBEDDING_MODEL、EMBEDDING_FALLBACK_MODELS、EMBEDDING_MAX_PAIRS(8)、EMBEDDING_BUDGET_MS(6000)、EMBEDDING_DEDUPE_THRESHOLD(留空 = 按模型 profile)、EMBEDDING_CACHE_TTL_MS(3600000)、EMBEDDING_CACHE_MAX_ENTRIES(300)、EMBEDDING_CIRCUIT_FAILURES(5)、EMBEDDING_CIRCUIT_COOLDOWN_MS(120000)全局 OpenRouter 配额:
OPENROUTER_MAX_CALLS_PER_MINUTE(30)、OPENROUTER_MAX_CONCURRENCY(2)
启动时 validateConfig 会把配置警告写到 stderr(例如启用了 embedding/decisions
但没配 OPENROUTER_API_KEY);RERANK_CANDIDATE_LIMIT 在加载配置时会被静默截到
上限 30。
freshness 继续支持 any/day/week/month/year。freshness_mode 默认是 soft:
支持原生时间过滤的 provider 会传递时间范围,其他 provider 只提供查询提示并返回
未严格验证 warning。strict 模式只保留有可解析 publishedAt 且满足 cutoff 的来源。
调研快速演变的题目(模型版本、定价、发布说明、今天的状态)时建议显式传
freshness_mode: "strict"。soft 只给 warning,不会把无法证明时间的新来源剔除。
时效性建议
web_search、web_research、research_start 和 research_followup 都会检测
query 的时效性信号(latest、current、changelog、version、最新、当前、
版本、实时 等)。检测到信号但调用方没有使用 strict 时,返回一条明确的
建议 warning,并在 freshness.intent 中给出 recommendedFreshness。
本项目不会静默切换模式:warning 只提示应该传什么,本次请求仍按调用方传入的参数
执行。FRESHNESS_INTENT_WARNING=off 可关闭该提示。
web_search 后端兼容
web_search 保留原有的 SearchResult 形状:始终返回 query、scope、
provider、sources 和 warnings。新增的 backend 只决定结果从哪里来:
{
"query": "DeepSeek web search API",
"backend": "hybrid",
"max_results": 5,
"freshness": "week"
}可选值:
external:旧行为,按 provider 顺序使用 AnySearch、SearXNG、Tavily。deepseek-search(新):只调用 DeepSeek 官方 Search API,返回结构化来源, 没有模型回答、不产生模型轮次,速度更快;quality: "balanced"/"deep"时与外部 provider 一样进入 OpenRouter rank fusion;freshness的day/week/month/year会翻译为服务端after:YYYY-MM-DD查询 运算符。hybrid:并行查询 AnySearch、SearXNG、Tavily 和deepseek-search,把四路 结果合并为同一个候选池;quality: "balanced"/"deep"时四路一起进入 rank fusion。hybrid不再包含 legacydeepseek-native模型路径,需要模型回答 时请显式使用backend: "deepseek-native"。deepseek-native(legacy):调用与web_research相同的 Anthropic Messages 原生搜索,返回mode: "native"、模型回答和带provider: "deepseek-native"的来源;为兼容旧客户端保留。auto:有DEEPSEEK_API_KEY时等价于hybrid;没有 key 时等价于external。单个 provider 失败不会丢掉其他 provider 的结果。
不传 backend 时使用 WEB_SEARCH_BACKEND;未设置该变量时使用 auto,有
DeepSeek key 的客户端默认会把 DeepSeek 官方 Search 纳入四源候选池。完全保持旧
的外部-only 行为时设置 WEB_SEARCH_BACKEND=external 或传 backend: "external"。示例环境默认设为 hybrid,方便直接体验四源融合。
deepseek-native 不执行 OpenRouter rank fusion;hybrid / deepseek-search
只有在 quality: "balanced" / "deep" 或旧 rerank: true 时才执行外部重排。
scope 仍按查询语言解析并原样返回。deepseek-search 会把 freshness 翻译成
Search API 的 after:YYYY-MM-DD 查询运算符(原生服务端过滤);legacy
deepseek-native 只把 freshness 作为查询提示传给 Messages 原生搜索,不应被
理解为严格的服务端时间过滤。需要完全排除 DeepSeek 时使用 external;需要
DeepSeek 官方 Search 参与统一融合时使用 hybrid 或默认 auto;需要旧的模型
回答路径时显式使用 deepseek-native。
deep 仍表示多 provider 召回加一次 rerank,不表示多轮对话。多轮研究请使用
research_start 开启 session,再用 research_followup 继续,最后用
research_close 释放内存状态;MCP 进程重启会清空 session。
默认情况下,识别为官方文档/API/source code 的 query 会自动从 deep 路由到 fast,
并在 warnings 中说明。启用 docs-intent veto 后(WEB_SEARCH_DECISIONS_MODE=on),
请求的 quality 为 balanced / deep、正则命中且模型高置信否定(p < 0.25)时会
取消这次 docs 路由(warnings 中给出 p),quality 与 rerank 保持不变;shadow 只
记录不改行为。研究 follow-up 不再把上一轮模型答案原文拼回下一次搜索,
只保留来源 URL 作为检索提示;legacy deepseek-native(Messages 路径)会被要求
优先引用 primary/official source。
OpenRouter 模型(v1.7.0)
v1.7.0 在 balanced / deep 路径上可选接入三个 OpenRouter 模型。三者共用一个
OpenRouter 客户端:OPENROUTER_MAX_CALLS_PER_MINUTE(默认 30)与
OPENROUTER_MAX_CONCURRENCY(默认 2)对重排、决策、嵌入统一生效,每个 provider
有独立熔断器。未配置 OPENROUTER_API_KEY 时三者自动跳过:重排回退 provider
顺序(applied: false),决策回退正则,embedding 不执行,搜索不受影响。
重排模型(rerank,balanced/deep 默认启用)
默认:
OPENROUTER_RERANK_MODEL=nvidia/nemotron-3.5-rerank-8b:free(下称 3.5 重排模型)。balanced默认改用低延迟的OPENROUTER_RERANK_MODEL_BALANCED=nvidia/llama-nemotron-rerank-vl-1b-v2:free(下称旧 1b-v2 模型)。deep默认继承OPENROUTER_RERANK_MODEL,可用OPENROUTER_RERANK_MODEL_DEEP覆盖。OPENROUTER_RERANK_FALLBACK_MODEL:可选;仅当主模型返回 HTTP 404(模型不可用) 时用该模型重试一次,其它错误不切换模型。OPENROUTER_RERANK_TIMEOUT_MS:留空或0时按模型 profile——旧 1b-v25000ms、3.5 模型12000ms;显式正整数覆盖。RERANK_NORMALIZATION:auto(默认)/raw/minmax。auto按模型家族 解析:3.5 系模型用minmax,旧 1b-v2 与未知/自定义模型用raw(绝对分数, 不做猜测性放大)。RERANK_CONFIDENCE_FLOOR(默认0.35)、RERANK_TOP1_MIN(默认0.85)、RERANK_CANDIDATE_LIMIT(默认30,上限 30)、RERANK_INPUT_CHARS(默认800)。
分数标定、弱信号保护与融合细节见「质量控制与融合重排」。
docs-intent veto(decisions,默认关闭)
在「官方文档」正则(ranking.hasOfficialIntent)命中后,用
parallel/decisions-fast:free 判断 query 是否真的在找官方文档。模型只能否决
正则的 false positive,不能提升非 docs query,也不参与召回或排序;默认关闭。
端点:
POST https://openrouter.ai/api/alpha/decisions;只发送原始 query。只对请求的
quality不是fast的搜索生效(balanced/deep,或旧rerank: true,映射为 balanced);fast请求不会发起决策调用。只有正则已命中时才调用,正则未命中直接返回;
off模式完全无请求。判定:
p < 0.25→ veto(取消 docs 路由,保持调用方请求的 quality 与 rerank);p > 0.40→ keep(沿用正则);0.25–0.40为 dead band,回退正则。模型是检索增强(web-grounded)的:它自行检索并返回引用,记录中约 10 条 URL, 因此属于一项独立的外部 egress。
失败、超时、拒答、非法响应、本地预算耗尽或熔断一律回退正则,不阻断搜索。
shadow仍会发起同样的模型调用,只记录 verdict 与 p、不改变行为;on才允许 veto。别名DECISIONS_MODE在未设置WEB_SEARCH_DECISIONS_MODE时生效。报告字段
decisions:mode、applied、verdict(veto/keep/fallback)、p、threshold、regexOfficialIntent、resolvedOfficialIntent、cached、fallbackReason、elapsedMs、annotations。mode 非off时即使本次跳过(例如 fast 请求)也可能出现fallback报告并带fallbackReason。
OPENROUTER_DECISIONS_THRESHOLD(默认 0.30)只写入报告的 threshold 字段;
实际判定使用固定的 0.25 / 0.40 边界。其余变量:
OPENROUTER_DECISIONS_MODEL、OPENROUTER_DECISIONS_TIMEOUT_MS(默认
4000)、OPENROUTER_DECISIONS_CACHE_TTL_MS(默认 86400000)、
OPENROUTER_DECISIONS_CACHE_MAX_ENTRIES(默认 500)、
WEB_SEARCH_DECISIONS_MAX_CALLS_PER_MINUTE(默认 4,与共享客户端配额分开)、
WEB_SEARCH_DECISIONS_CIRCUIT_COOLDOWN_MS(默认 300000)。
延迟与模型标识:该模型是检索增强的,冷启动单次调用约 1–2.5 秒(实测 p95 约
1.9 秒),因此默认超时取 4000ms,低于此值会把正常冷启动误判成 transport error
并回退正则。shadow / on 会让 balanced / deep 请求最多增加约 2–4 秒。
模型回显会去掉 :free 后缀(例如 parallel/decisions-fast-20261106),报告中可能
出现带构建日期的变体。
语义转载折叠(embedding,默认关闭)
可选的第二层去重,只修「同一篇文章的跨域转载」在正则去重后仍残留的情况,不参与 排序或过滤。
EMBEDDING_MODE:off(默认)/shadow(只报告wouldMerge)/on(实际合并)。默认模型
nvidia/nemotron-3.5-embed-8b:free(4096 维);回退链EMBEDDING_FALLBACK_MODELS默认nvidia/llama-nemotron-embed-vl-1b-v2:free(2048 维)→baai/bge-m3(1024 维,付费)→ 正则结果。回退按模型整体重试,不同模型的向量空间不混用。每个模型有独立 profile(batch / 并发 / 超时 / 默认阈值):8b 模型一次只发 1 条、 并发 8、超时 8000ms、阈值 0.62;vl-1b 模型 batch 10、并发 1、超时 5000ms、阈值 0.62;bge-m3 batch 10、并发 1、超时 8000ms、阈值 0.72。实际并发还受共享客户端
OPENROUTER_MAX_CONCURRENCY(默认 2)限制,profile 并发是上限。EMBEDDING_DEDUPE_THRESHOLD留空时按所用模型取阈值,显式设置则对整条回退链生效。只在
balanced/deep的重排路径执行;未配置OPENROUTER_API_KEY时跳过。只评估跨域、slug 不同、标题 Jaccard 在
[0.25, 0.6)的候选对;每次最多EMBEDDING_MAX_PAIRS(默认 8)对、最多嵌入 8 条来源文本。任何失败、超时、熔断或预算(
EMBEDDING_BUDGET_MS,默认 6000)耗尽都降级为SOURCE_IDENTITY_MODE的正则结果,不会让搜索失败。报告字段
embedding:mode、applied、model、dims、candidates、embedded、mergedPairs、partial、fallbackIndex、circuitOpen、elapsedMs、usage、wouldMerge(仅 shadow);合并条数同时写入sourceIdentity.semanticCopyCount。为什么默认
off:8b embedding 端点不稳定——单条输入可用,但一次请求 3 条以上 输入会稳定返回 502,实测可用率约 17%;on会带来额外延迟与失败回退。shadow/on最多增加约 6 秒(受EMBEDDING_BUDGET_MS默认 6000 限制)。启用前请先跑 「评估 harness」的 semantic 门控校准阈值。
其余变量:EMBEDDING_MODEL、EMBEDDING_CACHE_TTL_MS(默认 3600000)、
EMBEDDING_CACHE_MAX_ENTRIES(默认 300)、EMBEDDING_CIRCUIT_FAILURES
(默认 5)、EMBEDDING_CIRCUIT_COOLDOWN_MS(默认 120000)。
引用质量与来源独立性
合成答案里最常见的两个问题不是"排错了",而是"同一篇文章被当成多个来源"和
"多源数字一致其实是互相抄"。1.5.0 起针对这两点做了显式处理;v1.7.0 再增加一层
可选的语义转载折叠(EMBEDDING_MODE,默认 off),只补正则漏掉的跨域转载。
同一篇文章只算一个来源
SOURCE_IDENTITY_MODE=on(默认)会在重排和 rerank 之前折叠重复来源:
规范化 URL:去 tracking 参数、
/amp、index.html、尾斜杠折叠语言前缀:
/it/…、/ar/…、/en/…指向同一篇文章时合并为一条折叠
?lang=/?locale=/?hl=之类的语言参数跨域转载检测:不同域名下 slug 相同且标题高度相似时合并
合并时保留低权威风险的一方(官方/文档站优先于未知域名,未知域名优先于聚合站和
内容农场),并只回填缺失字段,不会覆盖已保留来源自己的标题或日期。日期冲突会
计入 sourceIdentity.conflictingDateCount 并产生 warning,而不是静默选一个。
返回结构新增:
{
"sourceIdentity": {
"applied": true,
"inputCount": 5,
"mergedCount": 2,
"languageVariantCount": 1,
"crossHostCopyCount": 1,
"conflictingDateCount": 0,
"independence": {
"independentDomains": 2,
"dominantDomainShare": 0.6,
"lowAuthorityShare": 0.4,
"level": "low"
}
}
}research_* 系列的 sourceQuality 同时返回 independentDomains 和
independence,用于判断这个答案是"多源印证"还是"单一来源改写"。
语义转载折叠(默认 off)
v1.7.0 的 EMBEDDING_MODE 是可选的第二层去重,只在正则(URL 规范化/语言前缀/跨域
slug + 标题相似度)漏掉「标题不够像」的跨域转载时补位,不参与排序或过滤:
候选对:不同域名、不同 slug、标题 Jaccard 在
[0.25, 0.6)每次最多评估
EMBEDDING_MAX_PAIRS(默认 8)对,最多嵌入 8 条来源文本shadow仍会发起同样的 embedding 请求,只报告「本可合并多少对」 (embedding.wouldMerge),返回来源不变on合并 cosine ≥ 阈值的候选对;保留低权威风险的一方,只回填缺失字段;日期 冲突计入sourceIdentity.conflictingDateCount并产生 warning合并条数写入
sourceIdentity.semanticCopyCount;语义相似不是独立印证,warning 会明确提示任何 embedding 失败/超时/熔断都降级为正则结果,不会让搜索失败
模型、阈值、启用范围与隐私影响见「OpenRouter 模型」。
聚合站和内容农场
src/hosts.ts 维护显式名单,包含实测中反复出现的内容农场
(ofox.ai、techsy.io、taskade.com 等)。名单内的域名:
永远不获得权威性加分
fast 清洗中被乘性降权(系数
0.35)
乘性而非加性是有原因的:实测中排名第 1 的 Reddit 结果得分为
1/1 + 0 − 0.12 = 0.88,而排名第 2 的官方文档页只有
1/2 + 0.7×0.4 = 0.78——有界的加性惩罚永远无法把第一名挤下去。乘性降权
才可以让明确的低质信号压过更好的原始位置。
未知域名保持中立,不做猜测性惩罚。
隐私
本项目不收集也不上传任何遥测数据。查询只会发送给你自己配置的检索/重排提供商; 启用 v1.7.0 的 OpenRouter 能力时,还会按需发送到 OpenRouter:重排发送候选标题/ URL/snippet,docs-intent 只发送原始 query(该模型为 web-grounded,会自行检索), embedding 发送候选标题/snippet/URL。三个能力默认只有重排启用,其余默认关闭。 凭据仅从进程环境读取,缓存只存在于内存。详见 PRIVACY.md。
本地运行
npm run doctor -- --json
node dist/index.js--doctor 只在终端输出各 provider 的健康状态,不会把健康检查注册成额外的
MCP 工具。健康检查会真实调用各 provider(包括一次 DeepSeek Search API 请求;
成功请求按官方价格计费)。
搜索查询会发送给用户配置的搜索提供商;选择 deepseek-search、hybrid、
deepseek-native,或使用 auto 且配置了 DEEPSEEK_API_KEY 时,查询会发送给
DeepSeek:deepseek-search / hybrid 走官方 Search API
(api.deepseek.com/v1/tools/search),
deepseek-native 与 web_research 走 Anthropic 兼容 Messages API
(api.deepseek.com/anthropic/v1/messages)。设置
DEEPSEEK_SEARCH_NEED_CONTENT=on 时,Search API 请求会带 need_content: true,响应中会附带页面正文。启用外部重排后,候选结果摘要还会发送给 OpenRouter。
启用 WEB_SEARCH_DECISIONS_MODE 时,原始 query 会发送给 OpenRouter 的
web-grounded 决策模型(它自行检索并返回引用);启用 EMBEDDING_MODE 时,最多
8 条候选来源的标题、snippet 和 URL 会发送给 OpenRouter embedding。两者默认关闭。
项目本身不包含遥测。
质量控制与融合重排
web_search 未配置后端时默认使用 quality: "fast" 和 backend: "auto";有
DeepSeek key 时会把 deepseek-search 加入多源候选池,没有 key 时退回 external。
只有 balanced / deep 会启用外部重排、docs-intent veto 与语义转载折叠;fast
不会向 OpenRouter 发起重排/决策/嵌入请求。启用外部重排后,候选结果摘要才会发送给
OpenRouter。
fast 默认使用 FAST_CLEANING_MODE=shadow:会计算权威性、聚合站降权、同域名
上限和 provider coverage,但不改变旧客户端的返回顺序。完成 held-out 评估后可
切换为 on;off 完全关闭清洗。
offline replay(npm run quality:replay,70 个 synthetic case)当前测得:
方法 | mean nDCG@5 | officialInTop1 | 重复来源占比 | 独立来源数 |
| 0.9383 | 0.857 | 0.029 | 3.73 |
| 0.9552 | 0.929 | 0.000 | 3.66 |
收益集中在实测反馈对应的两类 query:
aggregator-dominance(聚合站排在官方页之前):nDCG@5 0.7414 → 0.9949,officialInTop10 → 1official/current/ambiguous/exploratory:0.9811 → 0.9811,无回退syndication(同一文章多语言 + 跨域转载):重复槽位占比降到 0, 低权威来源占比 0.80 → 0.67
这些数字全部来自 synthetic fixture,只作为工程回归信号,不构成真实相关性
证明,因此 FAST_CLEANING_MODE 默认仍是 shadow;确认真实标注数据后可切到 on。
与之相对,SOURCE_IDENTITY_MODE 默认是 on,因为折叠"同一篇文章的重复 URL"是
正确性修复而不是排序偏好,不存在此消彼长的取舍。
quality | provider 候选 | 候选目标 | 行为 |
| 每路 10 | 10 | 按 provider 顺序降级,不重排 |
| 每路 10 | 20 | 并行检索、重排(默认旧 1b-v2 模型)并做 50/50 rank fusion |
| 每路 15 | 30 | 更大候选集、重排(默认 3.5-8b 模型)并做 50/50 rank fusion |
在 backend: "hybrid" / 默认 auto 且存在 DeepSeek key 时,上表中的“每路”包含
deepseek-search;候选源采用轮询合并,避免某一 provider 填满前 max_results
而把 DeepSeek 源挤掉。每路实际请求上限为 min(20, max(max_results, 10/10/15)),
因此 max_results 较大时 count 会高于表中数值。
重排按 quality 选模型:balanced 默认用低延迟的
nvidia/llama-nemotron-rerank-vl-1b-v2:free,deep 默认用
nvidia/nemotron-3.5-rerank-8b:free(可用环境变量覆盖,见「OpenRouter 模型」)。
3.5 模型的原始分数分布被压缩(实测约 0.015–0.262),v1.6 的绝对阈值(0.35 floor /
0.50 top-1)会让重排几乎不生效;v1.7.0 因此在融合层加入显式标定:
RERANK_NORMALIZATION=auto:3.5 系模型做 min-max 归一化;旧 1b-v2 与未知/ 自定义模型保持 raw(绝对分数),不对陌生分数尺度做猜测性放大归一化只在分布确有信号时启用:候选少于 3 条或分数完全相同时按原始分数处理
弱信号保护:
spread < 0.02、max < 0.08或spread/max < 0.15时把校准 分数清零并标记signalQuality: "weak",rank fusion 不使用重排证据、保持 provider 顺序融合仍为 50/50:原始排名与重排排名各占一半,重排贡献按置信度缩放;低于
RERANK_CONFIDENCE_FLOOR(默认0.35)的分数不产生重排证据,0.35–1 之间 线性缩放,避免“噪声但排名靠前”压过可靠候选top-1 保护:原始第一名只有在重排后仍处于前 2 名、且校准分数 ≥
RERANK_TOP1_MIN(默认0.85)时才受保护;重排胜者若要凭权威性替换第一 名,也必须达到同一门槛。官方域名只获得有限先验,不能凭 URL 形态绕过重排置信度
rerank 报告新增 normalization(解析后的标定模式:raw / minmax)、
scoreRange {min,max,spread}(标定前的原始范围)、signalQuality(strong /
weak)与 usage;弱信号时 signalQuality: "weak" 且校准分数全部清零(该次融合
不产生重排证据),应视为保持 provider 顺序。候选数不超过 max_results 时不会
调用重排,报告 reason: candidate_count_not_larger_than_result_limit。
{
"query": "DeepSeek 官方 Search API 如何计费",
"scope": "global",
"max_results": 8,
"quality": "balanced",
"backend": "external"
}OpenRouter 缺 key、限流、超时或返回异常时,web_search 会回退到多 provider
原始顺序,并在结果中设置 rerank.applied=false 和 warning,不会让整次搜索失败;
主模型返回 404 时会先按 OPENROUTER_RERANK_FALLBACK_MODEL 重试一次。
旧的 rerank: true 仍作为兼容别名映射到 balanced;显式 quality 优先。
provider 搜索结果在进程内缓存 10 分钟,重排结果缓存 30 分钟(缓存 key 含模型), 决策概率缓存 24 小时,embedding 向量缓存 1 小时,均为有上限的 TTL/LRU,不写入 磁盘。MCP 进程重启后缓存清空。embedding 只在启用时参与「语义转载折叠」,不参与 重排排序或融合。
评估 harness(v1.7.0)
v1.7.0 的模型选型由离线 fixture + 验收门控支撑,避免只看单次线上结果:
# 采集:需要 OPENROUTER_API_KEY;先 build(读取 dist 里的生产 prompt/策略),
# 只写 test/fixtures/*.json,默认总预算 120 次请求
npm run eval:capture
# 可选:--dry-run 只校验数据;--only=rerank,decisions,semantic;--refresh 重新采集
# 离线回放:无网络、无密钥;读 test/fixtures,写 work/eval/report.json 并打印摘要
npm run eval:replay
# 验收门控:读 work/eval/report.json,写 work/eval/acceptance.json
npm run eval:accept已提交的离线 fixture:
test/fixtures/rerank-cases.json:带 relevance 标签的候选集,记录新旧重排模型分数test/fixtures/decisions-docs-intent.json:docs-intent 概率(每 query 重复采集), 并记录promptVersion/questionHash/requestShape用于检测生产 prompt 漂移test/fixtures/semantic-capture.json:重复/非重复文本对的 8b embedding cosine
评估流水线

LaTeX/TikZ 源文件:
docs/diagrams/eval-pipeline.tex
验收门控(scripts/eval/accept.mjs):
模块 | 门控 |
rerank | new-minmax 的 paired fused nDCG@5 相对 old-raw 不低于 -0.01;mean provider coverage top-5 > 0;calibration 实际生效(applied rate > 0);paired case 数 ≥ 15 |
decisions | 决定性 veto 的 false negative = 0;precision ≥ 0.95;recall ≥ 0.85;决定性 case 数 ≥ 10;fixture 的 promptVersion / questionHash 与 dist 一致(漂移即 FAIL) |
semantic | 存在候选阈值使 precision ≥ 0.95、recall ≥ 0.80、FPR ≤ 0.03;比较 pair 数 ≥ 20 |
v1.7.0 验证结果(2026-11-10)
当前提交的 fixture 上的离线结果(npm run eval:replay / npm run eval:accept):
构建与测试:
npm run build通过;npm test20 个文件 / 263 tests 全绿。验收门控:PASS(9 pass / 0 fail / 0 blocked / 5 info)。
模块 | 结果 |
rerank(20 cases,19 个 paired) | baseline nDCG@5 0.8314;old-raw 0.8503;new-minmax 0.8376;paired new-minmax vs old-raw -0.0054(门控 ≥ -0.01)。new-raw 0.8254 = baseline(证明不校准就是 no-op);old-minmax 比 old-raw 低 0.0185(说明不能对所有模型强制 minmax)。new-minmax calibration applied 100%。延迟:old p50/p95 1023/2117ms,new 2280/3128ms(在 12s profile 内) |
decisions(20 queries,12 regex-positive,10 decisive) | decisive precision/recall 1.0 / 1.0,veto-FN 0;applicable(含 dead band 回退正则)precision 0.75、dead band 3、regex-only baseline 0.5;p95 2127ms;promptVersion/questionHash 与 dist 一致 |
semantic(24 pairs) | 阈值 0.62:precision/recall 1.0 / 1.0、FPR 0;min duplicate 0.8657 / max distinct 0.6115(margin 0.2542)。0.55 时 precision 0.583 / FPR 0.294,因此默认阈值取 0.62 |
补充说明:
以上是 production prompt/state 下的结果;
decisions的 applicable precision 0.75 只作为 INFO、不作为门控,因此 decisions 仍默认off,建议先用shadow积累线上数据再评估是否开启。独立验证:v1.6.0 与 v1.7.0 在 flags-off 的 fast 搜索上逐字节一致;缺 key/坏 key 只降级不失败;shadow 模式不改变行为。
eval:accept 退出码:0 = 全部门控 PASS;1 = 有 FAIL;2 = 有 BLOCKED(fixture 或
构建产物缺失,未测量)。work/eval/ 下的 JSON 报告被 .gitignore 排除;CI
(.github/workflows/eval-offline.yml)在 push / PR 时执行 build、test、
eval:replay、eval:accept,并上传报告 artifact。重新采集前请阅读
scripts/eval/capture.mjs 的请求预算与 502 跳过规则。
Available Tools
2 toolsweb_researchWeb ResearchC
Use DeepSeek native web search to research a question and return citeable sources.
Inputs: query (required), freshness, max_sources.
web_searchWeb SearchC
Search the live web and return normalized, citeable sources.
Inputs: query (required), scope, rerank, freshness, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
Both `web_search` and `web_research` say they search the live web and return citeable sources, so an agent has little basis to choose between them. The descriptions overlap heavily and do not clearly define a simple-search versus deep-research boundary.
Both tool names follow the same lowercase `web_<verb>` pattern, which is predictable and consistent. Although `search` and `research` are semantically close, the naming convention itself is uniform.
Two tools is on the thin side for a web search server, and the second tool appears to be a near-duplicate of the first. Still, two tools is a defensible minimal set for a simple query-and-results workflow.
The server covers basic live-web searching and question-style research, but there are no tools for fetching specific URLs, filtering results, or managing research sessions. Deeper research workflows would likely need workarounds.
Related MCP Connectors
Web search, fetch, extract, and research for AI agents. Markdown output + AI-synthesized answers.
Search the web, fetch any URL and map a site as clean, LLM-ready Markdown.
Search the agentic web. 4,100+ sites, 11 tools incl. check_url + verify_mcp for probe-before-use.
The best web search for your AI Agent
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides unified web search across multiple providers (Google, Tavily, DuckDuckGo, Brave) with automatic fallback, maximizing free API quota usage for AI workflows.16MIT
- AlicenseBqualityCmaintenanceEnables deep web search across multiple providers including Google, Bing, Brave, DuckDuckGo, and Perplexity, with support for comprehensive AI-powered research using intelligent multi-engine queries.245 npm9MIT
- AlicenseNot gradedqualityDmaintenanceProvides multi-provider web search capabilities with fallback chains, semantic reranking, and content extraction for grounded agent retrieval.1MIT
- AlicenseNot gradedqualityDmaintenanceEnables web searches across multiple engines (DuckDuckGo, Bing, Google, SerpAPI, Google CSE, Tavily) with no API key required for the free engines, plus automatic fallback, caching, and webpage content fetching.MIT