HugeGraph-AI

• 1: HugeGraph-LLM
• 2: HugeGraph-ML
• 3: HugeGraph-LLM 使用流程
• 4: 配置参考
• 5: HugeGraph-LLM REST API
• 6: Vermeer Python 客户端

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
6# 在 hugegraph-llm/.env 中设置 GRAPH_URL=server:8080，并填写匹配 Server 的账号
7cd docker
8docker 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 接口挂在同一个进程上，直接从源码启动时默认只监听本机 127.0.0.1:8001，可用 http://localhost:8001 访问。若显式启动源码入口且只需本机访问，可指定 --host 127.0.0.1；源码 Docker 镜像的 Dockerfile.llm 会覆盖默认值并监听 0.0.0.0:8001，不要在容器内改为 loopback，否则容器外无法通过映射端口访问。

环境要求

AI 总结项目文档：Ask DeepWiki

• Python 3.10 或 3.11（>=3.10,<3.12）
• uv 0.7 或更高版本
• HugeGraph Server 1.5.0 或更高版本；当前 workspace 中的 Python 客户端会拒绝可探测到的更低版本

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
6# 编辑 hugegraph-llm/.env：GRAPH_URL=server:8080，并设置与 Server 相符的 GRAPH_USER、GRAPH_PWD
7cd docker
8docker compose -f docker-compose-network.yml up -d
9docker compose -f docker-compose-network.yml ps

启动后可访问：

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

Compose 文件会把 ${PROJECT_PATH}/hugegraph-llm/.env 挂载到容器内的 /home/work/hugegraph-llm/.env，因此该文件必须在容器启动前存在。资源目录 hugegraph-llm/src/hugegraph_llm/resources 也可以用同样方式挂载，该挂载默认被注释掉。

应用读取 GRAPH_URL，Compose 注入的 HUGEGRAPH_HOST 和 HUGEGRAPH_PORT 不会覆盖它；因此容器内要将 GRAPH_URL 设为 server:8080，并在 .env 中配置匹配 HugeGraph Server 的用户名和密码。

容器镜像

Compose 文件引用未指定标签的 hugegraph/rag，Docker 会使用默认的 latest 标签。scripts/build_llm_image.sh 则以 docker/Dockerfile.llm 在本地构建 hugegraph/graphrag:1.7.0。Compose 引用的 hugegraph/rag:latest 与本地构建的 hugegraph/graphrag:1.7.0 是不同镜像；本地构建不会自动替换 Compose 所用镜像。要在 Compose 中运行本地构建结果，需将 Compose 的 image 改为 hugegraph/graphrag:1.7.0。该脚本只构建镜像，不会推送。两个 Dockerfile 都声明 8001 端口、以非 root 用户 work 运行，并用 curl -f http://localhost:8001/ 做镜像健康检查；两者都为资源目录声明数据卷。

scripts/build_llm_image.sh 会用 docker/Dockerfile.llm 构建并打上 hugegraph/graphrag:1.7.0 标签。

Kubernetes 部署

docker/charts/hg-llm 是 RAG 服务的 Helm chart，部署 hugegraph/graphrag 镜像。默认发布 NodePort 类型的 Service，把节点端口 8039 和服务端口 8080 映射到容器端口 8001，名称固定为 hg-llm-service。Ingress 和水平自动扩缩容已定义但默认关闭。

该 chart 只部署 RAG 服务，不会部署 HugeGraph Server。挂载的 .env 中要把 GRAPH_URL 设为 Pod 可访问的 HugeGraph 地址，并配置匹配的用户名和密码。

chart 中 image.tag 仍默认为 v0.0.1。当前构建脚本生成的标签是本地 hugegraph/graphrag:1.7.0；部署前须确保同名镜像已推送到集群可访问的仓库，或已加载到集群节点，并将 chart 的标签和拉取策略设为匹配的值。

chart 的 values.yaml 中，.env 和提示词 YAML 的挂载默认被注释掉。提示词 YAML 可用 ConfigMap；.env 可能含有密钥和密码，应使用 Secret，并把 volumes 中 env-config 的 configMap 改为 secret。Secret 和提示词 ConfigMap 可分别创建：

1kubectl create secret generic hugegraph-llm-env --from-file=.env=/path/to/.env
2kubectl create configmap hugegraph-llm-prompt-config --from-file=/path/to/config_prompt.yaml

随后取消 volumeMounts 段落的注释，并按需要启用提示词 ConfigMap 的 volumes 和挂载。Helm 模板会直接渲染 values.yaml 中的卷定义。

从源码启动

依赖应从仓库根目录按 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

设置 HG_DEV_RELOAD=1 可让 uvicorn 以自动重载方式启动，便于开发调试。

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

.env 路径按以下顺序解析：先看是否设置了 HUGEGRAPH_LLM_ENV_PATH；未设置时，从源码运行则使用 hugegraph-llm/.env；否则使用当前工作目录下的 .env。

主要功能

构建 RAG 索引

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

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

文本可以在 text 子页直接输入，也可以在 file 子页上传。上传支持 .txt、.docx 和 .pdf，并可一次选择多个文件。加密 PDF 以及没有可提取文本层的扫描件 PDF 会被拒绝。

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

该标签页还提供两个生成器。Graph Schema Generator 根据查询示例和少样本示例生成 Schema。Graph Extraction Prompt Generator 根据描述的场景和选定的参考示例生成抽取提示词。Graph Extraction Split Type 下拉框可在抽取前选择 document、paragraph 或 sentence 粒度。

GraphRAG

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

同一标签页还有批量回归测试面板，可从 .xlsx 或 .csv 文件读取问题、逐条作答，并返回可下载的结果文件。上传控件旁提供模板文件下载。

Text2Gremlin

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

对应的页面标签可以先用问题与 Gremlin 对照文件（.json 或 .csv）构建示例向量索引。未上传文件时使用内置的 resources/demo/text2gremlin.csv。

图工具与管理工具

Graph Tools 标签页可直接执行 Gremlin 查询、手动触发图备份，以及初始化 HugeGraph 演示数据。Admin Tools 标签页在校验 ADMIN_TOKEN 后展示 logs/llm-server.log 的末尾内容，并可刷新或清空该文件。

进程运行期间还有两个后台任务：每天 01:00 执行图备份的定时任务，以及持续更新顶点 id 向量的任务。

模型与向量后端

聊天、信息抽取和 Text2Gremlin 可以分别使用 OpenAI 兼容接口、Ollama 或 LiteLLM。嵌入模型可独立选择，同样支持这三种提供方。重排序支持 Cohere 和 SiliconFlow。

默认向量索引使用 FAISS。CUR_VECTOR_INDEX 可选 Faiss、Milvus 或 Qdrant，Web 页面的 5. Set up the vector engine. 面板提供同样的选择。Milvus 和 Qdrant 需要安装可选依赖：

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

页面操作流程见使用流程，完整环境变量见配置参考，HTTP 请求格式见REST API。

程序化调用

原有的 RAGPipeline 和 KgBuilder 类已被流水线调度器取代。通过 SchedulerSingleton 按名称调用流程：

 1from hugegraph_llm.flows.scheduler import SchedulerSingleton
 2
 3scheduler = SchedulerSingleton.get_instance()
 4res = scheduler.schedule_flow(
 5    "rag_graph_only",
 6    query="Tell me about Al Pacino.",
 7    graph_only_answer=True,
 8    vector_only_answer=False,
 9    raw_answer=False,
10    gremlin_tmpl_num=-1,
11    gremlin_prompt=None,
12)
13print(res.get("graph_only_answer"))

已注册的流程名包括 rag_raw、rag_vector_only、rag_graph_only、rag_graph_vector、text2gremlin、build_examples_index、build_vector_index、graph_extract、import_graph_data、update_vid_embeddings、get_graph_index_info、build_schema 和 prompt_generate。schedule_stream_flow 是对应的异步流式版本。

开发检查

先在仓库根目录安装模块和开发工具，再运行与 CI 一致的检查：

 1cd hugegraph-ai
 2uv sync --extra llm --extra dev
 3uv run ruff format --check .
 4uv run ruff check .
 5
 6cd hugegraph-llm
 7SKIP_EXTERNAL_SERVICES=true uv run pytest src/tests/config/ src/tests/document/ src/tests/middleware/ \
 8  src/tests/operators/ src/tests/models/ src/tests/indices/ src/tests/test_utils.py -v --tb=short
 9SKIP_EXTERNAL_SERVICES=true uv run pytest src/tests/integration/test_graph_rag_pipeline.py \
10  src/tests/integration/test_kg_construction.py src/tests/integration/test_rag_pipeline.py -v --tb=short

Git hook 通过 pre-commit 启用：

1cd hugegraph-ai
2pre-commit install
3pre-commit run --all-files

2 - HugeGraph-ML

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

环境要求

• Python 3.10 或更高版本
• HugeGraph Server 1.5.0 或更高版本；当前 workspace 中的 Python 客户端会拒绝可探测到的更低版本
• uv 0.7 或更高版本

所有服务端访问都通过同一仓库中的 hugegraph-python-client（即 pyhugegraph 包）完成。HugeGraph2DGL 使用 Gremlin 接口的 g.V().hasLabel(...) 和 g.E().hasLabel(...) 拉取点边，数据集导入函数则通过 schema 接口和顶点、边的批量接口写入，每批 500 条。

ML 依赖在仓库根目录的 [tool.uv] constraint-dependencies 中声明版本约束：

这些约束限定依赖版本，不指定 CPU 或 CUDA 构建。支持 gpu 参数的任务默认值 -1 表示使用 CPU；使用 GPU 时，需要安装彼此兼容的 CUDA 版 torch 和 dgl。

安装

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，让 uv 按 workspace 配置安装它及其本地客户端依赖。

已实现模型

下列模块均位于 hugegraph-ml/src/hugegraph_ml/models/。models/__init__.py 不做任何再导出，需要直接从模块文件导入。

GIN 的 pooling 参数可取 sum（默认）、mean、max、global_attention 和 set2set。

读取图数据

hugegraph-ml/src/hugegraph_ml/data/hugegraph2dgl.py 中的 HugeGraph2DGL 会创建 PyHugeClient，并把查询结果转换为 DGL 对象：

1from hugegraph_ml.data.hugegraph2dgl import HugeGraph2DGL
2
3hg2d = HugeGraph2DGL(
4    url="http://127.0.0.1:8080",
5    graph="hugegraph",
6    user="",
7    pwd="",
8    graphspace=None,
9)

节点特征写入 ndata["feat"]，标签写入 ndata["label"]，各掩码写入 ndata[<mask key>]。NodeEmbed 只要求 feat；NodeClassify、NodeClassifyWithEdge 和 NodeClassifyWithSample 要求 feat、label、train_mask、val_mask 和 test_mask，缺少任意一项都会抛出 ValueError。

导入示例数据集

hugegraph_ml.utils.dgl2hugegraph_utils 负责把 DGL、OGB 和 NetworkX 数据集写入 HugeGraph，供转换层读取。这些函数都接受与 HugeGraph2DGL 相同的 url、graph、user、pwd 和 graphspace 参数，并且多数会先把数据集名转为大写再匹配。

传入其他名称会抛出 ValueError("dataset not supported")。import_split_edge_from_ogb 还需要顶点导入返回的 idx_to_vertex_id 映射和 max_nodes 上限。

clear_all_data() 会清空目标图中的全部点和边。测试 fixture 先调用它，再导入 CORA、MUTAG 和 ACM，结束时再次调用。

AMAZONGATNE 和 AVAZU 不会自动下载，压缩包地址写在 import_hetero_graph_from_dgl_no_feat 和 import_hetero_graph_from_dgl_bgnn 上方的注释里。

任务

任务类位于 hugegraph-ml/src/hugegraph_ml/tasks/，均接收转换后的图和模型实例。

patience 默认值为 float("inf")。utils/early_stopping.py 中的 EarlyStopping 可以监控 loss 或 accuracy，保存最优权重并在训练结束时恢复。

可运行示例

脚本位于 hugegraph-ml/src/hugegraph_ml/examples/。在 hugegraph-ml/src 目录下执行：

1python ./hugegraph_ml/examples/dgi_example.py

每个脚本同时提供同名函数，可以导入后用较小的 epoch 数调用。

DGI 节点嵌入示例

先把 DGL 的 Cora 数据集导入 HugeGraph。数据集名会先转为大写，因此 cora 和 CORA 都会生成 CORA_vertex 和 CORA_edge 标签：

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())

evaluate() 返回类似 {'accuracy': 0.82, 'loss': 0.5714246034622192} 的字典。完整脚本是 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())

GRAND 每次增强采样都会返回一组 logits，NodeClassify 会对列表中的每个元素分别应用掩码后再计算损失。完整脚本是 hugegraph-ml/src/hugegraph_ml/examples/grand_example.py。

排查问题

• 连接失败：检查 HugeGraph Server 地址、端口和认证信息。
• Schema 不匹配：示例默认使用 CORA_vertex 和 CORA_edge，自有数据需要传入实际标签。
• ValueError: Graph is missing required node attribute ...：节点分类任务需要 ndata 中包含 feat、label、train_mask、val_mask 和 test_mask。请导入带掩码的数据集，或给 convert_graph 传入自定义的 mask_keys。
• ValueError: dataset not supported：导入函数只接受上表列出的名称，且 import_graph_from_ogb 匹配 ogbl-collab 时不做大写转换。
• DGL 或 PyTorch 导入失败：回到仓库根目录重新执行 uv sync --extra ml，并确认当前 Python 来自根目录 .venv。
• bgrl_example.py 目前在导入阶段就会失败：它从 hugegraph_ml.models.bgrl 导入 MLP_Predictor，而该模块中的类名是 MLPPredictor。
• care_gnn_example.py 读取 AMAZON_user_v 和三个 AMAZON_net_*_e 边标签，仓库内没有对应的导入函数，需要自行准备该数据集后再运行。

3 - HugeGraph-LLM 使用流程

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

0. 配置面板

标签页上方是可折叠的配置面板，共五个部分：1. Set up the HugeGraph server.、2. Set up the LLM.、3. Set up the Embedding.、4. Set up the Reranker. 和 5. Set up the vector engine.。每部分都有独立的应用按钮，应用后会把受支持的字段写回 .env。页面顶部还会显示当前提示词语言。

1. 构建 RAG 索引

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

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

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

输入来自 text 子页或 file 子页。上传支持 .txt、.docx 和 .pdf，可一次选择多个文件。

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

1. Import into Vector：切分文档并建立 chunk 向量索引。
2. Extract Graph Data (1)：按 Schema 抽取图数据。
3. Load into GraphDB (2)：把抽取结果写入 HugeGraph，并自动更新顶点向量。
4. Update Vid Embedding：重新生成顶点向量，通常只在图中已有数据时才需要单独执行。

这些按钮旁的 Graph Extraction Split Type 下拉框可选 document、paragraph 或 sentence。document 把输入整体作为一个单元，另外两种会在抽取前先切分长文档。

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

主控件下方还有两个折叠的辅助工具：

• Graph Schema Generator：根据查询示例和少样本示例生成 Schema，填入 Graph Schema 字段。
• Graph Extraction Prompt Generator：根据期望场景（例如社交关系、金融知识图谱）和选定的参考示例生成 Graph Extract Prompt Header。

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：完全跳过 Text2Gremlin，图召回直接使用预定义的图遍历。
• 等于 0：不带任何示例生成 Gremlin（zero-shot）。
• 大于 0：从示例索引中取相应数量的相近示例，并采用带模板的生成结果。示例数量会被限制在 0 到 10 之间。

该标签页的其他控件还有 Rerank method（bleu 或 reranker）、Graph Ratio、Near neighbor first 和 Query related information，以及可编辑的 Query Prompt 和 Keywords Extraction Prompt。

单条问答面板下方是批量回归测试面板。上传 .xlsx 或 .csv 问题文件，设置 Max Lines To Show，点击 Generate Answer (Batch)。答案会显示在预览表格中，并可下载为文件。上传控件旁提供模板文件下载。

3. Text2Gremlin

第三个标签页分为两部分。上半部分用问题与 Gremlin 对照文件（.json 或 .csv）构建示例向量索引；未上传文件时使用内置的 resources/demo/text2gremlin.csv。

下半部分把自然语言转换成 Gremlin：

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

Number of refer examples 设置取回的示例数量，范围 0 到 10，默认 2。结果显示在四个字段中：带模板的 Gremlin、不带模板的 Gremlin，以及两者各自的执行输出。

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

4. 图工具与管理工具

Graph Tools 标签页可直接对当前图执行 Gremlin 查询、手动触发图备份，并通过 beta 操作初始化 HugeGraph 演示数据。后台还有两个任务：每天 01:00 自动备份图数据，以及在进程运行期间持续更新顶点 id 向量。

Admin Tools 需要密码。输入已配置的 ADMIN_TOKEN 后可查看 logs/llm-server.log 的末尾内容（每 60 秒自动刷新），并可手动刷新或清空该文件。ADMIN_TOKEN 为空或仍是占位值 xxxx 时，访问会被拒绝。

设置 ENABLE_LOGIN=True 后，Web 页面会要求基础认证，用户名固定为 rag，密码是 USER_TOKEN；REST API 则要求把 USER_TOKEN 作为 Bearer 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 从 .env 读取运行配置，提示词单独保存在 config_prompt.yaml。两者使用不同的路径解析规则；不要把提示词文件当作 .env 的一部分。

.env 路径按以下顺序解析：

1. 若设置了环境变量 HUGEGRAPH_LLM_ENV_PATH，则使用该路径，开头的 ~ 会被展开。
2. 从源码运行时，使用 hugegraph-llm/.env。
3. 以已安装的包运行时，使用当前工作目录下的 .env。

该路径在导入配置模块时确定。设置 HUGEGRAPH_LLM_ENV_PATH 时，需在启动 Python 进程前设置；不能只把它写进将要读取的 .env 文件。覆盖路径使用相对路径时，以进程当前工作目录为基准。

提示词 YAML 路径按以下顺序解析：

1. 若进程环境中设置了 HUGEGRAPH_LLM_PROMPT_CONFIG_PATH，使用该路径，并展开开头的 ~。
2. 从源码运行时，使用 hugegraph-llm/src/hugegraph_llm/resources/demo/config_prompt.yaml。
3. 以已安装的包运行时，使用 ${XDG_CONFIG_HOME:-~/.config}/hugegraph-llm/config_prompt.yaml。

覆盖路径的环境变量也要在进程启动前设置。相对路径以进程当前工作目录为基准。源码 Docker 镜像通过 PYTHONPATH 指向源码目录，因此默认提示词路径仍位于 hugegraph-llm/src/hugegraph_llm/resources/demo/。

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

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

--update 默认开启，因此不带参数运行效果相同。配置模块首次导入时会为缺失的 .env 和提示词 YAML 按默认值创建文件；文件已存在时，生成器会交互询问是否覆盖。该命令会处理 HugeGraph、管理员、LLM、索引配置及提示词 YAML，不会在无确认的情况下覆盖已有文件。

.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 在本地运行，无需额外依赖。未安装可选依赖就选择 Milvus 或 Qdrant 时，会报错并指出缺少的包，因此需要先安装：

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

Web 页面的 5. Set up the vector engine. 面板提供同样的选择，并会保存所选引擎的连接配置。

登录与日志接口

ADMIN_TOKEN 为空或仍为 xxxx 时，/logs 会直接返回 403。

最小 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 中的值写入进程环境，再初始化配置对象；若 shell 中已经有同名变量，文件中的值会覆盖它。缺少的键使用配置类默认值，空值会被忽略，未知键会被忽略。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/index_config.py
• hugegraph-llm/src/hugegraph_llm/config/admin_config.py
• hugegraph-llm/src/hugegraph_llm/config/prompt_config.py
• hugegraph-llm/src/hugegraph_llm/config/models/base_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

所有接口都使用 POST：

认证

在 .env 中启用登录：

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

启用后，请求需要 Bearer token：

1Authorization: Bearer replace-with-a-secret

同一开关也会给 Gradio 页面加上基础认证，用户名固定为 rag，密码是 USER_TOKEN。token 不正确时返回 401，并带上 WWW-Authenticate: Bearer 响应头。ENABLE_LOGIN 保持 False 时所有接口都不做鉴权。

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（默认 0.5）、rerank_method（bleu 或 reranker，默认 bleu）、near_neighbor_first（默认 false）、custom_priority_info，以及三个自定义提示词字段 answer_prompt、keywords_extract_prompt 和 gremlin_prompt。省略提示词字段时使用 config_prompt.yaml 中的值。

gremlin_tmpl_num 决定图召回阶段 Text2Gremlin 的执行方式：小于 0 表示跳过 Text2Gremlin，直接使用预定义的图遍历；等于 0 表示不带示例生成 Gremlin；大于 0 表示从示例索引中取相应数量的示例。

query 为空或只有空白字符时返回 400。

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 可能包含 query、keywords、match_vids、graph_result_flag、gremlin、graph_result 和 vertex_degree_list。设置 get_vertex_only=true 可在顶点匹配后提前返回，此时接口会把 match_vids 替换为完整的顶点详情。

query 为空返回 400，请求类型错误返回 400，其他失败返回 500。

图抽取

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  }'

请求字段：

内联 Schema 必须是包含 vertexlabels 和 edgelabels 两个列表的对象。每个顶点标签需要非空的 name 和非空的 properties 列表；每条边标签需要非空的 name、source_label 和 target_label。propertykeys 可选，若存在必须是列表。

若 schema 传现有图名，必须同时传入 client_config，且 client_config.graph 必须和图名相同。这里的 client_config 只接受 graph、user、pwd 和 gs，未知字段会被拒绝，且没有 url 字段：

 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（始终为 succeeded）、result.vertices、result.edges、warnings 和 meta。include_meta 不为 true 时 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}，缺少占位符时请求校验失败，并会列出缺失的占位符。

example_num 默认是 0，表示不使用模板，取值会被限制在 0 到 10 之间。client_config 只在单次请求内覆盖 HugeGraph 连接，生成时使用的 Schema 是当前生效的图名。query 为空返回 400，生成失败返回 500。

运行时配置

POST /config/graph

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

user 和 pwd 默认是空字符串，gs 可选。

POST /config/llm 与 POST /config/embedding

两个端点使用同一个请求模型。/config/llm 会把 chat_llm_type、extract_llm_type 和 text2gql_llm_type 一起设为相同的值；要分别设置各任务的类型，只能通过 .env 或 Web 页面。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。

四个配置端点成功时都返回 201。它们会改动进程当前配置，并可能同步到 .env。/config/llm、/config/embedding 和 /config/rerank 在应用过程中抛出异常时会回滚到原有取值，/config/graph 不会。

/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 默认是 llm-server.log，只能是 logs/ 目录下的文件名，不能是绝对路径、不能包含路径分隔符，也不能解析为 . 或 ..。非法文件名返回 400。

ADMIN_TOKEN 未设置或仍是占位值时，在比对 token 之前就返回 403；token 不匹配时返回内容为 Invalid admin_token 的 403 响应。

成功时返回 text/plain 流：先回放文件末尾 125 行，然后像 tail -f 一样持续输出新内容。

6 - Vermeer Python 客户端

vermeer-python-client 是 Vermeer 的 Python SDK。Vermeer 是使用 Go 编写、以内存计算为主的图计算引擎。该 SDK 封装了 Vermeer master 的 REST API，可以在 Python 中列出图、提交加载和计算任务、读取任务状态。导入时使用的包名是 pyvermeer。

模块没有固定 Vermeer 服务端版本，它通过 HTTP 访问 Vermeer master，调用的接口见 API 概览。

环境要求

• 当前源码实际要求 Python 3.10 或更高版本；虽然该模块打包元数据声明 >=3.9，代码中的类型标注使用了 Python 3.10 语法
• 一个可通过 HTTP 访问的 Vermeer master。默认 HTTP 端口为 6688；Docker 部署需发布 6688:6688，见 Vermeer 快速上手。
• uv（推荐）或 pip

运行时依赖：requests、urllib3、python-dateutil、decorator、rich 和 setuptools。

安装

打包元数据中的发行包名是 vermeer-python-client，其版本号独立于仓库版本号管理。该包尚未发布到 PyPI，请从源码安装。

在 HugeGraph-AI 仓库根目录，使用 vermeer extra 把它安装到共用的虚拟环境中：

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

vermeer-python-client 是以可编辑路径依赖的方式接入的，并不是 uv workspace member，因此在仓库根目录直接执行 uv sync 不会安装它，必须显式指定该 extra（或使用 --all-extras）。

单独安装该模块：

1git clone https://github.com/apache/hugegraph-ai.git
2cd hugegraph-ai/vermeer-python-client
3uv sync
4source .venv/bin/activate

连接 Vermeer master

1from pyvermeer.client.client import PyVermeerClient
2
3client = PyVermeerClient(
4    ip="127.0.0.1",
5    port=6688,
6    token="",
7    timeout=(0.5, 15.0),
8    log_level="INFO",
9)

构造函数参数：

如果 Python 客户端运行在宿主机，ip 填宿主机可访问的 master 地址；如果运行在容器中，则填容器网络内的 master 地址。客户端只连接 master 的 HTTP API，HugeGraph PD/Store 地址则必须能由执行加载任务的 Vermeer 节点访问。

连接前需要了解的行为：

• 当 master 不校验鉴权时，token 可以是空字符串，但不能是 None，否则会话会抛出 ValueError("Vermeer Token must be provided.")。
• timeout 是 (连接超时, 读取超时) 二元组。VermeerConfig 自身的默认值是 (0.5, 15.0)，但客户端总是把自己的参数传下去，因此不传 timeout 时实际存入的是 None，请求会一直等待。需要超时就显式传入该二元组。
• 基础 URL 固定拼接为 http://{ip}:{port}/，即客户端只使用明文 HTTP。
• 每个请求都会设置 Content-Type: application/json，并把 params 序列化进请求体，GET 请求也是如此。
• 底层会话配置了对 HTTP 500、502、504 的最多 3 次重试和 0.1 的退避系数；状态码重试遵循 urllib3 默认允许的方法，POST 不在其中，因此不能依赖它自动重试任务提交。
• log_level 设置的是名为 VermeerClient 的共享日志器的级别。它的控制台 handler 固定为 INFO，因此目前 DEBUG 级别的记录不会打印到控制台。

端到端示例

模块自带一个可运行的示例：vermeer-python-client/src/pyvermeer/demo/task_demo.py。下面的版本在其基础上增加了有截止时间的任务轮询，先等待加载成功、再读取图并提交 PageRank 计算；PD 地址和 HugeGraph 密码从环境变量读取。服务端 worker group 也必须与任务空间的分配匹配；单 worker 快速上手可将 worker_group 设为 $，保留命名组时先按 Vermeer 快速上手 将该组绑定到任务空间。

 1import os
 2import time
 3
 4from pyvermeer.client.client import PyVermeerClient
 5from pyvermeer.structure.task_data import TaskCreateRequest
 6
 7client = PyVermeerClient(
 8    ip="127.0.0.1",
 9    port=6688,
10    token=os.getenv("VERMEER_TOKEN", ""),
11    timeout=(0.5, 15.0),
12    log_level="INFO",
13)
14
15# 列出 master 上的任务
16tasks = client.tasks.get_tasks()
17print(tasks.to_dict())
18
19# 从 HugeGraph 把图数据加载到 Vermeer
20create_response = client.tasks.create_task(
21    create_task=TaskCreateRequest(
22        task_type="load",
23        graph_name="DEFAULT-example",
24        params={
25            "load.hg_pd_peers": os.environ["VERMEER_PD_PEERS"],
26            "load.hugegraph_name": "DEFAULT/example/g",
27            "load.hugegraph_username": "admin",
28            "load.hugegraph_password": os.environ["HUGEGRAPH_PASSWORD"],
29            "load.parallel": "10",
30            "load.type": "hugegraph",
31        },
32    )
33)
34print(create_response.errcode, create_response.message)
35if create_response.errcode != 0:
36    raise RuntimeError(f"Could not create load task: {create_response.message}")
37
38def wait_task(task_id, success_state, poll_timeout=300.0):
39    deadline = time.monotonic() + poll_timeout
40    while True:
41        response = client.tasks.get_task(task_id)
42        if response.errcode != 0:
43            raise RuntimeError(f"Could not read task {task_id}: {response.message}")
44        task = response.task
45        print(task_id, task.state)
46        if task.state == success_state:
47            return task
48        if task.state in ("error", "canceled"):
49            raise RuntimeError(f"Task {task_id} ended with state {task.state}")
50        remaining = deadline - time.monotonic()
51        if remaining <= 0:
52            raise TimeoutError(f"Task {task_id} did not finish within {poll_timeout}s")
53        time.sleep(min(1.0, remaining))
54
55
56# 等待加载完成后再读取图
57wait_task(create_response.task.id, success_state="loaded")
58
59# 图加载完成后查看图信息
60print(client.graph.get_graph("DEFAULT-example").to_dict())
61
62# 在已加载的图上提交 PageRank 计算
63compute_response = client.tasks.create_task(
64    create_task=TaskCreateRequest(
65        task_type="compute",
66        graph_name="DEFAULT-example",
67        params={
68            "compute.algorithm": "pagerank",
69            "compute.parallel": "10",
70            "compute.max_step": "10",
71            "output.type": "local",
72            "output.parallel": "1",
73            "output.file_path": "result/pagerank",
74        },
75    )
76)
77if compute_response.errcode != 0:
78    raise RuntimeError(f"Could not create compute task: {compute_response.message}")
79wait_task(compute_response.task.id, success_state="complete")

加载任务以 loaded 表示成功，计算任务以 complete 表示成功；error 或 canceled 会中止示例。运行前设置 VERMEER_PD_PEERS，其值是 JSON 数组字符串，例如 export VERMEER_PD_PEERS='["hugegraph-pd:8686"]'；其中地址必须能由 Vermeer master 访问，PD 返回的 Store 地址也必须能由 worker 访问。只有 master 配置为 token 鉴权时才设置 VERMEER_TOKEN；不启用鉴权时空字符串可用。

示例的 output.type=local 会把结果写到执行任务的 worker 本地文件系统，文件名以 result/pagerank 为前缀。容器部署时需把 worker 的结果目录挂载出来才能从宿主机读取。poll_timeout 是客户端轮询截止时间；检查期限之间的请求仍受 HTTP 超时和 SDK 重试影响，因此实际结束时间可能越过该值。超时只停止客户端等待，不会取消服务端任务。

不要把真实的 HugeGraph 密码写死在脚本或配置文件中，请像上面这样从环境变量或凭据管理系统读取。

保存并运行文档中的端到端示例

将上方完整的增强示例代码保存为 vermeer_client_example.py，放在 hugegraph-ai/ 仓库根目录。在该目录使用已安装 vermeer extra 的 workspace 环境运行：

1uv sync --extra vermeer
2export VERMEER_PD_PEERS='["hugegraph-pd:8686"]'
3read -s -r HUGEGRAPH_PASSWORD
4export HUGEGRAPH_PASSWORD
5uv run --extra vermeer python vermeer_client_example.py

输入密码后按回车。将 hugegraph-pd:8686 替换为 Vermeer master 可访问的 PD 地址；若 master 启用了 token 鉴权，还要从本机凭据管理方式设置 VERMEER_TOKEN。上述命令运行的是文档增强示例，不是包内原始 demo。

包内原始 demo

vermeer-python-client/src/pyvermeer/demo/task_demo.py 是另一份精简示例：它把客户端端口写为 8688，把 PD 地址写为 127.0.0.1:8686，并使用 xxx 占位用户名和密码。它不会读取本页增强示例使用的环境变量，也没有任务状态轮询或 PageRank 计算。若运行该文件，需单独调整其中的服务地址和 HugeGraph 凭据；不能用它替代上面的文档示例命令。

API 概览

PyVermeerClient 以属性的方式暴露各个 API 组，目前注册了 graph 和 tasks 两个组。

client.graph

client.tasks

pyvermeer/api/master.py 和 pyvermeer/api/worker.py 目前只有许可证头，也没有注册到客户端上。因此尽管 pyvermeer/structure/ 下已经有 MasterResponse 和 WorkersResponse，master 和 worker 信息暂时还无法通过客户端获取。

client.send_request(method, endpoint, params) 是这两个组共用的请求入口。对于还没有封装的 Vermeer 接口，可以直接调用它，返回值是解析后的 JSON 字典。

请求与响应对象

TaskCreateRequest(task_type, graph_name, params) 序列化为 {"task_type": ..., "graph": ..., "params": ...}。注意 graph_name 在报文中的字段名是 graph，与 Vermeer REST API 的请求体一致。

所有响应类型都继承 BaseResponse，提供 errcode、message 属性和 to_dict() 方法。errcode 为 0 表示成功，1 表示错误，-1 表示响应体中没有该字段。

• GraphsResponse.graphs 和 GraphResponse.graph 返回 VermeerGraph 对象，包含 name、space_name、status、create_time、update_time、vertex_count、edge_count、workers、worker_group、use_out_edges、use_property、use_out_degree、use_undirected、on_disk 和 backend_option。
• TasksResponse.tasks、TaskResponse.task 和 TaskCreateResponse.task 返回 TaskInfo 对象，SDK 读取 id、state、create_user、create_type、create_time、start_time、update_time、graph_name、space_name、params、workers 和 error_message。
• 时间字段由 python-dateutil 解析为 datetime 对象，空字符串会解析为 None。

当前服务端以 task_type 返回任务类型，而 SDK 的 TaskInfo.type 按 type 读取，因此该属性目前为空；服务端还返回的 statistics_result 不会被 SDK 的 TaskInfo 保留。轮询状态请使用 TaskInfo.state。这是当前源码的字段契约差异。

任务参数

客户端不会校验 params，键和值都会原样传给 Vermeer，因此可用的参数名由引擎决定，而不是由 SDK 决定。加载参数以及各算法的参数请参考 Vermeer 快速上手。

使用流程与直接调用 REST API 相同：先创建 load 任务把图读入 Vermeer，等待任务完成，再针对已加载的图创建计算任务。

异常

pyvermeer.utils.exception 定义了四种异常，都由底层的 requests 或 JSON 解析失败包装而来：

1from pyvermeer.utils.exception import ConnectError, TimeOutError
2
3try:
4    graphs = client.graph.get_graphs()
5except (ConnectError, TimeOutError) as error:
6    print(error)

客户端不检查响应的 HTTP 状态码，请通过返回对象的 errcode 和 message 判断是成功还是 Vermeer 端返回了错误。

代码检查

在 HugeGraph-AI 仓库根目录执行格式化和静态检查：

1./style/code_format_and_analysis.sh

源码位于 vermeer-python-client/src/pyvermeer/。目前有少量 src/tests/structure/test_task_data.py 结构测试，没有覆盖 HTTP API 的集成测试。

参考

• GitHub 上的 vermeer-python-client
• Vermeer 图计算引擎
• Vermeer 快速上手
• HugeGraph-AI 快速上手