【免费下载链接】mini-ragAn Educational Project (step by step) to teach how to build a production-ready app for RAG application.项目地址https://gitcode.com/gh_mirrors/mi/mini-rag点击查看免费下载mini-rag 是一个手把手教你构建生产级 RAG检索增强生成应用的开源教学项目。它的数据库架构经历了一次教科书式的演进从早期的MongoDB Motor平滑迁移到PostgreSQL SQLAlchemy Alembic。本文将带你完整走一遍这条迁移路线——为什么换库、如何配置连接、如何用 SQLAlchemy 定义 ORM 模型、如何用 Alembic 管理表结构版本以及最终如何通过 Docker Compose 一键部署。一、为什么要从 MongoDB 迁移到 PostgreSQL早期教程中mini-rag 使用 MongoDB 存储项目projects、资产assets和数据块chunks数据以文档形式存放在集合中。但随着功能完善MongoDB 的自由开始暴露短板缺乏强关系约束chunks依赖assetsassets依赖projects文档数据库没有外键孤儿数据只能靠代码自觉维护事务与一致性弱RAG 管道中一次入库要同时写资产表和数据块表关系型事务更可靠没有内置的 Schema 版本管理表结构变更全凭手改难以追溯向量一体化趋势PostgreSQL 的 pgvector 扩展让向量检索和业务数据共存于同一数据库少维护一套存储。迁移后的技术栈对比一目了然能力迁移前MongoDB迁移后PostgreSQL驱动Motor异步asyncpg异步ORMPydantic-MongoSQLAlchemy 2.0结构管理无动态集合Alembic 迁移版本链关系约束应用层自行维护外键 级联关系向量存储独立 Qdrant可选 pgvector 内置 依赖文件 src/requirements.txt 中你能同时看到motor、pydantic-mongo旧栈残留和SQLAlchemy2.0.36、asyncpg、alembic、psycopg2、pgvector新栈组件这正是迁移过程留下的化石证据。二、连接配置环境变量驱动的连接串迁移的第一步是把数据库凭据收拢到统一的配置类中。在 src/helpers/config.py 里PostgreSQL 的连接参数由五个环境变量组成POSTGRES_USERNAME: str POSTGRES_PASSWORD: str POSTGRES_HOST: str POSTGRES_PORT: int POSTGRES_MAIN_DATABASE: strFastAPI 应用在启动阶段拼接连接串并创建异步引擎。关键代码位于 src/main.pypostgres_conn fpostgresqlasyncpg://{username}:{password}{host}:{port}/{database} app.db_engine create_async_engine(postgres_conn) app.db_client sessionmaker(app.db_engine, class_AsyncSession, expire_on_commitFalse)三个细节值得注意postgresqlasyncpg://指定 asyncpg 驱动这是 SQLAlchemy 对 PostgreSQL 最流行的异步方案expire_on_commitFalse提交后对象属性不被标记过期避免在请求结束后再次查库是异步 ORM 的高频优化项会话工厂挂在 app 上路由层通过依赖注入拿到 sessionModel 层统一复用。Linux 环境下别忘了先装底层库来自 README.mdsudo apt install libpq-dev gcc python3-dev否则psycopg2编译安装会失败——这是新手踩坑率最高的问题之一。三、SQLAlchemy 模型从集合到表结构的映射mini-rag 的模型统一继承一个声明式基类定义在 src/models/db_schemes/minirag/schemes/minirag_base.pyfrom sqlalchemy.ext.declarative import declarative_base SQLAlchemyBase declarative_base()所有表模型通过 schemes/init.py 集中导出。以核心三张表为例展示 Mongo 文档字段是如何翻译成 SQL 列的1️⃣ 项目表—— project.pyclass Project(SQLAlchemyBase): __tablename__ projects project_id Column(Integer, primary_keyTrue, autoincrementTrue) project_uuid Column(UUID(as_uuidTrue), defaultuuid.uuid4, uniqueTrue, nullableFalse) created_at Column(DateTime(timezoneTrue), server_defaultfunc.now()) updated_at Column(DateTime(timezoneTrue), onupdatefunc.now())2️⃣ 资产表—— asset.pyclass Asset(SQLAlchemyBase): __tablename__ assets asset_id Column(Integer, primary_keyTrue, autoincrementTrue) asset_uuid Column(UUID(as_uuidTrue), defaultuuid.uuid4, uniqueTrue, nullableFalse) asset_config Column(JSONB, nullableTrue) asset_project_id Column(Integer, ForeignKey(projects.project_id), nullableFalse) project relationship(Project, back_populatesassets)3️⃣ 数据块表—— datachunk.pyclass DataChunk(SQLAlchemyBase): __tablename__ chunks chunk_uuid Column(UUID(as_uuidTrue), defaultuuid.uuid4, uniqueTrue, nullableFalse) chunk_metadata Column(JSONB, nullableTrue) chunk_project_id Column(Integer, ForeignKey(projects.project_id), nullableFalse) chunk_asset_id Column(Integer, ForeignKey(assets.asset_id), nullableFalse)可以看到几个典型的PostgreSQL 化设计双 ID 策略自增Integer主键负责内部关系引用外键指向它UUID列对外暴露API 使用兼顾性能与安全JSONB 替代 Mongo 子文档asset_config、chunk_metadata这类半结构化数据用JSONB类型既保留了文档式灵活性又能建 GIN 索引外键 relationshipproject_id → asset → chunk三层关系由数据库强制执行relationship让 ORM 可以直接project.assets遍历时间戳自动化server_defaultfunc.now()保证创建时间由数据库生成onupdatefunc.now()处理更新时间显式索引__table_args__中为asset_project_id、chunk_asset_id等高频查询列声明了Index。对比迁移前的痕迹src/models/enums/DataBaseEnum.py 中仍保留着COLLECTION_PROJECT_NAME projects这类集合名枚举——MongoDB 时代的遗产如今只是历史注脚。四、异步 Model 层统一的增删改查入口模型层通过工厂模式包装数据库操作BaseDataModel.py 定义基类各 Model 只关心业务查询。以 AssetModel.py 为例async def create_asset(self, asset: Asset): async with self.db_client() as session: async with session.begin(): session.add(asset) await session.commit() await session.refresh(asset) return asset查询侧则使用 SQLAlchemy 2.0 风格的select()表达式见 ProjectModel.py 的分页查询query select(Project).offset((page - 1) * page_size).limit(page_size) projects await session.execute(query).scalars().all()这套工厂创建 异步会话 声明式查询的模式让上层路由如 routes/data.py、routes/nlp.py完全不感知数据库细节——换库只影响 Model 层以下这正是平滑迁移的核心价值。五、Alembic让表结构变更可追溯手动DROP TABLE/ 改列字段是生产事故的重灾区。mini-rag 引入 Alembic 做 Schema 版本控制目录位于 src/models/db_schemes/minirag/alembic/。1. 环境配置—— alembic/env.py 将元数据指向 ORM 基类target_metadata SQLAlchemyBase.metadata有了这行--autogenerate才能自动对比模型与数据库的差异生成迁移脚本。2. 版本链——versions/目录下当前有三份迁移迁移文件作用fee4cd54bd38初始建表projects、assets、chunks含索引与外键b9f9e870b09b新增celery_task_executions表任务幂等记录243ca8b683b0更新任务执行表结构3. 日常操作—— 项目文档 db_schemes/README.md 给出了标准三步流程# 复制模板并填入 sqlalchemy.url cp alembic.ini.example alembic.ini # 模型有变更时自动生成迁移 alembic revision --autogenerate -m Add ... # 应用所有迁移 alembic upgrade head配置模板见 alembic.ini.example把sqlalchemy.url改成你的实际连接串即可。六、Docker 部署pgvector 镜像 自动迁移生产部署时mini-rag 直接选用官方pgvector镜像见 docker-compose.ymlpgvector: image: pgvector/pgvector:0.8.0-pg17 ports: - 5400:5432 volumes: - pgvector:/var/lib/postgresql/data healthcheck: test: [CMD-SHELL, pg_isready -U postgres]两个细节体现生产级考虑选择 pgvector 镜像而非裸 postgres后续教程将向量索引入库无需额外装扩展healthcheck 保障启动顺序fastapi与celery-worker服务声明depends_on: pgvector: condition: service_healthy数据库就绪前应用不会抢跑。容器入口脚本 docker/minirag/entrypoint.sh 则把迁移固化到每次启动cd /app/models/db_schemes/minirag/ alembic upgrade head也就是说每次容器启动都会自动把表结构升级到最新版本迁移脚本与代码同仓库发布真正做到数据库随版本走。七、迁移经验清单新手避坑指南结合 mini-rag 的完整实践总结 5 条可复用的经验先迁结构再迁数据用 Alembic 按现有集合文档结构生成初始create_table迁移参考 初始迁移脚本再写一次性脚本从 Mongo 导出 JSON 批量导入 Postgres保留 UUID 对外、Int 对内对外 API 继续用 UUID 标识资源避免迁移改变接口契约半结构化字段用 JSONB不必为每个 metadata 字段建列兼顾灵活与可索引异步链路保持一致Motor → asyncpg 都是异步驱动async with会话模式几乎无缝替换路由层零改动迁移进容器生命周期entrypoint.sh里alembic upgrade head一步到位杜绝代码是新表、库是旧结构的错配。八、总结mini-rag 的这次迁移示范了 Python 生态中数据库升级的完整范式环境配置pydantic-settings→ 异步引擎asyncpg→ ORM 建模SQLAlchemy 2.0→ 版本迁移Alembic→ 容器化部署docker-compose。对 RAG 类应用而言PostgreSQL 还额外送上了 pgvector 这张向量数据库门票为后续在同一个库内完成语义检索打下基础。如果你正在为自己的 RAG 项目选型不妨直接参考这条被教学项目完整验证过的路线关系约束、事务、版本化迁移一个都不会少。赞分享【免费下载链接】mini-ragAn Educational Project (step by step) to teach how to build a production-ready app for RAG application.项目地址https://gitcode.com/gh_mirrors/mi/mini-rag点击查看免费下载相关推荐Cortex blocks 存储迁移实战从 Thanos 与 Prometheus 平滑迁移 TSDB 数据到 CortexCortex blocks 存储迁移实战从 Thanos 与 Prometheus 平滑迁移 TSDB 数据到 Cortex Cortex 的 blocks可观测性时序数据库后端指标监控从Flyway迁移到golang-migrate7个步骤实现平滑数据库迁移从Flyway迁移到golang migrate7个步骤实现平滑数据库迁移 如果你正在寻找一个更轻量、更灵活的数据库迁移工具从Flyway切换到golang数据库后端CLI开发工具Milvus数据迁移从传统数据库到向量数据库的平滑过渡Milvus数据迁移从传统数据库到向量数据库的平滑过渡 你是否正在为传统数据库无法高效处理AI时代的非结构化数据而烦恼是否想将现有业务系统中的文本、图像等数向量数据库数据库后端云原生人工智能上一篇GDAL gdal_sieve 栅格筛滤全解析清除小图斑噪声的算法原理、命令行实战与新式 gdal raster sieve 用法下一篇Zoraxy 工具链实战用 Go 编写的 HTTP/1.1 测试服务器排查协议兼容性创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考