快速开始
1. 各模块简介
-
gc-qa-rag-etl
用于知识库数据的采集、处理和向量化（ETL 流程），支持多种数据源和嵌入模型。包含 Web 管理界面，方便上传和处理文档。 -
gc-qa-rag-server
基于 FastAPI 的后端服务，提供语义检索、问答、推理等 API，集成向量数据库（Qdrant）和关系数据库（MySQL）。 -
gc-qa-rag-frontend
前端界面，基于 React + Ant Design，提供智能问答、搜索等功能。
2. 环境准备
通用要求
- 推荐操作系统：Windows 10/11 或 Linux
- 推荐 IDE：Visual Studio Code
依赖工具
- Python 3.13
- Node.js 18+、pnpm
- PDM（Python 包管理工具）
- Docker（可选，推荐用于生产部署）
- MySQL 8+
- Qdrant
3. 重要提醒：配置优先于部署 ⚠️
在开始任何部署之前，您必须先配置 API 密钥！
系统依赖大语言模型和嵌入模型提供服务，没有正确的 API 配置，部署后的系统将无法正常工作。密钥若有变更，需重启服务。
获取必要的 API 密钥
您需要准备以下 API 密钥：
-
大语言模型 API（任选其一）：
- 阿里云百炼平台：https://bailian.console.aliyun.com/
- OpenAI API：https://platform.openai.com/
- 其他兼容 OpenAI 格式的模型服务
-
嵌入模型 API：
- 推荐使用阿里云的文本嵌入模型（代码中默认使用 text-embedding-v4）
4. 部署步骤
4.1 最简单的方式：Docker 一键部署（推荐新手）
第一步：配置 API 密钥
在部署前，请按以下方式配置：
# 1. 克隆项目
git clone https://github.com/GrapeCity-AI/gc-qa-rag.git
cd gc-qa-rag
# 2. 配置ETL模块
# 编辑 sources/gc-qa-rag-etl/.config.production.json
# 填入您的API密钥
# 3. 配置服务端
# 编辑 sources/gc-qa-rag-server/.config.production.json
# 填入您的API密钥
第二步：一键部署
# 进入部署目录
cd sources/gc-qa-rag-server/deploy
# 启动核心服务（MySQL、Qdrant、后端、前端）
docker compose up -d --build
# 启动ETL服务
cd ../../gc-qa-rag-etl
docker build -t rag-etl:latest .
docker run -d --name rag-etl -p 8001:8001 -e GC_QA_RAG_ENV=production rag-etl:latest
第三步：上传数据并测试
- 访问 ETL 管理后台：http://localhost:8001
- 上传您的文档（PDF、Word、Markdown 等）
- 等待系统处理文档并生成问答对
- 将数据发布到知识库
- 访问前端界面：http://localhost:80
- 开始提问测试！
完整使用流程图：
配置API密钥 → Docker部署 → 上传文档 → ETL处理 → 发布数据 → 前端测试
4.2 手动部署各模块
如果您想深入了解各模块或进行开发，可以选择手动部署：
4.2.1 gc-qa-rag-etl
安装依赖
# 进入目录
cd sources/gc-qa-rag-etl
# 安装依赖
pdm install
配置环境（必须）
- 重要：修改
.config.development.json或.config.production.json，填写 LLM、Embedding、Qdrant 等服务的 API Key 和地址。
启动 ETL 管理服务
# 启动Web管理界面
pdm run server
# 访问 http://localhost:8001 进行文档上传和处理
命令行方式运行 ETL 流程
# 转换通用文档到文本文件
pdm run das
# 生成QA对并构建向量
pdm run etl
# 发布向量到知识库
pdm run ved
4.2.2 gc-qa-rag-server
安装依赖
cd sources/gc-qa-rag-server
pdm install
配置环境（必须）
- 重要：修改
.config.development.json或.config.production.json，配置数据库、Qdrant、LLM 等信息。
启动服务
# 开发模式
pdm run dev
# 生产模式
pdm run start
- 访问地址：
http://localhost:8000
Docker 部署
docker build -t rag-server .
docker run -p 8000:8000 rag-server
4.2.3 gc-qa-rag-frontend
安装依赖
cd sources/gc-qa-rag-frontend
pnpm install
本地开发
pnpm run dev
构建生产包
pnpm run build
Docker 部署
docker build -t rag-frontend .
docker run -p 80:80 rag-frontend
5. 新手完整操作指南
如果您是完全陌生的用户，建议严格按照以下顺序操作：
第一阶段：准备工作
- ✅ 确保 Docker 已安装
- ✅ 获取大语言模型 API 密钥
- ✅ 克隆项目到本地
第二阶段：配置系统
- ✅ 配置 ETL 模块的 API 密钥
- ✅ 配置服务端的 API 密钥
- ✅ 检查配置文件格式正确
第三阶段：部署服务
- ✅ 执行 Docker 一键部署命令
- ✅ 验证所有容器正常启动
- ✅ 检查服务是否可访问
第四阶段：添加数据
- ✅ 访问 ETL 管理界面 (http://localhost:8001)
- ✅ 上传测试文档
- ✅ 等待 ETL 处理完成
- ✅ 发布数据到知识库
第五阶段：测试使用
- ✅ 访问前端界面 (http://localhost:80)
- ✅ 基于上传的文档内容提问
- ✅ 验证系统回答质量
- ✅ 开始正式使用！
6. 常见问题与解决办法
- 部署后服务无响应：首先检查 API Key 是否正确配置，查看 Docker 日志排查错误。
- 前端无法获取答案：确认向量数据库中有数据，需要先通过 ETL 上传和处理文档。
- ETL 处理失败：检查文档格式是否支持，API 密钥是否有效。
- 端口冲突：确保 8000（后端）、80（前端）、8001（ETL）、3306（MySQL）、6333（Qdrant）未被占用。
- 依赖安装失败：检查 Python、Node.js、PDM、pnpm 版本，建议使用官方推荐版本。
- 数据库连接失败：确认 MySQL/Qdrant 配置正确，容器网络互通。
- DAS 配置疑问：DAS 是数据采集系统（爬虫），如果您只想上传本地文档，可以暂时留空。
如需详细参数说明或遇到其他问题，请查阅各模块的 README.md 或查看Docker 部署教程的详细说明。