mini-rag

这是一个用于问答任务的极简 RAG 模型实现。

课程介绍

这是一个教育项目，所有代码都通过一系列阿拉伯语 YouTube 视频进行了逐步讲解。请查看以下列表：

#	标题	链接	代码
1	关于课程 ماذا ولمـــاذا	视频	NA
2	我们将构建什么 ماذا سنبنى في المشروع	视频	NA
3	设置你的工具 الأدوات الأساسية	视频	NA
4	项目架构	视频	分支
5	欢迎来到 FastAPI	视频	分支
6	嵌套路由 + 环境变量	视频	分支
7	文件上传	视频	分支
8	文件处理	视频	分支
9	Docker - MongoDB - Motor	视频	分支
10	MongoDB 模式和模型	视频	分支
11	MongoDB 索引	视频	分支
12	数据管道增强	视频	分支
13	第一阶段检查	视频	分支
14	LLM 工厂	视频	分支
15	向量数据库工厂	视频	分支
16	语义搜索	视频	分支
17	增强答案	视频	分支
18	第一阶段检查 + 问题修复	视频	分支
19	Ollama 本地 LLM 服务器	视频	分支
20	从 MongoDB 到 Postgres + SQLAlchemy & Alembic	视频	分支
21	PgVector 的使用方法	视频	分支
22	应用部署 1/2	视频	分支
22	应用部署 2/2	视频	分支
24	Celery 工作者 1/2	视频	分支
25	Celery 工作者 2/2	视频	分支

系统要求

• Python 3.10

安装依赖

sudo apt update
sudo apt install libpq-dev gcc python3-dev

使用 MiniConda 安装 Python

1. 从这里下载并安装 MiniConda。
2. 使用以下命令创建一个新环境：

$ conda create -n mini-rag python=3.10

3. 激活环境：

$ conda activate mini-rag

（可选）设置命令行界面以提高可读性

export PS1="\[\033[01;32m\]\u@\h:\w\n\[\033[00m\]\$ "

（可选）使用 Colab + Ngrok 运行 Ollama 本地 LLM 服务器

• 查看笔记本 + 视频

安装步骤

安装所需包

$ pip install -r requirements.txt

设置环境变量

$ cp .env.example .env

运行 Alembic 迁移

$ alembic upgrade head

在 .env 文件中设置你的环境变量，例如 OPENAI_API_KEY 的值。

运行 Docker Compose 服务

$ cd docker
$ cp .env.example .env

• 使用你的凭据更新 .env

$ cd docker
$ sudo docker compose up -d

访问服务

• FastAPI: http://localhost:8000
• Flower 仪表盘: http://localhost:5555（管理员/密码来自环境变量）
• Grafana: http://localhost:3000
• Prometheus: http://localhost:9090

运行 FastAPI 服务器（开发模式）

$ uvicorn main:app --reload --host 0.0.0.0 --port 5000

Celery（开发模式）

在开发环境中，您可以手动运行 Celery 服务，而无需使用 Docker：

要运行 Celery 工作进程，您需要在另一个终端中执行以下命令：

$ python -m celery -A celery_app worker --queues=default,file_processing,data_indexing --loglevel=info

要运行 Beat 调度器，您可以在另一个终端中执行以下命令：

$ python -m celery -A celery_app beat --loglevel=info

要运行 Flower 仪表板，您可以在另一个终端中执行以下命令：

$ python -m celery -A celery_app flower --conf=flowerconfig.py

打开浏览器并访问 http://localhost:5555，即可查看仪表板。

Postman 集合

请从 /assets/mini-rag-app.postman_collection.json 下载 Postman 集合。

mini-rag 快速上手指南

mini-rag 是一个极简的 RAG（检索增强生成）模型实现，专为问答系统设计。本项目配套了详细的视频教程（阿拉伯语），适合希望从零构建 RAG 系统的开发者学习。

环境准备

系统要求

• 操作系统: Linux (推荐 Ubuntu/Debian) 或 macOS
• Python 版本: Python 3.10
• 容器工具: Docker & Docker Compose (用于运行数据库和中间件)

安装前置依赖

在终端执行以下命令安装系统级依赖：

sudo apt update
sudo apt install libpq-dev gcc python3-dev

配置 Python 环境 (推荐使用 Miniconda)

1. 下载并安装 Miniconda。

   国内加速建议：如果下载缓慢，可使用清华源镜像安装或配置 conda 镜像。

2. 创建并激活虚拟环境：

conda create -n mini-rag python=3.10
conda activate mini-rag

(可选) 优化终端提示符以便阅读：

export PS1="\[\033[01;32m\]\u@\h:\w\n\[\033[00m\]\$ "

安装步骤

1. 安装 Python 依赖

在项目根目录下执行：

pip install -r requirements.txt

提示：国内用户建议使用 -i https://pypi.tuna.tsinghua.edu.cn/simple 参数加速安装。

2. 配置环境变量

复制示例配置文件并编辑：

cp .env.example .env

请在 .env 文件中填入必要的密钥，例如 OPENAI_API_KEY。如果你计划使用本地大模型（如 Ollama），请参考项目提供的 Colab Notebook 进行设置。

3. 初始化数据库

执行 Alembic 迁移以创建数据库表结构：

alembic upgrade head

4. 启动基础设施服务 (Docker)

启动 PostgreSQL、Redis、Prometheus 等依赖服务：

cd docker
cp .env.example .env
# 编辑 docker/.env 填入你的凭证
sudo docker compose up -d

基本使用

启动开发服务器

在终端中运行 FastAPI 服务：

uvicorn main:app --reload --host 0.0.0.0 --port 5000

启动后台任务处理 (Celery)

RAG 的文件处理和索引构建需要异步任务支持。请新开终端窗口分别运行以下命令：

1. 启动 Celery Worker:

python -m celery -A celery_app worker --queues=default,file_processing,data_indexing --loglevel=info

2. 启动定时任务调度器 (Beat):

python -m celery -A celery_app beat --loglevel=info

3. (可选) 启动监控面板 (Flower):

python -m celery -A celery_app flower --conf=flowerconfig.py

访问服务

服务启动后，可通过以下地址访问：

• API 文档 (FastAPI): http://localhost:8000
• 任务监控 (Flower): http://localhost:5555 (默认账号密码见 .env 配置)
• 系统监控 (Grafana): http://localhost:3000
• 指标采集 (Prometheus): http://localhost:9090

测试接口

你可以下载项目的 Postman 集合 /assets/mini-rag-app.postman_collection.json 导入 Postman 进行快速测试，或直接通过 API 文档上传文件并发起问答请求。