English Version | 中文版
GC-QA-RAG is an enterprise-grade Retrieval-Augmented Generation (RAG) system. Through our innovative Advanced QA Pre-generation Technology, we intelligently transform unstructured product documentation, community posts, and other content into high-quality Q&A knowledge bases, significantly improving retrieval accuracy and user experience.
This project has completed comprehensive open-source adaptation. Thanks to its advanced QA pre-generation technology, it can adapt to documents in almost any domain, building precise and efficient intelligent Q&A systems. We welcome you to deploy it immediately and quickly validate its effectiveness on your data. See also: English README.md
GC-QA-RAG 是一个企业级的检索增强生成（RAG）系统。我们通过创新的 高级 QA 预生成技术，将非结构化的产品文档、社区帖子等内容，智能地转化为高质量的问答知识库，显著提升了检索的精准度和用户体验。
本项目已完成全面的开源适配改造。得益于其高级 QA 预生成技术的特性，它几乎可以适配任何领域的文档，构建精准、高效的智能问答系统。欢迎你立即部署，快速验证其在你的数据上的效果。
在线体验 Demo: https://ai-assist.grapecity.com.cn/
- 🎯 精准的检索效果：独创 高级 QA 预生成技术，相比传统文本切片，能更深刻地理解文档语义，使召回内容与用户问题的匹配度更高。
- 🏢 企业级场景验证：已在葡萄城多个产品线的真实业务中落地，无缝升级了传统搜索，每日服务大量用户，获得了积极反馈。
- 🚀 开箱即用的解决方案：提供从知识库构建（ETL）、后端服务到前端界面的完整代码，并支持 Docker 一键部署，助力开发者快速搭建自己的高质量 RAG 系统。
- 📚 详尽的文档教程：提供从产品设计、技术架构到落地经验的全方位文档，不仅是开源代码，更是一套可复用的实践方法论。
为验证系统的实际效果，我们让多个主流大语言模型参与了"活字格"低代码平台的认证考试。测评采用三种模式：直接生成答案、结合知识库检索（GC-QA-RAG）、Agent 自动规划检索（基于 GC-QA-RAG）。
测评结果汇总：
| 考试科目 | 模型 | 直接生成答案 | 结合知识库检索 (RAG) | Agent 自动规划检索 | 最大提升 |
|---|---|---|---|---|---|
| 认证工程师-科目一 (基础) | Claude-4-sonnet | 65.80% | 81.03% | 88.51% | +22.71% |
| GLM-4.5 | 61.21% | 84.20% | 87.07% | +25.86% | |
| Qwen3 | 67.82% | 83.05% | 85.92% | +18.10% | |
| 认证工程师-科目二 (实践) | Claude-4-sonnet | 57.41% | 69.44% | 70.37% | +12.96% |
| GLM-4.5 | 47.22% | 64.81% | 65.74% | +18.52% | |
| Qwen3 | 51.85% | 65.74% | 68.52% | +16.67% | |
| 高级认证工程师-科目一 (高级) | Claude-4-sonnet | 52.94% | 65.88% | 74.12% | +21.18% |
| GLM-4.5 | 57.65% | 67.06% | 68.24% | +10.59% | |
| Qwen3 | 54.12% | 61.18% | 68.24% | +14.12% |
核心发现：
- Agent 模式效果最显著：在所有测试中，Agent 自动规划检索模式的得分都是最高的，最高提升达 25.86%
- RAG 技术显著提升准确率：所有模型在获得外部知识库支持后，成绩都有大幅提高
- Claude-4-sonnet 综合表现最佳：在三个科目的 Agent 模式下均取得了最高分
📖 查看完整测评报告：《让 LLM 做低代码考试，谁会胜出？》
我们强烈推荐使用 Docker 进行一键部署，这是体验本项目的最快方式。
确保你的机器已经安装了 Docker 和 Docker Compose。
第一步：获取 API 密钥
您需要准备以下 API 密钥：
- 大语言模型 API：推荐使用阿里云百炼或OpenAI API
- 嵌入模型 API：推荐使用阿里云的文本嵌入模型（目前仅支持 text-embedding-v4）
第二步：配置和部署
# 1. 克隆项目
git clone https://github.com/GrapeCity-AI/gc-qa-rag.git
cd gc-qa-rag
# 2. 编辑 ETL 配置（也可在部署后的Web端界面修改配置）
cd sources/gc-qa-rag-etl/deploy
# 编辑 docker-compose.dockerhub.yml，取消注释并填入你的API密钥：
# GC_QA_RAG_LLM_API_KEY: "your_llm_api_key_here"
# GC_QA_RAG_EMBEDDING_API_KEY: "your_embedding_api_key_here"
# 3. 启动 ETL 服务
docker compose -f docker-compose.dockerhub.yml up -d
# 4. 编辑 RAG 配置
cd sources/gc-qa-rag-server/deploy
# 编辑 docker-compose.dockerhub.yml，取消注释并填入你的API密钥：
# GC_QA_RAG_LLM_DEFAULT_API_KEY: "your_llm_api_key_here"
# GC_QA_RAG_EMBEDDING_API_KEY: "your_embedding_api_key_here"
# 5. 启动 RAG 服务
docker compose -f docker-compose.dockerhub.yml up -d# 1. 克隆项目
git clone https://github.com/GrapeCity-AI/gc-qa-rag.git
cd gc-qa-rag
# 2. 配置API密钥 (必须！)
# 编辑 sources/gc-qa-rag-etl/.config.production.json 或 .env 文件
# 编辑 sources/gc-qa-rag-server/.config.production.json 或 .env 文件
# 填入您的API密钥
# 3. 进入 ETL 目录
cd sources/gc-qa-rag-etl/deploy
# 4. 构建 ETL 镜像，并启动服务
docker compose up -d --build
# 5. 进入 RAG 目录
cd sources/gc-qa-rag-server/deploy
# 6. 构建 RAG 镜像，并启动服务
docker compose up -d --build第三步：上传数据并开始使用
-
访问 ETL 管理后台:
http://localhost:8001- 上传您的 PDF、Word、Markdown 等文档
- 等待系统处理并生成问答对
- 发布数据到知识库
-
访问 RAG 问答主页:
http://localhost:80- 基于您上传的文档内容开始提问
- 享受智能问答体验！
完整操作流程：
准备API密钥 → 配置系统 → Docker部署 → 上传文档 → ETL处理 → 发布数据 → 前端测试 → 开始使用
更加详细的部署指南，请参考《Docker 部署教程》
如果你希望深入了解每个模块的细节，或者进行二次开发，可以选择手动部署。
环境依赖:
- Python 3.13+ (及 PDM)
- Node.js 16+ (及 pnpm)
- MySQL
- Qdrant
使用官方 Docker 镜像时，需要在 docker-compose.dockerhub.yml 文件中配置环境变量传递给容器。系统支持灵活的配置优先级：
配置优先级：.saved.json 文件 > Docker 环境变量 > .env 文件 > JSON 配置文件 > 默认值
.saved.json 文件：通过前端界面修改配置时动态生成，优先级最高，确保用户修改的配置能够生效- Docker 环境变量：适合生产环境部署，通过 docker-compose 文件设置
.env 文件：适合开发环境，存储敏感信息如 API 密钥- JSON 配置文件**：基础配置模板，支持复杂的嵌套配置结构
完整的环境变量列表请查看：
重要：无论选择哪种部署方式，都需要先配置 API 密钥！
详细步骤请参考我们的《快速开始指南》。
传统的 RAG 系统严重依赖于文档的“切片”（Chunking）质量。然而，简单的文本分割方法在处理复杂的企业级文档时，往往会遭遇上下文失真、语义歧义和版本冲突等问题，导致检索效果不佳。
我们最初也尝试了“全文投喂”的直观方案——将整篇文档交给大模型直接生成 QA 对。但实践证明，这条路充满陷阱：
- 对于短文档：模型缺乏足够上下文，极易“过度联想”，编造出原文不存在的信息。
- 对于长文档：模型存在“注意力天花板”，往往只能生成 10-15 个 QA 对，导致大量关键知识点被遗漏，或生成重复、泛化的内容。
为了从根本上解决这些问题，我们摒弃了粗糙的文本切片，设计了一套自适应、多阶段的高级 QA 预生成系统。其核心思想是：从“切割文本”转向“精准提炼知识点”。
这套系统主要通过以下创新机制实现：
我们不采用一刀切的方式，而是根据文档长短动态调整策略：
- 短文档 - 句子级精准控制：我们假设“一个句子对应一个知识点”，通过计算句子数量来动态指示模型生成等量的 QA 对，杜绝信息编造，确保内容忠于原文。
- 长文档 - 两阶段记忆-聚焦机制：我们独创了这种对话式生成方法。
- 第一阶段（记忆）：让大模型“记住”全文，构建完整的上下文背景（长期记忆）。
- 第二阶段（聚焦）：逐个片段提问，引导模型“聚焦”于局部细节进行精准的 QA 提取（短期专注）。 这种机制完美解决了长文档的信息覆盖度和生成质量问题。
所谓的“高级”之处不止于此。在生成核心 QA 的同时，系统还智能地派生出三种高价值数据，并一同存入向量数据库，极大增强了 RAG 系统的综合能力：
- ① 摘要 (Summary)：为每个知识点生成总结，提升生成时的上下文理解能力，利于大模型向用户推荐适合的关联文档。
- ② 扩充答案 (Full Answer)：为关键问题生成更详尽的解答，用于前端“展开更多”或作为生成答案时的丰富素材。
- ③ 同义问法 (Question Variants)：为每个问题生成多种相似问法，大幅提升对用户多样化提问的召回率。
我们为这套系统构建了完整的工程化保障，包括：自动化的文档解析、针对中文的自动分句、灵活的文本分组，以及最关键的多重容错 JSON 解析机制（从标准提取到强制转换，再到正则匹配），确保了在生产环境中几乎 100% 的生成成功率（失败时多为触发了内容合规机制）。
综上所述，GC-QA-RAG 的核心理念是：通过模拟人类“记忆-聚焦”的学习方式和精密的工程化设计，将非结构化文档智能地转化为结构化的、多维度的高质量知识库，为下游的精准检索和高质量回答奠定坚实基础。
本系统采用模块化设计，分为三大核心层：
- 构建层 (ETL): 负责从各种数据源（文档、网页、论坛）提取信息，通过 QA 生成 和 向量化，构建高质量的知识库。
- 检索层 (Retrieval): 接收用户查询，通过 问题改写、混合检索 和 RRF 排序，高效、精准地从知识库中召回最相关的信息。
- 生成层 (Generation): 将检索到的信息整合，交由大语言模型（LLM）生成最终流畅、准确的答案，并支持多轮对话。
更多细节请查阅《技术架构详解》。
我们为你准备了完整的项目文档，帮助你深入了解从背景、设计到实践的每一个环节。
访问我们的文档站：https://grapecity-ai.github.io/gc-qa-rag/
主要内容包括：
我们欢迎并鼓励社区参与贡献！无论是提交 Bug、提出功能建议，还是贡献代码，都对我们非常有价值。
![@github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=64&v=4){kind=small}