HugeGraph-AI

• 1: HugeGraph-LLM
• 2: HugeGraph-ML
• 3: HugeGraph-LLM 使用流程
• 4: 配置参考
• 5: HugeGraph-LLM REST API

1git clone https://github.com/apache/hugegraph-ai.git
2cd hugegraph-ai
3cp docker/env.template docker/.env
4# 编辑 docker/.env，将 PROJECT_PATH 改为当前仓库的绝对路径
5touch hugegraph-llm/.env
6cd docker
7docker compose -f docker-compose-network.yml up -d

1git clone https://github.com/apache/hugegraph-ai.git
2cd hugegraph-ai
3uv sync --extra llm
4source .venv/bin/activate
5cd hugegraph-llm
6python -m hugegraph_llm.demo.rag_demo.app

1cd hugegraph-ai
2uv sync --extra ml
3source .venv/bin/activate
4cd hugegraph-ml/src

1 - HugeGraph-LLM

HugeGraph-LLM 用于知识图谱构建、GraphRAG 和自然语言图查询。演示服务把 Gradio 页面和 FastAPI 接口挂在同一个进程上，默认监听 8001 端口。

环境要求

AI 总结项目文档：Ask DeepWiki

• Python 3.10 或 3.11
• uv 0.7 或更高版本
• HugeGraph Server 1.5 或更高版本

Docker Compose 部署

在 HugeGraph-AI 仓库根目录准备环境文件：

1git clone https://github.com/apache/hugegraph-ai.git
2cd hugegraph-ai
3cp docker/env.template docker/.env
4# 编辑 docker/.env，将 PROJECT_PATH 改为当前仓库的绝对路径
5touch hugegraph-llm/.env
6cd docker
7docker compose -f docker-compose-network.yml up -d
8docker compose -f docker-compose-network.yml ps

启动后可访问：

• HugeGraph Server：http://localhost:8080
• RAG 服务和 Web 页面：http://localhost:8001

从源码启动

依赖应从仓库根目录按 workspace 安装：

1git clone https://github.com/apache/hugegraph-ai.git
2cd hugegraph-ai
3uv sync --extra llm
4source .venv/bin/activate
5cd hugegraph-llm
6python -m hugegraph_llm.demo.rag_demo.app

自定义监听地址和端口：

1python -m hugegraph_llm.demo.rag_demo.app \
2  --host 127.0.0.1 \
3  --port 18001

服务以 hugegraph-llm/.env 保存模型、HugeGraph 和登录配置。提示词放在 hugegraph-llm/src/hugegraph_llm/resources/demo/config_prompt.yaml。缺少文件时，配置代码会按默认值创建。

主要功能

构建 RAG 索引

Web 页面的第一个标签页可以处理文本或文件，并执行以下操作：

1. 切分文本并写入 chunk 向量索引。
2. 按给定 Schema 从文本抽取顶点和边。
3. 将抽取结果写入 HugeGraph，并更新顶点向量索引。

Schema 可以是内联 JSON，也可以是现有图名。通过 REST API 使用图名时，必须同时传入匹配的 client_config.graph；内联 JSON 不会连接 HugeGraph，也不能附带 client_config。

GraphRAG

查询流程可以组合直接回答、chunk 向量召回和图召回。图召回先抽取关键词并匹配顶点，再尝试 Text2Gremlin；生成或执行失败时可回退到预定义的图遍历方式。请求参数可控制返回数量、向量距离阈值、模板数量和重排序方式。

Text2Gremlin

POST /text2gremlin 根据自然语言、图 Schema 和可选示例生成 Gremlin。自定义提示词必须保留 {query}、{schema}、{example} 和 {vertices} 四个占位符。

模型与向量后端

聊天、信息抽取和 Text2Gremlin 可以分别使用 OpenAI 兼容接口、Ollama 或 LiteLLM。嵌入模型也可以独立选择。默认向量索引使用 FAISS；安装 vectordb 可选依赖后，还可配置 Milvus 或 Qdrant：

1cd hugegraph-ai
2uv sync --package hugegraph-llm --extra vectordb

完整环境变量见配置参考，HTTP 请求格式见REST API。

开发检查

1cd hugegraph-ai
2./style/code_format_and_analysis.sh
3cd hugegraph-llm
4pytest

2 - HugeGraph-ML

HugeGraph-ML 从 HugeGraph 读取图数据并转换为 DGL 图，供节点嵌入、节点分类和图分类等任务使用。模型实现位于 hugegraph-ml/src/hugegraph_ml/models/。

环境要求

• Python 3.10 或更高版本
• HugeGraph Server 1.0 或更高版本，推荐 1.5 及以上版本
• uv 0.7 或更高版本

安装

1git clone https://github.com/apache/hugegraph-ai.git
2cd hugegraph-ai
3uv sync --extra ml
4source .venv/bin/activate
5cd hugegraph-ml/src

HugeGraph-ML 是根项目的路径依赖，但不属于 uv workspace members。应在仓库根目录选择 ml extra，不要在子目录建立另一套锁文件。

已实现模型

当前 README 列出的模型如下：

源码中还包含 GIN 图分类实现和供下游分类使用的 MLPClassifier。模型数量会随版本变化，以 src/hugegraph_ml/models/ 为准。

DGI 节点嵌入示例

先把 DGL 的 Cora 数据集导入 HugeGraph：

1from hugegraph_ml.utils.dgl2hugegraph_utils import import_graph_from_dgl
2
3import_graph_from_dgl("cora")

读取图并训练 DGI：

 1from hugegraph_ml.data.hugegraph2dgl import HugeGraph2DGL
 2from hugegraph_ml.models.dgi import DGI
 3from hugegraph_ml.models.mlp import MLPClassifier
 4from hugegraph_ml.tasks.node_classify import NodeClassify
 5from hugegraph_ml.tasks.node_embed import NodeEmbed
 6
 7hg2d = HugeGraph2DGL()
 8graph = hg2d.convert_graph(
 9    vertex_label="CORA_vertex",
10    edge_label="CORA_edge",
11)
12
13embed_model = DGI(n_in_feats=graph.ndata["feat"].shape[1])
14embed_task = NodeEmbed(graph=graph, model=embed_model)
15embedded_graph = embed_task.train_and_embed(
16    add_self_loop=True,
17    n_epochs=300,
18    patience=30,
19)
20
21classifier = MLPClassifier(
22    n_in_feat=embedded_graph.ndata["feat"].shape[1],
23    n_out_feat=embedded_graph.ndata["label"].unique().shape[0],
24)
25classify_task = NodeClassify(graph=embedded_graph, model=classifier)
26classify_task.train(lr=1e-3, n_epochs=400, patience=40)
27print(classify_task.evaluate())

完整脚本是 hugegraph-ml/src/hugegraph_ml/examples/dgi_example.py。

GRAND 节点分类示例

 1from hugegraph_ml.data.hugegraph2dgl import HugeGraph2DGL
 2from hugegraph_ml.models.grand import GRAND
 3from hugegraph_ml.tasks.node_classify import NodeClassify
 4
 5hg2d = HugeGraph2DGL()
 6graph = hg2d.convert_graph(
 7    vertex_label="CORA_vertex",
 8    edge_label="CORA_edge",
 9)
10model = GRAND(
11    n_in_feats=graph.ndata["feat"].shape[1],
12    n_out_feats=graph.ndata["label"].unique().shape[0],
13)
14task = NodeClassify(graph, model)
15task.train(lr=1e-2, weight_decay=5e-4, n_epochs=2000, patience=100)
16print(task.evaluate())

完整脚本是 hugegraph-ml/src/hugegraph_ml/examples/grand_example.py。

排查问题

• 连接失败：检查 HugeGraph Server 地址、端口和认证信息。
• Schema 不匹配：示例默认使用 CORA_vertex 和 CORA_edge，自有数据需要传入实际标签。
• DGL 或 PyTorch 导入失败：回到仓库根目录重新执行 uv sync --extra ml，并确认当前 Python 来自根目录 .venv。

3 - HugeGraph-LLM 使用流程

本文说明 HugeGraph-LLM Web 页面的处理流程。服务启动方式见 HugeGraph-LLM。

1. 构建 RAG 索引

第一个标签页负责两类索引：

• 将文档切分后写入 chunk 向量索引。
• 按 Schema 从文档抽取顶点和边，写入 HugeGraph，并维护顶点向量索引。

flowchart TD
    A[输入文档] --> B[文本切分]
    B --> C[生成 chunk 向量]
    C --> D[写入向量索引]
    B --> E[LLM 按 Schema 抽取顶点和边]
    E --> F[写入 HugeGraph]
    F --> G[更新顶点向量索引]

页面包含文档、Schema、抽取提示词和结果区域。常用操作有：

1. Import into Vector：切分文档并建立 chunk 向量索引。
2. Extract Graph Data：按 Schema 抽取图数据。
3. Load into GraphDB：把抽取结果写入 HugeGraph，并更新顶点向量。
4. Update Vid Embedding：重新生成顶点向量。

页面还可以查看或清除 chunk 索引、顶点索引和图数据。清除操作会删除已有数据，执行前先确认当前图和索引是否仍被其他查询使用。

2. GraphRAG 查询

第二个标签页提供四种回答范围：

• 直接使用 LLM 回答。
• 只使用 chunk 向量召回。
• 只使用图召回。
• 合并图召回与向量召回。

flowchart TD
    Q[问题] --> V[查询 chunk 向量索引]
    Q --> K[抽取关键词]
    K --> M[匹配图顶点]
    M --> T[生成并执行 Gremlin]
    T -->|失败| B[BFS 图遍历回退]
    T --> R[整理图结果]
    B --> R
    V --> S[合并与重排序]
    R --> S
    S --> A[生成答案]

图召回先用关键词精确匹配 HugeGraph 顶点，找不到时再用顶点向量做近似匹配。匹配结果会进入 Text2Gremlin；生成或执行失败时，流程可以回退到预定义的图遍历。

Template Num 控制 Text2Gremlin 使用的示例数量。小于等于 0 表示不提供模板，大于 0 表示从示例索引中取相应数量的相近模板。

3. Text2Gremlin

第三个标签页把自然语言转换成 Gremlin：

1. 读取当前图的 Schema。
2. 从示例向量索引取回相近的自然语言与 Gremlin 对。
3. 把问题、Schema、示例和已匹配顶点填入提示词。
4. 调用 LLM 生成 Gremlin，并按所选输出类型决定是否执行。

自定义提示词必须包含 {query}、{schema}、{example} 和 {vertices}。缺少任一占位符时，REST API 会拒绝请求。

4. 图工具与管理工具

Graph Tools 标签页用于直接执行图操作。Admin Tools 提供日志等管理能力。启用登录后，页面和 API 需要使用 USER_TOKEN；日志接口还要求单独配置安全的 ADMIN_TOKEN。

5. 提示词语言

在 hugegraph-llm/.env 中设置：

1# 英文提示词
2LANGUAGE=EN
3
4# 中文提示词
5LANGUAGE=CN

修改后重启服务。该配置选择内置提示词语言，不会自动翻译输入文档，也不是 /rag 请求体字段。

6. REST 调用

Web 页面和 REST API 使用同一套流程。需要程序集成时使用 /rag、/rag/graph、/graph/extract 和 /text2gremlin；请求结构见 REST API。

4 - 配置参考

HugeGraph-LLM 从 hugegraph-llm/.env 读取运行配置。提示词单独保存在 hugegraph-llm/src/hugegraph_llm/resources/demo/config_prompt.yaml，不会写入 .env。

运行以下命令可按配置类的默认值创建或更新文件：

1cd hugegraph-ai/hugegraph-llm
2python -m hugegraph_llm.config.generate --update

.env 包含密钥和密码，不要提交到版本库。

基础选项

OpenAI 兼容接口

聊天、抽取和 Text2Gremlin 可以使用不同端点、密钥和模型。

API 地址默认是 https://api.openai.com/v1；三个语言模型默认是 gpt-4.1-mini，嵌入模型默认是 text-embedding-3-small。

OPENAI_BASE_URL 和 OPENAI_API_KEY 可作为通用回退值。嵌入模型另有 OPENAI_EMBEDDING_BASE_URL 和 OPENAI_EMBEDDING_API_KEY 回退值。

LiteLLM

三个语言模型默认是 openai/gpt-4.1-mini，嵌入模型默认是 openai/text-embedding-3-small。模型名通常使用 供应商/模型 格式，具体取值由 LiteLLM 服务决定。

Ollama

主机默认是 127.0.0.1，端口默认是 11434，模型名没有默认值。使用前先在 Ollama 中拉取对应模型。

重排序

HugeGraph 连接与召回限制

外部向量数据库

默认实现可以使用本地 FAISS。启用可选依赖后还可配置：

安装对应依赖：

1cd hugegraph-ai
2uv sync --package hugegraph-llm --extra vectordb

登录与日志接口

ADMIN_TOKEN 为空或仍为 xxxx 时，/logs 会直接返回 403。生产环境应同时替换用户 token 和管理员 token。

最小 OpenAI 配置

 1LANGUAGE=CN
 2CHAT_LLM_TYPE=openai
 3EXTRACT_LLM_TYPE=openai
 4TEXT2GQL_LLM_TYPE=openai
 5EMBEDDING_TYPE=openai
 6
 7OPENAI_API_KEY=your-api-key
 8OPENAI_BASE_URL=https://api.openai.com/v1
 9OPENAI_CHAT_LANGUAGE_MODEL=gpt-4.1-mini
10OPENAI_EXTRACT_LANGUAGE_MODEL=gpt-4.1-mini
11OPENAI_TEXT2GQL_LANGUAGE_MODEL=gpt-4.1-mini
12OPENAI_EMBEDDING_MODEL=text-embedding-3-small
13
14GRAPH_URL=127.0.0.1:8080
15GRAPH_NAME=hugegraph
16GRAPH_USER=admin
17GRAPH_PWD=your-password

配置加载

配置类先提供代码默认值，再从 .env 和进程环境读取覆盖值。Web 页面和配置 API 可以在运行时更新当前设置，并把受支持的字段同步回 .env。手工改动 .env 后应重启服务；提示词 YAML 可由页面加载逻辑刷新。

配置定义位于：

• hugegraph-llm/src/hugegraph_llm/config/llm_config.py
• hugegraph-llm/src/hugegraph_llm/config/hugegraph_config.py
• hugegraph-llm/src/hugegraph_llm/config/admin_config.py
• hugegraph-llm/src/hugegraph_llm/config/prompt_config.py

5 - HugeGraph-LLM REST API

HugeGraph-LLM 演示进程同时提供 Web 页面和 REST API。默认地址是 http://localhost:8001：

1cd hugegraph-ai/hugegraph-llm
2python -m hugegraph_llm.demo.rag_demo.app \
3  --host 127.0.0.1 \
4  --port 8001

认证

在 .env 中启用登录：

1ENABLE_LOGIN=True
2USER_TOKEN=replace-with-a-secret

启用后，请求需要 Bearer token：

1Authorization: Bearer replace-with-a-secret

RAG

POST /rag

根据开关返回一种或多种回答。未显式指定时只启用 graph_only。

 1curl -X POST http://localhost:8001/rag \
 2  -H 'Content-Type: application/json' \
 3  -d '{
 4    "query": "Al Pacino 出演过哪些电影？",
 5    "raw_answer": false,
 6    "vector_only": false,
 7    "graph_only": true,
 8    "graph_vector_answer": false,
 9    "max_graph_items": 30,
10    "topk_return_results": 20,
11    "vector_dis_threshold": 0.9,
12    "topk_per_keyword": 1,
13    "gremlin_tmpl_num": 1,
14    "client_config": {
15      "url": "127.0.0.1:8080",
16      "graph": "hugegraph",
17      "user": "admin",
18      "pwd": "admin",
19      "gs": "DEFAULT"
20    }
21  }'

响应只包含已启用的回答字段：

1{
2  "query": "Al Pacino 出演过哪些电影？",
3  "graph_only": "..."
4}

其他可选参数包括 graph_ratio、rerank_method（bleu 或 reranker）、near_neighbor_first、custom_priority_info，以及三类自定义提示词。

POST /rag/graph

只执行图召回，不生成最终自然语言答案：

1curl -X POST http://localhost:8001/rag/graph \
2  -H 'Content-Type: application/json' \
3  -d '{
4    "query": "Al Pacino 出演过哪些电影？",
5    "get_vertex_only": false,
6    "gremlin_tmpl_num": 1,
7    "rerank_method": "bleu"
8  }'

响应的 graph_recall 可能包含 keywords、match_vids、gremlin、graph_result 和 vertex_degree_list。设置 get_vertex_only=true 可在顶点匹配后提前返回。

图抽取

POST /graph/extract

使用内联 Schema 时不会连接 HugeGraph：

 1curl -X POST http://localhost:8001/graph/extract \
 2  -H 'Content-Type: application/json' \
 3  -d '{
 4    "texts": ["Alice 在 Acme 工作。"],
 5    "schema": {
 6      "vertexlabels": [
 7        {"name": "person", "properties": ["name"]},
 8        {"name": "company", "properties": ["name"]}
 9      ],
10      "edgelabels": [
11        {
12          "name": "works_at",
13          "source_label": "person",
14          "target_label": "company",
15          "properties": []
16        }
17      ]
18    },
19    "language": "zh",
20    "split_type": "sentence",
21    "include_meta": true
22  }'

texts 可以是字符串或字符串数组。language 可选 zh、en，split_type 可选 document、paragraph、sentence。

若 schema 传现有图名，必须同时传入 client_config，且 client_config.graph 必须和图名相同：

 1{
 2  "texts": "Alice 在 Acme 工作。",
 3  "schema": "hugegraph",
 4  "client_config": {
 5    "graph": "hugegraph",
 6    "user": "admin",
 7    "pwd": "admin",
 8    "gs": "DEFAULT"
 9  }
10}

成功响应固定包含 status、result.vertices、result.edges、warnings 和 meta。

Text2Gremlin

POST /text2gremlin

1curl -X POST http://localhost:8001/text2gremlin \
2  -H 'Content-Type: application/json' \
3  -d '{
4    "query": "查找所有 person 顶点",
5    "example_num": 1,
6    "output_types": ["template_gremlin", "template_execution_result"]
7  }'

output_types 可包含：

• match_result
• template_gremlin
• raw_gremlin
• template_execution_result
• raw_execution_result

省略该字段时默认只返回 template_gremlin；传空数组表示由实现返回全部输出。自定义 gremlin_prompt 必须包含 {query}、{schema}、{example} 和 {vertices}。

运行时配置

POST /config/graph

1{
2  "url": "127.0.0.1:8080",
3  "graph": "hugegraph",
4  "user": "admin",
5  "pwd": "admin",
6  "gs": "DEFAULT"
7}

POST /config/llm 与 POST /config/embedding

两个端点使用同一个请求模型。OpenAI 或 LiteLLM 示例：

1{
2  "llm_type": "openai",
3  "api_key": "your-key",
4  "api_base": "https://api.openai.com/v1",
5  "language_model": "gpt-4.1-mini",
6  "max_tokens": "4096"
7}

Ollama 请求仍要提供公共字段；api_key 和 api_base 可传空字符串：

1{
2  "llm_type": "ollama/local",
3  "api_key": "",
4  "api_base": "",
5  "language_model": "qwen2.5:7b",
6  "host": "127.0.0.1",
7  "port": "11434"
8}

POST /config/rerank

1{
2  "reranker_type": "siliconflow",
3  "reranker_model": "BAAI/bge-reranker-v2-m3",
4  "api_key": "your-key"
5}

reranker_type 可选 cohere、siliconflow。Cohere 还可以传 cohere_base_url。

这些配置端点会改动进程当前配置，并可能同步到 .env。/rag、/rag/graph 和 /text2gremlin 的 client_config 只在单次请求期间覆盖 HugeGraph 连接；当前实现仍会临时改动进程全局设置，不适合用不同连接并发发起长请求。

日志

POST /logs

该接口要求 .env 中的 ADMIN_TOKEN 已改成安全值。请求体示例：

1{
2  "admin_token": "replace-with-an-admin-secret",
3  "log_file": "llm-server.log"
4}

log_file 只能是 logs/ 目录下的文件名，不能包含路径分隔符。