flowchart TB
    subgraph CLI["命令行入口层"]
        Init[graphrag init]
        Index[graphrag index]
        Update[graphrag update]
        Query[graphrag query]
        PromptTune[graphrag prompt-tune]
    end

    subgraph API["API 层"]
        IndexAPI[build_index]
        QueryAPI[global_search<br/>local_search<br/>drift_search<br/>basic_search]
        PromptAPI[generate_indexing_prompts]
    end

    subgraph Core["核心业务层"]
        direction TB
        
        subgraph IndexEngine["索引引擎"]
            Pipeline[Pipeline Factory]
            Workflows[Workflows]
            Operations[Operations]
        end
        
        subgraph QueryEngine["查询引擎"]
            GlobalSearch[Global Search]
            LocalSearch[Local Search]
            DriftSearch[DRIFT Search]
            BasicSearch[Basic Search]
        end
        
        subgraph ConfigSystem["配置系统"]
            ConfigLoader[Config Loader]
            Validation[Validation]
        end
    end

    subgraph DataLayer["数据层"]
        DataModel[Data Model<br/>Entity/Relationship/Community]
        Storage[Storage<br/>File/Blob/CosmosDB]
        Cache[Cache<br/>File/JSON/Memory]
        VectorStore[Vector Store<br/>Azure AI/LanceDB/CosmosDB]
    end

    subgraph AI["AI 服务层"]
        LLM[Language Model<br/>OpenAI/Azure/LiteLLM]
        Embedding[Embedding Model]
        Tokenizer[Tokenizer]
        PromptSystem[Prompt System]
    end

    subgraph Support["支撑层"]
        Callbacks[Callbacks]
        Logger[Logger]
        Factory[Factory]
    end

    CLI --> API
    API --> Core
    Core --> DataLayer
    Core --> AI
    Core --> Support
    IndexEngine --> Workflows
    Workflows --> Operations
    QueryEngine -.查询.-> DataModel
    IndexEngine -.写入.-> DataModel
    Operations --> LLM
    Operations --> Embedding
    QueryEngine --> LLM
    QueryEngine --> VectorStore
    ConfigSystem --> ConfigLoader

原始文档 → 文本分块 → 实体抽取 → 关系抽取 → 图合并 → 社区发现 → 社区报告生成 → 嵌入计算 → Parquet 文件

用户查询 → 查询嵌入 → 向量检索 → 上下文构建 → LLM 生成 → 响应返回

sequenceDiagram
    autonumber
    participant User as 用户/CLI
    participant API as API (build_index)
    participant Factory as Pipeline Factory
    participant Pipeline as Pipeline Runner
    participant WF_Load as Workflow: Load Documents
    participant WF_Extract as Workflow: Extract Graph
    participant WF_Community as Workflow: Create Communities
    participant WF_Report as Workflow: Community Reports
    participant WF_Embed as Workflow: Generate Embeddings
    participant LLM as LLM Service
    participant Storage as Storage Layer
    participant Cache as Cache Layer

    User->>API: build_index(config, method)
    API->>Factory: create_pipeline(config, method)
    Factory-->>API: Pipeline(workflows)
    
    API->>Pipeline: run_pipeline(pipeline, config, callbacks)
    
    Note over Pipeline: 工作流 1: 加载输入文档
    Pipeline->>WF_Load: run_workflow(config, context)
    WF_Load->>Storage: 读取原始文档 (CSV/Text/JSON)
    Storage-->>WF_Load: DataFrame(documents)
    WF_Load->>WF_Load: 文本分块 (text_splitting)
    WF_Load->>Storage: 写入 text_units.parquet
    WF_Load-->>Pipeline: text_units DataFrame
    
    Note over Pipeline: 工作流 2: 实体和关系抽取
    Pipeline->>WF_Extract: run_workflow(config, context)
    WF_Extract->>Storage: 读取 text_units.parquet
    Storage-->>WF_Extract: text_units DataFrame
    
    loop 每个 text_unit（异步并发）
        WF_Extract->>Cache: 检查缓存
        alt 缓存命中
            Cache-->>WF_Extract: 缓存的抽取结果
        else 缓存未命中
            WF_Extract->>LLM: 调用实体抽取提示词
            LLM-->>WF_Extract: 实体和关系列表 (JSON)
            WF_Extract->>Cache: 存储到缓存
        end
    end
    
    WF_Extract->>WF_Extract: 合并和去重实体/关系
    WF_Extract->>Storage: 写入 entities.parquet, relationships.parquet
    WF_Extract-->>Pipeline: entities, relationships
    
    Note over Pipeline: 工作流 3: 社区发现
    Pipeline->>WF_Community: run_workflow(config, context)
    WF_Community->>Storage: 读取 entities.parquet, relationships.parquet
    Storage-->>WF_Community: 图数据
    WF_Community->>WF_Community: Leiden 算法聚类
    WF_Community->>Storage: 写入 communities.parquet
    WF_Community-->>Pipeline: communities
    
    Note over Pipeline: 工作流 4: 社区报告生成
    Pipeline->>WF_Report: run_workflow(config, context)
    WF_Report->>Storage: 读取 communities.parquet
    Storage-->>WF_Report: communities DataFrame
    
    loop 每个社区（异步并发）
        WF_Report->>Cache: 检查缓存
        alt 缓存命中
            Cache-->>WF_Report: 缓存的报告
        else 缓存未命中
            WF_Report->>LLM: 调用社区报告生成提示词
            LLM-->>WF_Report: 社区报告 (JSON)
            WF_Report->>Cache: 存储到缓存
        end
    end
    
    WF_Report->>Storage: 写入 community_reports.parquet
    WF_Report-->>Pipeline: community_reports
    
    Note over Pipeline: 工作流 5: 文本嵌入
    Pipeline->>WF_Embed: run_workflow(config, context)
    WF_Embed->>Storage: 读取待嵌入数据
    Storage-->>WF_Embed: 文本列表
    
    loop 每个文本批次
        WF_Embed->>Cache: 检查缓存
        alt 缓存命中
            Cache-->>WF_Embed: 缓存的嵌入向量
        else 缓存未命中
            WF_Embed->>LLM: 调用嵌入 API
            LLM-->>WF_Embed: 嵌入向量数组
            WF_Embed->>Cache: 存储到缓存
        end
    end
    
    WF_Embed->>Storage: 写入嵌入列到 Parquet
    WF_Embed-->>Pipeline: 嵌入完成
    
    Pipeline-->>API: List[PipelineRunResult]
    API-->>User: 索引构建完成

sequenceDiagram
    autonumber
    participant User as 用户/CLI
    participant API as Query API
    participant Factory as Search Factory
    participant Search as Search Engine
    participant Context as Context Builder
    participant Vector as Vector Store
    participant LLM as LLM Service
    participant Storage as Storage Layer

    User->>API: local_search(config, query, ...)
    API->>Storage: 读取索引文件<br/>(entities/relationships/text_units/...)
    Storage-->>API: DataFrames
    
    API->>API: 数据模型转换<br/>(DataFrame → Entity/Relationship objects)
    
    API->>Factory: get_local_search_engine(config, data...)
    Factory->>Factory: 创建 LLM 实例
    Factory->>Factory: 创建 Embedding 实例
    Factory->>Factory: 创建 Tokenizer 实例
    Factory->>Factory: 创建 Context Builder 实例
    Factory-->>API: LocalSearch 实例
    
    API->>Search: stream_search(query)
    
    Note over Search,Context: 步骤 1: 构建上下文
    Search->>Context: build_context(query, ...)
    Context->>Context: 生成查询嵌入
    Context->>Vector: 向量相似度搜索 (top-k entities)
    Vector-->>Context: 匹配的实体列表
    
    Context->>Context: 扩展相关关系
    Context->>Context: 获取相关文本单元
    Context->>Context: 获取相关社区报告
    
    Context->>Context: Token 预算分配<br/>(text_unit_prop, community_prop)
    Context->>Context: 截断上下文以适应 token 限制
    Context-->>Search: ContextResult(context_text, entities, ...)
    
    Note over Search,LLM: 步骤 2: LLM 生成答案
    Search->>Search: 构建系统提示词 + 上下文 + 查询
    
    alt 流式模式
        loop 流式生成 token
            Search->>LLM: 调用 LLM (streaming=true)
            LLM-->>Search: token chunk
            Search-->>API: yield token chunk
            API-->>User: 流式输出 token
        end
    else 非流式模式
        Search->>LLM: 调用 LLM (streaming=false)
        LLM-->>Search: 完整响应文本
        Search-->>API: 响应文本 + 上下文数据
        API-->>User: 响应结果
    end

graph TB
    API --> Index
    API --> Query
    API --> Config
    
    CLI --> API
    CLI --> Config
    
    Index --> Workflows
    Index --> Storage
    Index --> Cache
    Index --> LLM
    Index --> DataModel
    Index --> Callbacks
    
    Query --> SearchEngines
    Query --> ContextBuilder
    Query --> VectorStores
    Query --> LLM
    Query --> DataModel
    
    Workflows --> Operations
    Operations --> LLM
    Operations --> Cache
    
    SearchEngines --> ContextBuilder
    ContextBuilder --> VectorStores
    
    LLM --> Tokenizer
    LLM --> Cache
    
    Config --> EnvReader
    Config --> Validation
    
    Storage --> ConfigPaths
    Cache --> Storage
    VectorStores --> Storage
    
    Logger -.日志.-> 所有模块
    Factory -.创建.-> Storage
    Factory -.创建.-> Cache
    Factory -.创建.-> VectorStores

import asyncio
from graphrag.config import load_config
from graphrag.api import build_index

# 1. 初始化项目（CLI）
# 命令: graphrag init --root ./my_project

# 2. 准备输入数据
# 将文档放入 ./my_project/input/

# 3. 加载配置
config = load_config(
    root_dir="./my_project",
    config_filepath="./my_project/settings.yaml"
)

# 4. 构建索引
async def main():
    results = await build_index(
        config=config,
        method="standard",  # 或 "fast"
        verbose=True
    )
    
    for result in results:
        print(f"Workflow: {result.workflow}")
        print(f"Runtime: {result.total_runtime}s")
        if result.errors:
            print(f"Errors: {result.errors}")

asyncio.run(main())

import asyncio
import pandas as pd
from graphrag.config import load_config
from graphrag.api import local_search

# 1. 加载配置
config = load_config(root_dir="./my_project")

# 2. 加载索引数据
entities = pd.read_parquet("./my_project/output/entities.parquet")
relationships = pd.read_parquet("./my_project/output/relationships.parquet")
text_units = pd.read_parquet("./my_project/output/text_units.parquet")
communities = pd.read_parquet("./my_project/output/communities.parquet")
community_reports = pd.read_parquet("./my_project/output/community_reports.parquet")
covariates = None  # 可选

# 3. 执行查询
async def main():
    response, context = await local_search(
        config=config,
        entities=entities,
        relationships=relationships,
        text_units=text_units,
        communities=communities,
        community_reports=community_reports,
        covariates=covariates,
        community_level=2,
        response_type="Multiple Paragraphs",
        query="What are the main themes in the documents?"
    )
    
    print("Response:", response)
    print("Context entities:", len(context.get("entities", [])))

asyncio.run(main())

import asyncio
from graphrag.config import load_config
from graphrag.api import build_index

# 1. 将新文档添加到 ./my_project/input/

# 2. 加载配置
config = load_config(root_dir="./my_project")

# 3. 执行增量更新
async def main():
    results = await build_index(
        config=config,
        method="standard",
        is_update_run=True,  # 关键参数
        verbose=True
    )
    
    print("Update completed")

asyncio.run(main())