QMD：本地文档语义搜索完全指南

# 语义搜索示例
qmd search "machine learning optimization techniques"
# 返回语义上相关的内容，不一定包含这些词

# 关键词搜索示例
qmd search "machine learning" --method bm25
# 只返回包含 "machine" 和 "learning" 的文档

# 初始化索引（扫描文档并创建数据库）
qmd index ~/documents

# 增量更新（只索引新文档或修改过的文档）
qmd index ~/documents --incremental

# 查看索引状态
qmd stats

# 启动 MCP Server
qmd mcp

# 输出示例
QMD MCP Server running on http://localhost:8080
MCP JSON-RPC endpoint: http://localhost:8080/mcp

<!-- CLAUDE.md -->
For any question about your local documents, use the qmd tool.

# QMD 语义搜索流程
def semantic_search(query, top_k=5):
    # 1. 使用 Ollama 将查询文本转换为向量
    query_embedding = ollama.embeddings(
        model="nomic-embed-text",
        prompt=query
    )
    
    # 2. 在向量数据库中搜索最相似的文档片段
    results = vector_db.search(
        query_embedding,
        n=top_k
    )
    
    # 3. 返回最相关的文档
    return results

# BM25 算法核心思想
def bm25_score(doc, query, k1=1.5, b=0.75):
    """
    - k1: 词频饱和参数（控制词频影响力）
    - b: 文档长度归一化参数
    """
    scores = []
    for term in query:
        tf = doc.term_freq(term)           # 词频
        df = corpus.doc_freq(term)        # 文档频率
        idf = log((N - df + 0.5) / (df + 0.5))  # 逆文档频率
        
        # BM25 公式
        score = idf * (tf * (k1 + 1)) / (tf + k1 * (1 - b + b * doc.len / avg_doc_len))
        scores.append(score)
    
    return sum(scores)

def hybrid_search(query, alpha=0.5):
    """
    alpha: 语义搜索权重 (1-alpha 是 BM25 权重)
    """
    # 获取语义搜索结果
    semantic_results = semantic_search(query)
    
    # 获取 BM25 结果
    bm25_results = bm25_search(query)
    
    # RRFR 融合
    fused_results = []
    for doc in corpus:
        rrf_score = 0
        for rank, result in enumerate(semantic_results[:k]):
            if result.doc == doc:
                rrf_score += 1 / (k + rank + 1)
        
        for rank, result in enumerate(bm25_results[:k]):
            if result.doc == doc:
                rrf_score += alpha / (k + rank + 1)
        
        fused_results.append((doc, rrf_score))
    
    return sorted(fused_results, key=lambda x: x[1], reverse=True)

# 安装 QMD
pip install qmd

# 验证安装
qmd --version

# 一键安装
curl -fsSL https://raw.githubusercontent.com/tobi/qmd/main/install.sh | sh

# 安装到指定目录
curl -fsSL https://raw.githubusercontent.com/tobi/qmd/main/install.sh | sh -s -- --prefix ~/.local

# macOS/Linux 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Windows: 下载安装包 https://ollama.com/download

# 启动 Ollama 服务
ollama serve

# 下载嵌入模型（推荐）
ollama pull nomic-embed-text

# 验证
ollama list

# Bash
qmd --completion bash >> ~/.bashrc

# Zsh
qmd --completion zsh >> ~/.zshrc

# Fish
qmd --completion fish > ~/.config/fish/completions/qmd.fish

# 创建索引（会扫描所有支持的文件）
qmd index ~/documents

# 指定目录
qmd index /path/to/papers

# 递归扫描子目录
qmd index ~/documents --recursive

# 查看索引统计
qmd stats

# 语义搜索（默认）
qmd search "What is transformer architecture?"

# 关键词搜索
qmd search "transformer attention" --method bm25

# 混合搜索
qmd search "neural network optimization" --method hybrid

# 显示更多结果
qmd search "machine learning" --top 10

# 简短输出
qmd search "python async"

# 输出示例
---
Score: 0.89
File: /docs/python-guide.md
Line: 42
Snippet: "Python's async/await syntax provides..."
---

Score: 0.85
File: /docs/advanced-python.md
Line: 128
Snippet: "Asynchronous programming in Python uses..."

# 增量索引（只处理新文件）
qmd index ~/documents --incremental

# 强制重建索引
qmd index ~/documents --rebuild

from qmd import QMD

# 初始化
qmd = QMD(
    data_dir="~/.local/share/qmd",  # 数据目录
    embed_model="nomic-embed-text"    # 嵌入模型
)

# 添加文档
qmd.add("~/documents/python-guide.md")
qmd.add("~/documents/notes/")

# 搜索
results = qmd.search("async programming in Python")
for result in results:
    print(f"{result.file}:{result.line} - {result.snippet}")

from qmd import SearchMethod

# 配置搜索参数
results = qmd.search(
    query="machine learning optimization",
    method=SearchMethod.HYBRID,  # 混合搜索
    alpha=0.7,                    # 语义权重
    top_k=10,                     # 返回结果数
    min_score=0.5                 # 最低分数阈值
)

# 只搜索特定格式
results = qmd.search(
    "Python best practices",
    extensions=[".md", ".txt"]    # 只搜索 Markdown 和文本
)

# 排除特定目录
results = qmd.search(
    "API design",
    exclude_dirs=[".git", "node_modules", "__pycache__"]
)

# 查看索引统计
stats = qmd.stats()
print(f"文档数: {stats['num_docs']}")
print(f"索引大小: {stats['index_size']} bytes")

# 重建索引
qmd.rebuild()

# 清理缓存
qmd.clean()

# 启动 Server
qmd mcp --port 8080

# 后台运行
qmd mcp --port 8080 &

# Local Document Search
For questions about code, documentation, or technical topics, use qmd to search local documents:

1. First, index the documents if not already done:
   `qmd index ~/path/to/documents`

2. Search using semantic or keyword search:
   `qmd search "your question here"`

3. For technical queries, prefer semantic search for best results.

{
  "mcpServers": {
    "qmd": {
      "command": "qmd",
      "args": ["mcp", "--port", "8080"],
      "env": {
        "QMD_DATA_DIR": "~/.local/share/qmd"
      }
    }
  }
}

[general]
# 数据目录
data_dir = "~/.local/share/qmd"

# 索引目录
index_dir = "~/.local/share/qmd/index"

# 日志级别
log_level = "INFO"

[search]
# 默认搜索方法 (semantic, bm25, hybrid)
default_method = "hybrid"

# 默认返回结果数
default_top_k = 5

# 语义搜索权重（用于混合搜索）
semantic_weight = 0.7

[embed]
# Ollama 服务地址
ollama_base_url = "http://localhost:11434"

# 嵌入模型
model = "nomic-embed-text"

# 批处理大小
batch_size = 32

[index]
# 并行线程数
num_workers = 4

# 文件大小限制（MB）
max_file_size = 50

# 排除的目录
exclude_dirs = [".git", "node_modules", "__pycache__", ".venv"]

# 使用多线程加速索引
qmd index ~/documents --num-workers 8

# SSD vs HDD
# SSD: ~1000 docs/min
# HDD: ~200 docs/min

# 查看内存使用
qmd stats

# 典型内存占用
# 10,000 文档: ~500MB RAM
# 100,000 文档: ~4GB RAM

# 检查 Ollama 是否运行
ollama list

# 如果没有运行，启动它
ollama serve

# 检查端口
curl http://localhost:11434

# 重新下载嵌入模型
ollama pull nomic-embed-text

# 使用其他模型
export QMD_EMBED_MODEL="mxbai-embed-large"

# 备份并重建索引
cp -r ~/.local/share/qmd ~/.local/share/qmd.bak
qmd index ~/documents --rebuild

# 检查 Ollama 是否运行
ollama list

# 如果没有运行，启动它
ollama serve

# 检查端口
curl http://localhost:11434

# 重新下载嵌入模型
ollama pull nomic-embed-text

# 使用其他模型
export QMD_EMBED_MODEL="mxbai-embed-large"

# 备份并重建索引
cp -r ~/.local/share/qmd ~/.local/share/qmd.bak
qmd index ~/documents --rebuild