graphmind (Arthurmgraf)

GraphMind

自主知识代理平台 --基于知识图、双引擎编排和自评估检索管道的代理RAG。

______________________________________________________________________

建筑

GraphMind在共享的混合检索层上运行两个编排引擎。 查询通过API输入，选择引擎，并通过自我评估 在返回答案之前。

                          +------------------+
                          |   FastAPI / MCP   |
                          |   Streamlit UI    |
                          +--------+---------+
                                   |
                          engine = ?
                     +-------------+-------------+
                     |                           |
          +----------v----------+     +----------v----------+
          |      LangGraph      |     |       CrewAI        |
          |   (state machine)   |     |  (role-based crew)  |
          |                     |     |                     |
          |  Planner            |     |  Research Agent     |
          |    |                |     |  Analysis Agent     |
          |  Retriever Agent    |     |  Synthesis Agent    |
          |    |                |     |  QA Agent           |
          |  Synthesizer        |     |                     |
          |    |                |     |  Sequential process |
          |  Evaluator          |     |  with shared tools  |
          |    |                |     |                     |
          |  score  retry (x2) |                |
          |   no  -> done       |                |
          +----------+----------+     +----------+
                     |                           |
                     +-------------+-------------+
                                   |
                    +--------------v--------------+
                    |    Hybrid Retrieval Layer    |
                    |                             |
                    |  +--------+   +---------+   |
                    |  | Qdrant |   |  Neo4j  |   |
                    |  | Vector |   |  Graph  |   |
                    |  +---+----+   +----+----+   |
                    |      |             |        |
                    |      +------+------+        |
                    |             |                |
                    |        RRF Fusion            |
                    +--------------+---------------+
                                   |
                    +--------------v--------------+
                    |       LLM Router            |
                    |  Groq -> Gemini -> Ollama   |
                    |    (cascading fallback)      |
                    +-----------------------------+

______________________________________________________________________

主要特点

• 双编排引擎 --用于确定性管道的LangGraph状态机；CrewAI基于角色的团队，用于协作多智能体推理。按查询选择。
• RRF混合检索 --将Qdrant向量相似性搜索与Neo4j图遍历相结合，通过互易秩融合进行融合，以提高召回率和精确度。
• 自我评估循环 --LangGraph评估器对每个答案进行评分。分数低于0.7会触发自动重写和重新查询循环（最多重试2次）。
• 多提供商LLM路由 --Groq、Google Gemini和Ollama之间的级联回退。如果主要提供商宕机或费率受限，下一个提供商将无缝衔接。
• 知识图谱构建 --从摄入的文档中自动提取实体和关系，构建一个丰富检索上下文的Neo4j图。
• 7-格式文件摄入 --Markdown、PDF、TXT、HTML、DOCX、CSV和JSON加载器，具有可配置的分块策略。
• NeMo护栏 --通过Colang流进行输入和输出安全过滤，以执行内容策略。
• 完全可观察性 --每个管道阶段的Langfuse跟踪、按请求成本跟踪和指标收集。
• 评估套件 --DeepEval和RAGAS基准测试用于衡量忠诚度、相关性和基础性。
• MCP服务器 --IDE工具的模型上下文协议集成（Claude代码、游标、VS代码）。
• 流线型仪表板 --用于查询、文档摄取、知识图统计和系统健康监控的Web UI。
• 85单元测试 通过10个测试文件。

______________________________________________________________________

技术栈

______________________________________________________________________

快速开始

先决条件

• Python 3.11+
• Docker和Docker Compose
• Groq API密钥（免费 console.groq.com)

1.克隆并安装

git clone https://github.com/arthurmgraf/graphmind.git
cd graphmind
pip install -e ".[dev,eval]"

2.启动基础设施

docker compose up -d

这将启动Qdrant、Neo4j、PostgreSQL、Langfuse和Ollama。

3.拉动嵌入模型

make pull-models

4.配置环境变量

export GROQ_API_KEY="your-key-here"
# Optional:
export GEMINI_API_KEY="your-key-here"
export NEO4J_PASSWORD="your-password"

5.跑步

# FastAPI server
make run
# or: graphmind

# Streamlit dashboard
make dashboard
# or: graphmind-dashboard

# MCP server (for IDE integration)
make mcp
# or: graphmind-mcp

6.摄入文件

# Via CLI
graphmind-ingest path/to/document.md --type md

# Via API
curl -X POST http://localhost:8000/api/v1/ingest \
  -H "Content-Type: application/json" \
  -d '{"content": "# My Doc\n\nContent here.", "filename": "doc.md", "doc_type": "md"}'

7.查询

# LangGraph engine (default)
curl -X POST http://localhost:8000/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{"question": "What is LangGraph?", "top_k": 10, "engine": "langgraph"}'

# CrewAI engine
curl -X POST http://localhost:8000/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{"question": "Compare CrewAI and LangGraph", "engine": "crewai"}'

______________________________________________________________________

项目结构

graphmind/
├── config/                          # YAML configuration files
├── diagrams/
│   └── generated/                   # Exported diagrams (architecture, agents, data-flow)
├── docs/
│   ├── adrs/                        # Architecture Decision Records (5 ADRs)
│   ├── getting-started.md
│   ├── running.md
│   ├── querying.md
│   ├── ingestion.md
│   ├── testing.md
│   ├── deployment.md
│   └── BUILD_REPORT.md
├── eval/                            # Benchmark datasets and reports
├── src/graphmind/
│   ├── agents/                      # LangGraph nodes + orchestrator
│   │   ├── planner.py               #   Query planning and decomposition
│   │   ├── retriever_agent.py       #   Hybrid retrieval execution
│   │   ├── synthesizer.py           #   Answer generation
│   │   ├── evaluator.py             #   Self-evaluation with retry logic
│   │   ├── orchestrator.py          #   LangGraph state machine wiring
│   │   └── states.py                #   TypedDict state definitions
│   ├── crew/                        # CrewAI multi-agent crew
│   │   ├── agents.py                #   Role definitions (Research, Analysis, Synthesis, QA)
│   │   ├── tasks.py                 #   Task specifications
│   │   ├── tools.py                 #   Shared tool wrappers
│   │   └── crew.py                  #   Crew assembly and kickoff
│   ├── api/                         # FastAPI application
│   │   ├── main.py                  #   App factory and middleware
│   │   └── routes/                  #   query, ingest, health endpoints
│   ├── dashboard/                   # Streamlit web UI
│   │   └── app.py                   #   Query, ingest, graph stats, system health
│   ├── ingestion/                   # Document processing pipeline
│   │   ├── loaders.py               #   7 format loaders (MD, PDF, TXT, HTML, DOCX, CSV, JSON)
│   │   ├── chunker.py               #   Configurable text chunking
│   │   └── pipeline.py              #   End-to-end ingestion orchestration
│   ├── knowledge/                   # Knowledge graph construction
│   │   ├── entity_extractor.py      #   LLM-based entity extraction
│   │   ├── relation_extractor.py    #   LLM-based relation extraction
│   │   ├── graph_builder.py         #   Neo4j graph population
│   │   └── graph_schema.cypher      #   Graph schema definition
│   ├── retrieval/                   # Hybrid retrieval layer
│   │   ├── embedder.py              #   Ollama embedding client
│   │   ├── vector_retriever.py      #   Qdrant vector search
│   │   ├── graph_retriever.py       #   Neo4j graph traversal
│   │   └── hybrid_retriever.py      #   RRF fusion of vector + graph results
│   ├── safety/                      # NeMo Guardrails
│   │   ├── guardrails.py            #   Guardrails integration
│   │   ├── config.py                #   Safety configuration
│   │   ├── config.yml               #   NeMo config file
│   │   └── rails.co                 #   Colang flow definitions
│   ├── observability/               # Monitoring and tracing
│   │   ├── langfuse_client.py       #   Langfuse integration
│   │   ├── cost_tracker.py          #   Per-request cost tracking
│   │   └── metrics.py               #   Metrics collection
│   ├── evaluation/                  # Evaluation framework
│   │   ├── deepeval_suite.py        #   DeepEval test suite
│   │   ├── ragas_eval.py            #   RAGAS evaluation metrics
│   │   ├── eval_models.py           #   Evaluation data models
│   │   └── benchmark.py             #   Benchmark runner
│   ├── mcp/                         # Model Context Protocol server
│   │   └── server.py                #   MCP tool definitions
│   ├── config.py                    # Pydantic Settings with YAML overlay
│   ├── llm_router.py               # Multi-provider LLM routing with fallback
│   └── schemas.py                   # 13 shared Pydantic models
├── tests/
│   ├── unit/                        # 85 unit tests across 10 files
│   │   ├── test_agents.py
│   │   ├── test_chunker.py
│   │   ├── test_config.py
│   │   ├── test_cost_tracker.py
│   │   ├── test_crew.py
│   │   ├── test_deepeval_suite.py
│   │   ├── test_hybrid_retriever.py
│   │   ├── test_loaders.py
│   │   ├── test_metrics.py
│   │   └── test_schemas.py
│   ├── integration/                 # Integration tests
│   └── conftest.py                  # Shared fixtures
├── docker-compose.yml               # Qdrant, Neo4j, PostgreSQL, Langfuse, Ollama
├── Makefile                         # Common commands
└── pyproject.toml                   # Project metadata and dependencies

______________________________________________________________________

发展

测试

# Run all unit tests (85 tests across 10 files)
make test

# Run with coverage report
make test-all

# Run a specific test file
pytest tests/unit/test_agents.py -v

装订和格式化

make lint
make format

评价基准

# Run DeepEval + RAGAS evaluation suite
make eval

______________________________________________________________________

编排引擎

GraphMind提供了两个编排引擎。通过以下方式选择每个查询 engine 参数。

LangGraph——状态机流水线

一种确定性的、基于图的管道，其中每个节点执行一个步骤。评估器节点实现了一个自校正循环：如果答案得分低于 0.7，它重写查询并重试（最多 2次).

CrewAI——基于角色的多智能体团队

由专业代理组成的协作团队，按顺序执行任务，通过CrewAI的内置机制委派和共享上下文。

何时使用Which

______________________________________________________________________

MCP集成

GraphMind公开了一个 MCP（模型上下文协议） 服务器，用于与AI驱动的IDE和工具集成。

配置

将以下内容添加到MCP客户端设置中（Claude Code、Cursor、VS Code等）：

{
  "mcpServers": {
    "graphmind": {
      "command": "graphmind-mcp",
      "args": []
    }
  }
}

可用工具

______________________________________________________________________

文档

______________________________________________________________________

架构决策记录

______________________________________________________________________

图表

架构和数据流图作为Excalidraw源文件进行维护并导出 到 diagrams/generated/ 目录，分为三类：

diagrams/generated/
├── agents/          # Agent interaction and delegation flows
├── architecture/    # High-level system architecture
└── data-flow/       # Data ingestion and retrieval pipelines

______________________________________________________________________

配置

所有设置均通过管理 config/settings.yaml 使用环境变量覆盖。 配置通过Pydantic Settings加载，提供类型安全和验证。

______________________________________________________________________

许可证

该项目根据 MIT许可证.

______________________________________________________________________

作者

亚瑟·马亚图 -- arthurmgraf@hotmail.com

github：