OpenRAG 贡献者完整指南3步搭建开发环境提交你的第一个 PR【免费下载链接】openragOpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.项目地址: https://gitcode.com/GitHub_Trending/open/openragOpenRAG是一个基于 Langflow、Docling 和 OpenSearch 构建的检索增强生成RAG开源平台支持文档摄取、语义搜索与 AI 对话。本文面向首次贡献的新手开发者带你快速搭建 OpenRAG 开发环境、理解项目结构并顺利提交你的第一个 Pull RequestPR。为什么选择 OpenRAGOpenRAG 采用 Monorepo单体仓库组织前后端、SDK 与文档全部在同一仓库内对新人非常友好组件目录技术栈默认端口后端 APIsrc/FastAPIPython 3.138000前端界面frontend/Next.js TypeScript Tailwind3000RAG 流程引擎容器Langflow文档摄取、检索、Agent 流程7860Python SDKsdks/python/openrag-sdkPyPI-TypeScript SDKsdks/typescript/openrag-sdknpm-文档站点docs/Docusaurus MDX- 新手建议从文档、SDK 或前端样式入手提交第一个 PR风险低、上手快再逐步深入src/后端核心逻辑。开发环境前置要求一次性装齐 4 个工具在动手之前确认本机已安装以下工具只需选择一种容器运行时工具版本要求说明Docker / Podman / Colima最新版容器运行时三选一即可Python3.13搭配 uv 包管理器Node.js18前端开发依赖Make任意macOS / Linux 通常预装⚠️内存提示推荐至少分配8GB RAM给容器运行时Podman/Colima否则 OpenSearch、Langflow、Docling 同时运行时可能出现卡顿或崩溃。一键搭建 OpenRAG 开发环境的步骤完整流程记录在 CONTRIBUTING.md 中核心只需 3 条命令# 1. 克隆仓库 git clone https://gitcode.com/GitHub_Trending/open/openrag cd openrag # 2. 校验工具 安装依赖并生成 .env make check_tools make setup # 3. 启动开发环境 make dev-cpu # 无 GPU 环境用这条有 GPU 用 make dev启动后本地服务地址前端http://localhost:3000后端 API 文档http://localhost:8000/docsLangflowhttp://localhost:7860配置环境变量.env 中的 4 个关键项make setup会从 .env.example 生成.env文件启动前至少需要填写OPENAI_API_KEY # LLM 服务密钥 OPENSEARCH_PASSWORD # 需符合 OpenSearch 密码复杂度要求 LANGFLOW_SUPERUSERadmin # Langflow 超级用户 LANGFLOW_SUPERUSER_PASSWORD其余变量均有默认值可在 .env.example 中逐项查看注释说明。推荐开发工作流本地热重载提速迭代纯容器模式适合体验但**开发调试推荐基础设施容器化 前后端本地运行**的组合改代码即时生效# 终端 1启动 OpenSearch、Langflow 等基础设施 make dev-local-cpu # 终端 2本地运行 FastAPI 后端热重载 make backend # 终端 3本地运行 Next.js 前端热重载 make frontend # 终端 4可选启动文档解析服务 Docling make docling高频 Make 命令速查表随时运行make help查看全部命令。日常最常用的命令作用make setup安装依赖并生成.envmake dev-cpu容器化启动全栈CPUmake backend/make frontend本地运行后端 / 前端make test运行后端测试套件make lint代码风格检查make logs/make logs-be查看全部 / 后端日志make status/make health容器状态 / 服务健康检查make stop/make clean停止服务 / 停止并清除数据卷熟悉项目结构快速定位要改的代码openrag/ ├── src/ # 后端 Python 代码 │ ├── api/ # REST API 端点 │ ├── services/ # 业务逻辑 │ ├── models/ # 数据模型 │ ├── connectors/ # 外部集成S3、OneDrive 等 │ └── config/ # 配置管理 ├── frontend/ # Next.js 前端 ├── flows/ # Langflow 流程定义JSON ├── docs/ # 文档站点源码 ├── tests/ # 单元测试与集成测试 ├── Makefile # 开发命令入口 └── docker-compose.yml # 容器编排 后端入口src/main.pyREST 路由装配src/api/router.py前端页面frontend/app/。提交前测试清单跑通 make test 与 make lint跑测试make test后端套件涉及基础设施的改动跑make test-integration跑检查make lint确保通过代码风格检查代码风格摘自 CONTRIBUTING.md后端遵循 PEP 8、使用类型注解、docstring 注释、structlog日志前端TypeScript 类型安全、Tailwind 样式、遵循现有组件模式补充测试为新功能添加测试用例修改已有代码时同步更新相关测试⚠️ 所有 PR 必须通过 CI 测试参见 .github/workflows/ 下的流水线定义才会被合并。提交第一个 PR从分支到合并的 5 个规范步骤Fork 并建分支从main创建功能分支命名清晰如fix/search-filter-empty写代码小步提交一个 PR 聚焦一个改动补文档修改功能时同步更新 docs/ 下的.mdx文档文档本地构建方式见 docs/docs/support/contribute.mdx写好 PR 描述说明改动动机、影响范围与测试方法如有关联 Issue写明Closes #编号回应评审关注维护者反馈并及时迭代AI 工具使用规范若使用 AI 工具生成较多代码请在 PR 描述中主动说明并自行仔细审查代码质量——低质量的 AI 生成 PR 可能被直接关闭。遇到环境问题怎么办端口冲突确认 3000 / 7860 / 8000 / 9200 / 5601 未被占用内存不足调大容器运行时资源Colima 8 CPU / 16GB 可流畅运行全栈彻底重置make stop make clean必要时make factory-reset恢复出厂状态恭喜你完成 OpenRAG 开发环境搭建 现在打开 CONTRIBUTING.md 对照检查一遍然后从仓库 Issue 列表中标记为新手友好的任务开始你的第一个 PR 吧。【免费下载链接】openragOpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.项目地址: https://gitcode.com/GitHub_Trending/open/openrag创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考