Skip to content

Configuration Reference

HugeGraph-LLM reads runtime configuration from .env and prompts from config_prompt.yaml. These files have different path-resolution rules; the prompt file is not part of .env.

The .env path is resolved in this order:

  1. HUGEGRAPH_LLM_ENV_PATH, if that environment variable is set. A leading ~ is expanded.
  2. hugegraph-llm/.env, when the package runs from a source checkout.
  3. .env in the current working directory, for an installed package.

The path is selected when the configuration module is imported. Set HUGEGRAPH_LLM_ENV_PATH before starting Python, not inside the .env file that will be loaded. Relative overrides are resolved against the process working directory.

The prompt YAML path is resolved in this order:

  1. HUGEGRAPH_LLM_PROMPT_CONFIG_PATH from the process environment, expanding a leading ~.
  2. hugegraph-llm/src/hugegraph_llm/resources/demo/config_prompt.yaml when running from source.
  3. ${XDG_CONFIG_HOME:-~/.config}/hugegraph-llm/config_prompt.yaml for an installed package.

Set path overrides before starting the process. Relative paths use its working directory. The source Docker image points PYTHONPATH at the source tree, so its default prompt path remains under hugegraph-llm/src/hugegraph_llm/resources/demo/.

Create or update files from configuration-class defaults with:

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

--update is enabled by default, so running without arguments has the same effect. On first configuration-module import, missing .env and prompt YAML files are created from defaults. The generator asks interactively before overwriting existing files. It handles HugeGraph, administrator, LLM, index, and prompt settings without overwriting existing files silently.

.env contains keys and passwords. Do not commit it to version control.

Basic Options

SettingDefaultDescription
LANGUAGEENPrompt language: EN or CN
CHAT_LLM_TYPEopenaiAnswer model: openai, litellm, or ollama/local
EXTRACT_LLM_TYPEopenaiInformation extraction model; same choices as above
TEXT2GQL_LLM_TYPEopenaiText2Gremlin model; same choices as above
EMBEDDING_TYPEopenaiEmbedding model; same choices as above, or empty
RERANKER_TYPEemptycohere or siliconflow
KEYWORD_EXTRACT_TYPEllmllm, textrank, or hybrid
WINDOW_SIZE3TextRank window size, from 1 to 10
HYBRID_LLM_WEIGHTS0.5Weight of LLM results in hybrid mode, from 0 to 1

OpenAI-Compatible APIs

Chat, extraction, and Text2Gremlin can use different endpoints, keys, and models.

PurposeAPI baseKeyModelDefault maximum tokens
AnswerOPENAI_CHAT_API_BASEOPENAI_CHAT_API_KEYOPENAI_CHAT_LANGUAGE_MODELOPENAI_CHAT_TOKENS=8192
ExtractionOPENAI_EXTRACT_API_BASEOPENAI_EXTRACT_API_KEYOPENAI_EXTRACT_LANGUAGE_MODELOPENAI_EXTRACT_TOKENS=256
Text2GremlinOPENAI_TEXT2GQL_API_BASEOPENAI_TEXT2GQL_API_KEYOPENAI_TEXT2GQL_LANGUAGE_MODELOPENAI_TEXT2GQL_TOKENS=4096
EmbeddingOPENAI_EMBEDDING_API_BASEOPENAI_EMBEDDING_API_KEYOPENAI_EMBEDDING_MODELNot applicable

The default API base is https://api.openai.com/v1. The default language model for all three tasks is gpt-4.1-mini, and the default embedding model is text-embedding-3-small.

OPENAI_BASE_URL and OPENAI_API_KEY provide general fallback values. Embeddings also support OPENAI_EMBEDDING_BASE_URL and OPENAI_EMBEDDING_API_KEY as fallback values.

LiteLLM

PurposeAPI baseKeyModelDefault maximum tokens
AnswerLITELLM_CHAT_API_BASELITELLM_CHAT_API_KEYLITELLM_CHAT_LANGUAGE_MODELLITELLM_CHAT_TOKENS=8192
ExtractionLITELLM_EXTRACT_API_BASELITELLM_EXTRACT_API_KEYLITELLM_EXTRACT_LANGUAGE_MODELLITELLM_EXTRACT_TOKENS=256
Text2GremlinLITELLM_TEXT2GQL_API_BASELITELLM_TEXT2GQL_API_KEYLITELLM_TEXT2GQL_LANGUAGE_MODELLITELLM_TEXT2GQL_TOKENS=4096
EmbeddingLITELLM_EMBEDDING_API_BASELITELLM_EMBEDDING_API_KEYLITELLM_EMBEDDING_MODELNot applicable

The default language model is openai/gpt-4.1-mini, and the default embedding model is openai/text-embedding-3-small. Model names generally use the provider/model form; supported values depend on the LiteLLM service.

Ollama

PurposeHostPortModel
AnswerOLLAMA_CHAT_HOSTOLLAMA_CHAT_PORTOLLAMA_CHAT_LANGUAGE_MODEL
ExtractionOLLAMA_EXTRACT_HOSTOLLAMA_EXTRACT_PORTOLLAMA_EXTRACT_LANGUAGE_MODEL
Text2GremlinOLLAMA_TEXT2GQL_HOSTOLLAMA_TEXT2GQL_PORTOLLAMA_TEXT2GQL_LANGUAGE_MODEL
EmbeddingOLLAMA_EMBEDDING_HOSTOLLAMA_EMBEDDING_PORTOLLAMA_EMBEDDING_MODEL

The default host is 127.0.0.1 and the default port is 11434. Model names have no defaults; pull the required models in Ollama before use.

Reranking

SettingDefaultDescription
COHERE_BASE_URLhttps://api.cohere.com/v1/rerankCohere rerank endpoint; CO_API_URL is a fallback
RERANKER_API_KEYemptyCohere or SiliconFlow key
RERANKER_MODELemptyModel name supported by the service

HugeGraph Connection and Retrieval Limits

SettingDefaultDescription
GRAPH_URL127.0.0.1:8080HugeGraph address; it is not split into IP and port
GRAPH_NAMEhugegraphGraph name
GRAPH_USERadminUser name
GRAPH_PWDxxxPassword
GRAPH_SPACEemptyGraphSpace name
LIMIT_PROPERTYFalseWhether to limit returned properties; read as a string by the configuration class
MAX_GRAPH_PATH10Maximum graph path length
MAX_GRAPH_ITEMS30Maximum number of graph retrieval items
EDGE_LIMIT_PRE_LABEL8Result limit for each edge label
VECTOR_DIS_THRESHOLD0.9Results beyond this vector-distance threshold are ignored
TOPK_PER_KEYWORD1Candidates per keyword
TOPK_RETURN_RESULTS20Results returned after reranking

Vector Index Backend

SettingDefaultDescription
CUR_VECTOR_INDEXFaissActive vector store: Faiss, Milvus, or Qdrant
QDRANT_HOSTempty
QDRANT_PORT6333
QDRANT_API_KEYempty
MILVUS_HOSTempty
MILVUS_PORT19530
MILVUS_USERempty
MILVUS_PASSWORDempty

FAISS is local and needs no extra dependency. Selecting Milvus or Qdrant without the optional dependencies raises an error that names the missing package, so install them first:

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

The same choice is available in the 5. Set up the vector engine. panel of the Web UI, which also persists the connection settings for the selected engine.

Login and Log API

SettingDefaultDescription
ENABLE_LOGINFalseWhether to require a Bearer token; read as a string by the configuration class
USER_TOKEN4321Token for the Web UI and regular APIs
ADMIN_TOKENxxxxAdministrator token used by /logs

/logs returns 403 when ADMIN_TOKEN is empty or still set to xxxx.

Warning

In production, set ENABLE_LOGIN=True, replace USER_TOKEN and ADMIN_TOKEN, and enforce a source IP allowlist at the firewall or network entry point. This protects only HugeGraph-LLM. Separately enable Server authentication and authorization, retain Server audit logs (normally audit-*.log), and grant GRAPH_USER minimum required permissions. The two services use different credentials.

Minimal OpenAI Configuration

LANGUAGE=EN
CHAT_LLM_TYPE=openai
EXTRACT_LLM_TYPE=openai
TEXT2GQL_LLM_TYPE=openai
EMBEDDING_TYPE=openai

OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_CHAT_LANGUAGE_MODEL=gpt-4.1-mini
OPENAI_EXTRACT_LANGUAGE_MODEL=gpt-4.1-mini
OPENAI_TEXT2GQL_LANGUAGE_MODEL=gpt-4.1-mini
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

GRAPH_URL=127.0.0.1:8080
GRAPH_NAME=hugegraph
GRAPH_USER=admin
GRAPH_PWD=your-password

Configuration Loading

Configuration classes supply code defaults. During initialization, values from the selected .env are written into the process environment before the configuration objects are created, overriding same-named shell variables. Missing keys use defaults; empty values and unknown keys are ignored. The Web UI and configuration APIs can update settings and write supported fields back to .env. Restart after manual .env edits; prompt YAML is read at service startup or page load.

Keys are matched case-insensitively.

Configuration definitions are in:

  • 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 for the loading and file-sync behaviour
Last modified 2026-09-30 · docs: sync core modules guides (#501) (a8c685794)