doc(ai): sync hugegraph-llm with main

content/cn/docs/quickstart/hugegraph-ai/_index.md

@@ -15,14 +15,31 @@ 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 管理 LLM 和 Python 客户端。HugeGraph-ML 是路径依赖模块，不在 workspace members 中。
+仓库使用 `uv` workspace，其成员是 `hugegraph-llm` 和 `hugegraph-python-client`。`hugegraph-ml` 和 `vermeer-python-client` 是可编辑的路径依赖，不在 workspace members 中。当前仓库版本为 `1.7.0`。
 
 ## 环境要求
 
-- HugeGraph-LLM：Python 3.10 或 3.11
-- HugeGraph-ML、Python 客户端：Python 3.10 或更高版本
+- HugeGraph-LLM：Python 3.10 或 3.11（`>=3.10,<3.12`）
+- HugeGraph-ML：Python 3.10 或更高版本
+- HugeGraph Python 客户端、Vermeer Python 客户端：Python 3.9 或更高版本
 - `uv` 0.7 或更高版本
-- HugeGraph Server 1.5 或更高版本
+- HugeGraph Server 1.3 或更高版本（推荐 1.5 或更高版本）
+
+## 可选依赖组
+
+根项目为每个模块声明一个 extra，另有几个组合项：
+
+| Extra | 安装内容 |
+|---|---|
+| `llm` | `hugegraph-llm` |
+| `ml` | `hugegraph-ml` |
+| `python-client` | `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 |
+| `all` | 四个模块包 |
+
+`hugegraph-llm` 自身还声明了 `vectordb` extra，用于安装 `pymilvus` 和 `qdrant-client`。
 
 ## Docker Compose 部署
 
@@ -70,6 +87,7 @@ cd hugegraph-ml/src
 ## 后续阅读
 
 - [HugeGraph-LLM](./hugegraph-llm.md)
+- [HugeGraph-LLM 使用流程](./quick_start.md)
 - [配置参考](./config-reference.md)
 - [REST API](./rest-api.md)
 - [HugeGraph-ML](./hugegraph-ml.md)

content/cn/docs/quickstart/hugegraph-ai/config-reference.md

@@ -6,13 +6,21 @@ weight: 4
 
 HugeGraph-LLM 从 `hugegraph-llm/.env` 读取运行配置。提示词单独保存在 `hugegraph-llm/src/hugegraph_llm/resources/demo/config_prompt.yaml`，不会写入 `.env`。
 
+`.env` 路径按以下顺序解析：
+
+1. 若设置了环境变量 `HUGEGRAPH_LLM_ENV_PATH`，则使用该路径，开头的 `~` 会被展开。
+2. 从源码运行时，使用 `hugegraph-llm/.env`。
+3. 以已安装的包运行时，使用当前工作目录下的 `.env`。
+
 运行以下命令可按配置类的默认值创建或更新文件：
 
 ```bash
 cd hugegraph-ai/hugegraph-llm
 python -m hugegraph_llm.config.generate --update
 ```
 
+`--update` 默认开启，因此不带参数运行效果相同。该命令会写入 HugeGraph、管理员、LLM 和索引配置，然后重新生成提示词 YAML。若 `.env` 已存在，会先询问是否覆盖。
+
 `.env` 包含密钥和密码，不要提交到版本库。
 
 ## 基础选项
@@ -91,27 +99,28 @@ API 地址默认是 `https://api.openai.com/v1`；三个语言模型默认是 `g
 | `TOPK_PER_KEYWORD` | `1` | 每个关键词的候选数 |
 | `TOPK_RETURN_RESULTS` | `20` | 重排序后返回的结果数 |
 
-## 外部向量数据库
-
-默认实现可以使用本地 FAISS。启用可选依赖后还可配置：
+## 向量索引后端
 
-| 配置项 | 默认值 |
-|---|---|
-| `QDRANT_HOST` | 空 |
-| `QDRANT_PORT` | `6333` |
-| `QDRANT_API_KEY` | 空 |
-| `MILVUS_HOST` | 空 |
-| `MILVUS_PORT` | `19530` |
-| `MILVUS_USER` | 空 |
-| `MILVUS_PASSWORD` | 空 |
+| 配置项 | 默认值 | 说明 |
+|---|---|---|
+| `CUR_VECTOR_INDEX` | `Faiss` | 当前使用的向量库：`Faiss`、`Milvus` 或 `Qdrant` |
+| `QDRANT_HOST` | 空 | |
+| `QDRANT_PORT` | `6333` | |
+| `QDRANT_API_KEY` | 空 | |
+| `MILVUS_HOST` | 空 | |
+| `MILVUS_PORT` | `19530` | |
+| `MILVUS_USER` | 空 | |
+| `MILVUS_PASSWORD` | 空 | |
 
-安装对应依赖：
+FAISS 在本地运行，无需额外依赖。未安装可选依赖就选择 `Milvus` 或 `Qdrant` 时，会报错并指出缺少的包，因此需要先安装：
 
 ```bash
 cd hugegraph-ai
 uv sync --package hugegraph-llm --extra vectordb
 ```
 
+Web 页面的 `5. Set up the vector engine.` 面板提供同样的选择，并会保存所选引擎的连接配置。
+
 ## 登录与日志接口
 
 | 配置项 | 默认值 | 说明 |
@@ -148,9 +157,13 @@ GRAPH_PWD=your-password
 
 配置类先提供代码默认值，再从 `.env` 和进程环境读取覆盖值。Web 页面和配置 API 可以在运行时更新当前设置，并把受支持的字段同步回 `.env`。手工改动 `.env` 后应重启服务；提示词 YAML 可由页面加载逻辑刷新。
 
+`.env` 中的未知键会被忽略而不是报错，空值会回退到代码默认值，键名匹配不区分大小写。
+
 配置定义位于：
 
 - `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`：加载与文件同步逻辑

content/cn/docs/quickstart/hugegraph-ai/hugegraph-llm.md

@@ -10,9 +10,9 @@ HugeGraph-LLM 用于知识图谱构建、GraphRAG 和自然语言图查询。演
 
 > AI 总结项目文档：[Ask DeepWiki](https://deepwiki.com/apache/hugegraph-ai)
 
-- Python 3.10 或 3.11
+- Python 3.10 或 3.11（`>=3.10,<3.12`）
 - `uv` 0.7 或更高版本
-- HugeGraph Server 1.5 或更高版本
+- HugeGraph Server 1.3 或更高版本（推荐 1.5 或更高版本）
 
 ## Docker Compose 部署
 
@@ -34,6 +34,32 @@ docker 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` 也可以用同样方式挂载，该挂载默认被注释掉。
+
+## 容器镜像
+
+| 镜像 | 构建文件 | 内容 |
+|---|---|---|
+| `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` |
+
+两个镜像都暴露 `8001` 端口，以非 root 用户 `work` 运行，为 `hugegraph-llm/src/hugegraph_llm/resources` 声明数据卷，并使用 `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 中 `image.tag` 仍默认为 `v0.0.1`，因此需要通过 `--set image.tag=1.7.0` 或修改 `values.yaml` 指向实际构建的标签。
+
+chart 的 `values.yaml` 中，`.env` 和提示词 YAML 的挂载默认被注释掉。要使用自定义配置，先创建两个 ConfigMap，再取消对应 `volumes` 和 `volumeMounts` 段落的注释：
+
+```bash
+kubectl create configmap hugegraph-llm-env --from-file=/path/to/.env
+kubectl create configmap hugegraph-llm-prompt-config --from-file=/path/to/config_prompt.yaml
+```
+
 ## 从源码启动
 
 依赖应从仓库根目录按 workspace 安装：
@@ -55,8 +81,12 @@ python -m hugegraph_llm.demo.rag_demo.app \
   --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 索引
@@ -67,34 +97,88 @@ Web 页面的第一个标签页可以处理文本或文件，并执行以下操
 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` 文件读取问题、逐条作答，并返回可下载的结果文件。上传控件旁提供模板文件下载。
+
 ![知识图谱构建器](/images/docs/hugegraph-ai/gradio-kg.jpg)
 
 ### 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。嵌入模型也可以独立选择。默认向量索引使用 FAISS；安装 `vectordb` 可选依赖后，还可配置 Milvus 或 Qdrant：
+聊天、信息抽取和 Text2Gremlin 可以分别使用 OpenAI 兼容接口、Ollama 或 LiteLLM。嵌入模型可独立选择，同样支持这三种提供方。重排序支持 Cohere 和 SiliconFlow。
+
+默认向量索引使用 FAISS。`CUR_VECTOR_INDEX` 可选 `Faiss`、`Milvus` 或 `Qdrant`，Web 页面的 `5. Set up the vector engine.` 面板提供同样的选择。Milvus 和 Qdrant 需要安装可选依赖：
 
 ```bash
 cd hugegraph-ai
 uv sync --package hugegraph-llm --extra vectordb
 ```
 
-完整环境变量见[配置参考](./config-reference.md)，HTTP 请求格式见[REST API](./rest-api.md)。
+页面操作流程见[使用流程](./quick_start.md)，完整环境变量见[配置参考](./config-reference.md)，HTTP 请求格式见[REST API](./rest-api.md)。
+
+## 程序化调用
+
+原有的 `RAGPipeline` 和 `KgBuilder` 类已被流水线调度器取代。通过 `SchedulerSingleton` 按名称调用流程：
+
+```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"))
+```
+
+已注册的流程名包括 `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 一致的检查：
+
 ```bash
 cd hugegraph-ai
-./style/code_format_and_analysis.sh
+uv sync --extra llm --extra dev
+uv run ruff format --check .
+uv run ruff check .
+
 cd hugegraph-llm
-pytest
+SKIP_EXTERNAL_SERVICES=true uv run pytest src/tests/config/ src/tests/document/ src/tests/middleware/ \
+  src/tests/operators/ src/tests/models/ src/tests/indices/ src/tests/test_utils.py -v --tb=short
+SKIP_EXTERNAL_SERVICES=true uv run pytest src/tests/integration/test_graph_rag_pipeline.py \
+  src/tests/integration/test_kg_construction.py src/tests/integration/test_rag_pipeline.py -v --tb=short
+```
+
+Git hook 通过 pre-commit 启用：
+
+```bash
+cd hugegraph-ai
+pre-commit install
+pre-commit run --all-files
 ```

content/cn/docs/quickstart/hugegraph-ai/quick_start.md

@@ -6,6 +6,10 @@ weight: 3
 
 本文说明 HugeGraph-LLM Web 页面的处理流程。服务启动方式见 [HugeGraph-LLM](./hugegraph-llm.md)。
 
+## 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 索引
 
 第一个标签页负责两类索引：
@@ -23,15 +27,24 @@ flowchart TD
     F --> G[更新顶点向量索引]
 ```
 
+输入来自 `text` 子页或 `file` 子页。上传支持 `.txt`、`.docx` 和 `.pdf`，可一次选择多个文件。
+
 页面包含文档、Schema、抽取提示词和结果区域。常用操作有：
 
 1. `Import into Vector`：切分文档并建立 chunk 向量索引。
-2. `Extract Graph Data`：按 Schema 抽取图数据。
-3. `Load into GraphDB`：把抽取结果写入 HugeGraph，并更新顶点向量。
-4. `Update Vid Embedding`：重新生成顶点向量。
+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 查询
 
 第二个标签页提供四种回答范围：
@@ -57,24 +70,40 @@ flowchart TD
 
 图召回先用关键词精确匹配 HugeGraph 顶点，找不到时再用顶点向量做近似匹配。匹配结果会进入 Text2Gremlin；生成或执行失败时，流程可以回退到预定义的图遍历。
 
-`Template Num` 控制 Text2Gremlin 使用的示例数量。小于等于 0 表示不提供模板，大于 0 表示从示例索引中取相应数量的相近模板。
+`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：
+第三个标签页分为两部分。上半部分用问题与 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，以及两者各自的执行输出。
+
 ![RAG 查询范围选择](/images/docs/hugegraph-ai/quick-start-03.jpg)
 
 自定义提示词必须包含 `{query}`、`{schema}`、`{example}` 和 `{vertices}`。缺少任一占位符时，REST API 会拒绝请求。
 
 ## 4. 图工具与管理工具
 
-`Graph Tools` 标签页用于直接执行图操作。`Admin Tools` 提供日志等管理能力。启用登录后，页面和 API 需要使用 `USER_TOKEN`；日志接口还要求单独配置安全的 `ADMIN_TOKEN`。
+`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`。
 
 ![RAG 界面中抽取的关键词](/images/docs/hugegraph-ai/quick-start-04.png)