This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

HugeGraph-AI

1: GraphRAG UI Details

Please refer to the AI repository README for the most up-to-date documentation, and the official website regularly is updated and synchronized.

AI summarizes the project documentation:

1. Summary

The hugegraph-llm is a tool for the implementation and research related to large language models. This project includes runnable demos, it can also be used as a third-party library.

As we know, graph systems can help large models address challenges like timeliness and hallucination, while large models can help graph systems with cost-related issues.

With this project, we aim to reduce the cost of using graph systems and decrease the complexity of building knowledge graphs. This project will offer more applications and integration solutions for graph systems and large language models.

Construct knowledge graph by LLM + HugeGraph
Use natural language to operate graph databases (Gremlin/Cypher)
Knowledge graph supplements answer context (GraphRAG → Graph Agent)

2. Environment Requirements

[!IMPORTANT]
python 3.10+ (not tested in 3.12)
hugegraph-server 1.3+ (better to use 1.5+)
uv 0.7+

3. Preparation

3.1 Docker

Docker Deployment
Alternatively, you can deploy HugeGraph-AI using Docker:

Ensure you have Docker installed
We provide two container images:
- Image 1: hugegraph/rag
  For building and running RAG functionality for rapid deployment and direct source code modification
- Image 2: hugegraph/rag-bin
  A binary translation of C compiled with Nuitka, for better performance and efficiency.

Pull the Docker images:

docker pull hugegraph/rag:latest # Pull Image 1
docker pull hugegraph/rag-bin:latest # Pull Image 2

Start the Docker container:

docker run -it --name rag -v path2project/hugegraph-llm/.env:/home/work/hugegraph-llm/.env -p 8001:8001 hugegraph/rag bash
docker run -it --name rag-bin -v path2project/hugegraph-llm/.env:/home/work/hugegraph-llm/.env -p 8001:8001 hugegraph/rag-bin bash

Start the Graph RAG demo:

# For Image 1
python ./src/hugegraph_llm/demo/rag_demo/app.py # or run python -m hugegraph_llm.demo.rag_demo.app

# For Image 2
./app.dist/app.bin

Access the interface at http://localhost:8001

3.2 Build from Source

Start the HugeGraph database, you can run it via Docker/Binary Package. There is a simple method by docker:
```
docker run -itd --name=server -p 8080:8080 hugegraph/hugegraph
```
You can refer to the detailed documents doc for more guidance.

Configuring the uv environment, Use the official installer to install uv, See the uv documentation for other installation methods

# You could try pipx or pip to install uv when meet network issues, refer the uv doc for more details
curl -LsSf https://astral.sh/uv/install.sh | sh  - # install the latest version like 0.7.3+

Clone this project

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

Configuration dependency environment
```
cd incubator-hugegraph-ai/hugegraph-llm
uv venv && source .venv/bin/activate
uv pip install -e .
```
If dependency download fails or too slow due to network issues, it is recommended to modify hugegraph-llm/pyproject.toml.
To start the Gradio interactive demo for Graph RAG, run the following command, then open http://127.0.0.1:8001 in your browser.
```
python -m hugegraph_llm.demo.rag_demo.app  # same as "uv run xxx"
```
The default host is 0.0.0.0 and the port is 8001. You can change them by passing command line arguments--host and --port.
```
python -m hugegraph_llm.demo.rag_demo.app --host 127.0.0.1 --port 18001
```
After running the web demo, the config file .env will be automatically generated at the path hugegraph-llm/.env. Additionally, a prompt-related configuration file config_prompt.yaml will also be generated at the path hugegraph-llm/src/hugegraph_llm/resources/demo/config_prompt.yaml. You can modify the content on the web page, and it will be automatically saved to the configuration file after the corresponding feature is triggered. You can also modify the file directly without restarting the web application; refresh the page to load your latest changes.
(Optional)To regenerate the config file, you can use config.generate with -u or --update.
```
python -m hugegraph_llm.config.generate --update
```
Note: Litellm support multi-LLM provider, refer litellm.ai to config it
(Optional) You could use hugegraph-hubble to visit the graph data, could run it via Docker/Docker-Compose for guidance. (Hubble is a graph-analysis dashboard that includes data loading/schema management/graph traverser/display).

(Optional) offline download NLTK stopwords

python ./hugegraph_llm/operators/common_op/nltk_helper.py

[!TIP]
You can also refer to our quick-start doc to understand how to use it & the basic query logic 🚧

4. Examples

4.1 Build a knowledge graph in HugeGraph through LLM

4.1.1 Build a knowledge graph through the gradio interactive interface

Parameter description:

Docs:
- text: Build rag index from plain text
- file: Upload file(s) which should be TXT or .docx (Multiple files can be selected together)
Schema: (Except 2 types)
- User-defined Schema (JSON format, follow the template to modify it)
- Specify the name of the HugeGraph graph instance, it will automatically get the schema from it (like “hugegraph”)
Graph extract head: The user-defined prompt of graph extracting
If it already exists the graph data, you should click “Rebuild vid Index” to update the index

gradio-config

4.1.2 Build a knowledge graph through code

The KgBuilder class is used to construct a knowledge graph. Here is a brief usage guide:

Initialization: The KgBuilder class is initialized with an instance of a language model. This can be obtained from the LLMs class.
Initialize the LLMs instance, get the LLM, and then create a task instance KgBuilder for graph construction. KgBuilder defines multiple operators, and users can freely combine them according to their needs. (tip: print_result() can print the result of each step in the console, without affecting the overall execution logic)
```
from hugegraph_llm.models.llms.init_llm import LLMs
from hugegraph_llm.operators.kg_construction_task import KgBuilder

TEXT = ""
builder = KgBuilder(LLMs().get_chat_llm())
(
    builder
    .import_schema(from_hugegraph="talent_graph").print_result()
    .chunk_split(TEXT).print_result()
    .extract_info(extract_type="property_graph").print_result()
    .commit_to_hugegraph()
    .run()
)
```

Import Schema: The import_schema method is used to import a schema from a source. The source can be a HugeGraph instance, a user-defined schema, or an extraction result. The method print_result can be chained to print the result.

# Import schema from a HugeGraph instance
builder.import_schema(from_hugegraph="xxx").print_result()
# Import schema from an extraction result
builder.import_schema(from_extraction="xxx").print_result()
# Import schema from user-defined schema
builder.import_schema(from_user_defined="xxx").print_result()

Chunk Split: The chunk_split method is used to split the input text into chunks. The text should be passed as a string argument to the method.

# Split the input text into documents
builder.chunk_split(TEXT, split_type="document").print_result()
# Split the input text into paragraphs
builder.chunk_split(TEXT, split_type="paragraph").print_result()
# Split the input text into sentences
builder.chunk_split(TEXT, split_type="sentence").print_result()

Extract Info: The extract_info method is used to extract info from a text. The text should be passed as a string argument to the method.

TEXT = "Meet Sarah, a 30-year-old attorney, and her roommate, James, whom she's shared a home with since 2010."
# extract property graph from the input text
builder.extract_info(extract_type="property_graph").print_result()
# extract triples from the input text
builder.extract_info(extract_type="property_graph").print_result()

Commit to HugeGraph: The commit_to_hugegraph method is used to commit the constructed knowledge graph to a HugeGraph instance.
```
builder.commit_to_hugegraph().print_result()
```
Run: The run method is used to execute the chained operations.
```
builder.run()
```
The methods of the KgBuilder class can be chained together to perform a sequence of operations.

4.2 Retrieval augmented generation (RAG) based on HugeGraph

The RAGPipeline class is used to integrate HugeGraph with large language models to provide retrieval-augmented generation capabilities. Here is a brief usage guide:

Extract Keyword: Extract keywords and expand synonyms.

from hugegraph_llm.operators.graph_rag_task import RAGPipeline
graph_rag = RAGPipeline()
graph_rag.extract_keywords(text="Tell me about Al Pacino.").print_result()

Match Vid from Keywords: Match the nodes with the keywords in the graph.
```
graph_rag.keywords_to_vid().print_result()
```
Query Graph for Rag: Retrieve the corresponding keywords and their multi-degree associated relationships from HugeGraph.
```
graph_rag.query_graphdb(max_deep=2, max_graph_items=30).print_result()
```
Rerank Searched Result: Rerank the searched results based on the similarity between the question and the results.
```
graph_rag.merge_dedup_rerank().print_result()
```

Synthesize Answer: Summarize the results and organize the language to answer the question.

graph_rag.synthesize_answer(vector_only_answer=False, graph_only_answer=True).print_result()

Run: The run method is used to execute the above operations.
```
graph_rag.run(verbose=True)
```

1 - GraphRAG UI Details

Follow up main doc to introduce the basic UI function & details, welcome to update and improve at any time, thanks

1. Core Logic of the Project

Build RAG Index Responsibilities:

Split and vectorize text
Extract text into a graph (construct a knowledge graph) and vectorize the vertices

(Graph)RAG & User Functions Responsibilities:

Retrieve relevant content from the constructed knowledge graph and vector database based on the query to supplement the prompt.

2. (Processing Flow) Build RAG Index

Construct a knowledge graph, chunk vector, and graph vid vector from the text.

graph TD;
    A[Raw Text] --> B[Text Segmentation]
    B --> C[Vectorization]
    C --> D[Store in Vector Database]

    A --> F[Text Segmentation]
    F --> G[LLM extracts graph based on schema \nand segmented text]
    G --> H[Store graph in Graph Database, \nautomatically vectorize vertices \nand store in Vector Database]
    
    I[Retrieve vertices from Graph Database] --> J[Vectorize vertices and store in Vector Database \nNote: Incremental update]

Four Input Fields:

Doc(s): Input text
Schema: The schema of the graph, which can be provided as a JSON-formatted schema or as the graph name (if it exists in the database).
Graph Extract Prompt Header: The header of the prompt
Output: Display results

Buttons:

Get RAG Info
- Get Vector Index Info: Retrieve vector index information
- Get Graph Index Info: Retrieve graph index information
Clear RAG Data
- Clear Chunks Vector Index: Clear chunk vector
- Clear Graph Vid Vector Index: Clear graph vid vector
- Clear Graph Data: Clear Graph Data
Import into Vector: Convert the text in Doc(s) into vectors (requires chunking the text first and then converting the chunks into vectors)
Extract Graph Data (1): Extract graph data from Doc(s) based on the Schema, using the Graph Extract Prompt Header and chunked content as the prompt
Load into GraphDB (2): Store the extracted graph data into the database (automatically calls Update Vid Embedding to store vectors in the vector database)
Update Vid Embedding: Convert graph vid into vectors

Execution Flow:

Input text into the Doc(s) field.
Click the Import into Vector button to split and vectorize the text, storing it in the vector database.
Input the graph Schema into the Schema field.
Click the Extract Graph Data (1) button to extract the text into a graph.
Click the Load into GraphDB (2) button to store the extracted graph into the graph database (this automatically calls Update Vid Embedding to store the vectors in the vector database).
Click the Update Vid Embedding button to vectorize the graph vertices and store them in the vector database.

3. (Processing Flow) (Graph)RAG & User Functions

The Import into Vector button in the previous module converts text (chunks) into vectors, and the Update Vid Embedding button converts graph vid into vectors. These vectors are stored separately to supplement the context for queries (answer generation) in this module. In other words, the previous module prepares the data for RAG (vectorization), while this module executes RAG.

This module consists of two parts:

HugeGraph RAG Query
(Batch) Back-testing

The first part handles single queries, while the second part handles multiple queries at once. Below is an explanation of the first part.

graph TD;
    A[Question] --> B[Vectorize the question and search \nfor the most similar chunk in the Vector Database &#40chunk&#41]

    A --> F[Extract keywords using LLM]
    F --> G[Match vertices precisely in Graph Database \nusing keywords; perform fuzzy matching in \nVector Database &#40graph vid&#41]
    G --> H[Generate Gremlin query using matched vertices and query with LLM]
    H --> I[Execute Gremlin query; if successful, finish; if failed, fallback to BFS]
    
    B --> J[Sort results]
    I --> J
    J --> K[Generate answer]

Input Fields:

Question: Input the query
Query Prompt: The prompt template used to ask the final question to the LLM
Keywords Extraction Prompt: The prompt template for extracting keywords from the question
Template Num: < 0 means disable text2gql; = 0 means no template(zero-shot); > 0 means using the specified number of templates

Query Scope Selection:

Basic LLM Answer: Does not use RAG functionality
Vector-only Answer: Uses only vector-based retrieval (queries chunk vectors in the vector database)
Graph-only Answer: Uses only graph-based retrieval (queries graph vid vectors in the vector database and the graph database)
Graph-Vector Answer: Uses both graph-based and vector-based retrieval

Execution Flow:

Graph-only Answer:

Extract keywords from the question using the Keywords Extraction Prompt.

Use the extracted keywords to:
- First, perform an exact match in the graph database.
- If no match is found, perform a fuzzy match in the vector database (graph vid vector) to retrieve relevant vertices.
text2gql: Call the text2gql-related interface, using the matched vertices as entities to convert the question into a Gremlin query and execute it in the graph database.
BFS: If text2gql fails (LLM-generated queries might be invalid), fall back to executing a graph query using a predefined Gremlin query template (essentially a BFS traversal).

Vector-only Answer:

Convert the query into a vector.
Search for the most similar content in the chunk vector dataset in the vector database.

Sorting and Answer Generation:

After executing the retrieval, sort the search (retrieval) results to construct the final prompt.
Generate answers based on different prompt configurations and display them in different output fields:
- Basic LLM Answer
- Vector-only Answer
- Graph-only Answer
- Graph-Vector Answer

4. (Processing Flow) Text2Gremlin

Converts natural language queries into Gremlin queries.

This module consists of two parts:

Build Vector Template Index (Optional): Vectorizes query/gremlin pairs from sample files and stores them in the vector database for reference when generating Gremlin queries.
Natural Language to Gremlin: Converts natural language queries into Gremlin queries.

The first part is straightforward, so the focus is on the second part.

graph TD;
    A[Gremlin Pairs File] --> C[Vectorize query]
    C --> D[Store in Vector Database]
    
    F[Natural Language Query] --> G[Search for the most similar query \nin the Vector Database \n&#40If no Gremlin pairs exist in the Vector Database, \ndefault files will be automatically vectorized&#41 \nand retrieve the corresponding Gremlin]
    G --> H[Add the matched pair to the prompt \nand use LLM to generate the Gremlin \ncorresponding to the Natural Language Query]

Input Fields for the Second Part:

Natural Language Query: Input the natural language text to be converted into Gremlin.

Schema: Input the graph schema.

Execution Flow:

Input the query (natural language) into the Natural Language Query field.
Input the graph schema into the Schema field.
Click the Text2Gremlin button, and the following execution logic applies:
1. Convert the query into a vector.
2. Construct the prompt:
  - Retrieve the graph schema.
  - Query the vector database for example vectors, retrieving query-gremlin pairs similar to the input query (if the vector database lacks examples, it automatically initializes with examples from the resources folder).

  - Generate the Gremlin query using the constructed prompt.

5. Graph Tools

Input Gremlin queries to execute corresponding operations.