DOCSEARCHbyAlgolia
Submit Docs

fast-graphrag

repository·main·Indexed 26 days ago

https://github.com/circlemind-ai/fast-graphrag

A streamlined, promptable framework for high-precision, agent-driven retrieval workflows using graph-based RAG. It provides an interpretable and efficient way to build retrieval pipelines, featuring the GraphRAG class for data insertion and querying, support for custom LLM services, checkpointing to prevent data corruption, and the ability to export graphs to GraphML format. Version 0.0.5.

Tokens
4K
Snippets
4
Records
33
Agent score
86%

What's inside fast-graphrag

  1. Quickstart with GraphRAG

    main

    To use fast-graphrag, initialize the GraphRAG class with a working directory, a domain description, example queries, and desired entity types. You can then insert text data into the graph. The graph is automatically persisted to the working_dir and will be retained upon subsequent initializations from the same directory.

    Example Usage:

    from fast_graphrag import GraphRAG

DOMAIN = "Analyze this story and identify the characters. Focus on how they interact with each other, the locations they explore, and their relationships."

EXAMPLE_QUERIES = [
    "What is the significance of Christmas Eve in A Christmas Carol?",
    "How does the setting of Victorian London contribute to the story's themes?",
    "Describe the chain of events that leads to Scrooge's transformation.",
    "How does Dickens use the different spirits (Past, Present, and Future) to guide Scrooge?",
    "Why does Dickens choose to divide the story into \"staves\" rather than chapters?"
]

ENTITY_TYPES = ["Character", "Animal", "Place", "Object", "Activity", "Event"]

grag = GraphRAG(
    working_dir="./book_example",
    domain=DOMAIN,
    example_queries="\n".join(EXAMPLE_QUERIES),
    entity_types=ENTITY_TYPES
)

with open("./book.txt") as f:
    grag.insert(f.read())

print(grag.query("Who is Scrooge?").response)

  2. Run the RAG performance benchmarks

    main

    You can run the benchmark scripts in the benchmarks/ directory to evaluate the retrieval capabilities of different RAG methods (VectorDB, LightRAG, GraphRAG, and Circlemind) on the 2wikimultihopqa dataset.

    • To view preloaded results and get performance numbers immediately, run evaluate_dbs.xx.
    • To regenerate the databases for the different methods from scratch, run create_dbs.xx.

    Requirements & Notes:

    • You must set an OPENAI_API_KEY environment variable.
    • Warning: Running LightRAG and GraphRAG can take over an hour to process and may be expensive.
    • The evaluation measures the percentage of queries for which all required evidence was successfully retrieved.

  3. Configure environment variables for fast-graphrag

    main

    Before running fast-graphrag, you must configure the following environment variables:

    • OPENAI_API_KEY: Your OpenAI API key.
    • CONCURRENT_TASK_LIMIT (Optional): Sets the limit for concurrent requests to the LLM. This is useful for controlling the number of simultaneous tasks, especially when running local models.
    export OPENAI_API_KEY="sk-..."
export CONCURRENT_TASK_LIMIT=8

  4. Install fast-graphrag

    main

    You can install fast-graphrag via PyPI for stability, or from source for potentially better performance.

    From PyPI (Recommended for stability):

    pip install fast-graphrag

    From Source (Recommended for best performance):

    # clone this repo first
cd fast_graphrag
poetry install
    pip install fast-graphrag

  5. Explore fast-graphrag examples

    main

    The examples folder contains tutorials for common use cases:

    • custom_llm.py: How to configure fast-graphrag to use different OpenAI API-compatible language models and embedders.
    • checkpointing.ipynb: How to use checkpoints to prevent irreversible data corruption.
    • query_parameters.ipynb: How to use different query parameters, such as with_references=True to include references to used information in the answer.

  6. Enable checkpointing in GraphRAG

    main
    To protect against data corruption across synchronized databases, you can enable checkpointing by setting the n_checkpoints parameter to an integer k > 0 when initializing the GraphRAG object. This tells the library to automatically maintain the k most recent checkpoints in memory and allow for rollbacks if necessary.

  7. Migrate a project to use checkpoints

    main

    If you have an existing project without checkpoints and want to enable them:

    1. Set the n_checkpoints flag in your GraphRAG initialization.
    2. Run an insert operation (even with an empty string/file).
    3. Verify the checkpoint was created by querying the graph.
    4. Check your working_dir for a new directory named with a timestamp (e.g., ./book_example/1731555907).
    5. Once verified, you can safely remove all files in the root of your working_dir (e.g., ./book_example/*.*), leaving only the checkpoint folders.

  9. Truncate TContext for Token Limits

    main

    The TContext class provides a truncate method to ensure the context fits within specific character or token limits. This is useful when preparing context for LLM prompts.

    Pass a dictionary max_chars where keys are the context components ('entities', 'relations', 'chunks') and values are the maximum allowed characters for each.

  11. Represent a Query Response with TQueryResponse

    main

    Use TQueryResponse to encapsulate the result of a RAG query. It contains the generated response string and the context used to produce it.

    It includes a powerful format_references method to transform numeric citations in the response (e.g., [1]) into formatted references (e.g., [DocIndex]) and returns a dictionary of the reference metadata.

  12. Configure GraphRAG via Config class

    main

    You can customize the behavior of GraphRAG by passing a Config instance to its constructor. The Config class provides granular control over:

    • Services: llm_service, embedding_service, chunking_service_cls, information_extraction_service_cls, and state_manager_cls.
    • Storage: graph_storage, entity_storage, and chunk_storage.
    • Upsert Policies: information_extraction_upsert_policy, node_upsert_policy, and edge_upsert_policy.
    • Ranking Policies: entity_ranking_policy, relation_ranking_policy, and chunk_ranking_policy.