项目地址: research/qmd/

核心架构洞察

1. Hybrid Search Pipeline

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
Query → [Strong Signal检测] → 跳过LLM扩展
     ↓
     expandQuery (LLM) → [lex, vec, hyde] 类型变体
     ↓
┌────┴────┐
BM25(lex)  Vector(vec/hyde)  ← batch embed优化
└────┬────┘
     ↓
RRF Fusion (带权重 + top-rank bonus)
     ↓
Chunk Document (智能Markdown分块)
     ↓
Pick Best Chunk (关键词重叠评分)
     ↓
Rerank (qwen3-reranker)
     ↓
Position-Aware Blend (RRF rank + reranker score)
     ↓
Final Results

2. 关键设计模式

模式 实现 洞察
Strong Signal Skip BM25 score > 0.85 且 gap > 0.15 高置信时跳过昂贵LLM调用
Smart Chunking 按Markdown标题层级评分 h1=100, h2=90…空白=20
Code Fence Protection 检测```区域禁止切割 避免破坏代码块
RRF Weight 前2个列表2x权重 原始查询优先级最高
Position-Aware Blend rank ≤3: 0.75RRF, ≤10: 0.60 保护头部结果不被rerank推翻

3. 查询类型系统

1
2
3
4
type QueryType = 'lex' | 'vec' | 'hyde';
// lex → BM25关键词
// vec → 语义向量
// hyde → 假设文档生成

4. RRF核心算法

1
2
score = Σ(weight / (k + rank + 1))  // k=60
// top-rank bonus: rank0 +0.05, rank1-2 +0.02

关键文件

文件 行数 功能
store.ts 3392 核心搜索pipeline
llm.ts 1421 GGUF模型抽象层
mcp.ts 876 MCP服务器实现
qmd.ts 3241 CLI入口

技术决策批判

优点:

  • 本地优先，隐私保护
  • 多层缓存（expandQuery, rerank）
  • 批量embedding优化
  • 结构化搜索支持LLM直接调用

局限:

  • Bun运行时依赖（非Node.js主流）
  • GGUF模型需要下载管理
  • 无时间衰减（文档年龄不影响排序）
  • 单机SQLite，无分布式支持

可借鉴点

  1. Strong Signal Skip - 适合所有LLM-augmented系统
  2. 智能分块 - Markdown感知的分段策略
  3. Position-Aware Blend - 平衡检索和重排序
  4. 类型化查询 - lex/vec/hyde分离路由

本地集成状态

位置: research/qmd/
状态: ✅ BM25搜索可用, ⚠️ 向量搜索需要 Homebrew SQLite

配置:

1
2
3
4
5
6
7
8
# Collection: workspace (408个md文件)
qmd collection add ~/Github/ws --name workspace --mask "**/*.md"

# Context
qmd context add qmd://workspace "个人工作空间"

# MCP HTTP 服务器
qmd mcp --http --port 8181 --daemon

API测试:

1
2
3
curl -X POST http://localhost:8181/search \
  -H "Content-Type: application/json" \
  -d '{"searches":[{"type":"lex","query":"cognitive debt"}],"limit":3}'

限制: macOS 上 sqlite-vec 需要扩展加载支持，默认系统 SQLite 不支持。BM25 可独立工作。