How to Implement Custom Entity Types in LightRAG Using addon_params

Configure the addon_params dictionary when initializing LightRAG or mutate rag.addon_params["entity_types"] at runtime to override the default entity extraction taxonomy without modifying core library code.

LightRAG constructs knowledge graphs by extracting entities from text using a configurable type system. By default, the pipeline recognizes the entity categories defined in DEFAULT_ENTITY_TYPES (located in [lightrag/constants.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/constants.py#L28-L41)), but you can customize this list through the addon_params configuration to support domain-specific taxonomies like medical diagnoses, legal clauses, or IT infrastructure components.

How addon_params Drives Entity Extraction

The LightRAG class aggregates configuration into a shared global_config dictionary during initialization (see __post_init__ in [lightrag/lightrag.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/lightrag.py#L49-L56)). The addon_params field is defined as:

# lightrag/lightrag.py

addon_params: dict[str, Any] = field(
    default_factory=lambda: {
        "language": get_env_value(
            "SUMMARY_LANGUAGE", DEFAULT_SUMMARY_LANGUAGE, str
        ),
        "entity_types": get_env_value("ENTITY_TYPES", DEFAULT_ENTITY_TYPES, list),
    }
)

When the extraction pipeline runs in [lightrag/operate.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/operate.py#L2834-L2837), it reads from this global configuration:

language = global_config["addon_params"].get("language", DEFAULT_SUMMARY_LANGUAGE)
entity_types = global_config["addon_params"].get(
    "entity_types", DEFAULT_ENTITY_TYPES
)

These values are interpolated into the LLM prompt template (lines 3320‑3345 in operate.py), where the list is joined into a comma-separated string. The model then returns entities constrained to these specific types, and _process_extraction_result() creates graph nodes using the verbatim type labels.

Three Methods to Configure Custom Entity Types

You can supply custom entity types through three mechanisms, listed here by override precedence (highest to lowest):

Constructor Parameter (Highest Precedence)

Pass a dictionary to the addon_params argument when instantiating LightRAG. This completely replaces the default factory values:

from lightrag.lightrag import LightRAG

rag = LightRAG(
    kv_storage="JsonKVStorage",
    vector_storage="NanoVectorDBStorage",
    graph_storage="NetworkXStorage",
    addon_params={
        "entity_types": ["Person", "Organization", "Product", "Vulnerability"],
        "language": "English",
    },
)

Runtime Mutation

Modify the dictionary after construction to change behavior for subsequent ingestion operations:

rag = LightRAG(...)  # initialization

rag.addon_params["entity_types"] = ["Asset", "Risk", "Regulation"]

Because addon_params resides in the shared global_config, changes propagate immediately to all downstream operations including summarization, reranking, and graph storage.

Environment Variables (Lowest Precedence)

Define ENTITY_TYPES in a .env file at your project root. The library loads this via load_dotenv() in [lightrag/api/config.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/api/config.py#L47-L51):

# .env

ENTITY_TYPES=Person,Organization,CustomDevice,SecurityPatch

Values are parsed as comma-separated strings and automatically injected into the default addon_params factory.

Implementation Examples

Basic Construction with Custom Types

from lightrag.lightrag import LightRAG

custom_entities = ["MedicalDevice", "Diagnosis", "TreatmentProtocol"]

rag = LightRAG(
    kv_storage="JsonKVStorage",
    vector_storage="NanoVectorDBStorage",
    graph_storage="NetworkXStorage",
    addon_params={"entity_types": custom_entities},
)

Full Ingestion Pipeline

from lightrag.lightrag import LightRAG
from pathlib import Path

rag = LightRAG(
    kv_storage="JsonKVStorage",
    vector_storage="NanoVectorDBStorage",
    graph_storage="NetworkXStorage",
    addon_params={
        "entity_types": ["SoftwareModule", "BugReport", "CodeCommit"],
        "language": "English",
    },
)

# Ingest documents

rag.ingest(Path("./repositories"))

# Query the resulting knowledge graph

results = rag.query("Which SoftwareModule fixes BugReport #442?")

Switching Types for Different Document Sets

# Initial extraction with general types

rag.addon_params["entity_types"] = ["Person", "Company", "Contract"]

# Later, switch to specialized types for technical documentation

rag.addon_params["entity_types"] = ["Server", "Database", "APIEndpoint"]
rag.ingest(Path("./technical_docs"))

Summary

• addon_params is the configuration gateway for entity type customization in LightRAG, stored in the shared global_config dictionary.
• Override methods: Constructor argument (highest priority), runtime dictionary mutation, or .env file ENTITY_TYPES variable (lowest priority).
• Prompt injection: The entity_types list is rendered into extraction prompts in operate.py, constraining the LLM to recognize only the specified categories.
• Persistence: Custom type labels are stored verbatim in the graph storage backend (Neo4j, NetworkX, etc.), enabling direct querying (e.g., MATCH (e:CustomDevice)) without schema migration.

Frequently Asked Questions

What is the default list of entity types in LightRAG?

The default taxonomy is defined as DEFAULT_ENTITY_TYPES in [lightrag/constants.py](https://github.com/HKUDS/LightRAG/blob/main/lightrag/constants.py#L28-L41). Typically includes general categories like "Person", "Organization", "Location", and "Event". You can inspect this constant to see the baseline before customizing.

Do I need to modify LightRAG source code to add new entity types?

No. The addon_params mechanism is designed for runtime configuration. By passing your custom list to the constructor or updating rag.addon_params["entity_types"], you alter the extraction behavior without touching files in the lightrag/ directory.

Will changing entity_types affect already extracted entities?

No. The entity_types configuration only affects the extraction phase for new documents being ingested. Existing nodes in the knowledge graph retain their original type labels. To reprocess old documents with new types, you must clear the storage and re-run rag.ingest().

Can I use different entity types for different documents in the same project?

Yes. Because addon_params is mutable, you can update rag.addon_params["entity_types"] between ingestion batches. Each call to rag.ingest() uses the current configuration, allowing you to process legal contracts with one taxonomy and technical manuals with another within the same LightRAG instance.

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