Md Kb Rag

md-kb rag

Docker优先的RAG服务器，使用YAML frontmatter将markdown知识库索引到Qdrant中，并通过MCP（流式HTTP）公开语义搜索。

构建为单个Rust二进制文件，用于类型安全、小型Docker映像和简单部署。

文档

• deploy/USAGE.md --设置指南、配置、前台、分块
• deploy/TROUBLESHOOTING.md --常见问题和修复
• deploy/config.example.yaml --完整注释配置参考
• deploy/ci-examples/ --webhook触发的重新索引的CI工作流示例

快速开始

# Clone and configure
git clone https://github.com/St0nefish/md-kb-rag.git
cd md-kb-rag
cp deploy/.env.example .env
# Edit .env: set MCP_BEARER_TOKEN, MODEL_PATH/MODEL_FILE, and GIT_PULL_TOKEN

# Download the embedding model (see "Embedding Models" below)

# Set source.git_url in config.yaml to point at your knowledge base repo
cp deploy/config.example.yaml config.yaml
# Edit config.yaml — at minimum, set source.git_url and uncomment the mount:
#   - ./config.yaml:/app/config.yaml:ro

# Start the stack (CPU mode by default)
# With git_url set, the server auto-clones the repo and runs a full index on first start
docker compose up -d

# Add MCP to Claude Code
claude mcp add --transport http kb-search \
  https://your-host:8001/mcp \
  --header "Authorization: Bearer $TOKEN"

推荐的设置使用 命名Docker卷 对于知识库。容器在首次启动时克隆仓库，并通过webhook获取更新——不需要主机端的git操作。看 部署/USAGE.md 有关此方法与绑定安装的详细信息。

看 deploy/config.example.yaml 所有可用选项及其默认值。

建筑

三种Docker服务：

CLI命令

md-kb-rag serve              # Start server (MCP + webhook endpoints)
md-kb-rag index              # Incremental index (only changed files)
md-kb-rag index --full       # Full re-index (clear state, re-embed everything)
md-kb-rag validate           # Validate all markdown files without indexing
md-kb-rag status             # Print collection stats + state DB info
md-kb-rag health             # Check if server is healthy

配置

配置从加载 config.yaml （或通过的路径 --config).每个字段都有一个合理的默认值，因此该文件是可选的。可以通过环境变量设置连接设置：

环境变量优先于配置文件值。如果必填字段均未设置(embedding.base_url, embedding.model, qdrant.url)，服务器退出时出现明显错误。

看 deploy/config.example.yaml 对于所有选项：

• 来源 --Git URL（首次启动时自动克隆）或知识库的绑定装载路径
• 索引 --包含/排除球形图案
• 前言 --必填字段、索引字段、默认值
• 分块 --具有可配置块大小的Markdown感知拆分
• 嵌入 --OpenAI兼容端点（与llama.cpp、vLLM等兼容）
• 矢量点 --连接URL和集合名称
• 验证 --严格/宽松模式，可选lint命令
• 网络钩子 --Gitea/GitHub/GitLab的HMAC验证（如果 WEBHOOK_SECRET 未设置）
• 主控程序 --服务器端口和承载令牌身份验证

嵌入模型

默认配置已针对 nomic-embed-ext-v2-moe （768尺寸，GGUF通过llama.cpp）。

下载

# Download from Hugging Face (requires huggingface-cli: pip install huggingface_hub)
huggingface-cli download nomic-ai/nomic-embed-text-v2-moe-GGUF \
  nomic-embed-text-v2-moe-Q8_0.gguf --local-dir ./data/models

# Or download directly from:
# https://huggingface.co/nomic-ai/nomic-embed-text-v2-moe-GGUF

然后设置 .env:

MODEL_PATH=./data/models
MODEL_FILE=nomic-embed-text-v2-moe-Q8_0.gguf

模型

要使用其他模型，请在 .env:

EMBEDDING_MODEL=bge-large-en-v1.5
EMBEDDING_VECTOR_SIZE=1024
MODEL_FILE=bge-large-en-v1.5-q8_0.gguf

或在 config.yaml （如果同时设置了环境变量和变量，则环境变量优先）。

注： 改变 vector_size 需要完全重新索引(index --full)它掉落并再现了Qdrant系列。

嵌入后端

开发人员 docker-compose.yml 默认为 CPU模式 它适用于任何硬件。对于生产部署，请从以下选项中选择特定于硬件的模板 deploy/templates/.

CPU（默认）

无需特殊司机即可在任何地方工作。适合小型知识库或初步测试。撰写文件使用 ghcr.io/ggml-org/llama.cpp:server.

康迪亚

最常见的GPU后端。需要 nvidia容器工具包 安装在主机上。用途 server-cuda12 带图片 deploy.resources.reservations.devices 用于GPU访问。

AMD ROCm

AMD GPU上的最佳性能。需要主机上的ROCm用户空间驱动程序。用途 server-rocm 带图片 /dev/kfd 和 /dev/dri 设备访问。

AMD Vulkan 的

比ROCm更简单的驱动程序设置——适用于标准Mesa Vulkan驱动程序。用途 server-vulkan 带图片 /dev/dri 设备访问。支持多GPU设置。

苹果硅（金属）

金属GPU加速 在Docker中不可用 （macOS上的Docker运行Linux VM）。选项：

1. 以本机方式运行llama服务器 — brew install llama.cpp，然后从你的模型和观点开始 EMBEDDING_BASE_URL 在它(http://host.docker.internal:8080/v1 如果kb-rag在Docker中运行）。
2. 使用CPU Docker镜像 --工作，但比原生金属慢。

外部API

完全跳过捆绑的嵌入服务。点 EMBEDDING_BASE_URL 在任何与OpenAI兼容的端点（OpenAI、Ollama、vLLM、TEI）上，删除 embeddings 来自compose的服务。

MCP搜索工具

这 search 工具接受：

网络钩子

张贴到 /hooks/reindex 触发器：

1. HMAC签名验证（Gitea/GitHub/GitLab）
2. 分支匹配 source.branch
3. git fetch + git merge --ff-only （如果 source.git_url 已配置）
4. 已更改文件的增量重新索引

webhook端点仅在以下情况下可用 WEBHOOK_SECRET 设置为非空值。

设置选项：

• 原生锻造webhook （推荐）--直接在Git forge的webhook设置中配置（或通过 tea/gh CLI）。不需要CI运行器。
• CI工作流程 --从流水线步骤触发。看 deploy/ci-examples/ Gitea和GitHub工作流示例。

Git拉取webhook： 集 source.git_url 在您的配置和 GIT_PULL_TOKEN 在 .env （对于私有HTTPS存储库）在webhook触发时自动更改容器拉取。看 deploy/USAGE.md 有关详细的设置说明。

增量索引

文件由SQLite状态数据库中的SHA256内容哈希跟踪。每次跑步时：

• 新文件 --验证、块化、嵌入、追加销售
• 更改文件 --删除旧向量，重新处理
• 已删除的文件 --删除向量和状态条目
• 未更改的文件 --跳过

点ID是确定性UUID（v5），来源于 file_path::chunk_index.

部署

所有部署工件都存在于 deploy/:

• 编写模板 — deploy/templates/ 为每个硬件后端（CPU、NVIDIA、ROCm、Vulkan、Apple Silicon）提供独立的编写文件
• 配置示例 — deploy/.env.example 和 deploy/config.example.yaml
• CI示例 — deploy/ci-examples/ 有Gitea和GitHub的webhook工作流示例
• 部署脚本 — deploy/deploy.sh 通过Docker上下文进行拉取和重启（配置如下 deploy/deploy.env)

Claude Code用户： 跑 /deploy-md-rag 用于交互式引导设置，包括硬件选择、型号下载、配置和MCP客户端连接。

手动设置： 从复制匹配的模板 deploy/templates/ 作为你的目标 docker-compose.yml，配置 .env 根据示例，并遵循 deploy/USAGE.md.

发展

# Set up git hooks (fmt + clippy on commit)
./scripts/setup-dev.sh

# Start only the dependencies
docker compose up qdrant embeddings -d

# Run the server locally (requires env vars for connection settings)
export EMBEDDING_BASE_URL=http://localhost:8080/v1
export EMBEDDING_MODEL=nomic-embed-text-v2-moe
export QDRANT_URL=http://localhost:6334
export MCP_BEARER_TOKEN=dev-token
cargo run -- serve

典型的工作流程：在本地开发，推送到功能分支，CI构建和测试，通过PR合并。请参阅 部署/USAGE.md 了解完整的设置演练。