veritasgraph

VeritasGraph — 受治理的本地部署 GraphRAG 与 Agent 框架

别再盲目切分文本块。结合树搜索结构与知识图谱推理，并将其接入受治理的 AI Agent。可 100% 在本地或云端运行。

🎯 传统 RAG 根据相似度进行猜测。VeritasGraph 根据结构进行推理。 不要只找文档——还要理解其中的关联，然后通过受治理的 Agent 采取行动。

🌐 访问网站 · ⭐ Star · 🍴 Fork · 💬 讨论 · 🐛 报告 bug

python -m veritasgraph_mcp     # from repo root (needs local Ollama for ingest/query)

▶️️ 在 YouTube 观看完整演讲与现场演示（27 分钟）

为什么向量 RAG 不适用于深度研究

• 归属信息是数据模型，而非提示词： 在写入时存储溯源信息，可防止读取时产生虚构的引用。
• 确定性检索： 图遍历完全可复现，可将事实证据轨迹与随机的大模型生成区分开来。
• 明确弃答： Agent 会识别缺失的图边，并返回“证据不足”，而非进行猜测。

📚 精选指南 — 在本地部署环境构建受治理的 AI Agent

完整介绍如何完全在自己的基础设施上设计、连接并交付受治理的 AI Agent。

📄 阅读指南：在本地部署环境构建受治理的 AI Agent（PDF）

▶️ 在 YouTube 观看操作指南

🚀 快速开始（2 行，无需 GPU）

pip install veritasgraph
veritasgraph demo --mode=lite

就这么简单——使用云 API（OpenAI/Anthropic）的交互式演示，无需本地模型。

export OPENAI_API_KEY="sk-..."        # Lite: cloud APIs, zero setup
veritasgraph demo --mode=lite

veritasgraph demo --mode=local --model=llama3.2   # 100% offline with Ollama
veritasgraph start --mode=full                    # full GraphRAG pipeline

实用链接： ⚡ 在线文档 · 🎮 在线演示 · 📖 文章 · 📄 研究论文

🏥 示例实现 — MedTrust Agent

MedTrust Agent 是 VeritasGraph 受治理 Agent 架构的完整、可复现示例实现，应用于医疗和制药工作流——一个零信任、可观测的大模型 Agent 框架（NEECON 2026 论文）。

• **零信任控制平面：**遵循最小权限原则的 IAM，并采用逐级授权——授权成功前不会运行任何工具。
• **受治理的回答：**必须提供 [doc#chunk] 引用；未引用来源的回答将被暂缓提供或转交人工审核。
• **防篡改审计：**采用密钥和哈希链的审计日志，并发布锚点。
• **诚实评估：**直接根据运行中的代码衡量安全性（阻止 100% 未授权操作，Wilson 95% 置信区间）；明确标注回答质量为示例性；包含 69 项测试、一套版本化的 40 种场景测试套件，以及一个单命令复现脚本。

python -m medtrust.demo    # end-to-end governed demo, 100% offline

📄 阅读完整说明：MedTrust Agent README

🧩 使用 VeritasGraph 构建

不断壮大的项目生态正在基于 VeritasGraph 构建企业级 GraphRAG、Agent 编排、事实核查和受治理推理方案。

社区项目与集成

• MeAkash77 / VeritasGraph-Enterprise-GraphRAG-Verifiable-AI-Platform — 企业级 GraphRAG 适配器和可验证 AI 平台模式。
• PTP063 / veritas-graph — 衍生项目和基于 VeritasGraph 概念的线上部署。
• RahulSagar2005 / multi-hop-rag — 多跳检索与推理工作流。
• lukehungngo / agentwall — 面向 Agent 安全与治理的推理流程。
• gajanan229 / Fact-checker-Agent — 聚焦证据的事实核查与解释模式。
• Minh-Tam-Solution / EndiorBot — 基于图推理构建的企业级聊天机器人和 AI Agent 集成。
• NistorDorinGabriel / Proiect_Licenta — 扩展了 VeritasGraph 启发式图推理技术的学术毕业论文项目。

如果你正在使用 VeritasGraph 构建项目并希望在此处展示，请提交 PR，或联系并附上简短的仓库介绍和用法摘要。

� 实时示例 — Floorplan-KG 工程量清单演示

一个无需设置、托管运行的示例，展示 VeritasGraph 如何应用于建筑图纸。上传楼层平面图 PDF（或选择内置示例），引擎便会提取房间、尺寸、开口、固定装置和明细表，然后构建知识图谱和工程量清单，供你查询；所有结果都可追溯至源图纸。

🏗️ 试用 Floorplan-KG 演示 — 免费，无需登录；运行实时 PyMuPDF/pdfplumber 提取流水线。

• 演示内容： PDF → 结构化房间/尺寸/明细表 → 知识图谱 → CSV/XLSX 工程量清单导出，并提供 VeritasGraph 辅助面板，可基于提取的图谱进行有依据的问答。
• 重要意义： 为文档 RAG 提供支持的同一套治理归因模型也适用于几何数据 — 每个测量值都能追溯到特定图纸和元素，而非猜测得出。
• 示例输出： 一张住宅平面图可在 200 ms 内返回约 17 个房间和约 2,400 平方英尺的数据。

Studio 是一个本地 Agent 构建工作区（FastAPI + 单页 UI），可让你从自己的文档构建知识图谱，并将其与工具、记忆、数据日志、护栏和 headroom 风格的上下文预算结合起来，接入 Agent；之后可与这些 Agent 实时聊天，并观察编排流水线的每个阶段。所有内容都通过 Ollama 100% 在本地运行。

🎮 试用 Studio Live — 稳定 URL，始终会重定向到当前运行的 Studio 隧道。

运行方式：

pip install -r requirements.txt
ollama serve & ollama pull qwen3:latest          # any local chat model
STUDIO_DATA_DIR="$PWD/studio_api/data" \
  uvicorn studio_api.main:app --host 127.0.0.1 --port 8200 --log-level warning
# Studio UI → http://localhost:8200/studio   ·   API docs → /docs

一条命令即可运行端到端演示（构建图谱，并驱动一个完整配置的 Agent 完成图谱推理、记忆回忆、PII 脱敏和护栏拦截）：

python3 demos/agent-studio/sample_pipeline.py --model qwen3:latest

# Backend (FastAPI on :8300)
cd clinical-kg/backend
pip install -r requirements.txt
python run.py

# Frontend (Next.js dashboard on :3200)
cd clinical-kg/frontend
npm install && npm run dev

cd municipality-incident-chatbot
pip install -r requirements.txt

# Interactive CLI
python cli.py
#   you> trash overflowing near the market | photo=garbage_overflow.jpg | zone=downtown

# Test suite
python -m pytest -q

企业场景 — 按照 Northwind Bank 合规测试手册，使用真实的金融服务数据逐步完成演练。

API 级示例和 curl 命令示例请参阅 studio_api/README.md。

🌳 + 🔗 图谱 + 树：终极检索

为何二选一？ VeritasGraph 不仅具备 PageIndex 的层级式“目录”导航，还拥有知识图谱的语义推理能力。

Document Root
├── [1] Introduction
│   ├── [1.1] Background ←── Tree Navigation
│   └── [1.2] Objectives
├── [2] Methodology ←───────── Graph Links
│   └── relates_to ──────────→ [3.1] Findings
└── [3] Results

📊 功能对比

🎬 实际效果展示

💡 您看到的内容： 查询会触发知识图谱中的多跳推理。发现连接时，节点会亮起，清楚展示答案究竟是如何得出的，而不仅仅是找到什么。

🔌 MCP 服务 — 将 IDE Agent 连接到 VeritasGraph

VeritasGraph 提供专用的 Model Context Protocol 服务——*首个面向 MCP 的零信任、气隙隔离企业级 GraphRAG 服务。*通过 JSON-RPC 2.0 stdio 将 Claude Desktop、Cursor、VS Code、Windsurf、Cline 或 Continue 直接连接到 GraphRAG 引擎，不会向外部传输任何数据。

python -m veritasgraph_mcp     # from repo root (needs local Ollama for ingest/query)

工具：veritasgraph_ingest_document、veritasgraph_query（带有 [doc#chunk] 引用的多跳答案）、veritasgraph_search_entities、veritasgraph_get_graph、veritasgraph_clear_graph。有关 IDE 注册代码片段，请参阅 veritasgraph_mcp/README.md。

🏥 VeritasGraph-MCP 用例 — Azure 上的生产级医疗 AI

真实部署： VeritasGraph MCP 服务运行于 Azure Functions，并结合 Azure AI Foundry，为临床决策支持提供由 GraphRAG 驱动的能力，包含可验证的引用和满足合规要求的架构。

Foundry Agent / MCP client
   → Identity (Entra ID + function key)
      → Azure Functions (Flex Consumption, 4 mcpToolTrigger tools)
         → veritasgraph-mcp + graphrag_engine
            → Azure OpenAI (extraction + reasoning)
            → Knowledge Graph
         → Durable Azure Files mount (externalized state)
         → Storage + App Insights (observability)

{
  "question": "Should we adjust warfarin for patient 4471 on amiodarone?",
  "answer": "Reduce the warfarin dose because amiodarone inhibits CYP2C9...",
  "citations": ["doc_warfarin_note#0", "doc_warfarin_note#1"],
  "reasoning_path": ["Amiodarone → CYP2C9", "CYP2C9 → Warfarin", "Warfarin → Bleeding Risk"]
}

📖 Python API

from veritasgraph import VisionRAGPipeline

pipeline = VisionRAGPipeline()                 # auto-detects available models
doc = pipeline.ingest_pdf("document.pdf")
result = pipeline.query("What are the key findings?")
print(result.answer)

from veritasgraph import VisionRAGPipeline

pipeline = VisionRAGPipeline()
doc = pipeline.ingest_pdf("report.pdf")

# View the document's hierarchical structure (like a Table of Contents)
print(pipeline.get_document_tree())
# Document Root
# ├── [1] Introduction (pp. 1-5)
# │   ├── [1.1] Background (pp. 1-2)
# │   └── [1.2] Objectives (pp. 3-5)
# └── [2] Methodology (pp. 6-15)

# Navigate to a specific section (tree-based retrieval)
section = pipeline.navigate_to_section("Methodology")
print(section['breadcrumb'])   # ['Document Root', 'Methodology']

# Or use graph-based semantic search
result = pipeline.query("What methodology was used?")
# → answer with section context: "📍 Location: Document > Methodology > Analysis Framework"

from veritasgraph import VisionRAGPipeline, VisionRAGConfig

config = VisionRAGConfig(ingest_mode="document-centric")  # tables stay intact!
pipeline = VisionRAGPipeline(config)
doc = pipeline.ingest_pdf("annual_report.pdf")

CLI

veritasgraph --version                                    # show version
veritasgraph info                                         # check dependencies
veritasgraph init my_project                              # initialize a project
veritasgraph ingest document.pdf --ingest-mode=document-centric   # Don't Chunk. Graph.
veritasgraph ingest https://youtube.com/watch?v=xxx       # auto-extract transcript
veritasgraph ingest https://example.com/article           # extract web article

安装选项

pip install veritasgraph            # basic (includes lite mode)
pip install veritasgraph[web]       # Gradio UI + visualization
pip install veritasgraph[graphrag]  # Microsoft GraphRAG integration
pip install veritasgraph[ingest]    # YouTube & web-article ingestion
pip install veritasgraph[all]       # everything

🏛️ 企业合规 — VeritasGraph + VeritasReason

GraphRAG 非常擅长描述文档中的内容。但诸如 “上个季度哪些采购订单违反了我们的职责分离政策？” 这样的企业问题，是针对结构化记录进行的规则评估问题，而不是相似度搜索。

为此，VeritasGraph 提供了一个配套模块：VeritasReason——一个确定性推理引擎（前向链式推理 + Rete + SPARQL），可对三元组存储执行策略规则，并返回带有 W3C PROV-O 溯源信息、可供审计的答案。

 Policy PDFs ─┐                        ┌─ ingest_structured.py (SQL → triples + text)
              ▼                        ▼
      VeritasGraph GraphRAG      VeritasReason (TripletStore + RuleSet
      (quotes policy text)       + ForwardChainer + PROV-O)
              └──────────┬───────────────┘
                         ▼
             Compliance answer + violators table + clause citations

30 秒快速测试（无需安装，仅使用标准库）

python tests/test_policy_compliance_demo.py

将虚拟 ERP 数据写入一个小型内存三元组存储，根据 rules/sod_policy.yaml 评估四条职责分离规则，并输出带有引用的违规者：

✓ Reasoner fired. Detected 4 violation(s):
  po:PO-2204 SOD-01   Approved & paid by emp:E118
  po:PO-2301 SOD-02   Requested & approved by emp:E091
  po:PO-2317 SOD-03   $48,750.00 approved by emp:E091 (role:Manager, not Director)
  po:PO-2402 SOD-04   Vendor vendor:V77 related to approver emp:E140

也可以安装并运行打包好的演示：

pip install veritas-reason
veritasreason-policy-demo

同样的模式也适用于休假政策违规（HRIS 考勤）、费用报销欺诈（分类账 + 收据）、临床方案违规（EHR + 指南）或 KYC/AML（交易 + 监视名单）。在 ingest_structured.py 中定义 SQL → 三元组映射，在 rules/*.yaml 中编写规则，然后用自然语言提问。完整演练请参见 veritas-reason/plan.md。

🔗 交互式图可视化

VeritasGraph 内置交互式 2D 知识图谱探索器（PyVis），可实时可视化实体和关系。

⚙️ 提供方支持（兼容 OpenAI）

VeritasGraph 适用于任何兼容 OpenAI 的 API，可混合搭配云端和本地服务：

此外还支持：Azure OpenAI、OpenRouter、Anyscale、LocalAI、vLLM。

cd graphrag-ollama-config
cp settings_openai.yaml settings.yaml
cp .env.openai.example .env       # edit with your provider settings
python -m graphrag.index --root . --config settings_openai.yaml
python app.py

⚠️ 嵌入模型必须与索引匹配。 如果你使用 nomic-embed-text（768 dims）建立索引，查询时必须使用相同模型——切换嵌入模型需要重新建立索引。详情请见 OPENAI_COMPATIBLE_API.md。

🐳 部署

五分钟快速上手（Docker）

运行完整技术栈（Ollama + Neo4j + Gradio），只需一条命令：

cd docker/five-minute-magic-onboarding
# set your Neo4j password in .env, then:
docker compose up --build

服务：Gradio UI → http://127.0.0.1:7860 · Neo4j → http://localhost:7474 · Ollama → http://localhost:11434。请参阅 docker/five-minute-magic-onboarding/README.md。

与团队分享（免费）

*免费套餐有一些限制。

🏗️ 架构

graph TD
    subgraph "Indexing Pipeline (one-time)"
        A[Source Documents] --> B{Document Chunking};
        B --> C{"LLM Extraction<br/>(Entities & Relationships)"};
        C --> D[Vector Index];
        C --> E[Knowledge Graph];
    end
    subgraph "Query Pipeline (real-time)"
        F[User Query] --> G{Hybrid Retrieval Engine};
        G -- "1. Vector search for entry points" --> D;
        G -- "2. Multi-hop graph traversal" --> E;
        G --> H{Pruning & Re-ranking};
        H -- "Rich context" --> I{LoRA-Tuned LLM Core};
        I -- "Answer + provenance" --> J{Attribution Layer};
        J --> K[Attributed Answer];
    end
    style A fill:#f2f2f2,stroke:#333,stroke-width:2px
    style F fill:#e6f7ff,stroke:#333,stroke-width:2px
    style K fill:#e6ffe6,stroke:#333,stroke-width:2px

四个阶段：

1. 自动构建知识图谱 — 将文档拆分为 TextUnits，提取 (head, relation, tail) 三元组，并在图数据库（例如 Neo4j）中组装节点和边。
2. 混合检索引擎 — 向量搜索查找入口节点，多跳遍历揭示隐藏关系，剪枝和重排序则保留最相关的事实。
3. LoRA 微调推理核心 — 在本地托管的 LoRA 微调开源模型生成带出处的答案，并通过高效微调提升推理和归因能力。
4. 归因与来源追溯层 — 将来源 ID、文本块和图节点传递到结构化、可追溯的 JSON 输出中。

为什么选择 VeritasGraph？

• ✅ 完全本地部署且安全 — 完全掌控自己的数据和模型。
• ✅ 可验证的归因 — 每项声明都能追溯到其来源。
• ✅ 高级图推理 — 回答复杂的多跳问题。
• ✅ 分层树结构 + 图谱 — 兼具 PageIndex 风格的目录导航与图谱的灵活性。
• ✅ 受治理的 Agent — 在 Studio 中整合护栏、记忆、工具和上下文预算。
• ✅ 开源且自主可控 — 采用 MIT 许可证，不受供应商锁定。

适用对象？ 构建企业搜索、合规助手、研究副驾驶、科学文献探索工具和 Agent 记忆系统的工程师——适用于任何答案取决于事实之间的关联方式，而不仅仅是事实是否出现在向量索引的相邻位置的场景。

🙌 致谢

本项目基于 HopRAG、Microsoft GraphRAG、LangChain & LlamaIndex 和 Neo4j 的基础工作构建。

🏆 奖项与引用

曾于 International Conference on Applied Science and Future Technology（ICASF 2025） 发表 — 📄 感谢证书。

@article{VeritasGraph2025,
  title={VeritasGraph: A Sovereign GraphRAG Framework for Enterprise-Grade AI with Verifiable Attribution},
  author={Bibin Prathap},
  journal={International Conference on Applied Science and Future Technology (ICASF)},
  year={2025}
}

Star 历史

基于 MIT 许可证授权。 ⭐ 为此仓库点星，关注开源、受治理的 GraphRAG 路线图。