You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hugegraph.apache.org by ji...@apache.org on 2026/09/26 14:21:05 UTC
(hugegraph-doc) 03/12: docs(cn): align AI setup and configuration loading
This is an automated email from the ASF dual-hosted git repository.
imbajin pushed a commit to branch docs/sync-cn-491
in repository https://gitbox.apache.org/repos/asf/hugegraph-doc.git
commit 781d152e49648182c2a928f5cc1c6e9ef12c9041
Author: imbajin <ji...@apache.org>
AuthorDate: Sat Sep 26 20:49:33 2026 +0800
docs(cn): align AI setup and configuration loading
---
.../quickstart/client/hugegraph-client-python.md | 4 ++--
content/cn/docs/quickstart/hugegraph-ai/_index.md | 15 ++++++++------
.../quickstart/hugegraph-ai/config-reference.md | 18 +++++++++++++----
.../docs/quickstart/hugegraph-ai/hugegraph-llm.md | 23 ++++++++++++++--------
.../docs/quickstart/hugegraph-ai/hugegraph-ml.md | 8 ++++----
5 files changed, 44 insertions(+), 24 deletions(-)
diff --git a/content/cn/docs/quickstart/client/hugegraph-client-python.md b/content/cn/docs/quickstart/client/hugegraph-client-python.md
index f858a600a..285a9c2de 100644
--- a/content/cn/docs/quickstart/client/hugegraph-client-python.md
+++ b/content/cn/docs/quickstart/client/hugegraph-client-python.md
@@ -18,14 +18,14 @@ weight: 2
## 安装
-发布到 PyPI 的包名是 `hugegraph-python`：
+发布到 PyPI 的发行包名是 `hugegraph-python`：
```bash
uv pip install hugegraph-python
# 也可以使用 pip install hugegraph-python
```
-> PyPI 上的发布版本落后于仓库代码。在源码中该发行包声明为 `hugegraph-python-client`，版本号与 HugeGraph-AI 其他模块保持一致，需要最新代码时请从源码安装。
+截至 2026-09-26，PyPI 最新发布版本是 `hugegraph-python` 1.5.0，要求 Python 3.9 或更高版本；详见 [PyPI 发布页](https://pypi.org/project/hugegraph-python/)。当前仓库源码版本为 1.7.0，目录名是 `hugegraph-python-client`，但项目元数据中的发行包名仍为 `hugegraph-python`，并要求 Python 3.10 或更高版本。需要当前源码时，请从 HugeGraph-AI workspace 安装。
如需使用仓库中的最新代码，请从 HugeGraph-AI 仓库根目录同步 workspace。`hugegraph-python-client` 是 workspace 成员，通过 `python-client` extra 暴露，因此仅执行 `uv sync` 不会安装它：
diff --git a/content/cn/docs/quickstart/hugegraph-ai/_index.md b/content/cn/docs/quickstart/hugegraph-ai/_index.md
index 0b2c129de..67db3e620 100644
--- a/content/cn/docs/quickstart/hugegraph-ai/_index.md
+++ b/content/cn/docs/quickstart/hugegraph-ai/_index.md
@@ -15,15 +15,16 @@ weight: 3
- [hugegraph-python-client](https://github.com/apache/hugegraph-ai/tree/main/hugegraph-python-client)：管理 Schema、图数据和 Gremlin 查询的 Python SDK。
- [vermeer-python-client](https://github.com/apache/hugegraph-ai/tree/main/vermeer-python-client)：调用 Vermeer 图计算服务的 Python SDK。
-仓库使用 `uv` workspace，其成员是 `hugegraph-llm` 和 `hugegraph-python-client`。`hugegraph-ml` 和 `vermeer-python-client` 是可编辑的路径依赖，不在 workspace members 中。当前仓库版本为 `1.7.0`。
+仓库使用 `uv` workspace，其成员是 `hugegraph-llm` 和 `hugegraph-python-client`。`hugegraph-ml` 和 `vermeer-python-client` 是可编辑的路径依赖，不在 workspace members 中。当前仓库版本为 `1.7.0`。客户端源码目录叫 `hugegraph-python-client`，但发行包名是 `hugegraph-python`。
## 环境要求
-- HugeGraph-LLM：Python 3.10 或 3.11（`>=3.10,<3.12`）
+- HugeGraph-AI 根目录 workspace：Python 3.10 或更高版本；HugeGraph-LLM 还要求低于 3.12
- HugeGraph-ML：Python 3.10 或更高版本
-- HugeGraph Python 客户端、Vermeer Python 客户端：Python 3.9 或更高版本
+- PyPI 上的 `hugegraph-python` 1.5.0：Python 3.9 或更高版本；当前仓库源码随 workspace 使用 Python 3.10 或更高版本
+- Vermeer Python 客户端：Python 3.9 或更高版本
- `uv` 0.7 或更高版本
-- HugeGraph Server 1.3 或更高版本（推荐 1.5 或更高版本）
+- HugeGraph Server 1.5.0 或更高版本；当前 workspace 的 Python 客户端会拒绝可探测到的更低版本
## 可选依赖组
@@ -33,7 +34,7 @@ weight: 3
|---|---|
| `llm` | `hugegraph-llm` |
| `ml` | `hugegraph-ml` |
-| `python-client` | `hugegraph-python-client` |
+| `python-client` | `hugegraph-python`（源码目录 `hugegraph-python-client`）|
| `vermeer` | `vermeer-python-client` |
| `dev` | pytest、pytest-cov、coverage、pylint、ruff、mypy、ty、pre-commit |
| `nk-llm` | `hugegraph-llm`、`hugegraph-python-client`，以及编译镜像所需的 Nuitka |
@@ -51,6 +52,7 @@ cd hugegraph-ai
cp docker/env.template docker/.env
# 编辑 docker/.env，将 PROJECT_PATH 改为当前仓库的绝对路径
touch hugegraph-llm/.env
+# 在 hugegraph-llm/.env 中设置 GRAPH_URL=server:8080，并填写匹配 Server 的账号
cd docker
docker compose -f docker-compose-network.yml up -d
```
@@ -71,7 +73,8 @@ cd hugegraph-llm
python -m hugegraph_llm.demo.rag_demo.app
```
-`uv sync` 会创建根目录下的 `.venv`。不要在 `hugegraph-llm` 子目录另建一套环境，否则容易绕过 workspace 锁定的依赖。
+`uv sync` 会在仓库根目录创建 `.venv`。从根目录安装可让 `uv` 一起解析 workspace 成员和路径依赖。
+当前仓库不跟踪 `uv.lock`；`uv sync` 会按 `pyproject.toml` 中的依赖声明和版本约束解析依赖。
## 安装 ML 依赖
diff --git a/content/cn/docs/quickstart/hugegraph-ai/config-reference.md b/content/cn/docs/quickstart/hugegraph-ai/config-reference.md
index 17a43d646..8db344859 100644
--- a/content/cn/docs/quickstart/hugegraph-ai/config-reference.md
+++ b/content/cn/docs/quickstart/hugegraph-ai/config-reference.md
@@ -4,7 +4,7 @@ linkTitle: "配置参考"
weight: 4
---
-HugeGraph-LLM 从 `hugegraph-llm/.env` 读取运行配置。提示词单独保存在 `hugegraph-llm/src/hugegraph_llm/resources/demo/config_prompt.yaml`，不会写入 `.env`。
+HugeGraph-LLM 从 `.env` 读取运行配置，提示词单独保存在 `config_prompt.yaml`。两者使用不同的路径解析规则；不要把提示词文件当作 `.env` 的一部分。
`.env` 路径按以下顺序解析：
@@ -12,6 +12,16 @@ HugeGraph-LLM 从 `hugegraph-llm/.env` 读取运行配置。提示词单独保
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/`。
+
运行以下命令可按配置类的默认值创建或更新文件：
```bash
@@ -19,7 +29,7 @@ cd hugegraph-ai/hugegraph-llm
python -m hugegraph_llm.config.generate --update
```
-`--update` 默认开启，因此不带参数运行效果相同。该命令会写入 HugeGraph、管理员、LLM 和索引配置，然后重新生成提示词 YAML。若 `.env` 已存在，会先询问是否覆盖。
+`--update` 默认开启，因此不带参数运行效果相同。配置模块首次导入时会为缺失的 `.env` 和提示词 YAML 按默认值创建文件；文件已存在时，生成器会交互询问是否覆盖。该命令会处理 HugeGraph、管理员、LLM、索引配置及提示词 YAML，不会在无确认的情况下覆盖已有文件。
`.env` 包含密钥和密码，不要提交到版本库。
@@ -155,9 +165,9 @@ GRAPH_PWD=your-password
## 配置加载
-配置类先提供代码默认值，再从 `.env` 和进程环境读取覆盖值。Web 页面和配置 API 可以在运行时更新当前设置，并把受支持的字段同步回 `.env`。手工改动 `.env` 后应重启服务；提示词 YAML 可由页面加载逻辑刷新。
+配置类先提供代码默认值。当前实现会在初始化时把所选 `.env` 中的值写入进程环境，再初始化配置对象；若 shell 中已经有同名变量，文件中的值会覆盖它。缺少的键使用配置类默认值，空值会被忽略，未知键会被忽略。Web 页面和配置 API 可以在运行时更新当前设置，并把受支持的字段同步回 `.env`。手工改动 `.env` 后应重启服务；提示词 YAML 会在服务启动或页面加载时读取。
-`.env` 中的未知键会被忽略而不是报错，空值会回退到代码默认值，键名匹配不区分大小写。
+键名匹配不区分大小写。
配置定义位于：
diff --git a/content/cn/docs/quickstart/hugegraph-ai/hugegraph-llm.md b/content/cn/docs/quickstart/hugegraph-ai/hugegraph-llm.md
index 748a8a7a0..82c535c07 100644
--- a/content/cn/docs/quickstart/hugegraph-ai/hugegraph-llm.md
+++ b/content/cn/docs/quickstart/hugegraph-ai/hugegraph-llm.md
@@ -4,7 +4,7 @@ linkTitle: "HugeGraph-LLM"
weight: 1
---
-HugeGraph-LLM 用于知识图谱构建、GraphRAG 和自然语言图查询。演示服务把 Gradio 页面和 FastAPI 接口挂在同一个进程上，默认监听 `8001` 端口。
+HugeGraph-LLM 用于知识图谱构建、GraphRAG 和自然语言图查询。演示服务把 Gradio 页面和 FastAPI 接口挂在同一个进程上，入口默认监听 `0.0.0.0:8001`；从本机访问可用 `http://localhost:8001`。仅需本机访问时，可显式指定 `--host 127.0.0.1`。
## 环境要求
@@ -12,7 +12,7 @@ HugeGraph-LLM 用于知识图谱构建、GraphRAG 和自然语言图查询。演
- Python 3.10 或 3.11（`>=3.10,<3.12`）
- `uv` 0.7 或更高版本
-- HugeGraph Server 1.3 或更高版本（推荐 1.5 或更高版本）
+- HugeGraph Server 1.5.0 或更高版本；当前 workspace 中的 Python 客户端会拒绝可探测到的更低版本
## Docker Compose 部署
@@ -24,6 +24,7 @@ cd hugegraph-ai
cp docker/env.template docker/.env
# 编辑 docker/.env，将 PROJECT_PATH 改为当前仓库的绝对路径
touch hugegraph-llm/.env
+# 编辑 hugegraph-llm/.env：GRAPH_URL=server:8080，并设置与 Server 相符的 GRAPH_USER、GRAPH_PWD
cd docker
docker compose -f docker-compose-network.yml up -d
docker compose -f docker-compose-network.yml ps
@@ -36,14 +37,16 @@ docker compose -f docker-compose-network.yml ps
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 的用户名和密码。
+
## 容器镜像
| 镜像 | 构建文件 | 内容 |
|---|---|---|
-| `hugegraph/rag` | `docker/Dockerfile.llm` | 包含源码的 Python 3.10 运行环境，入口是 `python -m hugegraph_llm.demo.rag_demo.app --host 0.0.0.0 --port 8001` |
-| `hugegraph/rag-bin` | `docker/Dockerfile.nk` | 基于 `nk-llm` extra 用 Nuitka 编译的二进制，入口是 `./app.dist/app.bin` |
+| `docker/Dockerfile.llm` | 源码运行镜像构建配方，入口是 `python -m hugegraph_llm.demo.rag_demo.app --host 0.0.0.0 --port 8001` |
+| `docker/Dockerfile.nk` | 基于 `nk-llm` extra 用 Nuitka 编译的二进制镜像构建配方，入口是 `./app.dist/app.bin` |
-两个镜像都暴露 `8001` 端口，以非 root 用户 `work` 运行，为 `hugegraph-llm/src/hugegraph_llm/resources` 声明数据卷，并使用 `curl -f http://localhost:8001/` 作为健康检查。
+Compose 文件引用未指定标签的 `hugegraph/rag`，因此会使用可变的 `latest` 标签。2026-09-26 查询 Docker Hub 时，该仓库列出 `hugegraph/rag:1.7.0`（linux/amd64）；若要固定到此版本，需把 Compose 中的 `image` 改为该标签，见 [Docker Hub 标签页](https://hub.docker.com/r/hugegraph/rag/tags)。`scripts/build_llm_image.sh` 则以 `docker/Dockerfile.llm` 在本地构建 `hugegraph/graphrag:1.7.0`。这两个镜像名不同，构建出的镜像不会自动替代 Compose 引用的镜像。该脚本只构建镜像，不会推送。两个 Dockerfile 都声明 `8001` 端口、以非 root 用户 `work` 运行，并用 `curl -f http://localhost:8001/` 做镜像健康检查；两者都为资源目录声明数据卷。
`scripts/build_llm_image.sh` 会用 `docker/Dockerfile.llm` 构建并打上 `hugegraph/graphrag:1.7.0` 标签。
@@ -51,15 +54,19 @@ Compose 文件会把 `${PROJECT_PATH}/hugegraph-llm/.env` 挂载到容器内的
`docker/charts/hg-llm` 是 RAG 服务的 Helm chart，部署 `hugegraph/graphrag` 镜像。默认发布 `NodePort` 类型的 Service，把节点端口 `8039` 和服务端口 `8080` 映射到容器端口 `8001`，名称固定为 `hg-llm-service`。Ingress 和水平自动扩缩容已定义但默认关闭。
-chart 中 `image.tag` 仍默认为 `v0.0.1`，因此需要通过 `--set image.tag=1.7.0` 或修改 `values.yaml` 指向实际构建的标签。
+该 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 的挂载默认被注释掉。要使用自定义配置，先创建两个 ConfigMap，再取消对应 `volumes` 和 `volumeMounts` 段落的注释：
+chart 的 `values.yaml` 中，`.env` 和提示词 YAML 的挂载默认被注释掉。提示词 YAML 可用 ConfigMap；`.env` 可能含有密钥和密码，应使用 Secret，并把 `volumes` 中 `env-config` 的 `configMap` 改为 `secret`。Secret 和提示词 ConfigMap 可分别创建：
```bash
-kubectl create configmap hugegraph-llm-env --from-file=/path/to/.env
+kubectl create secret generic hugegraph-llm-env --from-file=.env=/path/to/.env
kubectl create configmap hugegraph-llm-prompt-config --from-file=/path/to/config_prompt.yaml
```
+随后取消 `volumeMounts` 段落的注释，并按需要启用提示词 ConfigMap 的 `volumes` 和挂载。Helm 模板会直接渲染 `values.yaml` 中的卷定义。
+
## 从源码启动
依赖应从仓库根目录按 workspace 安装：
diff --git a/content/cn/docs/quickstart/hugegraph-ai/hugegraph-ml.md b/content/cn/docs/quickstart/hugegraph-ai/hugegraph-ml.md
index da8e67f52..2a524f420 100644
--- a/content/cn/docs/quickstart/hugegraph-ai/hugegraph-ml.md
+++ b/content/cn/docs/quickstart/hugegraph-ai/hugegraph-ml.md
@@ -9,12 +9,12 @@ HugeGraph-ML 从 HugeGraph 读取图数据并转换为 DGL 图，供节点嵌入
## 环境要求
- Python 3.10 或更高版本
-- HugeGraph Server 1.0 或更高版本，推荐 1.5 及以上版本
+- 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` 中固定版本：
+ML 依赖在仓库根目录的 `[tool.uv] constraint-dependencies` 中声明版本约束：
| 依赖 | 版本约束 |
|---|---|
@@ -27,7 +27,7 @@ ML 依赖在仓库根目录的 `[tool.uv] constraint-dependencies` 中固定版
| `numpy` | `~=1.24.4` |
| `pandas` | `~=2.2.3` |
-上述约束安装的是 CPU 版本。每个任务都有 `gpu` 参数，默认值 `-1` 表示使用 CPU；只有自行安装 CUDA 版的 `torch` 和 `dgl` 之后，才可以传入设备编号。
+这些约束限定依赖版本，不指定 CPU 或 CUDA 构建。支持 `gpu` 参数的任务默认值 `-1` 表示使用 CPU；使用 GPU 时，需要安装彼此兼容的 CUDA 版 `torch` 和 `dgl`。
## 安装
@@ -39,7 +39,7 @@ source .venv/bin/activate
cd hugegraph-ml/src
```
-HugeGraph-ML 是根项目的路径依赖，但不属于 `uv` workspace members。应在仓库根目录选择 `ml` extra，不要在子目录建立另一套锁文件。
+HugeGraph-ML 是根项目的路径依赖，但不属于 `uv` workspace members。应在仓库根目录选择 `ml` extra，让 `uv` 按 workspace 配置安装它及其本地客户端依赖。
## 已实现模型