Knowledge Rag

知识RAG

 ](https://www.npmjs.com/package/knowledge-rag) ](https://pepy.tech/projects/knowledge-rag)    

你的文档，你的机器，零云。Claude Code在本地搜索它们。

放下你的PDF、markdown、代码、笔记本-- 1800多个文件，39K个块，在3分钟内索引。

通过12个MCP工具进行混合搜索（BM25+语义向量+交叉编码器重新排序）。

所有内容都通过ONNX在本地运行。没有Docker，没有Ollama，没有API密钥，没有数据离开您的机器。

pip install knowledge-rag → restart Claude Code → search_knowledge("your query")

______________________________________________________________________

12个MCP工具 | 混合搜索+重新排名 | 20种文件格式 | 可选NVIDIA GPU | 100%本地

最新动态 | 支持格式 | 安装 | 配置 | API 参考 | 建筑

______________________________________________________________________

v3.9.0的新增功能

质量门——7柱PR验证

现在，每个PR（包括可靠性颠簸和单线修复）都会根据以下因素进行评估 35+自动检查 在任何人工审查之前，分布在7个支柱上：

加上a 夜间弹性工作流程 在选定模块上运行混沌故障注入（HF关闭、ChromaDB损坏、看门狗崩溃、ONNX零字节重放）、确定性检查（全套×3）和突变测试。

关键修补程序--不再有无声的零矢量损坏（v3.8.1）

FastEmbedEmbeddings.__call__ 不再接受异常和返回 [[0.0]*dim, ...] 当ONNX模型加载失败时。这个bug早就存在于master中，但并没有被发现：ChromaDB愉快地存储了零个嵌入， count() 报告正常数字时，智能重新索引会跳过它们，因为“已经索引”，查询返回的垃圾相似性没有可见的错误。现在加薪 EmbeddingModelLoadError / EmbeddingError 大声地。 所有v3.8.0用户都应该升级。 详细信息请参见 更新日志.

延迟加载嵌入——更便宜的空闲进程（v3.8.0）

FastEmbed ONNX型号（约200MB驻留）现在加载到 第一个查询，而不是在启动时。闲置 knowledge-rag 现在工艺真的很便宜。为什么这很重要：MCP stdio是每个客户端按协议的一个进程——多个克劳德代码窗口、克劳德桌面+IDE同时运行，或者打开额外连接的审查/批准流都会产生自己的进程。在v3.8.0之前，他们每个人都预先支付了完整的嵌入模型成本。现在，只有实际为查询提供服务的进程才会加载模型。公共API保持不变。

选择加入单实例保护（v3.8.0）

对于那些测量了他们的设置并希望每个服务器有一个硬上限的用户 data_dir:

export KNOWLEDGE_RAG_SINGLE_INSTANCE=1

第二个实例立即退出，代码为75。 默认为OFF 因此多客户端MCP的使用继续保持不变。陈旧PID恢复+SIGINT/SIGTERM清理正确连接。完整指南 docs/single-instance.md中的MCP配置示例 examples/mcp-config-single-instance.json.

5种安装方法

npx -y knowledge-rag                    # NPM — zero setup, auto-manages Python venv
pip install knowledge-rag               # PyPI — classic Python install
curl -fsSL .../install.sh | bash        # One-line installer (Linux/macOS/Windows)
docker pull ghcr.io/lyonzin/knowledge-rag  # Docker — models pre-downloaded
git clone ... && pip install -r ...     # From source

所有方法都产生相同的MCP服务器。看 安装 获取完整说明。

近期亮点

• v3.9.0 — 质量门 已激活：7个支柱（安全性、稳定性、内存泄漏、多功能性、可扩展性、版本控制、质量）的35+自动PR检查+夜间弹性套件（混乱、浸泡、确定性、突变）
• v3.8.1 --关键修补程序：大声失败嵌入（不再无声的零向量损坏）；Windows CI片已纠正（HF_HUB_OFFLINE+外壳：bash+atexit包装器）
• v3.8.0 --延迟加载嵌入、选择加入单实例保护、跨PyPI/NPM/Docker的版本同步
• v3.6.0 --多语言代码解析（C/C++/JS/TS/XML）、NPM包装器、Docker镜像、自动发布管道
• v3.5.2 --从pip包中自动发现CUDA DLL，优雅的GPU→CPU回退，显式CPU提供程序（在以下情况下无CUDA噪声 gpu: false)，已修复可编辑安装的BASE_DIR分辨率问题
• v3.5.1 --删除Python **提示：** 解析器调度是可扩展的。映射到的任何格式 _parsers 可以通过以下方式启用 supported_formats` 在config.yaml中。

______________________________________________________________________

特性

______________________________________________________________________

建筑

系统概述

flowchart TB
    subgraph MCP["MCP SERVER (FastMCP)"]
        direction TB
        TOOLS["12 MCP Tools
search | get | add | update | remove
reindex | list | stats | url | similar | evaluate"]
    end

    subgraph SEARCH["HYBRID SEARCH ENGINE"]
        direction LR
        ROUTER["Keyword Router
(word boundaries)"]
        SEMANTIC["Semantic Search
(ChromaDB)"]
        BM25["BM25 Keyword
(rank-bm25 + expansion)"]
        RRF["Reciprocal Rank
Fusion (RRF)"]
        RERANK["Cross-Encoder
Reranker"]

        ROUTER --> SEMANTIC
        ROUTER --> BM25
        SEMANTIC --> RRF
        BM25 --> RRF
        RRF --> RERANK
    end

    subgraph STORAGE["STORAGE LAYER"]
        direction LR
        CHROMA[("ChromaDB
Vector Database")]
        COLLECTIONS["Collections
security | ctf
logscale | development"]
        CHROMA --- COLLECTIONS
    end

    subgraph EMBED["EMBEDDINGS (In-Process)"]
        FASTEMBED["FastEmbed ONNX
BAAI/bge-small-en-v1.5
(384D, CPU or GPU)"]
        CROSSENC["Cross-Encoder
ms-marco-MiniLM-L-6-v2"]
        FASTEMBED --- CROSSENC
    end

    subgraph INGEST["DOCUMENT INGESTION"]
        PARSERS["20 Parsers
MD | PDF | TXT | PY | C | H | CPP | JS | JSX | TS | TSX | JSON | XML | CSV
DOCX | XLSX | PPTX | IPYNB | MQH | MQ4"]
        CHUNKER["Chunking
MD: section-aware
Other: 1000 chars + 200 overlap"]
        PARSERS --> CHUNKER
    end

    CLAUDE["Claude Code"] --> MCP
    MCP --> SEARCH
    SEARCH --> STORAGE
    STORAGE --> EMBED
    INGEST --> EMBED
    EMBED --> STORAGE

查询处理流程

flowchart TB
    QUERY["User Query
'mimikatz credential dump'"] --> EXPAND

    subgraph EXPANSION["Query Expansion"]
        EXPAND["Synonym Expansion
mimikatz -> mimikatz, sekurlsa, logonpasswords"]
    end

    EXPAND --> ROUTER

    subgraph ROUTING["Keyword Routing"]
        ROUTER["Keyword Router"]
        MATCH{"Word Boundary
Match?"}
        CATEGORY["Filter: redteam"]
        NOFILTER["No Filter"]

        ROUTER --> MATCH
        MATCH -->|Yes| CATEGORY
        MATCH -->|No| NOFILTER
    end

    subgraph HYBRID["Hybrid Search"]
        direction LR
        SEMANTIC["Semantic Search
(ChromaDB embeddings)
Conceptual similarity"]
        BM25["BM25 Search
(expanded query)
Exact term matching"]
    end

    subgraph FUSION["Result Fusion + Reranking"]
        RRF["Reciprocal Rank Fusion
score = alpha * 1/(k+rank_sem)
+ (1-alpha) * 1/(k+rank_bm25)"]
        RERANK["Cross-Encoder Reranker
Re-scores top 3x candidates
query+doc pair scoring"]
        SORT["Sort by Reranker Score
Normalize to 0-1"]

        RRF --> RERANK --> SORT
    end

    CATEGORY --> HYBRID
    NOFILTER --> HYBRID
    SEMANTIC --> RRF
    BM25 --> RRF

    SORT --> RESULTS["Results
search_method: hybrid|semantic|keyword
score + reranker_score + raw_rrf_score"]

文件摄入流程

flowchart LR
    subgraph INPUT["Input"]
        FILES["documents/
├── security/
├── development/
├── ctf/
└── general/"]
    end

    subgraph PARSE["Parse (20 formats)"]
        MD["Markdown"]
        PDF["PDF
(PyMuPDF)"]
        OFFICE["DOCX | XLSX
PPTX | CSV"]
        CODE["PY | C | H | CPP | JS | JSX
TS | TSX | JSON | XML | IPYNB"]
    end

    subgraph CHUNK["Chunk"]
        MDSPLIT["MD: Section-Aware
Split at ## headers"]
        TXTSPLIT["Other: Fixed-Size
1000 chars + 200 overlap"]
        DEDUP["SHA256 Dedup
Skip duplicate content"]
    end

    subgraph EMBED["Embed"]
        FASTEMBED["FastEmbed ONNX
bge-small-en-v1.5
(384D, CPU or GPU)"]
    end

    subgraph STORE["Store"]
        CHROMADB[("ChromaDB")]
        BM25IDX["BM25 Index"]
    end

    FILES --> MD & PDF & OFFICE & CODE
    MD --> MDSPLIT
    PDF & OFFICE & CODE --> TXTSPLIT
    MDSPLIT --> DEDUP
    TXTSPLIT --> DEDUP
    DEDUP --> EMBED
    EMBED --> STORE

hybrid_alpha参数效应

flowchart LR
    subgraph ALPHA["hybrid_alpha values"]
        A0["0.0
Pure BM25
Instant"]
        A3["0.3 (default)
Keyword-heavy
Fast"]
        A5["0.5
Balanced"]
        A7["0.7
Semantic-heavy"]
        A10["1.0
Pure Semantic"]
    end

    subgraph USE["Best For"]
        U0["CVEs, tool names
exact matches"]
        U3["Technical queries
specific terms"]
        U5["General queries"]
        U7["Conceptual queries
related topics"]
        U10["'How to...' questions
conceptual search"]
    end

    A0 --- U0
    A3 --- U3
    A5 --- U5
    A7 --- U7
    A10 --- U10

______________________________________________________________________

安装

先决条件

• Python 3.11+
• Claude 代码命令行工具
• 约200MB磁盘用于模型缓存（首次运行时自动下载）
• *可选：* NVIDIA GPU+CUDA加速嵌入(pip install knowledge-rag[gpu] + models.embedding.gpu: true 在配置中）

安装方法

选择一个——所有这些都产生相同的运行服务器。

选项A:NPX（最快）

需要Node.js 16+。自动处理Python venv、pip安装和版本升级。

claude mcp add knowledge-rag -s user -- npx -y knowledge-rag

就是这样。在第一轮比赛中， npx 在以下位置创建venv ~/.knowledge-rag/，安装PyPI包，并启动MCP服务器。后续运行重用缓存的venv。

选项B：单线安装器

# Linux/macOS:
curl -fsSL https://raw.githubusercontent.com/lyonzin/knowledge-rag/master/install.sh | bash

# Windows (PowerShell):
irm https://raw.githubusercontent.com/lyonzin/knowledge-rag/master/install.ps1 | iex

然后配置克劳德代码：

claude mcp add knowledge-rag -s user -- ~/knowledge-rag/venv/bin/python -m mcp_server.server

视窗: claude mcp add knowledge-rag -s user -- %USERPROFILE%\knowledge-rag\venv\Scripts\python.exe -m mcp_server.server

选项C:pip安装

mkdir ~/knowledge-rag && cd ~/knowledge-rag
python3 -m venv venv && source venv/bin/activate
pip install knowledge-rag
knowledge-rag init              # Exports config template, presets, creates documents/

然后配置克劳德代码：

claude mcp add knowledge-rag -s user -- ~/knowledge-rag/venv/bin/python -m mcp_server.server

windows用户：使用 python 而不是 python3, venv\Scripts\activate 而不是 source venv/bin/activate. Windows路径: claude mcp add knowledge-rag -s user -- %USERPROFILE%\knowledge-rag\venv\Scripts\python.exe -m mcp_server.server

选项D：从源克隆

git clone https://github.com/lyonzin/knowledge-rag.git ~/knowledge-rag
cd ~/knowledge-rag
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

然后配置克劳德代码：

claude mcp add knowledge-rag -s user -- ~/knowledge-rag/venv/bin/python -m mcp_server.server

选项E:Docker

docker pull ghcr.io/lyonzin/knowledge-rag:latest

claude mcp add knowledge-rag -s user -- \
  docker run -i --rm \
  -v ~/knowledge-rag/documents:/app/documents \
  -v ~/knowledge-rag/data:/app/data \
  ghcr.io/lyonzin/knowledge-rag:latest

模型已在映像中预先下载，没有首次运行延迟。

Alternative: manual JSON config

添加 ~/.claude.json:

窗户：

{
  "mcpServers": {
    "knowledge-rag": {
      "command": "C:\\Users\\YOUR_USER\\knowledge-rag\\venv\\Scripts\\python.exe",
      "args": ["-m", "mcp_server.server"]
    }
  }
}

Linux/macOS：

{
  "mcpServers": {
    "knowledge-rag": {
      "command": "/home/YOUR_USER/knowledge-rag/venv/bin/python",
      "args": ["-m", "mcp_server.server"]
    }
  }
}

替换 YOUR_USER 使用您的用户名，或使用来自的完整路径 echo $HOME.

验证

claude mcp list

首次启动时，服务器将：

1. 下载嵌入模型（~50MB，缓存在 models_cache/)
2. 自动索引中的任何文档 documents/ 目录
3. 开始监视文件更改（自动重新索引）

______________________________________________________________________

用法

添加文档

将您的文件放在 documents/ 目录，按类别组织：

documents/
├── security/          # Pentest, exploit, vulnerability docs
├── development/       # Code, APIs, frameworks
├── ctf/               # CTF writeups and methodology
├── logscale/          # LogScale/LQL documentation
└── general/           # Everything else

或者通过MCP工具以编程方式添加文档：

# Add from content
add_document(
    content="# My Document\n\nContent here...",
    filepath="security/my-technique.md",
    category="security"
)

# Add from URL
add_from_url(
    url="https://example.com/article",
    category="security",
    title="Custom Title"
)

搜索

配置后，Claude会自动使用RAG系统。您还可以控制搜索行为：

# Pure keyword search — instant, no embedding needed
search_knowledge("gtfobins suid", hybrid_alpha=0.0)

# Keyword-heavy (default) — fast, slight semantic boost
search_knowledge("mimikatz", hybrid_alpha=0.3)

# Balanced hybrid — both engines equally weighted
search_knowledge("SQL injection techniques", hybrid_alpha=0.5)

# Semantic-heavy — better for conceptual queries
search_knowledge("how to escalate privileges", hybrid_alpha=0.7)

# Pure semantic — embedding similarity only
search_knowledge("lateral movement strategies", hybrid_alpha=1.0)

索引

文档在首次启动时会自动编入索引。要管理索引，请执行以下操作：

# Incremental: only re-index changed files (fast)
reindex_documents()

# Smart reindex: detect changes + rebuild BM25
reindex_documents(force=True)

# Nuclear rebuild: delete everything, re-embed all (use after model change)
reindex_documents(full_rebuild=True)

评估检索质量

evaluate_retrieval(test_cases='[
    {"query": "sql injection", "expected_filepath": "security/sqli-guide.md"},
    {"query": "privilege escalation", "expected_filepath": "security/privesc.md"}
]')
# Returns: MRR@5, Recall@5, per-query results

______________________________________________________________________

API 参考

搜索与查询

search_knowledge

结合语义搜索+BM25关键字搜索和跨编码器重新排序的混合搜索。

退货：

{
  "status": "success",
  "query": "mimikatz credential dump",
  "hybrid_alpha": 0.5,
  "result_count": 3,
  "cache_hit_rate": "0.0%",
  "results": [
    {
      "content": "Mimikatz can extract credentials from memory...",
      "source": "documents/security/credential-attacks.md",
      "filename": "credential-attacks.md",
      "category": "security",
      "score": 0.9823,
      "raw_rrf_score": 0.016393,
      "reranker_score": 0.987654,
      "semantic_rank": 2,
      "bm25_rank": 1,
      "search_method": "hybrid",
      "keywords": ["mimikatz", "credential", "lsass"],
      "routed_by": "redteam"
    }
  ]
}

搜索方法值：

• hybrid：通过语义和BM25搜索找到（最高置信度）
• semantic：仅通过语义搜索找到
• keyword：仅通过BM25关键字搜索找到

______________________________________________________________________

get_document

检索特定文档的完整内容。

退货： JSON，包含文档内容、元数据、关键字和块计数。

______________________________________________________________________

reindex_documents

索引或重新索引知识库中的所有文档。

退货： 带有索引统计信息的JSON（索引、更新、跳过、删除、chunks_added、chunksremoved、dedup_skiped、elapsed_seconds）。

______________________________________________________________________

list_categories

列出所有文档类别及其文档计数。

退货：

{
  "status": "success",
  "categories": {
    "security": 52,
    "development": 8,
    "ctf": 12,
    "general": 3
  },
  "total_documents": 75
}

______________________________________________________________________

list_documents

列出所有索引文档，可选择按类别筛选。

退货： 包含id、源、类别、格式、块和关键字的JSON文档数组。

______________________________________________________________________

get_index_stats

获取知识库索引的统计数据。

退货：

{
  "status": "success",
  "stats": {
    "total_documents": 75,
    "total_chunks": 9256,
    "unique_content_hashes": 9100,
    "categories": {"security": 52, "development": 8},
    "supported_formats": [".md", ".txt", ".pdf", ".py", ".json", ".docx", ".xlsx", ".pptx", ".csv", ".ipynb"],
    "embedding_model": "BAAI/bge-small-en-v1.5",
    "embedding_dim": 384,
    "reranker_model": "Xenova/ms-marco-MiniLM-L-6-v2",
    "chunk_size": 1000,
    "chunk_overlap": 200,
    "query_cache": {
      "size": 12,
      "max_size": 100,
      "ttl_seconds": 300,
      "hits": 45,
      "misses": 23,
      "hit_rate": "66.2%"
    }
  }
}

______________________________________________________________________

文档管理

add_document

从原始内容向知识库添加新文档。将文件保存到documents目录并立即为其建立索引。

______________________________________________________________________

update_document

更新现有文档。从索引中删除旧块，并用新内容重新索引。

______________________________________________________________________

remove_document

从知识库索引中删除文档。（可选）从磁盘中删除文件。

______________________________________________________________________

add_from_url

从URL获取内容，剥离HTML（脚本、样式、导航、页脚、页眉），转换为markdown，并添加到知识库中。

______________________________________________________________________

search_similar

使用嵌入相似度查找与给定文档相似的文档。

______________________________________________________________________

evaluate_retrieval

使用测试查询评估检索质量。可用于调整 hybrid_alpha，测试查询扩展的有效性，或在重新索引后进行验证。

韵律学：

• MRR@5 （平均倒数排名）：预期文档的平均1/排名。1.0=总是第一个结果。
• Recall@5：在前5个结果中找到的预期文件的一小部分。1.0=全部找到。

______________________________________________________________________

配置

知识RAG可通过 config.yaml 项目根目录中的文件。如果不 config.yaml 如果存在，则使用合理的默认值——系统可以在零配置的情况下开箱即用。

快速开始

# Option 1: Use a preset
cp presets/cybersecurity.yaml config.yaml    # Offensive/defensive security, CTFs
cp presets/developer.yaml config.yaml        # Software engineering, APIs, DevOps
cp presets/research.yaml config.yaml         # Academic research, papers, studies
cp presets/general.yaml config.yaml          # Blank slate, pure semantic search

# Option 2: Start from the documented template
cp config.example.yaml config.yaml
# Edit config.yaml to your needs

更改后重新启动Claude代码 config.yaml.

config.yaml结构

# Paths — where your documents live
paths:
  documents_dir: "./documents"    # Scanned recursively
  data_dir: "./data"              # Index storage
  models_cache_dir: "./models_cache"  # Persistent embedding model cache

# Documents — what gets indexed and how
documents:
  supported_formats:              # File types to index
    - .md
    - .txt
    - .pdf
    - .docx
    - .ipynb
    # - .py                       # Uncomment to index code
  exclude_patterns:               # Glob patterns to skip
    - "node_modules"
    - ".venv"
    - "__pycache__"
  chunking:
    chunk_size: 1000              # Max chars per chunk
    chunk_overlap: 200            # Shared chars between chunks

# Models — AI models for search (all run locally, no API keys)
models:
  embedding:
    model: "BAAI/bge-small-en-v1.5"   # ONNX, ~33MB, auto-downloaded
    dimensions: 384
    gpu: false                         # Set true + pip install knowledge-rag[gpu]
  reranker:
    enabled: true                      # Falls back to RRF if model is unavailable
    model: "Xenova/ms-marco-MiniLM-L-6-v2"
    top_k_multiplier: 3               # Candidates fetched before reranking

# Search — result limits and collection name
search:
  default_results: 5
  max_results: 20
  collection_name: "knowledge_base"   # Change for separate knowledge bases

# Categories — auto-tag documents by folder path
# Set to {} to disable categorization entirely
category_mappings:
  "security/redteam": "redteam"
  "security/blueteam": "blueteam"
  "notes": "notes"

# Keyword routing — prioritize categories based on query keywords
# Set to {} for pure semantic search with no routing bias
keyword_routes:
  redteam:
    - pentest
    - exploit
    - privilege escalation

# Query expansion — expand abbreviations for better BM25 recall
# Set to {} for no expansion (search terms used as-is)
query_expansions:
  sqli:
    - sql injection
    - sqli
  privesc:
    - privilege escalation
    - privesc

看 config.example.yaml 完整记录的模板，每个字段都有解释。

预设

常见用例的预构建配置：

创建自己的预设：复制 config.example.yaml，填写您的类别/关键字/扩展名，保存到 presets/your-domain.yaml.

配置参考

路径

相对路径从项目根解析。绝对路径也有效。

文件

分块指南：简短笔记→ 500/100. 一般用途→ 1000/200. 长篇技术文档→ 1500/300.

对于 .md 文件，分块分割 ## 和 ### 首先是标题边界。大于的部分 chunk_size 它们被重叠地分块。非markdown文件使用固定大小的分块。

模型

如果重新链接器模型在本地不可用，并且机器无法下载，则搜索现在会从混合语义+BM25检索回退到RRF顺序。这保持 search_knowledge 离线可用，但在缓存重新链接器模型之前，对于不明确的查询，结果排序可能不太精确。

嵌入模型选项 （最快→ 最准确）：

• BAAI/bge-small-en-v1.5 --384D，约33MB（默认）
• BAAI/bge-base-en-v1.5 --768D，~130MB
• BAAI/bge-large-en-v1.5 --1024D，~335MB
• intfloat/multilingual-e5-small --384D，100多种语言

警告：索引后更改嵌入模型需要 reindex_documents(full_rebuild=True).

搜索

分类

将文件夹路径映射到类别名称。匹配文件夹中的文档会自动标记，从而启用筛选搜索。

category_mappings:
  "security/redteam": "redteam"
  "security": "security"

集 category_mappings: {} 禁用——文档仍然可以搜索，只是没有类别过滤器。

关键字路由

根据关键字将查询路由到类别。当查询包含列出的关键字时，该类别的结果将按优先级排列（不进行筛选——其他类别仍会显示，排名较低）。

keyword_routes:
  redteam:
    - pentest
    - exploit
    - sqli

单个单词关键字使用正则表达式单词边界(\b)--“api”与“RAPID”不匹配。多词关键字使用子字符串匹配。

集 keyword_routes: {} 用于纯语义搜索。

查询扩展

在BM25搜索之前，用同义词展开搜索词。支持单标记、双元组和完整查询匹配。

query_expansions:
  sqli:
    - sql injection
    - sqli
  k8s:
    - kubernetes
    - k8s

集 query_expansions: {} 没有扩张。

混合搜索调优

______________________________________________________________________

项目结构

knowledge-rag/
├── mcp_server/
│   ├── __init__.py          # Stdout protection + version
│   ├── config.py            # YAML config loader + defaults
│   ├── ingestion.py         # 20 parsers, chunking, metadata extraction
│   └── server.py            # MCP server, ChromaDB, BM25, reranker, 12 tools
├── config.example.yaml      # Documented config template (copy to config.yaml)
├── config.yaml              # Your active configuration (git-ignored)
├── presets/                  # Ready-to-use domain configurations
│   ├── cybersecurity.yaml
│   ├── developer.yaml
│   ├── research.yaml
│   └── general.yaml
├── documents/               # Your documents (scanned recursively)
├── data/
│   ├── chroma_db/           # ChromaDB vector database
│   └── index_metadata.json  # Incremental indexing state
├── models_cache/            # Persistent embedding model cache
├── tests/                   # Test suite (82 tests)
├── install.sh               # Linux/macOS installer
├── install.ps1              # Windows installer
├── venv/                    # Python virtual environment
├── requirements.txt
├── pyproject.toml
├── LICENSE
└── README.md

______________________________________________________________________

故障排除

Python版本不匹配

需要Python 3.11或更高版本。

python --version    # Must be 3.11+

FastEmbed模型下载失败

首次运行时，FastEmbed会将模型下载到 models_cache/.如果下载失败：

# Clear cache and retry
# Windows:
rmdir /s /q models_cache

# Linux/macOS:
rm -rf models_cache

# Then restart the MCP server

重新排序模型下载失败

在第一个查询中延迟加载重新链接器。如果模型未被缓存且机器处于脱机状态，则搜索将继续而不重新排序，并使用混合检索中的RRF顺序。要保持离线重新银行功能，请在在线时运行一个查询或预先填充 models_cache/ 在目标机器上。

您仍然可以在中明确禁用重新分级 config.yaml:

models:
  reranker:
    enabled: false

禁用重新排序可以减少内存使用，避免首次查询模型加载。权衡的结果是排名精度较低，尤其是当几个块匹配相同的术语但只有一个是最佳答案时。

ChromaDB指数在启动时崩溃

原生ChromaDB故障可能会在正常异常处理运行之前终止Python。Startup现在在初始化MCP服务器之前，在子进程中探测ChromaDB。如果探头崩溃，则激活 chroma_db/ 和 index_metadata.json 被移动到 data/backups/auto-repair-*，下一个启动程序可以重建一个干净的索引。

通过以下任一控制台脚本都可以获得相同的保护行为：

knowledge-rag
knowledge-rag-guarded

索引为空

# Check documents directory has files
ls documents/

# Force reindex via Claude Code:
# reindex_documents(force=True)

# Or nuclear rebuild if model changed:
# reindex_documents(full_rebuild=True)

MCP服务器未加载

1. 检查 ~/.claude.json 存在并且在中具有有效的JSON mcpServers 部分
2. 验证路径是否使用双反斜杠(\\)在Windows上
3. 完全重新启动Claude代码
4. 跑 claude mcp list 检查连接状态

“连接失败”错误

MCP服务器使用stdout进行JSON-RPC通信。如果库在init期间打印到stdout，则流将被损坏。v3.4.3+包括防止这种情况的stdout保护。如果您使用的是旧版本，请升级：

pip install --upgrade knowledge-rag

第一次查询速度慢

交叉编码器重新排序器模型在第一个查询上延迟加载。这为模型下载和加载增加了约2-3秒的一次性延迟。后续查询很快。如果无法加载模型，则搜索将回退到RRF排序，并且在服务器重新启动之前不会重试加载重新链接器。

内存使用

对于约200个文档，预计约300-500MB RAM。嵌入模型（约200MB ONNX运行时驻留，自v3.8.0以来的第一次查询时延迟加载）和重新链接器（约25MB，延迟加载）仅在实际使用时加载到内存中。对于非常大的知识库（1000多个文档），考虑启用GPU加速并使用排除模式来限制索引范围。

多个MCP客户端会产生重复的服务器

MCP stdio是每个客户端按协议的一个进程——多个克劳德代码窗口、克劳德桌面+IDE等，每个窗口都有自己的 knowledge-rag 过程。由于v3.8.0空闲进程很便宜（在第一次查询之前没有加载嵌入模型）。如果您已经测量并希望每个数据目录有一个服务器的硬上限，请选择加入：

export KNOWLEDGE_RAG_SINGLE_INSTANCE=1

第二个实例立即退出，代码为75。默认设置为OFF（多客户端友好）。完整指南： docs/single-instance.mdMCP配置示例： examples/mcp-config-single-instance.json.

______________________________________________________________________

更新日志

v3.9.0（2026-05-10）——质量门

主要治理+CI强化版本。中没有运行时行为更改 mcp_server/.公共API表面与v3.8.1保持不变。

• 新 质量门工作流程(.github/workflows/quality-gate.yml)在每个PR上执行7个支柱：安全性、稳定性、内存泄漏、多功能性、可扩展性、版本控制、质量。总共35+个状态检查。
• 新 夜间弹性工作流程(.github/workflows/nightly.yml)：混沌套件（故障注入）、1h浸泡测试（50K迭代循环）、确定性检查（全套件×3）、突变测试（mutmutmut）。自动在任何夜间故障时打开GitHub问题。
• 新 性能基准套件 bench/ （12个微基准测试，pytest基准测试），每个PR都有10%的回归门。
• 新 通过GitHub Pages的公共绩效仪表板(.github/workflows/bench-pages.yml)--每次提交的延迟/吞吐量图表。在启用repo Pages之前处于休眠状态。
• 新 通过假设对所有解析器进行基于属性的模糊测试(tests/test_ingestion_property.py)--每次CI运行200个随机示例。
• 新 记忆基线回归测试(tests/test_memory_baseline.py，通过psutil跨平台）——RSS限制在1000个查询以下；夜间浸泡放大到50K迭代。
• 新 属性/区域设置/格式/预设矩阵(tests/test_presets.py, tests/test_locale.py, tests/test_format_smoke.py).
• 新 向后兼容性回归测试(tests/test_backwards_compat.py)--v3.6.0/v.3.7.0中的遗留YAML配置仍然可以解析；所有12个MCP工具参数名称均已冻结。
• 新 基于AST的公共API表面差异(scripts/check_api_surface.py)--任何突破性变化块合并，基线为 .github/api-surface-baseline.json.
• 新 CHANGELOG执行(scripts/check_changelog.py)--面向用户的PR必须在下面添加一个项目符号 ## Unreleased；旁路 skip-changelog 标签。
• 新 测试计数反回归(scripts/check_test_count.py)--防止无声的测试删除。
• 新 每个PR标题都需要常规提交（通过以下方式提交 amannn/action-semantic-pull-request).
• 新 米皮 --strict 按模块展开（目前 instance_lock.py + preflight.py + scripts/)查询文件串覆盖率≥80%；氡、秃鹫、PR尺寸的警卫报告。
• 新 CI矩阵扩展到9个单元：Linux+Windows+ macOS × 3.11 + 3.12 + 3.13 （在v3.9.0中都是必需的；macOS/3.13在两个清理周期后从实验版升级）。
• 新 治理文件： CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, .github/PULL_REQUEST_TEMPLATE.md，3个问题模板，已扩展 CODEOWNERS.
• 新 预提交钩子：ruff、gitleaks、版本同步、常规提交。
• 杂务 .github/codecov.yml 执行覆盖趋势门（-0.5pp块；新代码≥70%）。

v3.8.1（2026-05-10）--修补程序

• FIX（关键）: FastEmbedEmbeddings.__call__ 当ONNX模型无法加载或 embed() 加薪。之前的行为悄无声息地破坏了索引——ChromaDB存储了零个嵌入， count() 报告正常数字，智能reindex跳过坏块，查询返回垃圾分数，没有可见错误。现在加薪 EmbeddingModelLoadError / EmbeddingError. (#36)
• 修复：粘性 _load_failed flag——加载失败后，后续调用会立即重新引发，而不是循环HuggingFace下载尝试（这是v3.8.0中的“冻结查询”用户体验）。
• 新：卫生检查 __call__ --嵌入计数和暗不匹配增加 EmbeddingError 而不是默默地返回格式错误的向量。
• 测试：7个新的回归案例 tests/test_lazy_embeddings.py，包括 test_does_not_return_zero_vectors_silently 作为全班虫子的守卫。
• 备注：这是master中预先存在的错误，不是v3.8.0引入的。v3.8.0延迟加载扩大了影响（故障转移到查询时间）。所有v3.8.0用户都应该升级。

v3.8.0（2026-05-10）

• 新：延迟加载FastEmbed嵌入模型（约200MB ONNX运行时）。在第一个查询而不是启动时加载--空闲 knowledge-rag 进程现在很便宜，这在MCP stdio客户端生成并行服务器进程（多个克劳德代码窗口、克劳德桌面+IDE等）时很重要。公共API保持不变。 (#32)
• 新：通过以下方式选择单实例防护 KNOWLEDGE_RAG_SINGLE_INSTANCE=1 有人是。 默认为OFF --多客户端MCP的使用继续保持不变。启用后，将为同一进程创建第二个服务器进程 data_dir 出口代码为75(EX_TEMPFAIL).包括过时的PID恢复和SIGINT/SIGTERM处理程序。看 docs/single-instance.md（#33，原概念由@Hohlas在#31中提出）
• 新: examples/mcp-config-single-instance.json --选择加入保护的MCP客户端配置示例。
• 文档新 docs/single-instance.md --何时使用，何时不使用，故障排除，完全激活参考。
• 文档：README“多个MCP客户端生成重复服务器”的故障排除部分+延迟嵌入的内存使用说明。
• 杂务：跨版本同步 pyproject.toml, mcp_server/__init__.py，以及 npm/package.json （自v3.5.x以来一直在漂移）。
• 杂务：pytest tmp_path_retention_count=1 以避免CI中的Windows atexit清理竞争。
• 路线图：跟踪v4.0共享服务架构（一个守护进程，许多瘦MCP客户端）作为多进程资源复制的长期解决方案。 (#34)

未发布

• 修复：启动前在子进程中探测ChromaDB，并将崩溃的持久索引移动到 data/backups/auto-repair-* 在MCP初始化之前。
• 修复：重新分级负载故障现在退回到RRF订购，而不是故障 search_knowledge 在离线机器上。
• 修复：Virtualenv项目根检测现在处理解析到系统解释器的Python符号链接。
• 新: knowledge-rag-guarded 控制台脚本保留为显式保护的启动别名。

v3.6.2（2026年4月23日）

• 基础设施：NPM来源证明（SLSA供应链安全），NPM页面上的完整自述文件
• 文档：重新组织安装部分——添加NPX和Docker安装方法，将What's New更新到v3.6.0

v3.6.0（2026年4月23日）

• 新：多语言代码解析-C(.cC.cpp/.h)，JavaScript(.js/.jsx)，TypeScript(.ts/.tsx)具有每种语言的函数/类/导入提取功能
• 新：XML解析器(.xml)--根元素和命名空间元数据提取
• 新：默认启用所有8种新格式，无需更改配置
• 新：NPM包装器(npx knowledge-rag)+Docker镜像(ghcr.io/lyonzin/knowledge-rag)
• 新：自动发布管道——PyPI（可信发布）、NPM、Docker GHCR
• 改进：代码分析器报告正确 language 每个文件类型的元数据（硬编码为 "python" 对于所有代码文件）

v3.5.2（2026-04-16）

• 新：从pip安装的NVIDIA软件包中自动发现CUDA 12 DLL——无需手动配置PATH
• 新：优雅的GPU→CPU回退 [WARN] CUDA初始化失败时的日志（缺少驱动程序、版本错误等）
• 修复：明确 CPUExecutionProvider 当 gpu: false --消除日志中嘈杂的CUDA探测错误
• 修复：BASE_DIR解析现在正确地首选具有以下内容的目录 config.yaml 那些只有 config.example.yaml （修复可编辑的安装）

v3.5.1（2026年4月16日）

• 修复：删除Python上限约束(=3.11).现在支持Python 3.13和3.14——onnxruntime为两者都提供了轮子。

v3.5.0（2026-04-16）

• 新：ONNX嵌入的可选GPU加速-- pip install knowledge-rag[gpu] + models.embedding.gpu: true 在配置中。NVIDIA GPU上的索引速度提高5-10倍，CPU自动回退。
• 文档：README中添加了支持的格式表（20种格式）

v3.4.3（2026年4月16日）

• 修复：通过保存/恢复模式纠正stdout保护-- __init__.py 在初始化过程中保存原始stdout并重定向到stderr， server.py main() 恢复它之前 mcp.run().v3.4.2的全局重定向破坏了MCP JSON-RPC响应通道。

v3.4.1（2026年4月16日）

• 修复: pip install knowledge-rag 现在自动从venv位置检测项目目录
• 新: install.sh --带有pip和源代码模式的Linux/macOS安装程序
• 改进：BASE_DIR解析链：环境变量→ 源目录→ venv父母→ CWD → 后备方案

v3.4.0（2026-04-16）

• 新: models_cache_dir --持久嵌入模型缓存，防止重新启动后重新下载
• 新: exclude_patterns --索引过程中基于glob的文件/目录排除
• 新：Jupyter Notebook（.ipynb）解析器--仅提取markdown和代码单元格源代码
• 新：MCP stdout保护--在服务器启动之前将stdout重定向到stderr
• 新：文件监视器弹性——达到Linux inotify限制时的优雅回退
• 新：MetaTrader（.mq4、.mqh）支持——opt-in代码解析
• 新：23个新测试（排除模式、ipynb解析器、stdout保护）

v3.3.x

• v3.3.2：YAML配置的完整类型验证、边界检查、版本同步
• v3.3.1：YAML空值崩溃修复，pip轮中捆绑的预设， knowledge-rag init 命令行界面
• v3.3.0版本：YAML配置系统，4个域预设，通用使用支持

v3.2.x

• v3.2.4：Symlink支持循环回路保护
• v3.2.3：pip安装的BASE_DIR智能检测
• v3.2.2：即插即用pip安装， KNOWLEDGE_RAG_DIR env 是
• v3.2.1：从损坏的ChromaDB中自动恢复
• v3.2.0版本：并行BM25+语义搜索，相邻块检索

v3.1.x

• v3.1.1：markdown chunker中的代码块保护，AAR类别，14个CVE别名
• v3.1.0：DOCX/XLSX/PPTX/CSV支持，文件监视器，MMR多样化，PyPI发布

v3.0.0（2026-03-19）

• 用FastEmbed替换Olama（ONNX正在处理中）
• 跨编码器重新排序、降价感知分块、查询扩展
• 6个新的MCP工具（共12个），从v2.x自动迁移

v2.x and earlier

• v2.2.0版本: hybrid_alpha=0 跳过Ollama，默认值从0.5更改为0.3
• v2.1.0：美人鱼建筑图
• v2.0.0版本：混合搜索、RRF融合、， hybrid_alpha 参数
• v1.1.0版本：增量索引、查询缓存、块重复数据删除
• v1.0.1：自动清理孤立文件夹，删除硬编码路径
• v1.0.0：首次发布

______________________________________________________________________

贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

______________________________________________________________________

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

______________________________________________________________________

致谢

• 色度数据库 --矢量数据库
• 快速嵌入 --ONNX运行时嵌入
• FastMCP --模型上下文协议框架
• PyMuPDF --PDF解析
• 排名bm25 --BM25霍加皮实施
• 看门狗 --文件系统监控
• python docx / openpyxl / python pptx --Office文档解析
• Yaml --YAML配置解析
• 美丽的汤 --URL摄取的HTML解析

______________________________________________________________________

作者

里昂。

安全研究员|开发人员

______________________________________________________________________

返回顶部