OneRAG：一个配置即切换的生产级 RAG 框架

深夜 11 点，产品经理催你上线新功能

深夜 11 点，你正为 RAG 系统的向量数据库选型头疼——用 ChromaDB 快速 PoC，还是直接上 Pinecone 应对生产流量？两个方案的代码路径几乎完全不同，改完怕引出其他问题。

OneRAG 就是来解决这个问题的：一个代码库，通过修改配置就能在 6 种向量数据库、5 种 LLM、6 种 Reranker 之间自由切换，无需重写业务逻辑。

---

项目起源：PM 的"贪心"需求

OneRAG 诞生于一个 RAG Chat Service 产品经理之手——他在多个项目迭代中发现，每次换向量数据库、换 LLM Provider 都要重写大量代码。既然 RAG 管道的前置检索 + 后置生成的逻辑是固定的，为什么不能把组件接口抽象出来？

于是他用 Python + FastAPI 搭建了这套框架，目标明确：让开发者用同一套代码，从 PoC 一路跑到生产环境。

目前项目已有 124 颗 GitHub Stars，采用 MIT 许可证。核心语言为 Python，主要话题涵盖 rag、vector-database、fastapi、langchain-alternative、graphrag 等。

---

类比解释：乐高积木式的 RAG 管道

想象你有一套乐高积木，基础底板是固定的（Query 入口 → 检索 → 重排序 → 生成 → 输出），但每一层积木块都可以自由替换：

积木层	可替换选项
检索层	Weaviate / ChromaDB / Pinecone / Qdrant / pgvector / MongoDB / Grok
生成层	Google Gemini / OpenAI / Anthropic Claude / Ollama / OpenRouter
重排序层	Jina / Cohere / Google / OpenAI / OpenRouter / Sentence-Transformers
缓存层	Memory / Redis / Semantic

替换方式极其简单——在 .env 或 YAML 中改一行配置即可。

---

核心功能：不是玩具，是生产级实现

完整的 RAG 管道

Query → Router → Expansion → Retriever → Cache → Reranker → Generator → PII Masking → Response

每个阶段都有明确的职责定义，支持细粒度配置：

• 查询路由：可选择 LLM 驱动或规则驱动
• 查询扩展：内置韩语同义词库、不常用词过滤，支持自定义词典
• 混合检索：Dense 向量检索 + BM25 关键词检索双管齐下
• GraphRAG：基于知识图谱的关系推理，适合复杂关联查询场景
• Agent 能力：支持工具执行和 MCP 协议扩展

OpenAI SDK 完全兼容

项目提供了 /v1/chat/completions 接口，完全兼容 OpenAI SDK。现有代码只需改一行 base_url：

from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")
response = client.chat.completions.create(
    model="gemini",
    messages=[{"role": "user", "content": "RAG是什么？"}],
)

这意味着 LangChain、Cursor、Open WebUI 等任何使用 OpenAI SDK 的工具，都能零成本接入 OneRAG。

配套 Web UI

项目自带 React 前端，提供实时流式聊天（WebSocket）和文档管理界面，支持多语言（韩/英/日/中）和深色模式。另有管理后台可监控会话和性能。

---

部署体验：从 5 分钟到一键启动

项目提供了三种启动方式，门槛逐级降低：

方式	需求	说明
make start	Docker	Weaviate + FastAPI + Swagger UI 一键启动
make easy-start	仅 Python	本地 ChromaDB，零配置快速体验
Ollama 模式	Ollama	离线运行，无需任何 API Key

其中 make easy-start 最为友好：自动生成配置、预置 25 条示例数据、CLI 界面直接对话。Ollama 模式下完全离线运行，适合安全敏感或无外网的环境。

---

技术深度：生产级质量的代码实践

项目采用了完整的工程化实践：

• 测试覆盖：2100+ 测试用例，Pytest + Vitest 双框架，CI/CD 流水线守护代码质量
• 多环境配置：8 套 docker-compose 配置，分别对应生产/开发/验证/Langfuse 可观测性/Neo4j 图数据库等场景
• 多阶段 Dockerfile：生产镜像经过优化裁剪，体积可控
• Feature Flag 架构：通过 YAML 控制各功能模块启停，无需修改代码
• 安全特性：内置 PII（个人身份信息）检测与脱敏，审计日志

技术栈方面，项目基于 FastAPI 构建 REST API，异步处理高效；Pydantic 做数据验证；无 LangChain 依赖（官方定位为"LangChain Alternative"），更轻量可控。

---

局限与挑战：不回避的问题

1. 向量数据库选型需谨慎：6 种后端各有优劣——Pinecone 是托管服务省运维但有成本，Weaviate 开源可私有部署但资源占用较高，ChromaDB 轻量适合本地但并发能力有限
2. 非完全无代码：虽然配置驱动，但高级功能（如 GraphRAG、Agent 工具链）仍需理解其工作原理
3. 韩语优化为主：项目文档和示例数据以韩语为主，其他语言用户需要自行适配词典和 Prompt

---

行业意义：RAG 民主化的有益探索

RAG 系统的核心痛点从来不是"能不能做"，而是"换了组件怎么办"。OneRAG 用配置驱动的方式，把这个痛点降低了一个量级。它不是最简单的 RAG 入门项目，但可能是最适合长期维护的项目之一。

随着向量数据库和 LLM 生态持续快速迭代，能够在不改变业务代码的前提下快速切换底层组件——这种灵活性本身就是一种竞争力。

---

相关资源

• GitHub: https://github.com/notadev-iamaura/OneRAG
• 许可证: MIT
• 主要语言: Python
• 实时演示: https://demo-frontend-production-3c93.up.railway.app (访问码: 1127)