Agentic RAG Knowledge Base

Agentic RAG Knowledge Base

把文档变成可对话的知识系统 Local-first Agentic RAG for private / on-prem knowledge Q&A

English · Start Here · Quickstart · Enterprise · Architecture

一个面向本地部署 / 私有知识管理的 Agentic RAG 系统：文档入库 → 混合检索 → 带来源问答 → Agent 工具调用 → 可选联网搜索。

适合：想快速搭私有知识库的团队，以及想在 RAG 之上继续做 Agent / 多模型 / 企业能力的开发者。

---

为什么不是「又一个 RAG Demo」

| 常见 RAG 项目 | 本项目 | | --- | --- | | 检索 → 一次生成回答 | RAG + ReAct Agent，可规划、调工具、多步推理 | | 只有向量检索 | 向量 + BM25 混合检索 + Rerank | | 脚本级 PoC | Vue 3 完整前端：流式对话、来源、历史、文件管理 | | 绑定单一云厂商 | Ollama / DeepSeek / OpenAI / Gemini 可切换 | | 难二次开发 | FastAPI + MCP Server，可接入 Cursor / Claude Desktop | | 无评测 | 内置 RAG 回测（vector / bm25 / hybrid） | | 难上生产 | 多租户、JWT/OIDC、审计、配额、Prometheus/Grafana |

---

核心能力

• Agentic Workflow — ReAct 推理循环：规划 → 工具调用 → 汇总
• Hybrid Retrieval + Rerank — ChromaDB + BM25，bge-reranker-v2-m3 精排
• GraphRAG — 轻量知识图谱，实体关系与多跳查询
• Streaming Chat UI — 流式回答、思维过程、来源（页码 / chunk）
• Local Embedding — bge-small-zh-v1.5，可完全离线
• Incremental Index — 文件哈希增量重建
• MCP Server — rag_search / graph_query 接入 IDE Agent
• RAG Evaluation — CLI + 前端一键回测
• Enterprise Ops — 多租户、审计、配额、Webhook、PII/ABAC、数据保留、合规导出、监控告警
• Web Search Ready — 可选 SearXNG / Tavily

---

产品预览

| 登录页 | 首页工作台 | | :---: | :---: | | | |

| 知识库构建 | 文件管理 | | :---: | :---: | | | |

| 带来源问答 | 智能 Agent | | :---: | :---: | | | |

| 设置 | | :---: | | |

---

Tech Stack

Frontend   Vue 3 · Vite · Element Plus
Backend    FastAPI · JWT / OIDC
Retrieval  ChromaDB · BM25 · Reranker · GraphRAG
LLM        Ollama · DeepSeek · OpenAI · Gemini
Ops        Docker Compose · Prometheus · Grafana · MCP

架构一览

┌─────────────┐     ┌──────────────────────┐     ┌─────────────────┐
│  Vue 3 UI   │────▶│  FastAPI + Agent     │────▶│  LLM Providers  │
│  Chat/KB/   │ SSE │  ReAct · Tools · MCP │     │  Ollama/Cloud   │
│  Eval/Admin │◀────│                      │◀────│                 │
└─────────────┘     └──────────┬───────────┘     └─────────────────┘
                               │
                    ┌──────────▼───────────┐
                    │ Hybrid Retriever     │
                    │ Vector + BM25 + Graph│
                    │ + Incremental Index  │
                    └──────────────────────┘

---

Quick Start

环境要求

• Python 3.10+
• Node.js 18+
• 可选：Ollama（本地模型）

1. 安装与配置

pip install -r requirements.txt
cd frontend && npm install && cd ..
cp .env.example .env

在 .env 中至少配置一种模型：

| 模式 | 关键配置 | | --- | --- | | 本地 | MODEL_PROVIDER=ollama | | 云端 | MODEL_PROVIDER=deepseek / openai / gemini + 对应 API Key |

2. 一键启动

Windows

powershell -ExecutionPolicy Bypass -File .\start.ps1
# 或双击 start.bat

macOS / Linux

bash start.sh

手动启动

python run_api.py          # API  → http://localhost:8000
cd frontend && npm run dev # UI   → http://localhost:5173

Docker Compose

cp .env.example .env
docker compose up -d --build
# Web → http://localhost

3. 第一次使用

1. 打开前端 → 设置 选择模型提供者
2. 上传 md / pdf / docx / txt
3. 构建知识库
4. 用「纯 RAG」或「智能模式」提问

4. 进阶

# RAG 回测
python run_backtest.py --build

# MCP（Cursor / Claude Desktop）
python mcp_server.py

---

项目结构

.
├── src/
│   ├── agent/        # Agent、工具、意图路由
│   ├── api/          # FastAPI 路由
│   ├── core/         # 向量库、检索、文档处理
│   ├── services/     # LLM、会话、RAG
│   ├── config/       # 配置
│   └── utils/        # 日志、监控、重试
├── frontend/         # Vue 3 前端
├── deploy/           # Docker / 监控 / SearXNG
├── docs/             # 文档与截图
├── documents/        # 默认知识源
└── vector_db/        # 向量持久化

常用配置

详见 [.env.example](.env.example)：

• MODEL_PROVIDER / DEEPSEEK_API_KEY / OLLAMA_MODEL / OLLAMA_API_URL
• VECTOR_DB_PATH / TOP_K / MAX_TOKENS
• 联网搜索：TAVILY_API_KEY

文档

| 文档 | 说明 | | --- | --- | | [Start Here](STARTHERE.md) | 最短上手路径 | | [Quickstart](QUICKSTART.md) | 快速开始 | | [Agent 架构](docs/AGENTARCHITECTURE.md) | ReAct / 工具路由 | | [企业部署](docs/ENTERPRISEDEPLOYMENT.md) | 多租户与运维 | | [Demo 素材清单](docs/DEMOASSETSCHECKLIST.md) | 截图 / GIF | | [日志排查](LOGQUICK_GUIDE.md) | 排障 |

---

English

Agentic RAG Knowledge Base is a local-first knowledge Q&A system for private deployments:

• Hybrid retrieval (vector + BM25) with reranking
• ReAct agent with tool calling and optional web search
• Vue 3 streaming chat UI with citations and history
• Multi-provider LLMs: Ollama, DeepSeek, OpenAI, Gemini
• MCP server for Cursor / Claude Desktop
• Built-in RAG evaluation and enterprise ops hooks

pip install -r requirements.txt
cd frontend && npm install && cd ..
cp .env.example .env
# set MODEL_PROVIDER + API key (or Ollama)
bash start.sh   # or start.ps1 / start.bat on Windows

Open http://localhost:5173, upload documents, build the index, and chat.

---

Roadmap

• 更稳的默认配置与新手引导
• HuggingFace Spaces / 在线 Demo
• 更完整的英文文档与示例知识库
• Agent 工具生态与插件市场

欢迎 Star / Issue / PR。如果你在私有化或中文知识库场景落地了，也欢迎分享反馈。

License

[MIT](LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: wdf-wyh
• Source: wdf-wyh/Agentic-RAG-Knowledge-Base
• License: MIT
• Homepage: https://github.com/wdf-wyh/Agentic-RAG-Knowledge-Base

Install and usage instructions live in the source repository linked above.