How to Set Up HugeGraph AI for Local Development: Docker and Source Installation Guide

You can set up HugeGraph AI locally using either Docker Compose for a quick containerized deployment or source installation with the uv package manager for full development control, accessing the RAG service at http://localhost:8001.

HugeGraph AI integrates the HugeGraph graph database with large language model (LLM) capabilities through a multi-module Python workspace. This guide walks you through configuring the apache/incubator-hugegraph-ai repository for local development, whether you prefer containerized services or a native Python environment with IDE debugging support.

Prerequisites

Before setting up HugeGraph AI, ensure you have the following tools installed:

• Python 3.10+ (tested and supported)
• Docker (optional but recommended for containerized services)
• uv package manager (version 0.7+)
• Git

Install uv if it is not already present:

curl -LsSf https://astral.sh/uv/install.sh | sh

Clone the Repository

Start by cloning the official repository and navigating to the project root:

git clone https://github.com/apache/incubator-hugegraph-ai.git
cd incubator-hugegraph-ai

The project organizes code into four main modules: hugegraph-llm/ for LLM-RAG services, hugegraph-ml/ for graph algorithms, hugegraph-python-client/ for REST API access, and vermeer-python-client/ for graph computing.

Choose Your Installation Method

Option A: Docker Compose (Recommended for Quick Start)

Docker Compose boots both the HugeGraph server and the RAG service together using the configuration in docker/docker-compose-network.yml.

First, copy the environment template and set your absolute project path:

cp docker/env.template docker/.env
sed -i "s|path_to_project|$(pwd)|" docker/.env

Start the services:

docker compose -f docker/docker-compose-network.yml up -d

Verify the containers are healthy:

docker compose -f docker/docker-compose-network.yml ps

After startup, the HugeGraph server is available at http://localhost:8080 and the RAG service (FastAPI + Gradio UI) runs at http://localhost:8001.

Option B: Source Installation (Full Control and IDE Debugging)

For development work requiring breakpoints and custom modifications, install from source:

1. Start a standalone HugeGraph container (required only once):

docker run -itd --name=server -p 8080:8080 hugegraph/hugegraph

2. Install project dependencies using uv, which automatically creates a .venv:

uv sync --extra llm

Use uv sync --all-extras to install all module dependencies, or add --extra vectordb if you need Milvus or Qdrant support.

3. Activate the virtual environment:

source .venv/bin/activate

4. Launch the demo application:

python -m hugegraph_llm.demo.rag_demo.app

The web interface opens at http://127.0.0.1:8001.

Configure Environment Variables

Whether using Docker or source installation, configuration resides in the .env file (generated from docker/env.template). Key variables include:

• HUGEGRAPH_HOST and HUGEGRAPH_PORT for server connection
• LANGUAGE (set to EN or CN to switch prompt languages)
• LLM_PROVIDER and provider tokens like OPENAI_API_KEY

The system uses LiteLLM under the hood for provider abstraction. Edit hugegraph-llm/.env directly when running from source, or modify docker/.env for Docker deployments.

Using the Scheduler Programmatically

Once the environment is running, interact with workflows directly through Python instead of the web UI. The SchedulerSingleton in hugegraph-llm/src/hugegraph_llm/flows/scheduler.py serves as the central entry point, caching GPipelines for efficiency.

from hugegraph_llm.flows.scheduler import SchedulerSingleton

# Example: Graph-only RAG query

scheduler = SchedulerSingleton.get_instance()
result = scheduler.schedule_flow(
    "rag_graph_only",
    query="Tell me about the movie Inception.",
    graph_only_answer=True,
    vector_only_answer=False,
    raw_answer=False,
    gremlin_tmpl_num=-1,
    gremlin_prompt=None,
)
print(result.get("graph_only_answer"))

Other available flows include rag_vector_only, text2gremlin, and build_examples_index, each constructing specific pipelines like RAGGraphOnlyFlow or Text2GremlinFlow internally.

Testing and Code Quality

Validate your setup by running the test suites for each module:

cd hugegraph-llm && pytest
cd ../hugegraph-python-client && pytest
cd ../hugegraph-ml && pytest

Format code and run linting using the provided script:

./style/code_format_and_analysis.sh

This executes ruff and pre-commit hooks across the codebase.

Key Source Files for Developers

File	Purpose
docker/env.template	Base environment configuration template copied to .env
docker/docker-compose-network.yml	Docker network and service orchestration
hugegraph-llm/src/hugegraph_llm/flows/scheduler.py	Central scheduler implementing SchedulerSingleton
hugegraph-llm/src/hugegraph_llm/demo/rag_demo/app.py	FastAPI entry point hosting the Gradio UI
hugegraph-llm/src/hugegraph_llm/config/config_data.py	Default schema templates for the UI
hugegraph-llm/README.md	High-level documentation and usage examples

Summary

• HugeGraph AI requires Python 3.10+, Docker, and the uv package manager for local development.
• Docker Compose in docker/docker-compose-network.yml provides the fastest setup, binding ports 8080 (graph server) and 8001 (RAG UI).
• Source installation uses uv sync --extra llm to create a virtual environment and python -m hugegraph_llm.demo.rag_demo.app to start services.
• Configuration happens through .env files derived from docker/env.template, controlling LLM providers, language settings, and database connections.
• The SchedulerSingleton class in hugegraph_llm/flows/scheduler.py enables programmatic execution of RAG and Gremlin-generation workflows.

Frequently Asked Questions

What is the difference between the Docker and source installation methods?

Docker Compose runs the HugeGraph server and RAG service in containers with minimal local setup, ideal for testing. Source installation creates a local Python virtual environment via uv, giving you full control over dependencies and enabling IDE debugging of the FastAPI application in hugegraph_llm/demo/rag_demo/app.py.

How do I connect to a different LLM provider?

Edit the LLM_PROVIDER variable in your .env file and add the corresponding API key (e.g., OPENAI_API_KEY). The project uses LiteLLM for provider routing, so any LiteLLM-supported backend works without code changes.

Can I use HugeGraph AI without Docker?

Yes. Run a standalone HugeGraph server using docker run -itd --name=server -p 8080:8080 hugegraph/hugegraph, then use uv sync --extra llm to install Python dependencies locally. This hybrid approach keeps the graph database containerized while running the Python RAG service natively for development.

Where is the pipeline scheduling logic implemented?

The scheduling logic resides in hugegraph-llm/src/hugegraph_llm/flows/scheduler.py. The SchedulerSingleton class manages GPipeline construction and caching, exposing the schedule_flow() method to execute specific workflows like rag_graph_only or text2gremlin programmatically.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}