Skip to content

Version 1.7 of the documentation is no longer actively maintained. The site that you are currently viewing is an archived snapshot. For up-to-date documentation, see the latest version.

HugeGraph-LLM REST API

The HugeGraph-LLM demo process serves both the Web UI and REST API. The default address is 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

Authentication

Enable login in .env:

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

Requests then require a Bearer token:

1Authorization: Bearer replace-with-a-secret

RAG

POST /rag

Returns one or more answer types according to the switches. When none is explicitly selected, only graph_only is enabled.

 1curl -X POST http://localhost:8001/rag \
 2  -H 'Content-Type: application/json' \
 3  -d '{
 4    "query": "Which movies feature 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  }'

The response contains only enabled answer fields:

1{
2  "query": "Which movies feature Al Pacino?",
3  "graph_only": "..."
4}

Other optional parameters include graph_ratio, rerank_method (bleu or reranker), near_neighbor_first, custom_priority_info, and three custom prompt fields.

POST /rag/graph

Runs graph retrieval without generating a final natural-language answer:

1curl -X POST http://localhost:8001/rag/graph \
2  -H 'Content-Type: application/json' \
3  -d '{
4    "query": "Which movies feature Al Pacino?",
5    "get_vertex_only": false,
6    "gremlin_tmpl_num": 1,
7    "rerank_method": "bleu"
8  }'

graph_recall in the response can contain keywords, match_vids, gremlin, graph_result, and vertex_degree_list. Set get_vertex_only=true to return immediately after vertex matching.

Graph Extraction

POST /graph/extract

An inline schema does not connect to HugeGraph:

 1curl -X POST http://localhost:8001/graph/extract \
 2  -H 'Content-Type: application/json' \
 3  -d '{
 4    "texts": ["Alice works at 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": "en",
20    "split_type": "sentence",
21    "include_meta": true
22  }'

texts can be a string or an array of strings. language accepts zh or en; split_type accepts document, paragraph, or sentence.

When schema is an existing graph name, also pass client_config, and make client_config.graph match that name:

 1{
 2  "texts": "Alice works at Acme.",
 3  "schema": "hugegraph",
 4  "client_config": {
 5    "graph": "hugegraph",
 6    "user": "admin",
 7    "pwd": "admin",
 8    "gs": "DEFAULT"
 9  }
10}

A successful response always contains status, result.vertices, result.edges, warnings, and meta.

Text2Gremlin

POST /text2gremlin

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

output_types can contain:

  • match_result
  • template_gremlin
  • raw_gremlin
  • template_execution_result
  • raw_execution_result

If omitted, only template_gremlin is returned by default. An empty array lets the implementation return all outputs. A custom gremlin_prompt must contain {query}, {schema}, {example}, and {vertices}.

Runtime Configuration

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 and POST /config/embedding

Both endpoints use the same request model. OpenAI or LiteLLM example:

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 requests still require the common fields; api_key and api_base can be empty strings:

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 accepts cohere or siliconflow. Cohere also accepts cohere_base_url.

These endpoints change the process’s active configuration and may write values back to .env. client_config in /rag, /rag/graph, and /text2gremlin overrides the HugeGraph connection for one request. The current implementation still changes process-global settings temporarily, so do not issue long-running requests with different connections concurrently.

Logs

POST /logs

This endpoint requires ADMIN_TOKEN in .env to be changed to a secure value. Example request body:

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

log_file must be a file name under logs/ and cannot contain path separators.

Last modified 2026-09-04 · docs: sync 1.7 documentation (4211f768b)