Content
# UniKB - Universal Enterprise-level RAG Knowledge Base Platform
> Multi-Agent + MCP + Hybrid Search + Full-Stack。
[](https://github.com/USTCCB/UniKB/actions) []() []() []() []() []()
## Introduction
UniKB is a Retrieval-Augmented Generation (RAG) platform designed for enterprise knowledge management scenarios. It collaborates with multiple agents, utilizes the MCP tool protocol, hybrid search, and re-ranking to provide users with answers in a streaming manner, along with retrieval snippets.
Supports flexible switching of multiple LLMs, such as DeepSeek, Qwen, and OpenAI.
## Core Features
- Hybrid Search: BM25 + Vector Semantics + RRF Fusion
- Re-ranking: Cross-Encoder (BGE-reranker) to suppress hallucinations
- Multi-Agent Collaboration: LangGraph-based Planner / Retriever / Coder / Reviewer process
- MCP Protocol: Native support for Model Context Protocol, extensible toolset
- Document Parsing: PDF, DOCX, Markdown, TXT, and image OCR (requires local installation of Tesseract)
- Streaming Q&A: SSE protocol + multi-turn dialogue management + citation tracing
- Engineering: JWT authentication + API Key + Docker Compose one-click deployment + GitHub Actions CI + GHCR image release CD
- Observability: Built-in LangFuse docking (optional, no side effects when closed)
- Evaluation System: Integrated RAGAS automatic evaluation (4 major indicators)
## Tech Stack
| Layer | Selection |
|---|---|
| LLM | DeepSeek / Qwen / OpenAI (configurable switching) |
| Agent Framework | LangChain + LangGraph |
| MCP Protocol | mcp 1.0+ (stdio + SSE transmission) |
| Backend | FastAPI + Uvicorn (asynchronous) |
| Frontend | Next.js 14 + TypeScript (App Router) |
| Vector Database | Chroma (lightweight, zero-configuration) |
| Retrieval | BM25 (rank_bm25) + Vector + RRF |
| Re-ranking | Cross-Encoder (BAAI/bge-reranker-base) |
| Database | PostgreSQL (conversation history) / SQLite (default) |
| Cache | Redis (Embedding / hot Q&A) |
| File | Local / MinIO switchable |
| Observability | LangFuse (optional) |
| Evaluation | RAGAS |
| Engineering | Docker Compose + GitHub Actions CI + GitHub Container Registry release |
## Architecture Diagram
```
+----------------------------------------------------------------+
| Next.js 14 (Frontend) |
| Chat UI Upload Sources History (shared AuthBar/Nav) |
+--------------------------+----------------------------------------+
| HTTPS / SSE
+--------------------------v----------------------------------------+
| FastAPI (Backend) |
| +----------+ +----------+ +-------------+ +----------+ |
| | Auth | |Documents | | Chat / SSE | | History | |
| +----------+ +----------+ +------+------+ +----------+ |
| | |
| +----------------v------------------+ |
| | LangGraph Multi-Agent | |
| | Planner -> Retriever -> Coder -> Reviewer |
| +---+----------+---------+---------+ |
| | | | |
| +------v-----+ +--v-----+ +--v-------+ |
| | RAG Link | |LLM Router| |MCP Toolset| |
| | BM25+Vec+RRF| |DS/Qwen/OAI| | (pluggable)| |
| +------+-----+ +--------+ +----------+ |
| | |
| +----------+--------+----------+----------+ |
| v v v v |
| Chroma PostgreSQL Redis LangFuse (optional) |
+--------------------------------------------------------------------+
```
## Test Coverage
The `backend/tests/` directory covers the following modules' pure algorithm/pure logic paths, **not dependent on heavy packages** (no need for torch / sentence-transformers / chromadb / mcp / ragas actual running):
| Module | Test File | Coverage Points |
|---|---|---|
| RAG Slicing | `test_chunker.py`, `test_chunking.py` | Chinese/super long/empty input/boundary |
| RRF Fusion | `test_rrf.py`, `test_retriever.py` | Multi/single/no intersection |
| Cross-Encoder Re-ranking | `test_reranker.py` | Sorting/empty input/score injection |
| LangGraph Agent Node | `test_agent.py` | Planner / Reviewer + rewriting closed loop |
| JWT Authentication | `test_auth.py` | Issuance/verification/expiration |
| Schema Input Verification | `test_schemas.py` | Registration/chat/document 12 cases |
| Configuration Management | `test_config_and_security.py` | env loading/routing/boundary |
| History API | `test_history_api.py` | CRUD/sorting/404 |
| Observability | `test_observability.py` | noop context + pipeline integration |
| RAGAS Script | `test_ragas_eval_script.py` | JSONL loading/formatting |
| FastAPI Registration | `test_smoke.py` | app/router/OpenAPI integrity |
| MCP Server | `test_mcp.py` | Automatic skip when missing packages |
CI runs **63 passed, 1 skipped**. To cover deeper (like real Chroma retrieval, Cross-Encoder inference), you need to run `docker compose up backend` locally, start the service, and download the models before running.
## Quick Start
### 0. Preparation
- Python 3.10+
- Node.js 18+ (frontend)
- Optional: Docker / Docker Compose
### 1. Clone and Install
```bash
git clone https://github.com/USTCCB/UniKB.git
cd UniKB
```
### 2. Configure Environment Variables
```bash
cd backend
cp .env.example .env
# Edit .env, fill in at least one LLM_API_KEY (DeepSeek / Qwen / OpenAI)
```
### 3. One-Click Start (Recommended Docker)
```bash
docker compose up -d
```
- Backend API: http://localhost:8000
- Frontend UI: http://localhost:3000
- API Documentation: http://localhost:8000/docs
Optional profiles:
```bash
docker compose --profile pg up -d # Add Postgres
docker compose --profile observability up -d # Add LangFuse self-hosting
```
### 4. Local Development Mode
```bash
# Backend
cd backend
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000
# Frontend (new terminal)
cd frontend
npm install
npm run dev
```
### 5. Run Tests
```bash
cd backend
python -m pytest -v --cov=app
```
## Key Function Demonstrations
### 1) Upload Document / Automatic Entry
```bash
curl -X POST http://localhost:8000/api/v1/documents/upload ^
-H "Authorization: Bearer YOUR_TOKEN" ^
-F "file=@./data/samples/handbook.pdf"
```
Returns `{ "doc_id": "...", "chunks": 87, "status": "indexed" }`
### 2) Intelligent Q&A (Streaming)
```bash
curl -N http://localhost:8000/api/v1/chat/stream ^
-H "Authorization: Bearer YOUR_TOKEN" ^
-H "Content-Type: application/json" ^
-d "{\"question\": \"What is the product's warranty period?\", \"kb_id\": \"default\"}"
```
### 3) Multi-Agent Collaboration Mode
Request body `{"mode": "agent", ...}`, the backend executes the Planner / Retriever / Coder / Reviewer full link, returning a trajectory with intermediate steps.
### 4) History Conversation
```bash
# List
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8000/api/v1/history
# Append
curl -X POST http://localhost:8000/api/v1/history/<sid>/append \
-H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
-d '{"role": "user", "content": "hi"}'
```
### 5) Retrieval Snippet Preview (Frontend Sources page uses the same interface)
```bash
# Get source events via SSE, or directly call /api/v1/chat/stream with question=keyword
```
## Project Structure
```
UniKB/
+- backend/ # FastAPI Backend
| +- app/
| | +- api/ # auth / chat / documents / history / health
| | +- core/ # config / logging / security / observability
| | +- rag/ # parser / chunker / embedding / retriever / reranker / pipeline
| | +- agents/ # LangGraph Multi-Agent + tools + llm_router
| | +- mcp/ # MCP Toolset
| | +- schemas/ # Pydantic models
| +- tests/ # Unit tests (63 passed) + RAGAS evaluation script
| +- Dockerfile
| +- requirements.txt
+- frontend/ # Next.js 14 (app/ + components/ + lib/)
| +- app/{chat,upload,sources,history}/page.tsx
| +- components/{AuthBar,Nav}.tsx
| +- lib/api.ts
+- docs/ # Architecture, interview explanations
+- data/samples/ # Sample documents
+- docker-compose.yml
+- .github/workflows/ # CI + image release (lint / pytest / frontend build / Docker / GHCR)
+- LICENSE
+- README.md
```
## Evaluation and Quality
```bash
cd backend
python -m tests.run_ragas_eval --kb default \
--dataset ../data/eval/qa.jsonl \
--out ../data/eval/ragas_report.json
```
Outputs faithfulness / answer_relevancy / context_precision / context_recall four core indicators + JSON report (including each sample).
## Observability (Optional)
Set in `.env`:
```
LANGFUSE_ENABLED=true
LANGFUSE_PUBLIC_KEY=pk-...
LANGFUSE_SECRET_KEY=sk-...
LANGFUSE_HOST=https://cloud.langfuse.com
```
The RAG pipeline (retriever / reranker / llm) will automatically write traces; no side effects when not enabled.
## Roadmap
- [x] Multi-LLM Routing
- [x] BM25 + Vector Hybrid Search + RRF
- [x] LangGraph Multi-Agent
- [x] MCP Protocol Adaptation
- [x] SSE Streaming Q&A
- [x] Multi-turn Dialogue / History Conversation / Citation Tracing
- [x] RAGAS Automatic Evaluation Script + JSON Report
- [x] LangFuse Observability (optional)
- [x] Docker Compose One-Click Start + Healthcheck
- [ ] User / Knowledge Base Multi-tenancy
- [ ] Postgres Migration to SQLAlchemy
- [ ] MinIO File Storage
## License
MIT
