文档 1.7 版本已不再积极维护，你当前浏览的是一份归档快照。
最新文档请参阅 最新版本。
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 可在顶点匹配后提前返回。
图抽取
使用内联 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_resulttemplate_gremlinraw_gremlintemplate_execution_resultraw_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/ 目录下的文件名，不能包含路径分隔符。