Content
# Tool List
> Based on MiMo + ChromaDB + Neo4j for financial domain retrieval-enhanced generation system.
Financial document knowledge base question-answering system. Through hybrid retrieval + knowledge graph + self-correction, combined with large language models to generate professional and accurate financial Q&A. Support Agent multi-step reasoning, MCP protocol access, and full-link observability.
## Performance Highlights
| Indicator | Value | Description |
| --- | --- | --- |
| Faithfulness | **0.82** | Self-Correction enabled, +1.8% compared to baseline |
| Context Precision | **0.73** | Hybrid retrieval RRF fusion |
| Reranker improvement | **+15.3%** | Faithfulness from 0.66 → 0.76 |
| Pure retrieval latency | **< 500ms** | Includes Embedding + ChromaDB + BM25 |
| Cache hit latency | **< 100ms** | FactCache structured cache hit |
| Test coverage | **446 tests** | ruff + mypy zero errors |
## System Architecture
```mermaid
graph TB
subgraph "User Entrance"
UI[Gradio 4.x Web UI]
API[FastAPI REST API]
WS[WebSocket Stream]
MCP[MCP Server]
end
subgraph "Query Routing"
CR{CacheRouter}
GR{GraphRouter}
end
subgraph "Search Engine"
BM25[BM25 keyword search]
VEC[Vector semantic search]
RRF[RRF fusion ranking]
RK[BGE-reranker precise ranking]
end
subgraph "Knowledge Layer"
FC[FactsCache structured cache]
KG[Neo4j knowledge graph]
DB[(ChromaDB vector database)]
end
subgraph "Generation and Correction"
LLM[MiMo-V2-Pro LLM]
SC[Four-layer self-correction]
end
subgraph "Agent"
RA[ReAct Agent]
T1[financial_search]
T2[knowledge_graph]
T3[calculator]
end
subgraph "Observability"
LF[Langfuse Trace]
end
UI --> CR
API --> CR
WS --> CR
MCP --> CR
CR -->|hit| FC
CR -->|miss| GR
GR -->|graph query| KG
GR -->|text retrieval| BM25
GR -->|text retrieval| VEC
BM25 --> RRF
VEC --> RRF
RRF --> RK
RK --> LLM
LLM --> SC
RA --> T1
RA --> T2
RA --> T3
SC --> LF
RA --> LF
VEC -.-> DB
BM25 -.-> DB
```
**Agent mode** follows an independent ReAct loop: `Thought → Action (financial_search / knowledge_graph / calculator) → Observation`, up to 6 steps of reasoning.
## Core Features
- **Hybrid Retrieval** — BM25 keyword + vector semantic + RRF fusion, balancing precise matching and semantic matching
- **GraphRAG** — Entity relationship triples + Neo4j/NetworkX dual backend + graph routing automatic judgment
- **ReAct Agent** — Handwritten ReAct loop (60 lines of core), 3 tools (retrieval/graph/calculator), up to 6 steps of reasoning
- **Four-layer self-correction** — Retrieval gating → rule pre-check → Claim NLI → external verification
- **Cache enhancement (CAG)** — FactCache structured knowledge cache, skipping retrieval when hit
- **MCP Server** — RAG capability encapsulated as MCP tool, directly callable by Claude Desktop/Cursor
- **Full-link tracking** — Langfuse Trace/Span, each query can be traced back for diagnosis
- **Multi-entrance** — Gradio 4.x (recommended) + Streamlit (compatible) + FastAPI REST + WebSocket streaming
- **446 tests** — ruff + mypy zero errors, pytest fully passed
## Technical Selection
| Component | Solution | Description |
| --- | --- | --- |
| LLM | **MiMo-V2-Pro** | Xiaomi self-developed large model, OpenAI compatible interface |
| Embedding | **bge-large-zh-v1.5** | Chinese semantic vector (SiliconFlow hosted) |
| Rerank | **BGE-reranker-v2-m3** | Cross-Encoder precise ranking, local operation |
| Vector database | **ChromaDB** | Lightweight, built-in persistence |
| Knowledge graph | **Neo4j** / NetworkX | Cypher query, factory mode switching |
| Retrieval fusion | **RRF** | Dual-path recall ranking fusion |
| Web UI | **Gradio 4.x** | Streaming output + dark financial theme |
| API | **FastAPI** | REST + WebSocket dual protocol |
| Observability | **Langfuse** | Full-link Trace/Span |
| Agent protocol | **MCP** | Tool service, supporting Claude Desktop |
| Code quality | **ruff + mypy + pytest** | 446 unit tests |
## Project Structure
```
financial-rag/
├── app.py # Streamlit entrance (compatible)
├── config.yaml # Global configuration
├── requirements.txt
├── pyproject.toml # ruff / mypy configuration
├── Dockerfile
├── docker-compose.yml
│
├── src/ # 10,800+ lines of source code
│ ├── config.py # Configuration loading (YAML + .env)
│ ├── rag_pipeline.py # RAG main process (synchronous + asynchronous)
│ ├── generator/ # MiMo LLM + Query Rewriting
│ ├── embeddings/ # SiliconFlow Embedding
│ ├── vectorstore/ # ChromaDB encapsulation
│ ├── retriever/ # Vector / BM25 / hybrid retrieval
│ ├── reranker/ # BGE-reranker precise ranking
│ ├── correction/ # Four-layer self-correction
│ ├── cache/ # Semantic-level query cache
│ ├── fact_cache/ # FactCache structured knowledge cache
│ ├── fact_extractor/ # Fact + Triple joint extraction
│ ├── graph/ # GraphRAG (Neo4j/NetworkX)
│ ├── agent/ # ReAct Agent + toolset
│ ├── observability/ # Langfuse tracking
│ ├── mcp_server/ # MCP Server
│ ├── api/ # FastAPI REST + WebSocket
│ ├── ui_gradio/ # Gradio 4.x UI (recommended)
│ ├── ui/ # Streamlit UI (compatible)
│ └── evaluation/ # RAGAS evaluation
│
├── docs/ # Documentation
│ ├── adr/ # Architecture decision records (7 articles)
│ ├── stages/ # Phase development documents
│ │ ├── graphrag/ # GraphRAG phase 1-5
│ │ ├── agent/ # Agent phase 1-5
│ │ └── upgrade/ # Competitiveness upgrade phase 1-7
│ └── mcp_integration_guide.md
│
├── scripts/
│ ├── benchmark.py # RAGAS evaluation
│ └── agent_benchmark.py # Agent LLM-as-Judge
│
├── tests/ # 446 unit tests
└── data/eval/ # 50+ evaluation datasets
```
## Quick Start
```bash
# 1. Clone
git clone https://github.com/Alfroul/financial-rag.git && cd financial-rag
# 2. Environment
python -m venv venv && venv\Scripts\activate # Windows
pip install -r requirements.txt
# 3. Configuration
cp .env.example .env
# Edit .env, fill in MIMO_API_KEY
# 4. Start (recommended Gradio)
python -m src.ui_gradio.app
# Or Streamlit (compatible)
streamlit run app.py
# Or FastAPI
python -m uvicorn src.api.app:app --reload --port 8000
```
### API Key
| Key | Required | Acquisition |
| --- | --- | --- |
| `MIMO_API_KEY` | Yes | [MiMo platform](https://platform.xiaomimimo.com/) |
| `SILICONFLOW_API_KEY` | No | [SiliconFlow](https://siliconflow.cn/) (Embedding usage, built-in MiMo compatibility) |
| `LANGFUSE_PUBLIC_KEY` / `SECRET_KEY` | No | [Langfuse Cloud](https://cloud.langfuse.com/) (disable tracking if not configured) |
| `NEO4J_PASSWORD` | No | Docker startup configuration (fallback to NetworkX if not configured) |
### MCP Server
See [`docs/mcp_integration_guide.md`](docs/mcp_integration_guide.md).
```bash
python -m src.mcp_server.server # stdio (Claude Desktop)
python -m src.mcp_server.server --sse --port 8080 # SSE (remote call)
```
Expose 3 MCP Tools: `financial_search` / `knowledge_graph_query` / `financial_analysis`.
### Docker
```bash
docker-compose up --build
```
- Gradio: `http://localhost:7860`
- Streamlit: `http://localhost:8501`
- REST API: `http://localhost:8000/docs`
## Data Preparation
| Format | Directory | Description |
| --- | --- | --- |
| TXT / MD | `data/raw/news/` | Financial news |
| PDF | `data/raw/reports/` | Research reports |
| JSON / CSV | `data/raw/qa/` | Structured Q&A |
Upload method: Web UI "Document Management" page drag-and-drop upload, or place in `data/raw/` and run `python -m src.index_builder`.
## Configuration
`config.yaml` main configuration items:
```yaml
llm:
model: "MiMo-V2-Pro"
temperature: 0.7
max_tokens: 2048
embedding:
model: "BAAI/bge-large-zh-v1.5"
chunker:
chunk_size: 512
strategy: "paragraph" # paragraph / title
hybrid:
strategy: "hybrid" # vector / bm25 / hybrid
rrf_k: 60
reranker:
enabled: false # local BGE-reranker precise ranking
top_n: 5
```
## API
```bash
python -m uvicorn src.api.app:app --reload --port 8000
```
Swagger UI: `http://localhost:8000/docs`
| Method | Path | Description |
| --- | --- | --- |
| `POST` | `/api/v1/query` | Synchronous query |
| `POST` | `/api/v1/query/stream` | SSE streaming |
| `WebSocket` | `/api/v1/ws/chat` | Bidirectional streaming |
| `GET` | `/api/v1/health` | Health check |
| `POST` | `/api/v1/documents/upload` | Document upload |
| `GET` | `/api/v1/documents/stats` | Document statistics |
## Benchmark
> `scripts/benchmark.py` + RAGAS framework, 50 financial evaluation datasets.
### Experiment History
| Round | LLM | Focus | Dataset |
| --- | --- | --- | --- |
| 1-7 | GLM-4-flash | vector / BM25 / hybrid comparison | 18 |
| 8 | Qwen3-8B (SiliconFlow) | Self-Correction effect | 50 |
| 9 | Qwen3-8b + GraphRAG | Graph + reranking | 50 |
### Round 8 Results (Self-Correction Effect)
| Configuration | Faithfulness | Answer relevance | Context precision | Context recall |
| --- | --- | --- | --- | --- |
| hybrid | 0.8020 | 0.3165 | 0.6959 | 0.6151 |
| hybrid + SelfCorrection | **0.8162** | **0.3278** | **0.7036** | **0.6188** |
### Round 9 Results (Retrieval Strategy Comparison)
| Configuration | Faithfulness | Answer relevance | Context precision | Context recall |
| --- | --- | --- | --- | --- |
| vector | 0.8010 | 0.3218 | 0.7034 | 0.6215 |
| hybrid | 0.6609 | 0.3267 | 0.7302 | 0.6091 |
| hybrid + Reranker | 0.7623 | 0.3298 | 0.6995 | 0.6341 |
| hybrid + Graph | 0.6909 | 0.3251 | 0.6988 | 0.5985 |
### Retrieval Latency
| Configuration | P50 (ms) | P95 (ms) | AVG (ms) |
| --- | --- | --- | --- |
| hybrid | 17,703 | 48,073 | 26,453 |
| hybrid + SelfCorrection | 19,221 | 60,306 | 27,410 |
> Latency includes LLM generation time, pure retrieval stage < 500ms.
### Key Conclusions
- **Recommended configuration**: hybrid + SelfCorrection — four indicators consistently positive improvement
- Self-Correction: faithfulness +1.8%, answer relevance +3.6%
- Reranker precise ranking: faithfulness from 0.66 to 0.76 (+15.3%)
- GraphRAG: faithfulness from 0.66 to 0.69 (+4.5%)
## Documentation
| Document | Description |
| --- | --- |
| [`docs/adr/`](docs/adr/) | Architecture decision records (7 articles): Neo4j selection, Agent design, MiMo migration, Langfuse, Gradio, MCP |
| [`docs/stages/graphrag/`](docs/stages/graphrag/) | GraphRAG phase development (5 phases): triple extraction → storage → retrieval → routing → integration |
| [`docs/stages/agent/`](docs/stages/agent/) | Agent phase development (5 phases): ReAct loop → tool → parser → Task Classifier → evaluation |
| [`docs/stages/upgrade/`](docs/stages/upgrade/) | Competitiveness upgrade (7 phases): MiMo → Langfuse → Gradio → MCP → Neo4j → WebSocket → Review |
| [`docs/mcp_integration_guide.md`](docs/mcp_integration_guide.md) | MCP Server integration guide (Claude Desktop/Cursor configuration) |
## Frequently Asked Questions
### Why choose RRF instead of weighted average?
RRF only depends on ranking position, naturally compatible with different retriever score scales. BM25 and cosine similarity have different dimensions, direct weighting requires normalization. RRF formula `1/(k+rank)` is simple and robust, k=60 is an empirical value.
### Two-Stage Retrieval (Coarse and Fine Ranking)?
Vector retrieval uses Bi-Encoder (independent encoding), which is fast but has limited accuracy. Reranker uses Cross-Encoder (joint encoding), which has high accuracy but is slow. Coarse ranking Top-30 → Fine ranking Top-5, balancing speed and accuracy.
### GraphRAG vs. Ordinary RAG?
Ordinary RAG only retrieves text fragments and cannot answer questions about cross-entity relationships. GraphRAG extracts triples to build a knowledge graph and supplements structured context through entity matching and path queries. GraphRouter automatically determines whether to use the graph path based on query features (comparative words, causal words, known entities).
### ReAct Agent Design?
Handwritten ReAct loop, independent of LangChain. Three tools: `financial_search` (RAG), `knowledge_graph` (graph), and `calculator` (secure calculator). Up to 6-step reasoning, with forced summarization if exceeded. Task Classifier handles boundary cases before the loop.
### What does MCP Server solve?
MCP is an Anthropic-led Agent interaction standard. Encapsulates RAG capabilities as MCP Tools, allowing Claude Desktop/Cursor to call directly without understanding internal implementation.
### Semantic Cache vs. Exact Match Cache?
Exact match cache only caches identical queries. Semantic cache uses Embedding cosine similarity; queries like "What is GDP" and "What does GDP mean" have a similarity > 0.95, hitting the same cache and significantly increasing hit rate.
### Effect of asyncio?
Hybrid retrieval uses `asyncio.gather` for parallel processing, reducing latency from the sum of both paths to the maximum. With full asynchronous Embedding/LLM, overall latency decreases by about 40%.
## Resume Description
> **Financial Domain RAG Knowledge Base Q&A System** | Python, FastAPI, Gradio, ChromaDB, Neo4j, MiMo
>
> - Hybrid retrieval (BM25 + vector RRF fusion) + BGE-reranker fine ranking + four-layer self-correction, Faithfulness reaching 0.82 (+15.3%)
> - GraphRAG knowledge graph path (Neo4j + entity matching + graph routing), handwritten 60-line ReAct Agent multi-step reasoning
> - FactCache structured cache (hit latency <100ms), Langfuse full-chain tracking, MCP protocol access
> - Gradio + FastAPI + WebSocket three entrances, Docker Compose deployment, 446 tests + ruff/mypy zero errors
## License
MIT
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available