Knowledge Rag

🚀 知識檢索增強生成（RAG）系統

知識檢索增強生成（RAG）系統是一個 100% 本地運行的語義搜索系統，它通過 MCP（模型上下文協議）與 Claude Code 集成。該系統能讓 Claude 在你的文檔（如 PDF、Markdown、代碼等）中進行搜索，為回答問題提供相關上下文。

🚀 快速開始

前提條件

• Windows 10/11
• Python 3.11 或 3.12
• Ollama（用於本地嵌入）
• Claude Code CLI

快速安裝（自動化）

# 克隆倉庫
git clone https://github.com/lyonzin/knowledge-rag.git
cd knowledge-rag

# 運行安裝程序
.\install.ps1

手動安裝

1. 安裝 Python 3.12

   # 從 https://www.python.org/downloads/ 下載
   # 或者使用 winget：
   winget install Python.Python.3.12
   

2. 安裝 Ollama

   # 從 https://ollama.com 下載
   # 或者使用 winget：
   winget install Ollama.Ollama
   

3. 拉取嵌入模型

   ollama pull nomic-embed-text
   

4. 克隆並設置項目

   git clone https://github.com/lyonzin/knowledge-rag.git
   cd knowledge-rag
   
   # 創建虛擬環境
   python -m venv venv
   .\venv\Scripts\activate
   
   # 安裝依賴項
   pip install -r requirements.txt
   

5. 為 Claude Code 配置 MCP

   在 ~/.claude.json 的 mcpServers 下添加：

   {
     "mcpServers": {
       "knowledge-rag": {
         "type": "stdio",
         "command": "cmd",
         "args": ["/c", "cd /d C:\\path\\to\\knowledge-rag && .\\venv\\Scripts\\python.exe -m mcp_server.server"],
         "env": {}
       }
     }
   }
   

   注意：我們使用 cmd /c 和 cd /d 來確保在啟動 Python 服務器之前正確設置工作目錄。這是因為 Claude Code 可能不遵守 MCP 配置中的 cwd 屬性。

6. 重啟 Claude Code

✨ 主要特性

📦 安裝指南

前提條件

• Windows 10/11
• Python 3.11 或 3.12
• Ollama（用於本地嵌入）
• Claude Code CLI

快速安裝（自動化）

# 克隆倉庫
git clone https://github.com/lyonzin/knowledge-rag.git
cd knowledge-rag

# 運行安裝程序
.\install.ps1

手動安裝

1. 安裝 Python 3.12

   # 從 https://www.python.org/downloads/ 下載
   # 或者使用 winget：
   winget install Python.Python.3.12
   

2. 安裝 Ollama

   # 從 https://ollama.com 下載
   # 或者使用 winget：
   winget install Ollama.Ollama
   

3. 拉取嵌入模型

   ollama pull nomic-embed-text
   

4. 克隆並設置項目

   git clone https://github.com/lyonzin/knowledge-rag.git
   cd knowledge-rag
   
   # 創建虛擬環境
   python -m venv venv
   .\venv\Scripts\activate
   
   # 安裝依賴項
   pip install -r requirements.txt
   

5. 為 Claude Code 配置 MCP

   在 ~/.claude.json 的 mcpServers 下添加：

   {
     "mcpServers": {
       "knowledge-rag": {
         "type": "stdio",
         "command": "cmd",
         "args": ["/c", "cd /d C:\\path\\to\\knowledge-rag && .\\venv\\Scripts\\python.exe -m mcp_server.server"],
         "env": {}
       }
     }
   }
   

   注意：我們使用 cmd /c 和 cd /d 來確保在啟動 Python 服務器之前正確設置工作目錄。這是因為 Claude Code 可能不遵守 MCP 配置中的 cwd 屬性。

6. 重啟 Claude Code

💻 使用示例

添加文檔

將文檔放在 documents/ 目錄下，並按類別組織：

documents/
├── security/          # 滲透測試、漏洞利用、漏洞文檔
│   ├── redteam/       # 紅隊相關
│   ├── blueteam/      # 藍隊相關
│   └── RTFM.pdf
├── logscale/          # LogScale/LQL 文檔
│   └── LQL_REFERENCE.md
├── ctf/               # CTF 解題報告和方法
├── development/       # 代碼、API、框架
│   └── api-docs.md
└── general/           # 其他所有內容
    └── notes.txt

索引文檔

Claude Code 啟動時會自動對文檔進行索引。若要手動重新索引：

# 在 Claude Code 聊天中：
使用 reindex_documents 工具並設置 force=true 來重建索引

搜索

直接向 Claude 提問！RAG 系統會自動提供上下文：

用戶：如何在 LogScale 中使用 formatTime？
Claude：[內部使用 search_knowledge，檢索相關內容塊]
        根據您的文檔，LogScale 中的 formatTime...

混合搜索控制

您可以控制語義搜索和關鍵詞搜索的平衡：

// 純關鍵詞搜索 - 即時響應，無需 Ollama（適用於精確術語的默認設置）
search_knowledge("gtfobins suid", hybrid_alpha=0.0)

// 關鍵詞為主（默認） - 快速響應，有輕微語義增強
search_knowledge("lolbas certutil", hybrid_alpha=0.3)

// 平衡混合搜索 - 兩種引擎權重相等
search_knowledge("SQL 注入技術", hybrid_alpha=0.5)

// 語義為主 - 更適合概念性查詢
search_knowledge("如何提升權限", hybrid_alpha=0.7)

// 純語義搜索 - 僅使用 Ollama，無關鍵詞匹配
search_knowledge("如何繞過身份驗證", hybrid_alpha=1.0)

📚 詳細文檔

MCP 工具

search_knowledge

結合語義搜索和 BM25 關鍵詞搜索的混合搜索。

參數：

返回值： 包含搜索結果的 JSON，包括內容、來源、相關性得分和搜索方法。

示例：

{
  "status": "success",
  "query": "mimikatz credential dump",
  "hybrid_alpha": 0.5,
  "result_count": 3,
  "results": [
    {
      "content": "Mimikatz 可以從內存中提取憑證...",
      "source": "C:/docs/security/redteam/credential-attacks.pdf",
      "filename": "credential-attacks.pdf",
      "category": "redteam",
      "score": 0.016393,
      "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。

list_categories

列出所有文檔類別及其文檔數量。

返回值：

{
  "status": "success",
  "categories": {
    "security": 52,
    "Detections_Rules ": 12,
    "redteam": 3,
    "blueteam": 3,
    "ctf": 2,
    "general": 1
  },
  "total_documents": 73
}

list_documents

列出所有已索引的文檔，可選擇按類別過濾。

參數：

get_index_stats

獲取知識庫索引的統計信息。

返回值：

{
  "status": "success",
  "stats": {
    "total_documents": 73,
    "total_chunks": 9256,
    "categories": {"security": 52, "logscale": 12, ...},
    "embedding_model": "nomic-embed-text",
    "chunk_size": 1000,
    "chunk_overlap": 200
  }
}

配置

關鍵詞路由

系統使用基於詞邊界的關鍵詞路由來提高搜索準確性。

flowchart TB
    QUERY["查詢: 'CVE-2021-44228 log4j'"] --> EXTRACT["提取關鍵詞"]

    subgraph ROUTES["🏷️ 關鍵詞路由 (config.py)"]
        SEC["security<br/>anti-bot, waf bypass, cloudflare..."]
        RED["redteam<br/>pentest, exploit, payload..."]
        BLUE["blueteam<br/>detection, sigma, yara..."]
        CTF["ctf<br/>ctf, flag, hackthebox..."]
        LOG["logscale<br/>logscale, humio, lql..."]
        DEV["development<br/>python, javascript, api..."]
    end

    EXTRACT --> CHECK{"詞邊界檢查 (\\b)"}

    CHECK -->|"'api' 在查詢中?"| BOUNDARY["不匹配 'RAPID' 或 'capital'"]
    CHECK -->|"'log4j' 匹配"| MATCHED["✓ 匹配 'security' 路由"]

    BOUNDARY --> NOROUTE["不應用路由"]
    MATCHED --> WEIGHT["加權評分<br/>多個匹配 = 更高置信度"]
    WEIGHT --> FILTER["過濾到 'security' 類別"]

在 mcp_server/config.py 中配置路由：

keyword_routes = {
    "security": ["anti-bot", "waf bypass", "cloudflare", ...],
    "redteam": ["pentest", "exploit", "payload", "reverse shell", ...],
    "blueteam": ["detection", "sigma", "yara", "incident response", ...],
    "ctf": ["ctf", "flag", "hackthebox", "tryhackme", ...],
    "Detections_Rules": ["logscale", "humio", "lql", "formatTime", ...],
    "development": ["python", "javascript", "api", "docker", ...]
}

詞邊界匹配：單字關鍵詞使用正則表達式詞邊界 (\b) 來防止誤匹配。例如，"api" 不會匹配 "RAPID"。

加權評分：當多個關鍵詞匹配時，匹配最多的類別獲勝。

分塊設置

在 config.py 中調整分塊大小和重疊：

chunk_size = 1000      # 每個分塊的字符數
chunk_overlap = 200    # 分塊之間的重疊字符數

嵌入模型

默認模型是 nomic-embed-text。若要更改：

1. 拉取不同的模型：ollama pull <model-name>
2. 更新 config.py：ollama_model = "<model-name>"

混合搜索調整

hybrid_alpha 參數控制平衡：

🔧 技術細節

系統架構

系統概述

flowchart TB
    subgraph MCP["🔌 MCP 服務器 (FastMCP)"]
        direction TB
        TOOLS["MCP 工具<br/>search_knowledge | get_document<br/>reindex_documents | list_categories"]
    end

    subgraph SEARCH["🔍 混合搜索引擎"]
        direction LR
        ROUTER["關鍵詞路由器<br/>(詞邊界)"]
        SEMANTIC["語義搜索<br/>(ChromaDB)"]
        BM25["BM25 關鍵詞搜索<br/>(rank-bm25)"]
        RRF["倒數排名融合 (RRF)"]

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

    subgraph STORAGE["💾 存儲層"]
        direction LR
        CHROMA[("ChromaDB<br/>向量數據庫")]
        COLLECTIONS["集合<br/>security | ctf<br/>logscale | development"]
        CHROMA --- COLLECTIONS
    end

    subgraph EMBED["🧠 嵌入層"]
        OLLAMA["Ollama<br/>nomic-embed-text<br/>(768 維)"]
        PARALLEL["並行處理<br/>(4 個工作線程)"]
        OLLAMA --- PARALLEL
    end

    subgraph INGEST["📄 文檔攝入"]
        PARSERS["解析器<br/>MD | PDF | TXT | PY | JSON"]
        CHUNKER["分塊<br/>1000 字符 + 200 重疊"]
        PARSERS --> CHUNKER
    end

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

數據流

1. 文檔攝入流程

flowchart LR
    subgraph INPUT["📁 輸入"]
        FILES["documents/<br/>├── security/<br/>├── logscale/<br/>├── ctf/<br/>└── development/"]
    end

    subgraph PARSE["📖 解析"]
        MD["Markdown 解析器"]
        PDF["PDF 解析器<br/>(PyMuPDF)"]
        TXT["文本解析器"]
        CODE["代碼解析器<br/>(PY/JSON)"]
    end

    subgraph CHUNK["✂️ 分塊"]
        SPLIT["文本分割器<br/>1000 字符"]
        OVERLAP["重疊<br/>200 字符"]
        SPLIT --> OVERLAP
    end

    subgraph EMBED["🧠 嵌入"]
        PARALLEL["線程池執行器<br/>(4 個工作線程)"]
        OLLAMA["Ollama API<br/>nomic-embed-text"]
        PARALLEL --> OLLAMA
    end

    subgraph STORE["💾 存儲"]
        CHROMADB[("ChromaDB")]
        BM25IDX["BM25 索引"]
    end

    FILES --> MD & PDF & TXT & CODE
    MD & PDF & TXT & CODE --> CHUNK
    CHUNK --> EMBED
    EMBED --> STORE

2. 查詢處理流程（混合搜索）

flowchart TB
    QUERY["🔍 用戶查詢<br/>'mimikatz credential dump'"] --> ROUTER

    subgraph ROUTING["📍 關鍵詞路由"]
        ROUTER["關鍵詞路由器"]
        MATCH{"詞邊界匹配？"}
        CATEGORY["過濾器: redteam"]
        NOFILTER["無過濾器"]

        ROUTER --> MATCH
        MATCH -->|是| CATEGORY
        MATCH -->|否| NOFILTER
    end

    subgraph HYBRID["⚡ 混合搜索"]
        direction LR
        SEMANTIC["語義搜索<br/>(ChromaDB)<br/>概念相似度"]
        BM25["BM25 搜索<br/>(rank-bm25)<br/>精確術語匹配"]
    end

    subgraph FUSION["🔀 結果融合"]
        RRF["倒數排名融合<br/>分數 = Σ 1/(k + 排名)"]
        COMBINE["合併排名<br/>+ 去重"]
        SORT["按合併分數排序"]

        RRF --> COMBINE --> SORT
    end

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

    SORT --> RESULTS["📋 結果<br/>搜索方法: hybrid|semantic|keyword<br/>語義排名 + BM25 排名"]

3. hybrid_alpha 參數效果

flowchart LR
    subgraph ALPHA["hybrid_alpha 值"]
        A0["0.0<br/>純 BM25<br/>⚡ 即時"]
        A3["0.3 (默認)<br/>關鍵詞為主<br/>⚡ 快速"]
        A5["0.5<br/>平衡"]
        A7["0.7<br/>語義為主"]
        A10["1.0<br/>純語義<br/>🐢 較慢"]
    end

    subgraph USE["最佳適用場景"]
        U0["CVE、工具名稱<br/>精確匹配<br/>無需 Ollama"]
        U3["技術查詢<br/>特定術語"]
        U5["通用查詢"]
        U7["概念性查詢<br/>相關主題"]
        U10["'如何...' 問題<br/>需要 Ollama"]
    end

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

項目結構

flowchart TB
    subgraph ROOT["📁 knowledge-rag/"]
        direction TB

        subgraph SERVER["🐍 mcp_server/"]
            INIT["__init__.py"]
            CONFIG["config.py<br/>(設置、路由)"]
            INGEST["ingestion.py<br/>(解析、分塊)"]
            SERV["server.py<br/>(MCP、ChromaDB、BM25)"]
        end

        subgraph DOCS["📚 documents/"]
            SEC["security/<br/>滲透測試、漏洞利用"]
            LOG["logscale/<br/>LQL 文檔"]
            DEV["development/<br/>代碼、API"]
            GEN["general/<br/>其他所有內容"]
        end

        subgraph DATA["💾 data/"]
            CHROMA["chroma_db/<br/>(向量存儲)"]
            META["index_metadata.json"]
        end

        subgraph FILES["📄 根文件"]
            INSTALL["install.ps1"]
            REQS["requirements.txt"]
            README["README.md"]
            CHANGE["CHANGELOG.md"]
        end
    end

knowledge-rag/
├── mcp_server/
│   ├── __init__.py
│   ├── config.py          # 配置設置
│   ├── ingestion.py       # 文檔解析和分塊
│   └── server.py          # MCP 服務器、ChromaDB、BM25
├── documents/             # 您的文檔放在這裡
│   ├── security/
│   ├── Detections_Rules/
│   ├── development/
│   └── general/
├── data/
│   ├── chroma_db/         # 向量數據庫存儲
│   └── index_metadata.json
├── .claude/
│   └── mcp.json           # 項目 MCP 配置
├── venv/                  # Python 虛擬環境
├── install.ps1            # 自動化安裝程序
├── requirements.txt       # Python 依賴項
├── CHANGELOG.md           # 版本歷史
└── README.md              # 本文件

📄 許可證

本項目採用 MIT 許可證 - 詳情請參閱 LICENSE 文件。

致謝

• ChromaDB - 向量數據庫
• Ollama - 本地大語言模型和嵌入
• FastMCP - MCP 框架
• PyMuPDF - PDF 解析
• rank-bm25 - BM25 實現

作者

Ailton Rocha (Lyon)

AI 操作員 | 安全研究員 | 開發者