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 操作员 | 安全研究员 | 开发者