hugegraph/rag-bin

HugeGraph-LLM

连接图数据库与大语言模型的桥梁

🎯 概述

HugeGraph-LLM是一个综合工具包，结合了图数据库与大语言模型的能力。它实现了HugeGraph与LLMs的无缝集成，用于构建智能应用。

核心功能

• 🏗️ 知识图谱构建 - 使用LLMs + HugeGraph自动构建知识图谱
• 🗣️ 自然语言查询 - 通过自然语言操作图数据库（支持Gremlin/Cypher）
• 🔍 图增强RAG - 利用知识图谱提高回答准确性（GraphRAG & Graph Agent）

详细源代码文档请访问我们的DeepWiki页面。（推荐）

📋 前置要求

[!IMPORTANT]

• Python: 3.10+（未在3.12上测试）
• HugeGraph Server: 1.3+（推荐：1.5+）
• UV包管理器: 0.7+

代码质量（ruff + pre-commit）

• 使用Ruff进行代码检查和格式化：
  • ruff format .
  • ruff check .
• 通过pre-commit启用Git钩子：
  • pre-commit install（在根目录执行）
  • pre-commit run --all-files
• 配置文件：../.pre-commit-config.yaml

🚀 快速开始

选择您偏好的部署方式：

选项1：Docker Compose（推荐）

同时启动HugeGraph Server和RAG服务的最快方式：

bash
# 1. 设置环境
cp docker/env.template docker/.env
# 编辑docker/.env并将PROJECT_PATH设置为实际项目路径
# 所有可用配置选项参见"config.md"
# 如果hugegraph-llm下没有.env配置文件，执行以下命令
cd hugegraph-llm && touch .env && cd ..

# 2. 部署服务
cd docker
docker-compose -f docker-compose-network.yml up -d

# 3. 验证部署
docker-compose -f docker-compose-network.yml ps

# 4. 访问服务
# HugeGraph Server: http://localhost:8080
# RAG Service: http://localhost:8001

选项2：单独Docker容器

对各个组件有更多控制需求时使用：

可用镜像

• hugegraph/rag - 开发镜像，可访问源代码
• hugegraph/rag-bin - 生产优化的二进制镜像（使用Nuitka编译）

bash
# 1. 创建网络
docker network create -d bridge hugegraph-net

# 2. 启动HugeGraph Server
docker run -itd --name=server -p 8080:8080 --network hugegraph-net hugegraph/hugegraph

# 3. 启动RAG服务
docker pull hugegraph/rag:latest
docker run -itd --name rag \
  -v /path/to/your/hugegraph-llm/.env:/home/work/hugegraph-llm/.env \
  -p 8001:8001 --network hugegraph-net hugegraph/rag

# 4. 监控日志
docker logs -f rag

选项3：从源码构建

用于开发和自定义：

bash
# 1. 启动HugeGraph Server
docker run -itd --name=server -p 8080:8080 hugegraph/hugegraph

# 2. 安装UV包管理器（如未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 3. 克隆并设置项目
git clone https://github.com/apache/incubator-hugegraph-ai.git
cd incubator-hugegraph-ai

# 配置环境（详细选项参见config.md），如不存在.env文件将自动创建

# 4. 安装依赖并激活环境
# 注意：如果下载缓慢，取消注释../pyproject.toml中的镜像行或使用：uv config --global index.url https://pypi.tuna.tsinghua.edu.cn/simple
# 或创建本地uv.toml设置镜像以避免git diff（参见根目录uv.toml示例）
uv sync --extra llm  # 自动创建.venv并安装依赖
source .venv/bin/activate  # 激活一次 - 以下所有命令均假设在此环境中

# 5. 启动RAG演示
python -m hugegraph_llm.demo.rag_demo.app
# 访问地址：http://127.0.0.1:8001

# 6.（可选）自定义主机/端口
python -m hugegraph_llm.demo.rag_demo.app --host 127.0.0.1 --port 18001

额外设置（可选）

[!NOTE] 以下命令假设您已从步骤4激活虚拟环境

bash
# 如需使用向量数据库后端（如Milvus、Qdrant），同步可选依赖：
uv sync --extra vectordb

# 下载NLTK停用词以优化文本处理
python ./src/hugegraph_llm/operators/common_op/nltk_helper.py

# 更新配置文件
python -m hugegraph_llm.config.generate --update

[!TIP]

• uv sync会自动创建虚拟环境（.venv）并安装所有依赖
• 使用source .venv/bin/activate激活一次 - 后续所有命令均假设在此环境中
• 详细使用示例参见https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph-llm/quick_start.md

💡 使用示例

知识图谱构建

交互式Web界面

使用Gradio界面进行可视化知识图谱构建：

输入选项：

• 文本：直接输入文本用于RAG索引创建
• 文件：上传TXT或DOCX文件（支持多选）

Schema配置：

• 自定义Schema：JSON格式，遵循https://github.com/apache/incubator-hugegraph-ai/blob/aff3bbe25fa91c3414947a***be812c20ef11/hugegraph-llm/src/hugegraph_llm/config/config_data.py#L125
• HugeGraph Schema：使用现有图实例schema（如"hugegraph"）

!知识图谱构建器

🔧 配置

运行演示后，配置文件会自动生成：

• 环境配置：hugegraph-llm/.env
• 提示词配置：hugegraph-llm/src/hugegraph_llm/resources/demo/config_prompt.yaml

语言支持

系统支持中英文提示词。切换语言方法：

1. 编辑.env文件：将LANGUAGE=en改为LANGUAGE=CN（或反之）
2. 重启应用：系统将自动生成所选语言的提示词

支持值：

• LANGUAGE=EN - 英文提示词（默认）
• LANGUAGE=CN - 中文提示词

[!NOTE] 使用Web界面时配置更改会自动保存。手动修改后，刷新页面即可加载更新。

LLM提供商支持：本项目使用LiteLLM实现多提供商LLM支持。

编程示例（新工作流引擎）

如果您之前使用过RAGPipeline或KgBuilder等高级类，项目现在通过Scheduler API提供稳定流程。使用SchedulerSingleton.get_instance().schedule_flow(...)以编程方式调用工作流。以下是符合新架构的简洁工作示例。

1. RAG（仅图）查询示例

python
from hugegraph_llm.flows.scheduler import SchedulerSingleton

scheduler = SchedulerSingleton.get_instance()
res = scheduler.schedule_flow(
  "rag_graph_only",
  query="Tell me about Al Pacino.",
  graph_only_answer=True,
  vector_only_answer=False,
  raw_answer=False,
  gremlin_tmpl_num=-1,
  gremlin_prompt=None,
)

print(res.get("graph_only_answer"))

2. RAG（仅向量）查询示例

python
from hugegraph_llm.flows.scheduler import SchedulerSingleton

scheduler = SchedulerSingleton.get_instance()
res = scheduler.schedule_flow(
  "rag_vector_only",
  query="Summarize the career of Ada Lovelace.",
  vector_only_answer=True,
  vector_search=True
)

print(res.get("vector_only_answer"))

3. 文本转Gremlin（text2gremlin）示例

python
from hugegraph_llm.flows.scheduler import SchedulerSingleton

scheduler = SchedulerSingleton.get_instance()
response = scheduler.schedule_flow(
  "text2gremlin",
  "find people who worked with Alan Turing",
  2,  # example_num
  "hugegraph",  # schema_input（图名称或schema）
  None,  # gremlin_prompt_input（可选）
  ["template_gremlin", "raw_gremlin"],
)

print(response.get("template_gremlin"))

4. 构建示例索引（text2gremlin示例使用）

python
from hugegraph_llm.flows.scheduler import SchedulerSingleton

examples = [{"id": "natural language query", "gremlin": "g.V().hasLabel('person').valueMap()"}]
res = SchedulerSingleton.get_instance().schedule_flow("build_examples_index", examples)
print(res)

迁移指南：RAGPipeline / KgBuilder → Scheduler流程

变更原因：内部执行引擎已重构为基于管道的调度器（GPipeline + GPipelineManager）。调度器提供稳定入口点，同时保持流程实现的模块化。

如需迁移特定代码片段，请提交PR或issue并包含旧代码，我们可提供针对性转换。

🤖 开发者指南

[!IMPORTANT] 对于使用AI编码辅助为hugegraph-llm贡献代码的开发者：

• 入门必读：首先阅读../rules/README.md了解完整的AI辅助开发工作流
• 模块上下文：将此目录中的AGENTS.md重命名为LLM的上下文文件（如CLAUDE.md、copilot-instructions.md）
• 代码分析：遵循../rules/prompts/project-deep.md中的综合分析方法
• 文档：保持../rules/prompts/project-general.md中的结构化文档标准
• 质量标准：确保类型注解、适当测试和一致的模式
• 业务逻辑：专注于图-LLM集成逻辑和RAG管道优化

这些指南确保一致的代码质量和可维护的图-AI集成。

📚 其他资源

• 图可视化：使用https://hub.docker.com/r/hugegraph/hubble%E8%BF%9B%E8%A1%8C%E6%95%B0%E6%8D%AE%E5%88%86%E6%9E%90%E5%92%8Cschema%E7%AE%A1%E7%90%86
• API文档：探索REST API端点以进行集成
• 社区：加入讨论并为项目做贡献

许可证：Apache License 2.0 | 社区：Apache HugeGraph