金大哥 - flexible-graphrag MCP 详情

article

README

🚀 灵活图增强检索生成平台（Flexible GraphRAG）

灵活图增强检索生成平台（Flexible GraphRAG） 是一个支持文档处理、知识图谱自动构建、检索增强生成（RAG）和图增强检索生成（GraphRAG）设置、混合搜索（全文、向量、图）以及人工智能问答查询功能的平台。

灵活图增强检索生成平台的人工智能聊天界面，展示了从网页数据源生成并在Neo4j中显示的图

🚀 快速开始

灵活图增强检索生成平台是一个可配置的混合搜索系统，它可以选择性地结合向量相似度搜索、全文搜索以及对来自多个数据源（文件上传、云存储、企业仓库、网络源）处理后的文档进行知识图谱图增强检索生成。它基于LlamaIndex构建，该框架提供了抽象层，支持多种向量、搜索图数据库和大语言模型。文档可以使用Docling（默认）或LlamaParse（云API）进行解析。它既有带有REST端点的FastAPI后端，也有用于像Claude Desktop等MCP客户端的模型上下文协议（MCP）服务器。此外，还提供了简单的Angular、React和Vue UI客户端（使用FastAPI后端的REST API），用于与系统进行交互。

✨ 主要特性

混合搜索：结合向量嵌入、BM25全文搜索和图遍历，实现全面的文档检索。
知识图谱图增强检索生成：从文档中提取实体和关系，在图数据库中创建图，以进行基于图的推理。
可配置架构：LlamaIndex为向量数据库、图数据库、搜索引擎和大语言模型提供商提供了抽象层。
多源摄入：使用Docling或LlamaParse文档解析器处理来自13个数据源（文件上传、云存储、企业仓库、网络源）的文档。
带有REST API的FastAPI服务器：提供用于文档摄入、混合搜索和人工智能问答查询的REST API。
MCP服务器：为Claude Desktop等MCP客户端提供工具，用于文档和文本摄入、混合搜索和人工智能问答查询。
UI客户端：Angular、React和Vue UI客户端支持选择数据源（文件系统、Alfresco、CMIS等）、摄入文档、执行混合搜索和人工智能问答查询。
Docker部署灵活性：支持独立部署和Docker部署模式。Docker基础设施通过docker-compose提供模块化数据库选择，包括向量、图和搜索数据库可以通过单行注释进行包含或排除。可以选择混合部署（数据库在Docker中，后端和UI独立）或完全容器化。

💻 使用示例

基础用法

以下是使用FastAPI后端启动服务的示例代码：

cd flexible-graphrag
uv run start.py

高级用法

如果你想使用Docker进行部署，可以参考以下步骤：

# 仅部署你需要的数据库
docker-compose -f docker/docker-compose.yaml -p flexible-graphrag up -d

# 在docker-compose.yaml中注释掉你不需要的服务：
# - includes/neo4j.yaml          # 如果你使用自己的Neo4j，请注释掉
# - includes/kuzu.yaml           # 如果你不使用Kuzu，请注释掉
# - includes/qdrant.yaml         # 如果你使用Neo4j、Elasticsearch或OpenSearch进行向量搜索，请注释掉
# - includes/elasticsearch.yaml  # 如果你不使用Elasticsearch，请注释掉
# - includes/elasticsearch-dev.yaml  # 如果你不使用Elasticsearch，请注释掉
# - includes/kibana.yaml         # 如果你不使用Elasticsearch，请注释掉
# - includes/opensearch.yaml     # 如果你不使用，请注释掉
# - includes/alfresco.yaml       # 如果你想使用自己安装的Alfresco，请注释掉
# - includes/app-stack.yaml      # 如果你想将后端和UI放在Docker中，请取消注释
# - includes/proxy.yaml          # 如果你想将后端和UI放在Docker中，请取消注释
#   (注意：app-stack.yaml中有环境配置，可以使用它来定制向量、图、搜索和大语言模型)

# 在Docker外部运行后端和UI客户端
cd flexible-graphrag
uv run start.py

📚 详细文档

前端截图

Angular前端 - 标签式界面

点击查看Angular UI截图（浅色主题）

| 数据源标签 | 处理标签 | 搜索标签 | 聊天标签 | |-------------|----------------|------------|----------| | | | | |

React前端 - 标签式界面

点击查看React UI截图（深色主题）

| 数据源标签 | 处理标签 | 搜索标签 | 聊天标签 | |-------------|----------------|------------|----------| | | | | |

点击查看React UI截图（浅色主题）

| 数据源标签 | 处理标签 | 搜索标签 | 聊天标签 | |-------------|----------------|------------|----------| | | | | |

Vue前端 - 标签式界面

点击查看Vue UI截图（浅色主题）

| 数据源标签 | 处理标签 | 搜索标签 | 聊天标签 | |-------------|----------------|------------|----------| | | | | |

系统组件

FastAPI后端 (`/flexible-graphrag`)

REST API服务器：提供用于文档摄入、搜索和问答的端点。
混合搜索引擎：结合向量相似度、BM25和图遍历。
文档处理：通过集成Docling实现高级文档转换。
可配置架构：基于环境的所有组件配置。
异步处理：后台任务处理，提供实时进度更新。

MCP服务器 (`/flexible-graphrag-mcp`)

Claude Desktop集成：用于人工智能助手工作流程的模型上下文协议服务器。
双传输模式：HTTP模式用于调试，stdio模式用于Claude Desktop。
工具套件：提供9个用于文档处理、搜索和系统管理的专用工具。
多种安装方式：pipx系统安装或uvx免安装执行。

UI客户端 (`/flexible-graphrag-ui`)

Angular前端：采用Material Design和TypeScript。
React前端：使用现代React、Vite和TypeScript。
Vue前端：采用Vue 3组合式API、Vuetify和TypeScript。
统一功能：所有客户端都支持异步处理、进度跟踪和取消操作。

Docker基础设施 (`/docker`)

模块化数据库选择：通过单行注释包含或排除向量、图和搜索数据库。
灵活部署：混合模式（数据库在Docker中，应用程序独立）或完全容器化。
NGINX反向代理：通过适当的路由统一访问所有服务。
数据库仪表盘：集成了Kibana（Elasticsearch）、OpenSearch Dashboards、Neo4j Browser和Kuzu Explorer的Web界面。

数据源

灵活图增强检索生成平台支持13种不同的数据源，用于将文档摄入到知识库中：

文件与上传源

文件上传 - 通过支持拖放的Web界面直接上传文件

云存储源

Amazon S3 - 集成AWS S3存储桶
Google Cloud Storage (GCS) - 谷歌云存储桶
Azure Blob Storage - 微软Azure blob容器
OneDrive - 微软OneDrive个人/商业存储
SharePoint - 微软SharePoint文档库
Box - Box.com云存储
Google Drive - 谷歌云端硬盘文件存储

企业仓库源

CMIS (内容管理互操作性服务) - 行业标准的内容仓库接口
Alfresco - Alfresco企业内容管理/内容仓库

网络源

网页 - 从网页URL提取内容
维基百科 - 通过标题或URL摄入维基百科文章
YouTube - 处理YouTube视频字幕

每个数据源都包括：

配置表单：易于使用的凭据和设置界面
进度跟踪：实时的每个文件进度指示器
灵活认证：支持各种认证方法（API密钥、OAuth、服务账户）

文档处理选项

所有数据源都支持两种文档解析器选项：

Docling（默认）：

开源，本地处理
免费，无API费用
内置OCR，用于处理图像和扫描文档
通过以下方式配置：DOCUMENT_PARSER=docling

LlamaParse：

基于云的API服务，具有先进的人工智能
使用Claude Sonnet 3.5进行多模态解析
提供三种模式：
- parse_page_without_llm - 每页1个信用点
- parse_page_with_llm - 每页3个信用点（默认）
- parse_page_with_agent - 每页10 - 90个信用点
通过以下方式配置：DOCUMENT_PARSER=llamaparse + LLAMAPARSE_API_KEY
从LlamaCloud获取API密钥

两种解析器都支持PDF、办公文档（DOCX、XLSX、PPTX）、图像、HTML等，并具有智能格式检测功能。

支持的文件格式

系统通过在Docling（高级处理）和直接文本处理之间进行智能路由，处理15种以上的文档格式：

文档格式（Docling处理）

PDF：.pdf - 高级布局分析、表格提取、公式识别
微软办公文档：.docx, .xlsx, .pptx - 完整保留结构并提取内容
网页格式：.html, .htm, .xhtml - 标记结构分析
数据格式：.csv, .xml, .json - 结构化数据处理
文档格式：.asciidoc, .adoc - 保留标记的技术文档

图像格式（Docling OCR）

标准图像：.png, .jpg, .jpeg - OCR文本提取
专业图像：.tiff, .tif, .bmp, .webp - 支持布局的OCR处理

文本格式（直接处理）

纯文本：.txt - 直接摄入，以实现最佳分块
Markdown：.md, .markdown - 保留技术文档的格式

处理智能性

自适应输出：表格转换为Markdown，文本内容转换为纯文本，以实现最佳实体提取
格式检测：根据文件扩展名和内容分析自动路由
回退处理：对不支持的格式进行优雅降级

数据库配置

灵活图增强检索生成平台使用三种类型的数据库来实现其混合搜索功能。每个数据库都可以通过环境变量独立配置。

搜索数据库（全文搜索）

配置：通过SEARCH_DB和SEARCH_DB_CONFIG环境变量进行设置

BM25（内置）：基于本地文件的BM25全文搜索，使用TF-IDF排名
- 仪表盘：无（基于文件）
- 配置：
```
SEARCH_DB=bm25
SEARCH_DB_CONFIG={"persist_dir": "./bm25_index"}
```
- 适用于：开发、小数据集、简单部署
Elasticsearch：企业级搜索引擎，具有高级分析器、分面搜索和实时分析功能
- 仪表盘：Kibana（http://localhost:5601），用于搜索分析、索引管理和查询调试
- 配置：
```
SEARCH_DB=elasticsearch
SEARCH_DB_CONFIG={"hosts": ["http://localhost:9200"], "index_name": "hybrid_search"}
```
- 适用于：需要复杂文本处理的生产工作负载
OpenSearch：由AWS主导的开源分支，具有原生混合评分（向量 + BM25）和k-NN算法
- 仪表盘：OpenSearch Dashboards（http://localhost:5601），用于集群监控和搜索管道管理
- 配置：
```
SEARCH_DB=opensearch
SEARCH_DB_CONFIG={"hosts": ["http://localhost:9201"], "index_name": "hybrid_search"}
```
- 适用于：具有强大社区支持的经济高效的替代方案
无：禁用全文搜索（仅向量搜索）
- 配置：
```
SEARCH_DB=none
```

向量数据库（语义搜索）

配置：通过VECTOR_DB和VECTOR_DB_CONFIG环境变量进行设置

⚠️ 向量维度兼容性

关键：在不同的嵌入模型之间切换时（例如，OpenAI ↔ Ollama），由于维度不兼容，您必须删除现有的向量索引：

OpenAI：1536维（text-embedding-3-small）或3072维（text-embedding-3-large）
Ollama：384维（all-minilm，默认）、768维（nomic-embed-text）或1024维（mxbai-embed-large）
Azure OpenAI：与OpenAI相同（1536或3072维）

有关每个数据库的详细清理说明，请参阅VECTOR-DIMENSIONS.md。

支持的向量数据库

Neo4j：可以作为向量数据库使用，需要单独的向量配置
- 仪表盘：Neo4j Browser（http://localhost:7474），用于Cypher查询和图可视化
- 配置：
```
VECTOR_DB=neo4j
VECTOR_DB_CONFIG={"uri": "bolt://localhost:7687", "username": "neo4j", "password": "your_password", "index_name": "hybrid_search_vector"}
```
Qdrant：专用向量数据库，具有高级过滤功能
- 仪表盘：Qdrant Web UI（http://localhost:6333/dashboard），用于集合管理
- 配置：
```
VECTOR_DB=qdrant
VECTOR_DB_CONFIG={"host": "localhost", "port": 6333, "collection_name": "hybrid_search"}
```
Elasticsearch：可以作为向量数据库使用，需要单独的向量配置
- 仪表盘：Kibana（http://localhost:5601），用于索引管理和数据可视化
- 配置：
```
VECTOR_DB=elasticsearch
VECTOR_DB_CONFIG={"hosts": ["http://localhost:9200"], "index_name": "hybrid_search_vectors"}
```
OpenSearch：可以作为向量数据库使用，需要单独的向量配置
- 仪表盘：OpenSearch Dashboards（http://localhost:5601），用于集群和索引管理
- 配置：
```
VECTOR_DB=opensearch
VECTOR_DB_CONFIG={"hosts": ["http://localhost:9201"], "index_name": "hybrid_search_vectors"}
```

Chroma：开源向量数据库，具有双部署模式

仪表盘：Swagger UI（http://localhost:8001/docs/），用于API测试和管理（HTTP模式）

配置（本地模式）：

VECTOR_DB=chroma
VECTOR_DB_CONFIG={"persist_directory": "./chroma_db", "collection_name": "hybrid_search"}

配置（HTTP模式）：

VECTOR_DB=chroma
VECTOR_DB_CONFIG={"host": "localhost", "port": 8001, "collection_name": "hybrid_search"}

Milvus：云原生、可扩展的向量数据库，用于相似度搜索
- 仪表盘：Attu（http://localhost:3003），用于集群和集合管理
- 配置：
```
VECTOR_DB=milvus
VECTOR_DB_CONFIG={"uri": "http://localhost:19530", "collection_name": "hybrid_search"}
```
Weaviate：具有语义能力和数据丰富功能的向量搜索引擎
- 仪表盘：Weaviate Console（http://localhost:8081/console），用于模式和数据管理
- 配置：
```
VECTOR_DB=weaviate
VECTOR_DB_CONFIG={"url": "http://localhost:8081", "index_name": "HybridSearch"}
```
Pinecone：托管向量数据库服务，针对实时应用程序进行了优化
- 仪表盘：Pinecone Console（基于Web），用于索引和命名空间管理
- 本地信息仪表盘：http://localhost:3004（使用Docker时）
- 配置：
```
VECTOR_DB=pinecone
VECTOR_DB_CONFIG={"api_key": "your_api_key", "region": "us-east-1", "cloud": "aws", "index_name": "hybrid-search"}
```
PostgreSQL：传统数据库，带有pgvector扩展，用于向量相似度搜索
- 仪表盘：pgAdmin（http://localhost:5050），用于数据库管理、向量查询和相似度搜索
- 配置：
```
VECTOR_DB=postgres
VECTOR_DB_CONFIG={"host": "localhost", "port": 5433, "database": "postgres", "username": "postgres", "password": "your_password"}
```
LanceDB：现代、轻量级向量数据库，专为高性能机器学习应用程序设计
- 仪表盘：LanceDB Viewer（http://localhost:3005），用于CRUD操作和数据管理
- 配置：
```
VECTOR_DB=lancedb
VECTOR_DB_CONFIG={"uri": "./lancedb", "table_name": "hybrid_search"}
```

无图增强检索生成的RAG

对于不进行知识图谱提取的更简单部署，配置如下：

VECTOR_DB=qdrant  # 任何向量存储
SEARCH_DB=elasticsearch  # 任何搜索引擎
GRAPH_DB=none
ENABLE_KNOWLEDGE_GRAPH=false

结果：

向量相似度搜索（语义）
全文搜索（基于关键字）
无图遍历
更快的处理速度（无图提取）

图数据库（知识图谱 / 图增强检索生成）

配置：通过GRAPH_DB和GRAPH_DB_CONFIG环境变量进行设置

Neo4j属性图：主要的知识图谱存储，支持Cypher查询
- 仪表盘：Neo4j Browser（http://localhost:7474），用于图探索和查询执行
- 配置：
```
GRAPH_DB=neo4j
GRAPH_DB_CONFIG={"uri": "bolt://localhost:7687", "username": "neo4j", "password": "your_password"}
```
Kuzu：嵌入式图数据库，专为查询速度和可扩展性而构建，针对处理非常大型图数据库上的复杂分析工作负载进行了优化。支持属性图数据模型和Cypher查询语言
- 仪表盘：Kuzu Explorer（http://localhost:8002），用于图可视化和Cypher查询
- 配置：
```
GRAPH_DB=kuzu
GRAPH_DB_CONFIG={"db_path": "./kuzu_db", "use_structured_schema": true, "use_vector_index": true}
```
FalkorDB：“一个超级快速的图数据库，在底层使用GraphBLAS进行稀疏邻接矩阵图表示。我们的目标是为大语言模型提供最佳的知识图谱（图增强检索生成）。”
- 仪表盘：FalkorDB Browser（http://localhost:3001）（从灵活图增强检索生成平台的Vue前端使用的3000端口迁移而来）
- 配置：
```
GRAPH_DB=falkordb
GRAPH_DB_CONFIG={"url": "falkor://localhost:6379", "database": "falkor"}
```
ArcadeDB：多模型数据库，支持图、文档、键值和搜索功能，支持SQL和Cypher查询
- 仪表盘：ArcadeDB Studio（http://localhost:2480），用于图可视化、SQL/Cypher查询和数据库管理
- 配置：
```
GRAPH_DB=arcadedb
GRAPH_DB_CONFIG={"host": "localhost", "port": 2480, "username": "root", "password": "password", "database": "flexible_graphrag", "query_language": "sql"}
```
MemGraph：实时图数据库，原生支持流数据和高级图算法
- 仪表盘：MemGraph Lab（http://localhost:3002），用于图可视化和Cypher查询
- 配置：
```
GRAPH_DB=memgraph
GRAPH_DB_CONFIG={"url": "bolt://localhost:7687", "username": "", "password": ""}
```
NebulaGraph：分布式图数据库，专为大规模数据设计，具有水平可扩展性
- 仪表盘：NebulaGraph Studio（http://localhost:7001），用于图探索和nGQL查询
- 配置：
```
GRAPH_DB=nebula
GRAPH_DB_CONFIG={"space": "flexible_graphrag", "host": "localhost", "port": 9669, "username": "root", "password": "nebula"}
```
Amazon Neptune：完全托管的图数据库服务，支持属性图和RDF模型
- 仪表盘：Graph-Explorer（http://localhost:3007），用于可视化图探索，或Neptune Workbench（AWS控制台），用于基于Jupyter的查询
- 配置：
```
GRAPH_DB=neptune
GRAPH_DB_CONFIG={"host": "your-cluster.region.neptune.amazonaws.com", "port": 8182}
```
Amazon Neptune Analytics：无服务器图分析引擎，用于大规模图分析，支持openCypher
- 仪表盘：Graph-Explorer（http://localhost:3007）或Neptune Workbench（AWS控制台）
- 配置：
```
GRAPH_DB=neptune_analytics
GRAPH_DB_CONFIG={"graph_identifier": "g-xxxxx", "region": "us-east-1"}
```
无：禁用知识图谱提取，仅使用RAG模式
- 配置：
```
GRAPH_DB=none
ENABLE_KNOWLEDGE_GRAPH=false
```
- 当您只需要向量 + 全文搜索而不需要图遍历时使用

大语言模型配置

配置：通过LLM_PROVIDER和特定于提供商的环境变量进行设置

大语言模型提供商

OpenAI：GPT模型，具有可配置的端点
- 配置：
```
USE_OPENAI=true
LLM_PROVIDER=openai
OPENAI_API_KEY=your_api_key_here
OPENAI_MODEL=gpt-4o-mini
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
```
- 模型：gpt-4o-mini（默认）、gpt-4o、gpt-4-turbo、gpt-3.5-turbo
- 嵌入模型：text-embedding-3-small（1536维，默认）、text-embedding-3-large（3072维）
Ollama：本地大语言模型部署，注重隐私和控制
- 配置：
```
USE_OPENAI=false
LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3.2:latest
OLLAMA_EMBEDDING_MODEL=all-minilm
```
- 模型：llama3.2:latest（默认）、llama3.1:8b、gpt-oss:20b、qwen2.5:latest
- 嵌入模型：all-minilm（384维，默认）、nomic-embed-text（768维）、mxbai-embed-large（1024维）

Azure OpenAI：企业级OpenAI集成

配置：（未测试 - 可能需要更改配置代码）

LLM_PROVIDER=azure
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
AZURE_OPENAI_API_KEY=your_api_key_here
AZURE_OPENAI_DEPLOYMENT=your_deployment_name
AZURE_OPENAI_EMBEDDING_DEPLOYMENT=your_embedding_deployment
AZURE_OPENAI_API_VERSION=2024-02-15-preview

Anthropic Claude：Claude模型，用于复杂推理
- 配置：（未测试 - 可能需要更改配置代码）
```
LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=your_api_key_here
ANTHROPIC_MODEL=claude-3-sonnet-20240229
```
Google Gemini：谷歌最新的语言模型
- 配置：（未测试 - 可能需要更改配置代码）
```
LLM_PROVIDER=gemini
GOOGLE_API_KEY=your_api_key_here
GEMINI_MODEL=gemini-pro
```

大语言模型性能建议

使用LlamaIndex时OpenAI与Ollama的一般性能比较

根据对OpenAI GPT-4o-mini和Ollama模型（llama3.1:8b、llama3.2:latest、gpt-oss:20b）的测试，在LlamaIndex操作中，OpenAI始终优于Ollama模型。

Ollama配置

当使用Ollama作为大语言模型提供商时，您必须在启动Ollama服务之前配置系统范围的环境变量。这些设置可以优化性能并启用并行处理。

关键要求：

系统范围配置环境变量（不在Flexible GraphRAG的.env文件中）
OLLAMA_NUM_PARALLEL=4对于并行文档处理至关重要
更改环境变量后，始终重新启动Ollama服务

有关完整的设置说明，请参阅docs/OLLAMA-CONFIGURATION.md，包括：

所有环境变量配置
特定平台的安装步骤（Windows、Linux、macOS）
性能优化指南
常见问题排查

MCP工具（适用于Claude Desktop等MCP客户端）

MCP服务器为文档智能工作流程提供了9个专用工具：

| 工具 | 用途 | 使用方法 | |------|---------|-------| | get_system_status() | 系统健康和配置 | 验证设置和数据库连接 | | ingest_documents(data_source, paths) | 批量文档处理 | 处理来自文件系统、CMIS、Alfresco的文件/文件夹 | | ingest_text(content, source_name) | 自定义文本分析 | 分析特定的文本内容 | | search_documents(query, top_k) | 混合文档检索 | 查找相关的文档摘录 | | query_documents(query, top_k) | 人工智能问答 | 从文档语料库中生成答案 | | test_with_sample() | 系统验证 | 使用示例内容进行快速测试 | | check_processing_status(id) | 异步操作监控 | 跟踪长时间运行的摄入任务 | | get_python_info() | 环境诊断 | 调试Python环境问题 | | health_check() | 后端连接性 | 验证API服务器连接 |

客户端支持

Claude Desktop和其他MCP客户端：通过stdio传输进行原生MCP集成
MCP Inspector：通过HTTP传输进行调试和开发
多种安装方式：pipx（系统范围）或uvx（免安装）选项

🔧 技术细节

技术实现

系统结合了三种检索方法，实现全面的混合搜索：

向量相似度搜索：使用嵌入来查找语义相似的内容，基于含义而非精确的单词匹配。
全文搜索：基于关键字的搜索，使用：
- 搜索引擎：Elasticsearch或OpenSearch（实现BM25算法）
- 内置选项：LlamaIndex的本地BM25实现，适用于更简单的部署。
图遍历：利用知识图谱查找相关实体和关系，实现图增强检索生成（GraphRAG），通过实体连接和语义关系揭示上下文相关信息。

图增强检索生成的工作原理：系统从文档中提取实体（人物、组织、概念）和关系，将它们存储在图数据库中，然后在检索过程中使用图遍历，不仅查找直接匹配，还通过实体连接查找相关信息。这使得系统能够提供更全面的答案，整合概念之间的上下文关系。

测试清理

在测试之间，您可以清理数据：

向量索引：有关向量数据库清理说明，请参阅docs/VECTOR-DIMENSIONS.md。
图数据：有关图相关的清理命令，请参阅flexible-graphrag/README-neo4j.md。
Neo4j：在无人使用的测试Neo4j数据库上使用。

📦 安装指南

先决条件

必需条件

Python 3.10+（支持3.10、3.11、3.12、3.13）
UV包管理器
Node.js 16+
npm或yarn
Neo4j图数据库
Ollama或带有API密钥的OpenAI（用于大语言模型处理）

可选条件（取决于数据源）

符合CMIS标准的仓库（例如，Alfresco） - 仅在使用CMIS数据源时需要
Alfresco仓库 - 仅在使用Alfresco数据源时需要
文件系统数据源无需额外设置

设置

🐳 Docker部署

Docker部署提供两种主要方法：

选项A：数据库在Docker中，应用程序独立（混合模式）

最佳适用场景：开发、外部内容管理系统、灵活部署

# 仅部署你需要的数据库
docker-compose -f docker/docker-compose.yaml -p flexible-graphrag up -d

# 在docker-compose.yaml中注释掉你不需要的服务：
# - includes/neo4j.yaml          # 如果你使用自己的Neo4j，请注释掉
# - includes/kuzu.yaml           # 如果你不使用Kuzu，请注释掉
# - includes/qdrant.yaml         # 如果你使用Neo4j、Elasticsearch或OpenSearch进行向量搜索，请注释掉
# - includes/elasticsearch.yaml  # 如果你不使用Elasticsearch，请注释掉
# - includes/elasticsearch-dev.yaml  # 如果你不使用Elasticsearch，请注释掉
# - includes/kibana.yaml         # 如果你不使用Elasticsearch，请注释掉
# - includes/opensearch.yaml     # 如果你不使用，请注释掉
# - includes/alfresco.yaml       # 如果你想使用自己安装的Alfresco，请注释掉
# - includes/app-stack.yaml      # 如果你想将后端和UI放在Docker中，请取消注释
# - includes/proxy.yaml          # 如果你想将后端和UI放在Docker中，请取消注释
#   (注意：app-stack.yaml中有环境配置，可以使用它来定制向量、图、搜索和大语言模型)

# 在Docker外部运行后端和UI客户端
cd flexible-graphrag
uv run start.py

使用场景：

✅ 文件上传：通过Web界面直接上传文件
✅ 外部CMIS/Alfresco：连接到现有的内容管理系统
✅ 开发：易于调试和热重载
✅ 混合环境：数据库在容器中，应用程序在主机上

选项B：整个栈在Docker中（完整模式）

最佳适用场景：生产部署、隔离环境、容器化内容源

# 部署包括后端和UI的所有内容
docker-compose -f docker/docker-compose.yaml -p flexible-graphrag up -d

特性：

✅ 所有数据库预配置（Neo4j、Kuzu、Qdrant、Elasticsearch、OpenSearch、Alfresco）
✅ 后端 + 3个UI客户端（Angular、React、Vue）在容器中
✅ NGINX反向代理，具有统一的URL
✅ 持久数据卷
✅ 内部容器网络

启动后的服务URL：

Angular UI：http://localhost:8070/ui/angular/
React UI：http://localhost:8070/ui/react/
Vue UI：http://localhost:8070/ui/vue/
后端API：http://localhost:8070/api/
Neo4j Browser：http://localhost:7474/
Kuzu Explorer：http://localhost:8002/

数据源工作流程：

✅ 文件上传：通过Web界面直接上传文件（拖放或点击文件选择对话框）
✅ Alfresco/CMIS：连接到现有的Alfresco系统或CMIS仓库

停止服务

要停止并移除所有Docker服务：

# 停止所有服务
docker-compose -f docker/docker-compose.yaml -p flexible-graphrag down

配置更改的常见工作流程：

# 停止服务，进行更改，然后重新启动
docker-compose -f docker/docker-compose.yaml -p flexible-graphrag down
# 根据需要编辑docker-compose.yaml或.env文件
docker-compose -f docker/docker-compose.yaml -p flexible-graphrag up -d

配置

模块化部署：在docker/docker-compose.yaml中注释掉你不需要的服务。
环境配置（对于应用栈部署）：
- 环境变量直接在docker/includes/app-stack.yaml中配置。
- 数据库连接使用host.docker.internal进行容器间通信。
- 默认配置包括OpenAI/Ollama大语言模型设置和数据库连接。

有关详细的Docker配置，请参阅docker/README.md。

🔧 本地开发设置

环境配置

创建环境文件（跨平台）：

# Linux/macOS
cp flexible-graphrag/env-sample.txt flexible-graphrag/.env

# Windows命令提示符
copy flexible-graphrag\env-sample.txt flexible-graphrag\.env

编辑.env文件，添加你的数据库凭据和API密钥。

Python后端设置

导航到后端目录：
```
cd project-directory/flexible-graphrag
```

使用UV创建并激活虚拟环境：

# 从项目根目录
uv venv
.\.venv\Scripts\Activate  # 在Windows上（在命令提示符和PowerShell中都适用）
# 或者
source .venv/bin/activate  # 在macOS/Linux上

安装Python依赖项：

# 导航到flexible-graphrag目录并安装需求
cd flexible-graphrag
uv pip install -r requirements.txt

通过复制示例文件并自定义，创建.env文件：
```
# 复制示例环境文件（使用适合你平台的命令）
cp env-sample.txt .env  # Linux/macOS
copy env-sample.txt .env  # Windows
```
编辑.env文件，添加你的特定配置。有关详细的设置指南，请参阅docs/ENVIRONMENT-CONFIGURATION.md。

前端设置

生产模式（后端不提供前端服务）：

后端API：http://localhost:8000（仅FastAPI服务器）
前端部署：单独部署（nginx、Apache、静态托管等）
独立和Docker前端都指向本地主机上的后端：8000

开发模式（前端和后端分别运行）：

后端API：http://localhost:8000（仅FastAPI服务器）
Angular开发：http://localhost:4200（ng serve）
React开发：http://localhost:5173（npm run dev）
Vue开发：http://localhost:5174（npm run dev）

选择以下前端选项之一进行工作：

React前端

导航到React前端目录：
```
cd flexible-graphrag-ui/frontend-react
```
安装Node.js依赖项：
```
npm install
```
启动开发服务器（使用Vite）：
```
npm run dev
```

React前端将在http://localhost:5174可用。

Angular前端

导航到Angular前端目录：

cd flexible-graphrag-ui/frontend-angular

安装Node.js依赖项：
```
npm install
```
启动开发服务器（使用Angular CLI）：
```
npm start
```

Angular前端将在http://localhost:4200可用。

注意：如果ng build给出预算错误，请使用npm start进行开发。

Vue前端

导航到Vue前端目录：
```
cd flexible-graphrag-ui/frontend-vue
```
安装Node.js依赖项：
```
npm install
```
启动开发服务器（使用Vite）：
```
npm run dev
```

Vue前端将在http://localhost:3000可用。

运行应用程序

启动Python后端

从项目根目录：

cd flexible-graphrag
uv run start.py

后端将在http://localhost:8000可用。

启动你首选的前端

按照前端设置部分中的说明，为你选择的前端框架进行操作。

前端部署

构建前端

# Angular（可能有预算警告 - 开发时可安全忽略）
cd flexible-graphrag-ui/frontend-angular
ng build

# React
cd flexible-graphrag-ui/frontend-react
npm run build

# Vue
cd flexible-graphrag-ui/frontend-vue
npm run build

Angular构建注意事项：

预算警告在Angular中很常见，开发时通常可以安全忽略。
对于生产环境，考虑优化捆绑包大小或调整angular.json中的预算限制。
开发模式：使用npm start避免构建问题。

启动生产服务器

cd flexible-graphrag
uv run start.py

后端提供：

/api/*下的API端点
专注于数据处理和搜索的独立操作
与前端服务关注点的清晰分离

后端API端点：

API基础：http://localhost:8000/api/
API端点：/api/ingest、/api/search、/api/query、/api/status等。
健康检查：http://localhost:8000/api/health

前端部署：

手动部署：使用你首选的方法（nginx、Apache、静态托管等）独立部署前端。
前端配置：独立和Docker前端都指向后端的http://localhost:8000/api/。
每个前端可以根据你的需求单独构建和部署。

全栈调试

项目包含一个sample-launch.json文件，其中包含VS Code的调试配置，适用于所有三个前端选项和后端。将此文件复制到.vscode/launch.json以使用这些配置。

关键调试配置包括：

React和Python全栈：同时调试React前端和Python后端
Angular和Python全栈：同时调试Angular前端和Python后端
Vue和Python全栈：同时调试Vue前端和Python后端
注意，结束调试时，你需要分别停止Python后端和前端。

每个配置都设置了适当的端口、源映射和调试工具，以实现无缝的开发体验。你可能需要调整launch.json文件中的端口和路径，以匹配你的特定设置。

使用方法

系统提供了一个标签式界面，用于文档处理和查询。请按以下步骤操作：

1. 数据源标签

配置你的数据源并选择要处理的文件：

文件上传数据源

选择：从数据源下拉菜单中选择“文件上传”
添加文件：
- 拖放：直接将文件拖到上传区域
- 点击选择：点击上传区域打开文件选择对话框（支持多选）
- 注意：如果在通过对话框选择文件后拖放新文件，仅使用拖放的文件
支持的格式：PDF、DOCX、XLSX、PPTX、TXT、MD、HTML、CSV、PNG、JPG等
下一步：点击“配置处理 →”进入处理标签

Alfresco仓库

选择：从数据源下拉菜单中选择“Alfresco仓库”
配置：
- Alfresco基础URL（例如，http://localhost:8080/alfresco）
- 用户名和密码
- 路径（例如，/Sites/example/documentLibrary）
下一步：点击“配置处理 →”进入处理标签

CMIS仓库

选择：从数据源下拉菜单中选择“CMIS仓库”
配置：
- CMIS仓库URL（例如，http://localhost:8080/alfresco/api/-default-/public/cmis/versions/1.1/atom）
- 用户名和密码
- 文件夹路径（例如，/Sites/example/documentLibrary）
下一步：点击“配置处理 →”进入处理标签

2. 处理标签

处理你选择的文档并监控进度：

开始处理：点击“开始处理”开始文档摄入
监控进度：查看每个文件的实时进度条
文件管理：
- 使用复选框选择文件
- 点击“移除所选（N）”从列表中移除所选文件
- 注意：这将从处理队列中移除文件，而不是从你的系统中移除
处理管道：文档通过Docling转换、向量索引和知识图谱创建进行处理

3. 搜索标签

对已处理的文档进行搜索：

混合搜索

目的：查找并排名最相关的文档摘录
用法：输入搜索词或短语（例如，“机器学习算法”、“财务预测”）
操作：点击“搜索”按钮
结果：按相关性排名的文档摘录列表，带有相关性得分和源信息
最适用场景：研究、事实核查、在文档中查找特定信息

问答查询

目的：获取人工智能生成的自然语言问题的答案
用法：输入自然语言问题（例如，“研究论文的主要发现是什么？”）
操作：点击“提问”按钮
结果：人工智能生成的叙述性答案，综合了多个文档中的信息
最适用场景：总结、分析、获取复杂主题的概述

4. 聊天标签

用于文档问答的交互式对话界面：

聊天界面：
- 你的问题：垂直显示在右侧
- 人工智能答案：垂直显示在左侧
用法：输入问题并按Enter或点击发送
对话历史记录：所有问题和答案都保留在聊天历史记录中
清除历史记录：点击“清除历史记录”按钮开始新对话
最适用场景：迭代提问、跟进查询、对话式文档探索

项目结构

/flexible-graphrag：基于LlamaIndex的Python FastAPI后端
- main.py：FastAPI REST API服务器（简洁，无MCP）
- backend.py：API和MCP共享的业务逻辑核心
- config.py：数据源、数据库和大语言模型提供商的可配置设置
- hybrid_system.py：使用LlamaIndex的主要混合搜索系统
- document_processor.py：集成Docling的文档处理
- factories.py：用于创建大语言模型和数据库的工厂类
- sources.py：数据源连接器（文件系统、CMIS、Alfresco）
- requirements.txt：FastAPI和LlamaIndex依赖项
- start.py：uvicorn的启动脚本
- install.py：安装辅助脚本
/flexible-graphrag-mcp：独立的MCP服务器
- main.py：基于HTTP的MCP服务器（调用REST API）
- pyproject.toml：MCP包定义，依赖项最少
- README.md：MCP服务器设置和安装说明
- 轻量级：仅4个依赖项（fastmcp、nest-asyncio、httpx、python-dotenv）
/flexible-graphrag-ui：前端应用程序
- /frontend-react：React + TypeScript前端（使用Vite构建）
  - /src：源代码
  - vite.config.ts：Vite配置
  - tsconfig.json：TypeScript配置
  - package.json：Node.js依赖项和脚本
- /frontend-angular：Angular + TypeScript前端（使用Angular CLI构建）
  - /src：源代码
  - angular.json：Angular配置
  - tsconfig.json：TypeScript配置
  - package.json：Node.js依赖项和脚本
- /frontend-vue：Vue + TypeScript前端（使用Vite构建）
  - /src：源代码
  - vite.config.ts：Vite配置
  - tsconfig.json：TypeScript配置
  - package.json：Node.js依赖项和脚本
/docker：Docker基础设施
- docker-compose.yaml：主组合文件，包含模块化包含项
- /includes：模块化数据库和服务配置
- /nginx：反向代理配置
- README.md：Docker部署文档
/docs：文档
- ARCHITECTURE.md：完整的系统架构和组件关系
- DEPLOYMENT-CONFIGURATIONS.md：独立、混合和完整Docker部署指南
- ENVIRONMENT-CONFIGURATION.md：环境设置指南，包括数据库切换
- VECTOR-DIMENSIONS.md：向量数据库清理说明
- SCHEMA-EXAMPLES.md：知识图谱模式示例
- PERFORMANCE.md：性能基准和优化指南
- DEFAULT-USERNAMES-PASSWORDS.md：数据库凭据和仪表盘访问
- PORT-MAPPINGS.md：所有服务的完整端口参考
/scripts：实用脚本
- create_opensearch_pipeline.py：OpenSearch混合搜索管道设置
- setup-opensearch-pipeline.sh/.bat：跨平台管道创建
/tests：测试套件
- test_bm25_*.py：BM25配置和集成测试
- conftest.py：测试配置和夹具
- run_tests.py：测试运行器

📄 许可证

本项目根据Apache License 2.0许可。有关详细信息，请参阅LICENSE文件。

flexible-graphrag

README

🚀 灵活图增强检索生成平台（Flexible GraphRAG）

🚀 快速开始

✨ 主要特性

💻 使用示例

基础用法

高级用法

📚 详细文档

前端截图

Angular前端 - 标签式界面

React前端 - 标签式界面

Vue前端 - 标签式界面

系统组件

FastAPI后端 (/flexible-graphrag)

MCP服务器 (/flexible-graphrag-mcp)

UI客户端 (/flexible-graphrag-ui)

Docker基础设施 (/docker)

数据源

文件与上传源

云存储源

企业仓库源

网络源

文档处理选项

支持的文件格式

文档格式（Docling处理）

图像格式（Docling OCR）

文本格式（直接处理）

处理智能性

数据库配置

搜索数据库（全文搜索）

向量数据库（语义搜索）

⚠️ 向量维度兼容性

支持的向量数据库

无图增强检索生成的RAG

图数据库（知识图谱 / 图增强检索生成）

大语言模型配置

大语言模型提供商

大语言模型性能建议

Ollama配置

MCP工具（适用于Claude Desktop等MCP客户端）

客户端支持

🔧 技术细节

技术实现

测试清理

📦 安装指南

先决条件

必需条件

可选条件（取决于数据源）

设置

🐳 Docker部署

选项A：数据库在Docker中，应用程序独立（混合模式）

选项B：整个栈在Docker中（完整模式）

停止服务

配置

🔧 本地开发设置

环境配置

Python后端设置

前端设置

React前端

Angular前端

Vue前端

运行应用程序

启动Python后端

启动你首选的前端

前端部署

构建前端

启动生产服务器

全栈调试

使用方法

1. 数据源标签

文件上传数据源

Alfresco仓库

CMIS仓库

2. 处理标签

3. 搜索标签

混合搜索

问答查询

4. 聊天标签

项目结构

FastAPI后端 (`/flexible-graphrag`)

MCP服务器 (`/flexible-graphrag-mcp`)

UI客户端 (`/flexible-graphrag-ui`)

Docker基础设施 (`/docker`)