# How to Deploy a Knowledge Graph Constructed by HugeGraph AI: Complete Deployment Guide

> Deploy your HugeGraph AI knowledge graph with Docker Compose for production, build from source for development, or automate with the Scheduler API for CI/CD. Learn the complete deployment guide.

- Repository: [The Apache Software Foundation/incubator-hugegraph-ai](https://github.com/apache/incubator-hugegraph-ai)
- Tags: how-to-guide
- Published: 2026-02-24

---

**You can deploy a HugeGraph AI knowledge graph using Docker-Compose for immediate production use, build from source for development workflows, or automate via the Scheduler API for CI/CD pipelines, following a three-stage pipeline of document chunking, graph extraction, and vertex vectorization.**

Deploying a knowledge graph constructed by HugeGraph AI transforms unstructured documents into a queryable property graph enhanced with vector search capabilities. The apache/incubator-hugegraph-ai repository provides modular deployment options that support both interactive prototyping through a Gradio interface and headless automation via Python APIs.

## Understanding the Knowledge Graph Construction Pipeline

Before deploying, understand the three-stage pipeline implemented in the HugeGraph AI source code:

- **Stage 1: Text → Vector → Chunk Index**: Raw documents are split into chunks and embedded using `read_documents` in [`hugegraph_llm/utils/vector_index_utils.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph_llm/utils/vector_index_utils.py), storing vectors in Milvus or Qdrant for semantic search.

- **Stage 2: Text → Graph Extraction**: An LLM extracts vertices and edges according to a user-defined schema via `extract_graph` in [`hugegraph_llm/utils/graph_index_utils.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph_llm/utils/graph_index_utils.py), constructing a property graph structure.

- **Stage 3: Graph → Vertex-Vector Index**: Every graph vertex is embedded and indexed via `update_vid_embedding` in [`hugegraph_llm/utils/graph_index_utils.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph_llm/utils/graph_index_utils.py) to enable graph-enhanced RAG retrieval.

## Deployment Methods

### Docker-Compose Deployment (Recommended)

The fastest way to deploy a complete stack uses the Docker Compose configuration defined in [`docker/docker-compose-network.yml`](https://github.com/apache/incubator-hugegraph-ai/blob/main/docker/docker-compose-network.yml).

1. **Clone the repository and configure environment variables**:

```bash
git clone https://github.com/apache/incubator-hugegraph-ai.git
cd incubator-hugegraph-ai
cp docker/env.template docker/.env

# Edit docker/.env to set PROJECT_PATH to your local checkout path

```

2. **Start the services**:

```bash
cd docker
docker compose -f docker-compose-network.yml up -d

```

This command launches two containers:
- `hugegraph-server` (image `hugegraph/hugegraph`) exposing port **8080** for the REST API and Hubble UI
- `hugegraph-llm` (built from `docker/Dockerfile.llm`) exposing port **8001** for the Gradio-based KG construction interface

3. **Verify the deployment**:

```bash
docker compose -f docker-compose-network.yml ps

```

4. **Access the services**:
- **HugeGraph Server**: `http://localhost:8080`
- **RAG/KG Service**: `http://localhost:8001`

Use the Gradio UI to click **Import into Vector**, **Extract Graph Data**, and **Update Vid Embedding** to complete the three-stage pipeline.

### Build and Run from Source

For development or customization requiring code modifications:

1. **Start the graph server**:

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

```

2. **Install Python dependencies using `uv`**:

```bash
git clone https://github.com/apache/incubator-hugegraph-ai.git
cd incubator-hugegraph-ai
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync --extra llm

```

The `uv sync --extra llm` command installs LLM-related packages including `litellm`, `gradio`, and vector database clients. For Milvus or Qdrant support, run `uv sync --extra vectordb`.

3. **Launch the demo application**:

```bash
source .venv/bin/activate
python -m hugegraph_llm.demo.rag_demo.app

```

The Gradio interface starts on `127.0.0.1:8001`, allowing you to construct the knowledge graph through the web UI.

### Programmatic Deployment for CI/CD

Automate knowledge graph construction without manual UI interaction using the `SchedulerSingleton` API from [`hugegraph_llm/flows/scheduler.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph_llm/flows/scheduler.py) and flow definitions from [`hugegraph_llm/flows/__init__.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph_llm/flows/__init__.py):

```python
from hugegraph_llm.flows.scheduler import SchedulerSingleton
from hugegraph_llm.flows import FlowName

scheduler = SchedulerSingleton.get_instance()

# Stage 1: Index document chunks

scheduler.schedule_flow(FlowName.IMPORT_CHUNKS, docs=["document.txt"])

# Stage 2: Extract graph structure

schema = {
    "vertex_labels": [{"name": "Person", "properties": ["name", "birth"]}],
    "edge_labels": [{"name": "knows", "source_label": "Person", "target_label": "Person"}]
}
scheduler.schedule_flow(
    FlowName.GRAPH_EXTRACT,
    schema=schema,
    texts=["...raw text content..."],
    example_prompt="Extract entities and relationships.",
    graph_type="property_graph"
)

# Stage 3: Persist to HugeGraph and index vertices

scheduler.schedule_flow(FlowName.IMPORT_GRAPH_DATA, data="auto", schema=schema)
scheduler.schedule_flow(FlowName.UPDATE_VID_EMBEDDINGS)

```

## Step-by-Step Deployment Examples

### Complete Docker-Compose Workflow

After executing `docker compose -f docker-compose-network.yml up -d`:

1. Navigate to `http://localhost:8001` in your browser
2. Paste source documents into the text area and click **Import into Vector** (executes the `import_chunks` flow via [`vector_index_utils.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/vector_index_utils.py))
3. Define a JSON schema specifying vertex and edge labels, then click **Extract Graph Data** (triggers `graph_extract` flow via `extract_graph`)
4. Click **Load into GraphDB** to persist the property graph to the HugeGraph server at `localhost:8080`
5. Click **Update Vid Embedding** to populate the graph-vid vector index using `update_vid_embedding` in [`graph_index_utils.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/graph_index_utils.py)

### Python CI/CD Deployment Script

For automated deployments in production pipelines:

```python

# deploy_kg.py

import os
from hugegraph_llm.flows.scheduler import SchedulerSingleton
from hugegraph_llm.flows import FlowName

scheduler = SchedulerSingleton.get_instance()

# Load source documents

with open("data/corpus.txt", "r") as f:
    raw_text = f.read()

# Execute complete pipeline

scheduler.schedule_flow(FlowName.IMPORT_CHUNKS, raw_text)
scheduler.schedule_flow(
    FlowName.GRAPH_EXTRACT,
    schema={
        "vertex_labels": [{"name": "Article", "properties": ["title"]}],
        "edge_labels": [{"name": "cites", "source_label": "Article", "target_label": "Article"}]
    },
    texts=[raw_text]
)
scheduler.schedule_flow(FlowName.IMPORT_GRAPH_DATA, data="auto", schema=schema)
scheduler.schedule_flow(FlowName.UPDATE_VID_EMBEDDINGS)

print("✅ Knowledge graph deployed and ready for queries")

```

Execute the script after activating the virtual environment:

```bash
source .venv/bin/activate
python deploy_kg.py

```

## Summary

- **Three-stage architecture**: Document chunking via [`vector_index_utils.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/vector_index_utils.py), graph extraction via [`graph_index_utils.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/graph_index_utils.py), and vertex vectorization via `update_vid_embedding`.
- **Docker-Compose deployment**: Use [`docker/docker-compose-network.yml`](https://github.com/apache/incubator-hugegraph-ai/blob/main/docker/docker-compose-network.yml) to launch the complete stack with HugeGraph server on port 8080 and the RAG service on port 8001.
- **Source-based deployment**: Install with `uv sync --extra llm` and run `python -m hugegraph_llm.demo.rag_demo.app` for development environments.
- **Programmatic automation**: Use `SchedulerSingleton.schedule_flow()` with `FlowName` enums to build and deploy knowledge graphs in CI/CD pipelines.
- **Core utilities**: The [`hugegraph_llm/utils/graph_index_utils.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph_llm/utils/graph_index_utils.py) module handles graph data import and embedding updates, while [`hugegraph_llm/utils/vector_index_utils.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph_llm/utils/vector_index_utils.py) manages document processing.

## Frequently Asked Questions

### What are the system requirements for deploying HugeGraph AI?

For Docker-Compose deployments, allocate at least 4GB RAM for the HugeGraph server container and 2GB for the LLM service. The server requires port 8080 for the REST API and Hubble UI, while the RAG interface uses port 8001. Production deployments with large vector indexes require additional disk space for Milvus or Qdrant data volumes configured in `docker/env.template`.

### Can I deploy HugeGraph AI without Docker?

Yes. Run the HugeGraph server independently using the `hugegraph/hugegraph` Docker image or a native installation, then install the Python components from the apache/incubator-hugegraph-ai repository using `uv sync --extra llm`. Activate the virtual environment and launch the web interface with `python -m hugegraph_llm.demo.rag_demo.app` to access the Gradio UI on `localhost:8001`.

### How do I update an existing knowledge graph with new data?

Use the Scheduler API to incrementally process additional documents. Call `scheduler.schedule_flow(FlowName.IMPORT_CHUNKS, new_documents)` followed by `FlowName.GRAPH_EXTRACT` with your existing schema definition. Then execute `FlowName.IMPORT_GRAPH_DATA` to merge new vertices and edges into the existing graph, and `FlowName.UPDATE_VID_EMBEDDINGS` to refresh the vector indexes for graph-RAG retrieval.

### Where is the knowledge graph data physically stored?

The property graph persists in the HugeGraph server (port 8080), which uses RocksDB or other configurable backends. Vector embeddings for document chunks and graph vertices are stored separately in your configured vector database—either Milvus, Qdrant, or built-in stores—managed through [`vector_index_utils.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/vector_index_utils.py) and indexed via the `update_vid_embedding` function in [`graph_index_utils.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/graph_index_utils.py) according to the apache/incubator-hugegraph-ai source code.