# flagopen/flagembedding architecture

> Architecture diagram of the GitHub repository flagopen/flagembedding, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/flagopen/flagembedding
- Repository: https://github.com/flagopen/flagembedding

## Overview

##### Major high-level components
- Core Library (FlagEmbedding package)
– The abstract layer (“abc”) that defines the interfaces for evaluation, fine-tuning, and inference.
– Evaluation modules that implement various benchmarks and evaluation pipelines (AIR-Bench, BEIR, MTEB, etc.).
– Fine-tuning modules that include separate sub-components (embedder and reranker) that further split into decoder-only, encoder-only, and even layerwise variants.
– Inference modules that provide “auto” interfaces (e.g. FlagAutoModel) for embedding and reranking.
- Research and Experimental Branches:
– The “research” directory, which contains prototypes, experiments, and implementation of additional models (BGE_M3, C_MTEB, LLARA, LM_Cocktail, LongLLM, etc.) for further extension of core capabilities.
- Tutorials and Examples:
– The “Tutorials” and “examples” directories that act as client-side demonstrations (quick start, usage instructions, fine-tuning examples) for guiding user integration.
- Documentation & Community:
– The “docs” directory and README support materials like API documentations, quick start guides, and CI/CD configuration in “.github/workflows” for automated testing/documentation.

- Use a layered approach with top layers representing the user-facing interfaces (tutorials, examples, command-line scripts) and lower layers representing core implementations.
– Show how user scripts/calls (via tutorials or from client applications) invoke the inference API (FlagAutoModel) to process input text and obtain embeddings.
– Illustrate how fine-tuning components receive data from both prepared datasets (from the “dataset” directory and jsonl example files) and training scripts, then produce refined embedding or reranker models.
– Indicate that evaluation components take in predicted outputs (embeddings, ranking scores) and compare them with benchmarks from multiple evaluation suites.
- How the “abc” abstraction layer serves as the foundation and how concrete implementations “inherit” from these via the finetune, evaluation, and inference subdirectories.

##### Modular and extensible design pattern
- Components into modules and submodules. For example, separate embedder versus reranker pipelines in both fine-tuning and inference.
– Rectangles for core modules (e.g., “abc”, “evaluation”, “finetune” and “inference”).
– Rounded rectangles for research experiments and prototypes.

##### Relevant technologies and roles
- Clearly label that the system is built with Python and integrates libraries (likely HuggingFace Transformers or similar LLM frameworks) to enable retrieval, embedding generation, and enhanced reranking.
- Demonstrate that the front layer (tutorials and examples) feeds into the core API implementations, which in turn interact with various benchmarking tasks.

- Submodule, such as the two main pipelines (embedder and reranker), is represented with its various subtypes (decoder-only, encoder-only, layerwise, etc.) when relevant.
- That the repository also integrates a robust documentation and tutorial system which is essential for user onboarding and system demonstrations.

## Diagram (Mermaid)

```mermaid
flowchart TD 
    %% User Interface & Documentation
    subgraph "User Interface & Documentation"
        UI1["Tutorials"]:::client
        UI2["Examples"]:::client
        UI3["Documentation"]:::docs
        UI4["README"]:::docs
        UI5["CI/CD Workflows"]:::workflows
    end

    %% Core Library (FlagEmbedding Package)
    subgraph "Core Library (FlagEmbedding)"
        A["ABC Interfaces"]:::core
        E["Evaluation Modules"]:::evaluation
        F["Fine-tuning Modules"]:::finetune
        I["Inference Modules"]:::inference
    end

    %% Research & Experimental Branches
    R["Research & Experimental Branches"]:::research

    %% Data flow and relationships
    UI1 -->|"invoke"| I
    UI2 -->|"invoke"| I
    A -->|"implements"| E
    A -->|"implements"| F
    A -->|"implements"| I
    F -->|"model_update"| I
    I -->|"produce_outputs"| E
    R -->|"extends"| A
    R -->|"extends"| F
    R -->|"extends"| I
    UI3 -->|"guides"| UI1
    UI3 -->|"guides"| UI2
    E -->|"feedback"| UI3

    %% Click Events
    click A "https://github.com/flagopen/flagembedding/tree/master/FlagEmbedding/abc"
    click E "https://github.com/flagopen/flagembedding/tree/master/FlagEmbedding/evaluation"
    click F "https://github.com/flagopen/flagembedding/tree/master/FlagEmbedding/finetune"
    click I "https://github.com/flagopen/flagembedding/tree/master/FlagEmbedding/inference"
    click R "https://github.com/flagopen/flagembedding/tree/master/research"
    click UI1 "https://github.com/flagopen/flagembedding/tree/master/Tutorials"
    click UI2 "https://github.com/flagopen/flagembedding/tree/master/examples"
    click UI3 "https://github.com/flagopen/flagembedding/tree/master/docs"
    click UI4 "https://github.com/flagopen/flagembedding/blob/master/README.md"
    click UI5 "https://github.com/flagopen/flagembedding/tree/master/.github/workflows"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef evaluation fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef finetune fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef inference fill:#A9DFBF,stroke:#28B463,stroke-width:2px;
    classDef research fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;
    classDef client fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef docs fill:#D5F5E3,stroke:#229954,stroke-width:2px;
    classDef workflows fill:#F9D3F3,stroke:#A569BD,stroke-width:2px;
```
