哈基图 HarKinGraph

哈基图 是一个高性能的图计算引擎，基于 CSR（Compressed Sparse Row）存储格式，支持在极限内存情景下的超大规模图计算。

特性

• 🚀 极致性能: 基于 CSR 压缩存储格式，优化内存访问模式
• 💾 超大规模: 支持 十亿级图数据，通过 MMap 突破内存限制
• 🔧 灵活配置: 支持混合/DISK/两种存储模式
• 📊 丰富算法: 内置共同邻居、K-跳、弱连通分量、子图匹配等算法
• 🌐 RESTful API: HTTP 服务接口，易于集成
• ⚡ 哈气导入: 处理超内存数据集，无惧数据规模

架构设计

核心模块

1. 图存储层 (graph)

• Graph 接口: 定义图的基本操作接口
• CSRGraph: 基于 CSR 格式的内存图存储实现
• MMapCSRGraph: 基于内存映射文件的 CSR 图存储，支持超大规模图
• MixCSRGraph: 混合模式图存储，结合内存和 MMap 的优势
• CSCGraph: CSC（Compressed Sparse Column）格式图存储
• PackedLabelCSRGraph: 支持标签压缩的 CSR 图
• GraphStore: 图存储管理器，单例模式管理图实例

2. 图构建器 (graph.builder)

• CSRGraphBuilder: CSR 图构建器基类
• MMapCSRGraphBuilder: MMap 模式图构建器
• MixCSRGraphBuilder: 混合模式图构建器

3. 数据加载层 (load)

• Load 接口: 定义数据加载规范
• HaQiLoad: HaQi 格式数据加载实现
  • ExternalSort: 外部排序，处理超大规模数据
  • MergeAndRemap: 数据合并与 ID 重映射

4. ID 映射层 (mapping)

• IDMapping: ID 映射接口
• MMapSortedLongIntMap: 基于内存映射的排序 Long-Int 映射表

5. 算法层 (algo)

• Algorithm 接口: 算法统一接口
• CommonNeighbor: 共同邻居算法
• KHop: K-跳邻居算法
• KHopOptimized: 优化版 K-跳算法
• WeakConnected: 弱连通分量算法, 支持动态推拉模式
• SubGraphMatching: 子图匹配算法（基于 VF3P 改进）
  • VF3P 模块: 高效的子图同构匹配算法实现

6. 服务层 (service)

• HarKinGraphServer: HTTP 服务器，提供计算服务接口
• Handler 系列: 各算法的请求处理器
  • CommonNeighborHandler
  • KHopHandler / KHopOptimizedHandler
  • WeakConnectedHandler
  • SubgraphMatchingHandler

7. 工具层 (utils)

• Args: 命令行参数解析
• GraphUtils: 图操作工具类
• JSONUtils: JSON 序列化/反序列化
• MD5Utils: MD5 哈希工具
• AtomicBitSet: 线程安全的位集合
• ProgressTracker: 进度跟踪器

数据流架构

原始数据 → Load (HaQiLoad) → ExternalSort → MergeAndRemap
         → GraphBuilder → Graph (CSR/MMap/Mix) → GraphStore
         → HarKinGraphServer → AlgorithmHandler → Algorithm → 结果返回

技术特性

• CSR 压缩存储: 高效的稀疏图存储格式
• 内存映射支持: 通过 MMap 支持超大规模图（TB 级）
• 外部排序: 处理超内存数据集
• 多种图存储模式: 内存/MMap/混合模式可选
• 高性能算法: 优化的图算法实现
• HTTP 服务: RESTful API 接口
• Java 21 Preview 特性: 利用最新 Java 特性优化性能

编译打包

环境要求

• JDK: 21 或更高版本
• Maven: 3.9+

编译命令

# 编译项目
mvn clean compile

# 打包（生成 Fat JAR，包含所有依赖）
mvn clean package

打包后会在 target/ 目录生成：

• harkin-1.0-SNAPSHOT.jar - 包含所有依赖的可执行 JAR

运行

# 运行 JAR（需要传入配置参数）
java --enable-preview -jar target/harkin-1.0-SNAPSHOT.jar [参数]

# 通过 Maven 运行
mvn exec:java

# 指定 JVM 参数运行（推荐用于大规模图）
java --enable-preview \
  -Xmx5836m \
  -XX:+UseG1GC \
  --add-opens=java.base/java.io=ALL-UNNAMED \
  -jar target/harkin-1.0-SNAPSHOT.jar [参数]

重要说明

• --enable-preview: 必需，项目使用了 Java 21 的预览特性
• --add-opens=java.base/java.io=ALL-UNNAMED: 必需，某些底层库需要访问 JDK 内部 API
• Maven Shade Plugin: 自动打包所有依赖和 SPI 配置到单个 JAR
• 主类: cn.harkingraph.HarKinLauncher

开发模式

# 在 IDE 中运行时，需要添加 VM Options:
--enable-preview --add-opens=java.base/java.io=ALL-UNNAMED

快速开始

1. 启动服务

# 编译打包
mvn clean package

# 运行服务 (指定边文件路径和加载模式)
java --enable-preview \
  -Xmx6g \
  --add-opens=java.base/java.io=ALL-UNNAMED \
  -jar target/harkin-1.0-SNAPSHOT.jar \
  data/edges.csv MIX
  
# 脚本启动模式
./start.sh data/edges.csv [MIX/DISK]
# 第一个参数路径，第二个参数模式，MIX或者DISK

参数说明：

• 参数1 (必需): 边文件路径，如 data/edges.csv
• 参数2 (可选): 加载模式，可选值：
  • MIX (默认): 混合模式，极致性能访问性能
  • DISK: 内存映射模式，支持超大图，极致优化内存占用

服务启动后监听端口：8080