Content
# person_rag
Lightweight Personal/Team Knowledge Base RAG Service: **BM25 Keyword Search + DeepSeek Generated Answers**, no vector database required.
[](LICENSE)
## Features
- **BM25 Retrieval**: based on `jieba` tokenization, suitable for Chinese operation and maintenance documents
- **DeepSeek Q&A**: if retrieval hits, answers based on knowledge base; if not, falls back to general knowledge
- **Web UI**: streaming output, Markdown rendering, source tracing
- **MCP Server**: for clients like Cursor/Claude Desktop to call knowledge base
- **API Access Log**: optional MySQL logging of IP, input, output, and time consumption
- **Rate Limiting and Security**: IP rate limiting, optional API Key, Redis counting
## Quick Start
### 1. Clone and Dependencies
```bash
git clone https://github.com/your-username/person_rag.git
cd person_rag
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
```
### 2. Configure Environment Variables
```bash
cp .env.example .env
```
Edit `.env`, at least set:
```env
DEEPSEEK_API_KEY=sk-your-key-here
```
Optional: MySQL logging, Redis rate limiting, site domain, ICP filing number, etc. (see `.env.example`).
### 3. Prepare Knowledge Base
Place Markdown documents in `docs/` directory (repository already includes operation and maintenance example documents).
### 4. Start Service
```bash
# Development mode
python -m app.main
# Or run in background (Linux)
chmod +x start_person_rag.sh stop_person_rag.sh
./start_person_rag.sh
```
Access in browser: `http://localhost:8000/`
## Project Structure
```
person_rag/
├── app/
│ ├── main.py # FastAPI entry
│ ├── rag.py # RAG retrieval and generation
│ ├── indexer.py # BM25 indexing
│ ├── mcp_server.py # MCP tool definition
│ ├── api_log.py # access log middleware
│ └── db.py # MySQL log storage
├── docs/ # knowledge base Markdown documents
├── static/ # web frontend
├── start_person_rag.sh
└── .env.example
```
## API
| Method | Path | Description |
|------|------|------|
| GET | `/api/health` | health check and index statistics |
| POST | `/api/chat` | Q&A (JSON) |
| POST | `/api/chat/stream` | streaming Q&A (SSE) |
| POST | `/api/rebuild` | rebuild BM25 index |
## MCP Access
HTTP method (after service starts):
```json
{
"mcpServers": {
"person-rag": {
"url": "https://your-domain.com/mcp"
}
}
}
```
Local stdio method see `mcp.config.example.json`.
Available tools: `search_knowledge`, `ask_knowledge`, `list_documents`, `rebuild_index`, `knowledge_health`.
## Environment Variables
| Variable | Description | Default |
|------|------|--------|
| `DEEPSEEK_API_KEY` | DeepSeek API key | required |
| `SITE_URL` | external domain (SEO/sitemap) | auto-inferred |
| `ICP_BEIAN_NUMBER` | ICP filing number (footer) | empty |
| `MCP_ENABLED` | enable MCP service | `true` |
| `MCP_MOUNT_PATH` | MCP mount path | `/mcp` |
| `API_LOG_ENABLED` | MySQL access log | `true` |
| `RATE_LIMIT_ENABLED` | IP rate limiting | `true` |
Complete list see [`.env.example`](.env.example).
## Production Deployment Suggestions
1. Use Nginx reverse proxy and configure HTTPS
2. Set `SITE_URL`, `ICP_BEIAN_NUMBER` (if required for filing)
3. Configure `RAG_API_KEYS` to protect sensitive interfaces
4. MySQL/Redis not exposed to public network
5. See [SECURITY.md](SECURITY.md) for details
## Knowledge Base Documents
`docs/` directory contains Linux, Nginx, MySQL, Jenkins, Git, etc. operation and maintenance notes (example content has been desensitized, domain/IP are placeholders).
## License
[MIT](LICENSE)
