MiniRAG

MiniRAG

A self-hosted RAG knowledge base in a single Spring Boot process: SQLite storage, hybrid retrieval, cited answers, and a built-in MCP server. No vector database, no message queue.

Live demo (ask the owner for the access code) · Evaluation report

Features

• Hybrid retrieval — in-memory cosine + SQLite FTS5 (BM25), fused with RRF; optional LLM rerank
• Cited answers — clickable [n] citations; only sources actually cited are displayed
• Streaming web UI — SSE, typewriter rendering, markdown, retrieval-mode switcher (vector / hybrid / rerank)
• Small footprint — single process, ~250MB RSS, runs on a 1GB VPS
• Multiple interfaces — MCP server (SSE transport), REST API, web UI, WeChat Work callback integration

Quick start

docker run -d --name minirag -p 18090:18090 --memory 512m \
  -v $(pwd)/data:/app/data \
  -e DEEPSEEK_API_KEY=sk-... \
  -e EMBEDDING_API_KEY=sk-... \
  ghcr.io/kimelody/minirag:latest

Open http://localhost:18090 and start asking. Data lives in ./data (SQLite, created automatically).

Configuration

Env	Required	Default	Description
DEEPSEEK_BASE_URL	no	https://api.deepseek.com	Any OpenAI-compatible chat endpoint
DEEPSEEK_API_KEY	yes	—	Chat model API key
EMBEDDING_BASE_URL	no	https://api.siliconflow.cn/v1	OpenAI-compatible embeddings endpoint
EMBEDDING_API_KEY	yes	—	Embeddings API key
EMBEDDING_MODEL	no	BAAI/bge-m3	Embedding model
DEMO_KEY	no	—	Visitor access code for read APIs; unset = open (local dev)
ADMIN_KEY	no	—	Admin key required for ingest APIs

MCP

Two tools: query(question, mode?) — ask and get a cited answer; ingest_text(docId, text, adminKey) — add a document.

{
  "mcpServers": {
    "minirag": {
      "url": "http://localhost:18090/sse"
    }
  }
}

The hosted demo endpoint requires basic auth: https://minirag.kimelody.de5.net/sse (ask the owner for credentials).

REST API

Method	Path	Description
POST	/api/chat	Ask; returns answer + cited sources (JSON)
POST	/api/chat/stream	Same, streamed as SSE (meta / token / sources / done)
GET	/api/search?q=&mode=	Retrieval debug: vector | hybrid | rerank
POST	/api/documents/text	Ingest {docId, text} (requires X-Admin-Key)
POST	/api/documents	Ingest an uploaded file, multipart (requires X-Admin-Key)

Evaluation

An eval harness ships in eval/: labeled question sets, Top-1 / Recall / MRR scoring over three retrieval modes — hybrid+rerank reaches Top-1 100% / MRR 1.0 on the demo set (report); a 20-question labor-law evaluation with corpus-cleaning scripts lives in eval/law/. Bring your own corpus; raw source texts are not redistributed.

Build from source

mvn package
java -jar target/minirag-0.1.0-SNAPSHOT.jar

Requires Java 21. API keys can be put in a .env file in the working directory (git-ignored).

中文说明

单进程私有化 RAG 知识库：SQLite 存储 + 混合检索（向量 + BM25，RRF 融合，可选 LLM 重排），回答带可点击引用角标，自带网页演示、REST API 与 MCP server（SSE），内存占用约 250MB，1GB 小服务器可跑。在线演示（访问码联系作者）。

License

MIT