Flexible Graphrag

🚀 靈活圖增強檢索生成平臺（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種不同的數據源，用於將文檔攝入到知識庫中：

文件與上傳源

1. 文件上傳 - 通過支持拖放的Web界面直接上傳文件

雲存儲源

2. Amazon S3 - 集成AWS S3存儲桶
3. Google Cloud Storage (GCS) - 谷歌雲存儲桶
4. Azure Blob Storage - 微軟Azure blob容器
5. OneDrive - 微軟OneDrive個人/商業存儲
6. SharePoint - 微軟SharePoint文檔庫
7. Box - Box.com雲存儲
8. Google Drive - 谷歌雲端硬盤文件存儲

企業倉庫源

9. CMIS (內容管理互操作性服務) - 行業標準的內容倉庫接口
10. Alfresco - Alfresco企業內容管理/內容倉庫

網絡源

11. 網頁 - 從網頁URL提取內容
12. 維基百科 - 通過標題或URL攝入維基百科文章
13. 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

配置

1. 模塊化部署：在docker/docker-compose.yaml中註釋掉你不需要的服務。
2. 環境配置（對於應用棧部署）：
   • 環境變量直接在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後端設置

1. 導航到後端目錄：

   cd project-directory/flexible-graphrag
   

2. 使用UV創建並激活虛擬環境：

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

3. 安裝Python依賴項：

   # 導航到flexible-graphrag目錄並安裝需求
   cd flexible-graphrag
   uv pip install -r requirements.txt
   

4. 通過複製示例文件並自定義，創建.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前端

1. 導航到React前端目錄：

   cd flexible-graphrag-ui/frontend-react
   

2. 安裝Node.js依賴項：

   npm install
   

3. 啟動開發服務器（使用Vite）：

   npm run dev
   

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

Angular前端

1. 導航到Angular前端目錄：

   cd flexible-graphrag-ui/frontend-angular
   

2. 安裝Node.js依賴項：

   npm install
   

3. 啟動開發服務器（使用Angular CLI）：

   npm start
   

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

注意：如果ng build給出預算錯誤，請使用npm start進行開發。

Vue前端

1. 導航到Vue前端目錄：

   cd flexible-graphrag-ui/frontend-vue
   

2. 安裝Node.js依賴項：

   npm install
   

3. 啟動開發服務器（使用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以使用這些配置。

關鍵調試配置包括：

1. React和Python全棧：同時調試React前端和Python後端
2. Angular和Python全棧：同時調試Angular前端和Python後端
3. Vue和Python全棧：同時調試Vue前端和Python後端
4. 注意，結束調試時，你需要分別停止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文件。