Verse Rag

verse-rag

Local-first RAG MCP Server for Verse / UEFN Documentation

Fully air-gapped · Ollama embeddings · pgvector · Model Context Protocol

______________________________________________________________________

概述

诗歌抹布 生产准备好了吗 模型上下文协议（MCP） 服务器，使AI编码助手能够抓取、索引和语义搜索文档——完全在本地基础设施上。

最初分叉自 coleam00/mcp-crawl4ai-rag，这个fork是对存储层和嵌入层的彻底重写：

结果是一个完全离线运行的堆栈，没有外部API调用，没有云依赖，也没有API成本。

______________________________________________________________________

建筑

Claude Code / AI Client
        │  SSE (port 8051)
        ▼
  ┌─────────────┐
  │  MCP Server │  crawl4ai_mcp.py — FastMCP + Crawl4AI
  └──────┬──────┘
         │ httpx
         ▼
  ┌──────────────┐       ┌─────────────────┐
  │  PostgREST   │──────▶│  PostgreSQL 16  │
  │  (REST API)  │       │  + pgvector     │
  └──────────────┘       └─────────────────┘
         │
         │ /api/embed
         ▼
  ┌─────────────┐
  │   Ollama    │  qwen3-embedding:8b (4096 dims)
  └─────────────┘

服务（Docker Compose）：

Ollama在主机上（或在另一个容器中）作为单独的服务运行——这个堆栈通过 ollama Docker网络。

______________________________________________________________________

MCP工具

所有抓取工具都会立即返回——嵌入和存储在后台任务中运行，因此MCP调用永远不会阻止等待Ollama。

______________________________________________________________________

先决条件

• 码头工人 和 Docker Compose
• 奥拉玛 跑步与 qwen3-embedding:8b 拉：

  ollama pull qwen3-embedding:8b

• 三个外部Docker网络： mcps, nginx, ollama

  docker network create mcps
  docker network create nginx
  docker network create ollama

______________________________________________________________________

快速开始

1.克隆

git clone https://github.com/berry-13/verse-rag.git
cd verse-rag

2.构建MCP镜像

docker build -f docker/Dockerfile -t verse-rag:latest .

3.启动堆栈

docker compose -f docker/compose.yml up -d

这将开始：

• PostgreSQL与pgvector(verse-rag-db)
• PostgREST自动REST层(verse-rag-postgrest)
• 端口上的MCP服务器 8051 (verse-rag-mcp)

4.连接您的MCP客户端

克劳德代码：

claude mcp add-json verse-rag '{"type":"sse","url":"http://localhost:8051/sse"}' --scope user

任何SSE兼容客户端：

{
  "mcpServers": {
    "verse-rag": {
      "transport": "sse",
      "url": "http://localhost:8051/sse"
    }
  }
}

______________________________________________________________________

配置

所有配置都是通过环境变量进行的。中的默认值 docker/compose.yml 已准备好用于标准本地设置。

______________________________________________________________________

RAG战略

混合搜索(USE_HYBRID_SEARCH=true)

将pgvector余弦相似度与PostgreSQL全文搜索相结合(tsvector).结果以加权组合的形式评分(0.7 矢量+ 0.3 文本）使用a FULL OUTER JOIN 在 hybrid_search_crawled_pages SQL函数。

最适合技术文档，其中精确的术语匹配（函数名、关键字）与语义相似性都很重要。

重新排名(USE_RERANKING=true)

初始检索后，应用交叉编码器模型(cross-encoder/ms-marco-MiniLM-L-6-v2)根据原始查询对结果进行重新评分和排序。在CPU上本地运行，无需API成本。增加约100-200毫秒的查询延迟，以换取更好的结果排序。

______________________________________________________________________

数据库模式

这 init.sql 创建：

• crawled_pages --主桌 vector(4096) 嵌入（匹配 qwen3-embedding:8b)、来源标签和a UNIQUE(url, chunk_number) 幂等扰动的约束
• match_crawled_pages() --向量相似性搜索函数
• hybrid_search_crawled_pages() --组合式矢量+全文搜索功能
• GIN指数 content 用于全文搜索
• B-树指数 source_id 用于源过滤

注： ivfflat/hnsw 索引限制为2000个维度。在4096个dims时，查询使用顺序扫描——这对于文档规模的数据集来说是可以接受的。

______________________________________________________________________

业绩说明

• 批量嵌入： 页面中的所有块都嵌入在一个单独的块中 /api/embed 打电话给Ollama
• 批量追加销售： 所有记录都写在一个单独的 POST 使用以下方式发布gREST Prefer: resolution=merge-duplicates
• 信号量： 嵌入请求通过以下方式序列化 asyncio.Semaphore(1) 因为Ollama一次处理一个嵌入作业
• 即发即弃： 爬行工具立即返回；背景 asyncio.Task 处理嵌入+存储。通过以下方式监控进度：

  docker logs verse-rag-mcp -f

______________________________________________________________________

发展

代码更改后重建

只有最后一个Docker层(COPY src/)在源代码更改时无效，因此重建很快：

docker build -f docker/Dockerfile -t verse-rag:latest . && \
docker compose -f docker/compose.yml up -d mcp

项目结构

verse-rag/
├── src/
│   ├── crawl4ai_mcp.py   # MCP server, tool definitions, lifespan
│   └── utils.py          # Embeddings, chunking, PostgREST client
├── docker/
│   ├── Dockerfile        # Build definition
│   ├── compose.yml       # Full stack definition
│   └── init.sql          # PostgreSQL schema + functions
├── knowledge_graphs/     # Optional Neo4j hallucination detection
└── pyproject.toml

______________________________________________________________________

故障排除

CUDA不可用/Olama SIGABRT

GPU可能在 Exclusive_Process 模式。重置它：

sudo nvidia-smi -c 0

此操作在重新启动时重置，必须在驱动程序重新加载后重新应用。

容器重启后MCP工具挂起

Claude Code缓存SSE会话ID。重新启动MCP容器后，在使用任何工具之前，重新启动Claude Code以清除过时的会话。

嵌入无声地失败

检查后台任务输出：

docker logs verse-rag-mcp -f | grep -E "✅|❌"

______________________________________________________________________

许可证

麻省理工学院