MindGraph

欢迎来到 MindGraph，这是一个概念验证性的开源、以 API 为主导的图数据库项目，专为自然语言交互（输入和输出）而设计。该原型可作为构建和定制您自己的 CRM 解决方案的模板，重点在于易于集成和可扩展性。有关更多背景信息，请参阅 X 上的公告。

快速入门

前置条件

在开始之前，请确保已安装以下内容：

• Python 3.6 或更高版本
• Poetry（依赖管理和打包工具）

安装

1. 克隆仓库：

   git clone https://github.com/yourusername/MindGraph.git
   

2. 进入项目目录：

   cd MindGraph
   

3. 使用 Poetry 安装项目依赖：

   poetry install
   

   此命令将为项目创建一个虚拟环境，并安装 pyproject.toml 文件中指定的所有所需包。

   • 注意：如果遇到任何依赖错误，可以运行 poetry add <name_of_dependency> 来添加依赖项。

环境设置

1. 在项目根目录下创建一个 .env 文件。

2. 打开 .env 文件，添加以下行，将 YOUR_API_KEY 替换为您的实际 OpenAI API 密钥：

   OPENAI_API_KEY=YOUR_API_KEY
   

运行应用程序

安装完依赖后，您可以使用以下命令启动 Flask 服务器：

poetry run python main.py

服务器将在 http://0.0.0.0:81 启动。

项目结构

MindGraph 分为几个关键组件：

• main.py：应用程序的入口点。
• app/__init__.py：设置 Flask 应用并集成蓝图。
• models.py：管理实体和关系的内存图数据结构。
• views.py：包含 API 路由定义。
• integration_manager.py：负责动态注册和管理集成函数。
• signals.py：设置用于创建、更新和删除实体的信号。

集成系统

MindGraph 采用了一个复杂的集成系统，旨在动态扩展应用程序的基础功能。该系统的核心是 integration_manager.py，它充当各种集成函数的注册表和执行器。这种模块化架构使 MindGraph 能够无缝地整合 AI 驱动的功能，例如通过 natural_input.py 等集成将自然语言输入处理为结构化的知识图谱。其他集成，包括 add_multiple_conditional、conditional_entity_addition 和 conditional_relationship_addition，协同工作，以确保应用程序数据模型的完整性和增强。

功能

实体管理：实体存储在内存图中，以便快速访问和操作，支持对人员、组织及其相互关系的 CRUD 操作。

集成触发器：可以通过 HTTP 请求触发自定义集成函数，使 CRM 能够与外部系统交互或执行额外的处理。

搜索功能：可以使用自定义查询参数轻松搜索实体及其关系。

AI 就绪：专为 AI 集成设计，便于引入智能数据处理和决策功能。

API 端点

MindGraph 提供了一系列 RESTful 端点：

• POST /<entity_type>：创建实体。
• GET /<entity_type>/<int:entity_id>：获取实体。
• GET /<entity_type>：列出某一类型的全部实体。
• PUT /<entity_type>/<int:entity_id>：更新实体。
• DELETE /<entity_type>/<int:entity_id>：删除实体。
• POST /relationship：建立新关系。
• GET /search/entities/<entity_type>：搜索实体。
• GET /search/relationships：查找关系。

自定义集成端点

• POST /trigger-integration/<integration_name>：激活预定义的集成函数。

前端概述

MindGraph 的前端提供了一个轻量级的交互式 Web 界面，便于动态可视化和管理基于图的数据模型。虽然 MindGraph 主要作为 API 使用，但前端对于演示目的非常有帮助。它利用 HTML、CSS、JavaScript、Cytoscape.js 进行图可视化，并使用 jQuery 处理 AJAX 请求。

功能

• 图可视化：使用 Cytoscape.js 进行交互式图渲染。
• 动态数据交互：支持实时数据获取、添加以及无需页面刷新即可更新图。
• 搜索与高亮：允许用户搜索节点，在图中高亮显示并列出匹配结果。目前搜索表单也被双重用于自然语言查询，这其实并不合理，但却是快速展示功能的一种方式。（此界面仅用于演示，MindGraph 本身应作为 API 使用）
• 数据提交表单：包括自然语言、URL 输入以及 CSV 文件上传表单。
• 响应式设计：适应各种设备和屏幕尺寸。

工作流程

1. 初始化：页面加载时，初始化图的样式和布局。
2. 用户交互：通过界面，用户可以：
   • 搜索节点，结果会在图中高亮显示，并在侧边栏中列出。
   • 使用支持多种输入方式的表单添加数据。
   • 刷新图以反映最新的后端数据。
3. 数据处理：用户输入会被发送到后端进行处理和集成，前端图可视化会相应更新。

基于模式的知识图谱创建

MindGraph 使用 schema.json 文件来定义其知识图谱中实体的结构和关系。该模式充当解释和组织自然语言输入以形成连贯图格式的蓝图。它详细说明了节点类型（例如，Person、Organization、Concept）以及它们之间可能存在的关系，从而确保生成的知识图谱遵循一致的格式。这种方法允许自动化的 AI 驱动处理自然语言输入，生成反映输入文本中复杂相互关系的结构化数据。

在 AI 集成中使用 schema.json

当 create_knowledge_graph 函数处理输入时，它会参考 schema.json 文件，以了解如何将识别出的实体及其关系映射到知识图谱中。这包括：

• 根据模式定义识别节点类型和属性。
• 确定有效的关系类型及其特征。
• 将输出结构化为与预期图谱格式一致的形式，从而实现与应用程序数据模型的无缝集成。

该模式确保由 AI 生成的知识图谱不仅与应用程序的数据模型保持一致，而且信息丰富、细节详尽，能够准确捕捉输入中描述的实体之间的细微关系。

优势

• 一致性：确保所有从自然语言输入生成的知识图谱都遵循相同的结构规则，使数据集成和解释更加简便。
• 灵活性：只需修改 schema.json 文件即可轻松更新和扩展知识图谱的结构，而无需更改代码库。
• AI 集成：通过提供明确的预期输出结构，便于使用先进的 AI 模型进行自然语言处理，从而提升应用程序从非结构化数据中提取有意义见解的能力。

开发与扩展

添加新的集成

要将新集成引入 MindGraph，请在 integrations 目录下创建一个 Python 模块。该模块应定义集成的逻辑，并包含一个用于将集成连接到 IntegrationManager 的 register 函数。请确保您的集成能与应用程序的各个组件正确交互，例如与用于数据操作的 models.py 和用于通过 API 端点激活的 views.py 进行协作。这种方法允许 MindGraph 通过模块化和可重用的代码动态扩展其功能。

使用信号机制

针对实体生命周期事件会发出信号，这些信号提供了扩展功能或与其他系统同步的钩子。

数据库集成与使用

MindGraph 支持灵活的数据库集成，以增强其数据存储和检索能力。开箱即用，MindGraph 已内置对内存数据库和更强大的云数据库 NexusDB 的支持。这种灵活性使其能够轻松适应不同的部署环境和使用场景。

支持的数据库

• InMemoryDatabase：一种简单的内存图数据结构，适用于快速原型设计和测试。由于其非持久性，不建议用于生产环境。
• NexusDB：一款一体化云数据库，专为存储图、表格、文档、文件、向量等数据而设计。它提供共享的知识图谱，用于全面的数据管理和分析。 配置数据库
• NebulaGraph：一种分布式、可扩展且速度极快的图数据库，支持实时查询和分析。非常适合大规模图数据的存储和处理。
• FalkorDB：一种知识型数据库，具有低延迟和高吞吐量的特点，并内置向量搜索功能，同时广泛支持 Cypher 查询语言。

数据库集成由 DATABASE_TYPE 环境变量控制。要选择数据库，请设置此变量：

• memory 表示使用内存数据库。
• nexusdb 表示集成 NexusDB。

export DATABASE_TYPE=nexusdb

• nebulagraph 表示集成 NebulaGraph。

注意：对于正在运行的 NebulaGraph，可以考虑使用 Docker Desktop 扩展，或者使用 NebulaGraph-Lite 在 Colab/Linux 上通过 pip 安装，也可以在 官方文档 中探索更多选项。

export DATABASE_TYPE=nebulagraph
export NEBULA_ADDRESS=127.0.0.1:9669

• falkordb 表示集成 FalkorDB。

注意：对于正在运行的 FalkorDB，可以考虑使用 Docker 镜像。

export DATABASE_TYPE=falkordb
export FALKOR_HOST=127.0.0.1
export FALKOR_PORT=6379
export FALKOR_GRAPH_ID=mindgraph

添加新的数据库集成

要将新的数据库系统集成到 MindGraph 中：

1. 实现数据库集成：在 app/integrations/database 下创建一个新的 Python 模块，遵循 base.py 中定义的抽象基类 DatabaseIntegration。您的实现应为基类中的所有抽象方法提供具体实现。

2. 注册您的集成：修改 app/integrations/database/__init__.py 中的数据库类型检测逻辑，以包含您的新数据库类型。这需要添加一个额外的 elif 语句来检查您的数据库类型，并相应地设置 CurrentDBIntegration。

3. 配置环境变量：如果您的集成需要自定义环境变量（例如连接字符串、认证信息），请确保在 MindGraph 部署环境中正确记录并设置这些变量。

模式管理

对于需要模式定义的数据库（如 NexusDB），请在您的集成模块中纳入模式管理策略。这可能涉及在启动时检查和更新数据库模式，以确保其与当前版本 MindGraph 的兼容性。

示例命令

通过 curl 创建一个人：

curl -X POST http://0.0.0.0:81/people \
-H "Content-Type: application/json" \
-d '{"name":"Jane Doe","age":28}'

示例用例

为了展示 MindGraph 集成系统的强大功能，以下是一些示例命令：

触发自然输入集成

curl -X POST http://0.0.0.0:81/trigger-integration/natural_input \
-H "Content-Type: application/json" \
-d '{"input":"XYZ 公司组织了一场活动，John Doe 和 Jane Smith 参加了。"}'

贡献

说实话……我并不维护项目。如果您想接手或管理这个项目，请告诉我（Twitter/X 是一个不错的渠道）。否则，就按原样享受这个概念验证入门套件吧 :)

许可证

MindGraph 采用 MIT 许可证进行分发。更多信息请参阅 LICENSE 文件。

联系方式

只需在 Twitter/X 上标记我 https://twitter.com/yoheinakajima

项目链接：https://github.com/yoheinakajima/MindGraph

MindGraph 快速上手指南

MindGraph 是一个开源的、基于图结构的 API 优先项目，专为自然语言交互设计。它可作为构建自定义 CRM 解决方案的模板，支持通过 AI 将非结构化文本转化为结构化的知识图谱。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (WSL)
• Python：版本 3.6 或更高
• 包管理工具：Poetry (用于依赖管理和虚拟环境创建)

提示：国内用户安装 Poetry 时若遇网络问题，可配置国内镜像源加速：

poetry config pypi.mirror https://pypi.tuna.tsinghua.edu.cn/simple

安装步骤

1. 克隆项目仓库

   git clone https://github.com/yourusername/MindGraph.git
   

2. 进入项目目录

   cd MindGraph
   

3. 安装依赖 使用 Poetry 安装项目所需的所有依赖包并创建虚拟环境：

   poetry install
   

   注：若安装过程中出现缺失依赖的错误，可运行 poetry add <依赖包名称> 进行补充。

4. 配置环境变量 在项目根目录下创建 .env 文件，并填入您的 OpenAI API Key：

   OPENAI_API_KEY=YOUR_API_KEY
   

   (请将 YOUR_API_KEY 替换为您实际的密钥)

5. (可选) 配置数据库 默认使用内存数据库（仅适合测试）。若需持久化存储，可通过设置环境变量切换数据库类型（如 NexusDB, NebulaGraph, FalkorDB）：

   export DATABASE_TYPE=nexusdb
   # 或其他数据库类型的配置变量
   

基本使用

1. 启动服务

使用以下命令启动 Flask 服务器：

poetry run python main.py

服务启动后，默认监听地址为 http://0.0.0.0:81。

2. 调用 API 创建实体

MindGraph 提供 RESTful API。您可以使用 curl 命令快速创建一个“人物”实体：

curl -X POST http://0.0.0.0:81/people \
-H "Content-Type: application/json" \
-d '{"name":"Jane Doe","age":28}'

3. 前端可视化（演示用）

打开浏览器访问 http://localhost:81，即可看到基于 Cytoscape.js 的交互式图谱界面。您可以在界面上：

• 通过表单输入自然语言、URL 或上传 CSV 文件来生成图谱数据。
• 搜索节点并高亮显示关系。
• 实时查看后端数据的图形化展示。

核心功能概览

• 实体管理：支持对人、组织等实体及其关系的增删改查（CRUD）。
• AI 集成：内置 Schema 驱动机制，可自动解析自然语言输入并映射为符合定义的结构化图谱。
• 扩展性：通过在 integrations 目录添加 Python 模块，可动态注册新的处理逻辑或连接外部系统。