# facebookresearch/fid architecture

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

- Interactive diagram: https://gitdiagram.com/facebookresearch/fid
- Repository: https://github.com/facebookresearch/fid

## Overview

##### Project type and purpose
- This is an open-source question-answering toolkit that implements two key pipelines:
- Fusion-in-Decoder “reader” models (generative QA)
- Retriever training via distillation from the reader
- It provides end-to-end scripts to download raw QA datasets (NaturalQuestions, TriviaQA), preprocess them, index a knowledge source (Wikipedia), train and evaluate both retrievers and readers, and distill reader knowledge back into the retriever.

##### File structure
- Top-level scripts:
- get-data.sh, get-model.sh – downloading datasets & pretrained models
- train_reader.py, test_reader.py – train/evaluate the Fusion-in-Decoder reader
- train_retriever.py – train the retriever using distillation
- generate_passage_embeddings.py, passage_retrieval.py – index passages and perform retrieval at query time
- evaluate_retrieved_passages.py – analysis utilities
- src/ directory (core library modules):
- data.py – data loading & formatting
- preprocess.py – data preprocessing (tokenization, truncation)
- index.py – embedding generation and indexing logic
- model.py – model definitions (reader & retriever architectures)
- evaluation.py – metrics & evaluation loops
- options.py – CLI argument parsing
- util.py, slurm.py – helper functions, cluster job wrappers
- Configs and environments: requirements.txt, setup.py

##### README for additional insights
- Two main workflows are described:
I. Fusion-in-Decoder reader train/test
II. Distilling knowledge from reader to retriever (4 steps: cross-attention score extraction, retriever training, indexing, retrieval)
- Calls out core dependencies: PyTorch, Transformers, NumPy
- Mentions “inspired by DPR” – so embedding + FAISS-style index concept

##### Elements
- Blue for data components
- Green for training pipelines
- Orange for inference / indexing pipelines
- Gray for external dependencies (PyTorch, Transformers, FAISS)

##### Detail without overthinking
- Break the system into as many logical pieces as possible
- Both offline (training / indexing) and online (retrieval → reader) flows

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Components
    subgraph "Data Layer"
        direction TB
        GetData["get-data.sh"]:::data
        GetModel["get-model.sh"]:::data
    end

    %% Preprocessing
    Preprocess["Tokenization & Formatting"]:::data
    DataLoad["Data Loading & Formatting"]:::data

    %% Training Pipelines
    subgraph "Training Pipelines"
        direction TB
        subgraph "Reader Pipeline" 
            direction TB
            TrainReader["train_reader.py"]:::training
            TestReader["test_reader.py"]:::training
            ModelDef["Model Definitions"]:::training
        end
        subgraph "Retriever Pipeline"
            direction TB
            TrainRetriever["train_retriever.py"]:::training
            ModelDef                               
        end
    end

    %% Indexing & Embedding
    Embeddings["Passage Embedding Generation"]:::inference
    Indexing["Indexing (FAISS-style)"]:::inference

    %% Online Retrieval & Reader Inference
    Retrieval["passage_retrieval.py"]:::inference
    ReaderInfer["Fusion-in-Decoder Inference"]:::inference

    %% Evaluation
    EvalScript["evaluate_retrieved_passages.py"]:::inference
    EvalLib["src/evaluation.py"]:::inference

    %% Utilities & Config
    subgraph "Utilities & Config"
        direction TB
        Options["src/options.py"]:::util
        Slurm["src/slurm.py"]:::util
        Util["src/util.py"]:::util
        Requirements["requirements.txt"]:::config
        Setup["setup.py"]:::config
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        PyTorch["PyTorch"]:::external
        Transformers["Transformers"]:::external
        NumPy["NumPy"]:::external
        FAISS["FAISS/ANN Index"]:::external
    end

    %% Data Flow
    GetData --> Preprocess
    GetModel --> Preprocess
    Preprocess --> DataLoad

    DataLoad --> TrainReader
    DataLoad --> TrainRetriever

    TrainReader --> TestReader
    TestReader -->|cross-attention scores| TrainRetriever

    TrainRetriever --> Embeddings
    ModelDef --> TrainReader
    ModelDef --> TrainRetriever

    Embeddings --> Indexing
    Indexing --> Retrieval
    Retrieval --> ReaderInfer
    ReaderInfer --> EvalScript
    Retrieval --> EvalScript
    EvalScript --> EvalLib

    %% Utilities usage
    Options -.-> TrainReader
    Options -.-> TrainRetriever
    Slurm -.-> TrainReader
    Slurm -.-> TrainRetriever
    Util -.-> Preprocess
    Util -.-> DataLoad

    %% External usage
    PyTorch -.-> TrainReader
    PyTorch -.-> TrainRetriever
    Transformers -.-> ModelDef
    NumPy -.-> Preprocess
    FAISS -.-> Indexing

    %% Click Events
    click GetData "https://github.com/facebookresearch/fid/blob/main/get-data.sh"
    click GetModel "https://github.com/facebookresearch/fid/blob/main/get-model.sh"
    click Preprocess "https://github.com/facebookresearch/fid/blob/main/src/preprocess.py"
    click DataLoad "https://github.com/facebookresearch/fid/blob/main/src/data.py"
    click TrainReader "https://github.com/facebookresearch/fid/blob/main/train_reader.py"
    click TestReader "https://github.com/facebookresearch/fid/blob/main/test_reader.py"
    click TrainRetriever "https://github.com/facebookresearch/fid/blob/main/train_retriever.py"
    click ModelDef "https://github.com/facebookresearch/fid/blob/main/src/model.py"
    click Embeddings "https://github.com/facebookresearch/fid/blob/main/generate_passage_embeddings.py"
    click Indexing "https://github.com/facebookresearch/fid/blob/main/src/index.py"
    click Retrieval "https://github.com/facebookresearch/fid/blob/main/passage_retrieval.py"
    click EvalScript "https://github.com/facebookresearch/fid/blob/main/evaluate_retrieved_passages.py"
    click EvalLib "https://github.com/facebookresearch/fid/blob/main/src/evaluation.py"
    click Options "https://github.com/facebookresearch/fid/blob/main/src/options.py"
    click Slurm "https://github.com/facebookresearch/fid/blob/main/src/slurm.py"
    click Util "https://github.com/facebookresearch/fid/blob/main/src/util.py"

    %% Styles
    classDef data fill:#E3F2FD,stroke:#90CAF9,color:#0D47A1;
    classDef training fill:#E8F5E9,stroke:#66BB6A,color:#1B5E20;
    classDef inference fill:#FFF3E0,stroke:#FFA726,color:#E65100;
    classDef util fill:#ECEFF1,stroke:#B0BEC5,color:#37474F;
    classDef config fill:#F3E5F5,stroke:#BA68C8,color:#4A148C;
    classDef external fill:#FAFAFA,stroke:#BDBDBD,color:#424242;\
```
