使用说明
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 < 0.7 ? | +----------+----------+
| yes -> 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个测试文件。
技术栈
| 组件 | 技术 | 目的 |
|---|---|---|
| 编排 | LangGraph + 船员AI | 双引擎：状态机+基于角色的多智能体团队 |
| LLM 路由 Groq / 双子座 / 奥拉玛 | 具有级联回退功能的多提供商 | |
| 矢量存储 | Qdrant | 语义相似度搜索 |
| 图形数据库 | Neo4j | 实体关系遍历 |
| 嵌入件 | 奥拉玛 （nomic嵌入文本） | 768个昏暗的本地嵌入 |
| 安全 | NeMo护栏 | 通过Colang流进行输入/输出过滤 |
| 可观察性 | 浪伏 | 跟踪、成本跟踪、评估 |
| 评价 | DeepEval + 拉加斯 | 可信度、相关性、基础性指标 |
| API 快速API | 用于查询、摄取、健康的REST端点 | |
| MCP服务器 | 模型上下文协议 | IDE集成（克劳德代码、游标、VS代码） |
| 仪表板 | 溪流 | 用于查询、摄取和监视的Web UI |
| 配置 | Pydantic设置 | 使用YAML覆盖的类型安全配置 |
| 数据模型 | Pydantic v2 | 跨平台的13个共享模型 |
| 基础设施 | Docker Compose | Qdrant、Neo4j、PostgreSQL、Langfuse、Ollama |
快速开始
先决条件
- 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次).
| 节点 | 责任 |
|---|---|
| 规划师 | 将查询分解为子问题和检索策略 |
| 寻回犬代理 | 执行混合检索（向量+图+RRF） |
| 合成器 | 根据检索到的上下文生成可靠的答案 |
| 评估者 | 对答案进行评分；如果质量不足，则触发重试循环 |
CrewAI——基于角色的多智能体团队
由专业代理组成的协作团队，按顺序执行任务，通过CrewAI的内置机制委派和共享上下文。
| 代理 | 角色 |
|---|---|
| 研究代理 | 检索相关信息并对其进行排名 |
| 分析代理 | 识别模式、矛盾和差距 |
| 合成剂 | 撰写连贯、结构良好的答案 |
| QA代理 | 验证准确性和完整性 |
何时使用Which
| 标准 | 语言图 | CrewAI |
|---|---|---|
| 确定性流 | 是 | 否 |
| 自我评估重试 | 内置 | 通过QA代理 |
| 多视角分析 | 单管道 | 多个代理协作 |
| 最适合 | 事实问答、精确检索 | 复杂分析、比较任务 |
MCP集成
GraphMind公开了一个 MCP（模型上下文协议） 服务器，用于与AI驱动的IDE和工具集成。
配置
将以下内容添加到MCP客户端设置中（Claude Code、Cursor、VS Code等）：
{
"mcpServers": {
"graphmind": {
"command": "graphmind-mcp",
"args": []
}
}
}
可用工具
| 工具 | 说明 |
|---|---|
query |
针对知识库提问 |
ingest |
将文档引入系统 |
graph_stats |
检索知识图统计数据（实体、关系、计数） |
health |
检查所有组件的系统健康状态 |
文档
| 文档 | 描述 |
|---|---|
| 入门指南 | 安装和初始设置指南 |
| 跑步 | 如何运行API、仪表板和MCP服务器 |
| 询问 | 查询API引用和引擎选择 |
| 摄入 | 文档摄取格式和管道详细信息 |
| 测试 | 测试套件结构、运行测试、编写新测试 |
| 部署 | 生产部署指南 |
| 构建报告 | 完整的项目构建报告 |
架构决策记录
| ADR | 决定 |
|---|---|
| ADR-001 | 具有级联回退的多提供商LLM路由 |
| ADR-002 | 基于互序融合的混合检索 |
| ADR-003 | LangGraph代理RAG管道设计 |
| ADR-004 | IDE工具的MCP服务器集成 |
| ADR-005 | 双引擎架构（LangGraph+CrewAI） |
图表
架构和数据流图作为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加载，提供类型安全和验证。
| 变量 | 必填 | 默认 | 描述 |
|---|---|---|---|
GROQ_API_KEY |
是 | -- | Groq API密钥（主要LLM提供程序） |
GEMINI_API_KEY |
否 | -- | Google Gemini API密钥（回退LLM） |
NEO4J_PASSWORD |
是 | -- | Neo4j数据库密码 |
LANGFUSE_PUBLIC_KEY |
否 | -- | Langfuse公钥用于可观察性 |
LANGFUSE_SECRET_KEY |
否 | -- | 用于可观察性的Langfuse密钥 |
QDRANT_URL |
没有 | http://localhost:6333 |
Qdrant矢量存储URL |
NEO4J_URI |
没有 | bolt://localhost:7687 |
Neo4j连接URI |
OLLAMA_BASE_URL |
没有 | http://localhost:11434 |
Ollama API基础URL |
许可证
该项目根据 MIT许可证.
作者
亚瑟·马亚图 -- arthurmgraf@hotmail.com
github： github/arthurmgraf/graphind
