Enterprise RAG

一个面向实际联调和评测的最小可运行 RAG 后端。

当前仓库刻意收敛到一条稳定主线：

• 文档上传与知识库管理
• 文本类文档切块
• 向量检索
• 问答接口 /api/v1/qa
• 查询日志落库
• 适合被外部评测系统接入

当前默认推荐组合：

• Python 3.11+
• FastAPI
• SQLite
• 本地 simple 向量存储
• DashScope 作为 embedding 和 generation provider

可选扩展：

• 图片 OCR ingestion 通过 ENABLE_IMAGE_OCR=true 打开 并额外安装 pillow 和 pytesseract

生产化增强已经接入：

• PostgreSQL 配置支持
• Alembic migration 基础设施
• repository / service 分层
• 异步 ingestion job
• RQ / Redis worker 队列
• 文档状态和入库任务状态查询
• 结构化日志和 request id
• 最小管理前端页 /admin

当前范围

这个版本重点保证：

• 本地容易跑通
• API 输出稳定
• 能和外部评测系统对接
• 适合直接放 GitHub 演示

同时保留可选扩展入口，而不是把默认安装重新做回一个很重的全家桶。

当前不包含：

• 默认启用的多模态处理
• OSS 存储
• Redis 缓存
• Docker / K8s 一键部署文档

项目结构

enterprise-rag/
├── src/
│   ├── api/
│   │   ├── auth.py
│   │   └── main.py
│   ├── config/
│   │   └── settings.py
│   ├── core/
│   │   ├── document_processor.py
│   │   ├── embeddings.py
│   │   ├── hybrid_retriever.py
│   │   ├── llm.py
│   │   ├── rag_engine.py
│   │   ├── reranker.py
│   │   └── vector_store.py
│   ├── models/
│   │   ├── database.py
│   │   └── schemas.py
│   ├── repositories/
│   │   ├── document_repository.py
│   │   ├── ingestion_job_repository.py
│   │   ├── knowledge_base_repository.py
│   │   └── query_log_repository.py
│   ├── services/
│   │   ├── auth_service.py
│   │   ├── file_storage_service.py
│   │   └── knowledge_base_service.py
│   └── utils/
├── alembic/
│   ├── env.py
│   └── versions/
├── data/
├── uploads/
├── requirements.txt
└── .env.example

快速开始

1. 创建虚拟环境

cd /Users/mumu/Desktop/enterprise-rag
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. 配置环境变量

cp .env.example .env.local

至少需要改这几个值：

DB_TYPE=sqlite
DB_NAME=./data/enterprise_rag.db
VECTOR_DB_TYPE=simple
DASHSCOPE_API_KEY=your_dashscope_api_key
DEFAULT_EMBEDDING_PROVIDER=alibaba
DEFAULT_LLM_PROVIDER=alibaba

如果你要跑 PostgreSQL，建议改成：

DB_TYPE=postgresql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=postgres
DB_NAME=enterprise_rag
AUTO_CREATE_TABLES=false
VECTOR_DB_TYPE=chroma
CHROMA_PERSIST_DIR=./data/chroma

如果你想改成 OpenAI，也可以：

OPENAI_API_KEY=your_openai_api_key
DEFAULT_EMBEDDING_PROVIDER=openai
DEFAULT_LLM_PROVIDER=openai

如果你想启用可选图片 OCR：

pip install pillow pytesseract

然后在 .env.local 里打开：

ENABLE_IMAGE_OCR=true

3. 启动服务

uvicorn src.api.main:app --host 127.0.0.1 --port 8000 --reload

接口文档：

• http://127.0.0.1:8000/docs
• http://127.0.0.1:8000/health
• http://127.0.0.1:8000/ready
• http://127.0.0.1:8000/admin

4. 可选：启动 RQ Worker

本地默认是：

TASK_QUEUE_BACKEND=eager

这会在应用进程内直接执行任务，适合开发调试。

如果你要切到真正的 worker 队列：

TASK_QUEUE_BACKEND=rq
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
TASK_QUEUE_NAME=ingestion

然后分别启动 API 和 worker：

uvicorn src.api.main:app --host 127.0.0.1 --port 8000 --reload
python -m src.workers.rq_worker

Alembic Migration

安装依赖后可以直接执行：

alembic upgrade head

如果是 PostgreSQL 生产环境，建议：

1. 把 .env.local 里的 AUTO_CREATE_TABLES=false
2. 先执行 alembic upgrade head
3. 再启动应用

默认账号

服务首次启动时会自动创建管理员：

• 用户名：admin
• 密码：admin123

最小使用流程

1. 登录

curl -X POST "http://127.0.0.1:8000/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123"
  }'

2. 查看知识库

curl -X GET "http://127.0.0.1:8000/api/v1/knowledge-bases" \
  -H "Authorization: Bearer YOUR_TOKEN"

3. 上传文档

curl -X POST "http://127.0.0.1:8000/api/v1/knowledge-bases/YOUR_KB_ID/documents" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@sample.txt"

现在这个接口会返回一个异步 ingestion job：

• job_id
• document_id
• status
• content_hash

4. 查看文档和入库任务状态

curl -X GET "http://127.0.0.1:8000/api/v1/knowledge-bases/YOUR_KB_ID/documents" \
  -H "Authorization: Bearer YOUR_TOKEN"

curl -X GET "http://127.0.0.1:8000/api/v1/knowledge-bases/YOUR_KB_ID/ingestion-jobs" \
  -H "Authorization: Bearer YOUR_TOKEN"

curl -X GET "http://127.0.0.1:8000/api/v1/ingestion-jobs/YOUR_JOB_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

如果任务失败，也可以重试：

curl -X POST "http://127.0.0.1:8000/api/v1/ingestion-jobs/YOUR_JOB_ID/retry" \
  -H "Authorization: Bearer YOUR_TOKEN"

5. 最小管理台

访问：

http://127.0.0.1:8000/admin

这个页面会直接调用后端接口，展示：

• ingestion jobs
• 文档状态
• query logs
• request id / queue job id

适合做最小演示和运维排障。

6. 问答

curl -X POST "http://127.0.0.1:8000/api/v1/qa" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "退款流程是什么？",
    "knowledge_base_id": "YOUR_KB_ID",
    "top_k": 3,
    "llm_provider": "alibaba",
    "use_hybrid_search": false,
    "use_rerank": false,
    "use_query_rewrite": false
  }'

/api/v1/qa 返回结构

当前问答接口返回的关键字段：

• answer
• sources
• contexts
• retrieval_time
• generation_time
• total_time
• request_id
• rag_metadata
• token_usage
• estimated_cost_usd

其中 rag_metadata 会返回本次请求的实际运行配置，例如：

• embedding_provider
• llm_provider
• llm_model
• use_hybrid_search
• use_rerank
• use_query_rewrite

这使它很适合接入外部评测系统，例如 rag-observer-eval。

评测系统如何接入

如果外部评测系统需要调用本服务，只需要：

1. 登录拿 token
2. 调 /api/v1/qa
3. 读取 answer + contexts

这是当前推荐的被测输出协议。

当前推荐配置

本地演示

DB_TYPE=sqlite
DB_NAME=./data/enterprise_rag.db
AUTO_CREATE_TABLES=true
VECTOR_DB_TYPE=simple
DEFAULT_EMBEDDING_PROVIDER=alibaba
DEFAULT_LLM_PROVIDER=alibaba
TASK_QUEUE_BACKEND=eager
USE_HYBRID_SEARCH=false
USE_RERANK=false
USE_QUERY_REWRITE=false
USE_QUERY_EXPANSION=false

想切到 Chroma

VECTOR_DB_TYPE=chroma
CHROMA_PERSIST_DIR=./data/chroma

PostgreSQL 生产建议

DB_TYPE=postgresql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=postgres
DB_NAME=enterprise_rag
AUTO_CREATE_TABLES=false
TASK_QUEUE_BACKEND=rq
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

想启用可选图片 OCR

ENABLE_IMAGE_OCR=true

开启后会额外支持：

• .png
• .jpg
• .jpeg
• .bmp
• .gif

说明

这个仓库当前优先解决的是：

• 后端主链清晰
• 本地最小可运行
• 输出结构适合评测

当前的取舍是：

• 默认路径仍然是文本 RAG
• 多模态能力以可选扩展方式接入
• 这样既保住通用性，也不把默认依赖重新拖重

如果你要继续扩展，建议优先做：

1. 自动化 seed 数据
2. 更稳定的 experiment 样例
3. 更完善的权限和知识库管理前端