qsearch

qsearch

我为自己的日常研究构建了这个工具。完成 100 多次研究冲刺后，我的 Agent 总是产生幻觉，因为它读取的是 200 字符的摘要。qsearch 为它提供完整内容和多引擎来源信息——在本地运行，由我掌控。

由于读取的是 200 字符的摘要而非完整页面，AI Agent 会有 17–33% 的事实因幻觉而丢失（斯坦福大学 2024 年研究）。现有搜索 API 不会透露哪些引擎给出了相同结果。现有知识图谱要么价格高昂，面向企业，要么受供应商锁定。

qsearch 是一款开源搜索层，可为 Agent 提供完整内容和多引擎来源信息——在你的机器上运行，由你掌控，现在即可用于 MCP。

✅ v0.4.0 已在 qsearch.pro 上线。 多引擎归因，包含 URL 来源信息的可信语料库（engines[]、sweep_count、trust_score），/ui 语料库查看器，以及适用于 Claude Code 和任何符合规范的客户端的 MCP-over-HTTP。 📖 架构： ARCHITECTURE.md · 愿景： docs/VISION.md · 技术规范： docs/TRUST_MESH.md · 联邦架构深入解析： docs/FEDERATION_ARCHITECTURE.md

演示

60 秒快速了解：/health（服务正在运行，且在本地）→ /sweep（多引擎 engines[] 归因）→ /verify（引文来源是否真正支持该论断？）。运行 npm start 后，通过 bash scripts/record-demo.sh 在本地复现——参见 docs/launch/README-demo-embed.md。

快速入门

5 分钟内运行——免费套餐，无需 API 密钥：

git clone https://github.com/theYahia/qsearch.git && cd qsearch
cp .env.example .env.local       # works as-is on the $0 SearXNG tier
docker compose up -d             # Meilisearch + Qdrant + SearXNG
npm install && npm start         # → qsearch on http://localhost:8080

# multi-engine attribution in one call
curl -X POST http://localhost:8080/sweep \
  -H "Content-Type: text/plain" \
  --data-binary $'t1|self-hosted search engine\n'
# → parsed_snippets.md with "Engines: google, duckduckgo, brave (count=3)"

broad 扫描层级使用可自托管的 SearXNG 运行，完全免费。只有在需要 focused/critical 层级时，才需要添加 Brave 密钥。完整设置（Brave 密钥、Ollama、MCP 服务）见下文。

# 1. Clone
git clone https://github.com/theYahia/qsearch.git
cd qsearch

# 2. Get a Brave Search API key (BYOK, $5/mo for ~1000 queries)
#    → https://brave.com/search/api/ → sign up → copy key

# 3. Configure
cp .env.example .env.local
# Set BRAVE_API_KEY=your_key
# Set SEARXNG_URL=http://localhost:8888 (for multi-engine attribution)

# 4. Start infrastructure (Meilisearch + Qdrant + SearXNG)
docker compose up -d

# 5. (Optional) Pull Ollama models for local LLM cleaning + embedding rerank
#    Without them, search still works — just no cleaned_markdown and no rerank.
ollama pull qwen2.5:7b-instruct   # ~5GB, cleaner (used by /sweep_context)
ollama pull nomic-embed-text      # 274MB, embedding rerank (Phase B)

# 6. Install & run
npm install
npm start            # → qsearch v0.4.0 on http://localhost:8080

# 7. (Optional) MCP server for Claude Code / Workbench / OpenClaw
npm run start:mcp    # → http://0.0.0.0:8081

# 8. Test multi-engine attribution
curl -X POST http://localhost:8080/sweep \
  -H "Content-Type: text/plain" \
  --data-binary $'t1|self-hosted search engine\n'
# → parsed_snippets.md with "Engines: google, duckduckgo, brave (count=3)"

我日常如何使用

每次研究冲刺，我都会运行双重扫描：

# Brave sweep (primary, authoritative)
python research/scripts/brave_sweep.py queries.txt _raw_data/topic_2026-04-28/brave/

# qsearch sweep (secondary, auto-indexes into corpus)
curl -X POST http://localhost:8080/sweep?topic=my_topic \
  -H "Content-Type: text/plain" --data-binary @queries.txt

在同一领域完成 10 多次冲刺后，/corpus/top?min_engines=3 会显示哪些 URL 在多个会话中经受住了多个独立搜索引擎的检验。这些才是我真正信任的来源。

qsearch 的存在意义

如今，每个 AI Agent 都会陷入同一个失效循环：

Agent → Tavily/Exa/Serper API → 200-char snippets → hallucinated answer

三大问题：

1. 仅有摘要并不足够。Stanford 2024 年生产环境 RAG 审计测得 Lexis+ AI 和 Westlaw 的幻觉率为 17–33%，尽管它们声称“不会产生幻觉”。在 Wikipedia 问答中，完整内容比基于摘要的 RAG 高 7.3 个百分点（arxiv 2501.01880）。

2. **缺少可信度信号。**搜索 API 返回排序列表，却不告诉你哪些引擎达成了一致。排名第 3 位的 SEO 垃圾内容，看起来和排名第 4 位的权威来源毫无区别。

3. **没有记忆。**每次搜索都从零开始。同样的垃圾内容会再次出现，同样的权威来源也始终得不到识别。

qsearch 解决了这三个问题：

• 抓取并清理完整内容，而不只是摘要。
• 每条结果都有 engines[] 字段——公开显示 Google、DDG、Brave、Qwant 和 Startpage 的来源归属（通过 SearXNG 聚合）。
• 本地语料库持续累积——每个 URL 都会在多轮搜索中逐步形成可信度档案。

工作原理

flowchart LR
    A[Your agent] -->|query| Q[qsearch]
    Q -->|fan out| B[Brave Search API]
    Q -->|fan out| S["SearXNG\n(Google, DDG, Brave, Qwant, …)"]
    B -->|results| Q
    S -->|results + engines[]| Q
    Q -->|index by URL| C["Local corpus\n(Meilisearch + Qdrant)"]
    C -->|trust score| Q
    Q -->|re-ranked + full content + provenance| A

    style C fill:#fde68a,stroke:#d97706,color:#000
    style Q fill:#93c5fd,stroke:#2563eb,color:#000
    style S fill:#86efac,stroke:#16a34a,color:#000

黄色节点是你的私有语料库。被 5 个引擎、经过 3 轮搜索、涵盖 4 个主题找到的 URL，会自然形成可信度评分——无需人工排序、集中式权威机构，也无需云端往返。

qsearch 对比

API — v0.4.0

搜索端点

/search 接受：query、n_results（1–20）、freshness（pd/pw/pm/py）、search_lang、country、corpus_first（默认为 true）、corpus_only（默认为 false）。

/sweep 接受 text/plain 请求体，每行一个查询，格式为 label|query[|priority][|domain]：

• priority ∈ broad（默认，SearXNG，$0）/ focused（Brave，约 $0.005）/ critical（Brave + LLM Context，约 $0.01）
• domain ∈ general（默认）/ scholarly（arxiv+PubMed+S2，$0）/ ru（偏向 language=ru-RU 的 SearXNG，$0）

# Examples
bench_a|qdrant production latency benchmarks|focused
sch_a|crispr cas9 off target effects|broad|scholarly
ru_a|tadviser сро рейтинг 2025|broad|ru
crit_a|self-hosted vector DB choice 2026|critical
gen|simple search|broad        # 2-field still works — defaults broad/general

会自动将结果索引到 Meilisearch，并将 engines[] 和 engine_count 设为可筛选字段。

/academic_search 接受 JSON：{ query, n_results (1-20), sources?: ["arxiv","pubmed","semanticscholar"] }。并行请求全部三个来源，按 DOI／标题去重，并交错返回排名靠前的结果。

多引擎归因示例

curl -X POST http://localhost:8080/sweep \
  -H "Content-Type: text/plain" \
  --data-binary $'t1|self-hosted search engine 2026\n'

输出摘录（parsed_snippets.md）：

**1. GitHub - searxng/searxng**
- URL: https://github.com/searxng/searxng
- Engines: google, duckduckgo, brave, qwant (count=4)
  > A privacy-respecting, hackable metasearch engine...

**2. random-blog.io/seo-spam-2026**
- URL: https://random-blog.io/seo-spam-2026
- Engines: google (count=1)
  > Best self-hosted search engines you must try...

URL #1 的 engine_count=4——由 4 个独立引擎找到。URL #2 的 engine_count=1——仅由一个引擎找到。可信度信号直接构建在数据中，而非事后附加。

在 Meilisearch 中按可信度筛选

curl -H "Authorization: Bearer masterKey" \
  "http://localhost:7700/indexes/qsearch_corpus/documents?filter=engine_count%20%3E%3D%203"

仅返回由 3 个或更多引擎找到的 URL——即你的高可信度子集。

MCP 集成

MCP 服务位于此仓库中——没有对应的 npm 包。请从源代码运行：

git clone https://github.com/theYahia/qsearch.git && cd qsearch
npm install
npm start            # REST API on :8080 — must be running first
npm run start:mcp    # MCP server (Streamable HTTP) on :8081

Claude Code

添加到 ~/.claude/settings.json：

{
  "mcpServers": {
    "qsearch": {
      "type": "http",
      "url": "http://localhost:8081"
    }
  }
}

可用工具：

• mcp__qsearch__web_search — 通过 Brave 或 SearXNG 进行网页搜索
• mcp__qsearch__sweep — 批量研究搜索，支持多引擎归因
• mcp__qsearch__academic_search — 通过 arxiv + PubMed + Semantic Scholar 搜索同行评审论文
• mcp__qsearch__sweep_context — 第 3 阶段本地 LLM 页面内容提取（免费，Ollama）
• mcp__qsearch__verify_citation — 被引用的 URL 是否确实支持该主张？（Supported/Partial/Unsupported/Fabricated）
• mcp__qsearch__economy_report — 与全用 Brave 的基准相比的成本明细
• mcp__qsearch__index_research — 按 glob 模式索引本地 .md 文件
• mcp__qsearch__news_search — 新闻搜索（需要 Brave 密钥）
• mcp__qsearch__context_search — 深度提取页面内容（需要 Brave 密钥）

其他基于 HTTP 的 MCP 客户端

qsearch 在端口 :8081 的 / 路径上提供 Streamable HTTP 传输。兼容 Claude Desktop（HTTP 模式）、OpenClaw 以及任何符合规范的 MCP 客户端。

技术栈

路线图

完整介绍以及在能够兑现承诺之前为何联邦功能仅属于研究方向，请参阅 docs/VISION.md。

权衡说明

• 冷启动。 首次扫描需要 5–10 秒（引擎扇出 + 语料库索引）。建议作为长期运行的守护进程使用。
• 向量搜索在 Windows 上受限。 Qdrant 需要 bare-runtime；并非支持所有平台。全文搜索 Meilisearch 可在所有平台上运行。
• SearXNG 速率限制。 必须自托管 — 公共实例会被 Google 屏蔽。我们的 docker-compose 已处理此问题。
• engines[] 需要 SearXNG。 纯 Brave 模式仍可运行，但会失去多引擎信号。
• 获取完整内容会增加延迟。 约 31 秒，而朴素摘要检索约 3 秒（双向 RAG 研究）。qsearch 通过 /context 端点将此功能设为可选。

关注

• 🌐 在线演示： qsearch.pro
• ⭐ Star： github.com/theYahia/qsearch
• 🐦 X： @TheTieTieTies

许可证

Apache-2.0 — 详见 LICENSE。独立项目。BYOK。可自托管。无供应商锁定。

WWmcp 的一部分 · Telegram：@vhodvai