RAGFlow GraphRAG 知识库问答与 AI 编排流实践指南

核心镜像约 9 GB，拉取时间视网络环境而定。启动后检查日志：

docker logs -f ragflow-server

出现成功提示后，浏览器访问 http://IP_OF_YOUR_MACHINE（默认端口 80）。首次登录前需在 service_conf.yaml 中配置 user_default_llm 及对应的 API Key。

系统配置详解

RAGFlow 的配置主要涉及三个文件：

1. .env：存放基础环境变量，如 SVR_HTTP_PORT、MYSQL_PASSWORD、MINIO_PASSWORD 等。
2. service_conf.yaml：配置后台服务连接信息、LLM 工厂及中间件参数。
3. docker-compose-CN.yml：定义容器编排规则。

务必确保 .env 中的变量值与 service_conf.yaml 保持一致。所有配置修改后需重启服务：

docker compose -f docker-compose-CN.yml up -d

如需修改 HTTP 端口，可在 docker-compose-CN.yml 中将 80:80 改为自定义映射（如 8080:80）。

源码编译与安装

如需从源码构建镜像或调试底层逻辑，请按以下步骤操作：

1. 克隆仓库并进入目录：

   git clone https://github.com/infiniflow/ragflow.git
   cd ragflow/
   

2. 创建虚拟环境：

   conda create -n ragflow python=3.11.0
   conda activate ragflow
   pip install -r requirements.txt
   

   若 CUDA 版本大于 12.0，需额外安装适配的 onnxruntime-gpu：

   pip uninstall -y onnxruntime-gpu
   pip install onnxruntime-gpu --extra-index-url https://aiinfra.pkgs.visualstudio.com/PublicPackages/_packaging/onnxruntime-cuda-12/pypi/simple/
   

3. 配置入口脚本： 复制 docker/entrypoint.sh 至当前目录，编辑 PY 和 PYTHONPATH 路径：

   cp docker/entrypoint.sh .
   vi entrypoint.sh
   

   获取 Python 路径：which python；获取项目路径：pwd。
4. 启动基础服务：

   cd docker
   docker compose -f docker-compose-base.yml up -d
   

5. 验证配置一致性： 检查 docker/.env 与 conf/service_conf.yaml 中的 IP 地址及端口是否匹配本机实际配置。
6. 启动主服务：

   chmod +x ./entrypoint.sh
   bash ./entrypoint.sh
   

7. 部署 WebUI： 按照控制台指引完成前端服务的部署与访问。

模型接入与管理

RAGFlow 支持多种大语言模型接入方式，满足不同场景需求。

商业模型接入

支持主流商业大模型厂商，需配置相应的 API Key。建议在生产环境中将密钥存储在安全的位置，避免硬编码。

本地模型部署

• Ollama：适用于轻量级本地模型运行，支持快速部署。
• Xinference：适合企业级私有化部署，提供丰富的模型管理功能。

知识库构建与 GraphRAG

分块模板说明

RAGFlow 提供多种文档解析模板，以适应不同数据结构：

GraphRAG 分块机制

启用'Knowledge Graph'模式后，系统将执行以下流程：

1. 文本切分：将文档切分为约 512 token 的块。
2. 图谱提取：调用 LLM 识别块内的实体（节点）与关系（边）。
3. 图谱构建：整合所有块的图谱信息，形成全局知识网络。
4. 检索增强：查询时不仅匹配文本相似度，还利用图谱关系进行推理。

Embedding 模型支持

内置多种开源 Embedding 模型，可根据语言环境选择：

• BAAI/bge-large-zh-v1.5 (中文)
• jinaai/jina-embeddings-v2-base-en (英文)
• sentence-transformers/all-MiniLM-L6-v2 (通用)

智能问答与 AI 编排

通过 Agent 模块，用户可以组合多个工具与知识库，构建自动化工作流。例如，HR 招聘助手可以自动解析简历、匹配岗位并生成面试评价。

编排流设计

1. 触发器：设定事件或定时任务。
2. 节点选择：集成知识库检索、API 调用、代码执行等节点。
3. 逻辑控制：支持条件分支与循环。
4. 输出格式化：自定义最终返回结果的结构。

常见问题与故障排查

资源不足导致 ES 卡死

Elasticsearch 默认占用较多内存。若遇到索引构建卡顿，需调整 .env 中的 MEM_LIMIT。

# 根据物理内存调整，建议设置为总内存的 70%-80%
MEM_LIMIT=72864896288

磁盘空间不足

若系统盘使用率超过 95%，可能导致写入失败。错误日志通常显示 no_shard_available_action_exception。 解决方案：迁移 Docker 存储路径至大容量分区。

1. 停止容器。
2. 修改 Docker 配置 daemon.json 指向新路径。
3. 迁移现有数据目录。
4. 重启 Docker 服务。

网络异常

启动后浏览器提示 network abnormal，通常是因为后端服务未完全就绪。请等待 docker logs 输出稳定后再访问。

生产环境最佳实践

安全性加固

• API Key 管理：使用环境变量或密钥管理服务（如 Vault），禁止明文存储。
• 网络隔离：将数据库与向量库置于内网，仅开放必要的 API 端口。
• 访问控制：启用 RBAC 权限管理，限制敏感知识库的访问范围。

性能调优

• 向量索引：根据数据量选择合适的索引类型（HNSW vs Flat）。
• 并发处理：调整 Worker 数量以平衡 CPU 负载与响应速度。
• 缓存策略：开启 Redis 缓存热点查询结果，减少重复计算。

监控与日志

建议接入 Prometheus + Grafana 监控集群状态，定期清理过期日志以防磁盘爆满。同时，记录用户查询日志以便分析检索效果与优化 Prompt。

通过上述配置与实践，RAGFlow 能够为企业提供一个稳定、高效且可解释的 AI 知识库解决方案，有效支撑复杂业务场景下的智能化需求。