# singularguy/multimodalrag architecture

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

- Interactive diagram: https://gitdiagram.com/singularguy/multimodalrag
- Repository: https://github.com/singularguy/multimodalrag

## Overview

下面针对该项目“基于 CLIP、Faiss 和智谱AI的多模态 RAG 系统”，分步说明如何为架构图绘制提供指导，帮助负责人快速且准确地将系统分解成各个组件，并在图中呈现其关系与交互。

##### 确定项目类型与目的
- 本项目是一个“多模态检索增强生成”（RAG）演示工具 / Python脚本，主要作用是：
· 离线将文本（`data.json`）与图像（`images/`）转为向量并建立索引；
· 在线接收多模态查询（文本／图像或二者），检索相关内容并调用外部 LLM（智谱AI）生成回答。
- 面向开发者，可部署于命令行环境中，没有前端 UI，仅提供脚本使用示例。

##### 分析文件结构
- 根目录下有：
· `yangrouchuan.py`（主脚本，负责启动整个流程）
· `data.json`（文档元数据）
· `images/`（与文档对应的图像文件）
· `requirements.txt`（依赖，包括 Faiss、transformers、SQLite 驱动等）
· 若干 Jupyter Notebook（演示代码与中间结果，不影响核心架构）
- 架构上可识别出典型的四个模块：编码、索引、检索与生成。

##### 结合 README 深入理解
- 四个核心类：
· MultimodalEncoder：加载 CLIP，对文本与图像做 embed
· Indexer：管理 Faiss 索引与 SQLite 元数据表，并持久化
· Retriever：编码查询、在 Faiss 中检索，利用 SQLite 拿回元数据
· Generator：拼装 Prompt，调用智谱AI API 生成回答
- 还有两个主要“阶段”：
· 离线索引阶段（Encoder → Indexer）
· 在线查询阶段（Retriever → Generator）

##### 绘制系统设计图的核心思路
a. 主组件：
1) Data Store：
- JSON 数据源 (`data.json`)
- 图像文件 (`images/`)
2) MultimodalEncoder
3) Indexer
- Faiss 向量索引
- SQLite 数据库
4) Retriever
5) Generator
6) External Service：智谱AI API
7) User / CLI（触发查询与展示回答）
b. 数据流与交互：
- 离线流程（通常用虚线或不同颜色表示）：
1) 从 `data.json` + 图像读取原始数据
2) MultimodalEncoder 生成 embedding
3) Indexer 将 embedding 扔到 Faiss，并将 metadata 存到 SQLite；持久化到磁盘（`.faiss` 文件 + `.db`）
- 在线查询流程（主流程）：
1) 用户在 CLI 提交文本/图片/多模态查询
2) Retriever 调用 MultimodalEncoder 编码查询
3) 在 Faiss 中执行相似度搜索，拿到 top-k id 列表
4) 使用 SQLite 拿到对应文档元数据（文本描述 + 图像路径）
5) Generator 拼装 Prompt，调用智谱AI API 获取 LLM 结果
6) CLI 显示输出
c. 重要模式与原则：
- 模块化：四大职责清晰分离
- 持久化与解耦：Faiss 与 SQLite 各司其职
- 可扩展：更换 LLM / CLIP / 索引策略时局部改动
d. 关键技术栈：
- Python 3.9+、Hugging Face Transformers (`openai/clip-vit-base-patch32`)、Faiss（`IndexIDMap2` + `IndexFlatIP`）、SQLite、Requests 或官方 SDK 调用智谱AI（`glm-4-flash`）。

##### 针对该项目的绘图指南
- 使用 UML 部件图或架构图形式：
· 每个组件用带标签的矩形框表示（区分“静态组件”“动态组件”）
· 离线流程与在线流程分别用不同颜色（例如灰色 vs 蓝色）或虚线/实线区分
- 建议图中包含：
1) Data Ingestion（JSON + Images）
2) Encoder → Indexer（箭头标明 Embedding 生成与持久化）
3) Index Storage：Faiss 文件 + SQLite DB
4) Query Flow：User CLI → Retriever → Faiss + SQLite → Generator → ZhipuAPI → CLI
5) 外部服务：智谱AI API 图标或云服务图标
- 设计要点：
· 用不同形状（圆角矩形 / 平行四边形 /数据库图标）区分：
- 算法模块（Encoder/Indexer/Retriever/Generator）
- 存储（JSON、Images、.faiss、.db）
- 外部服务（智谱AI API）
· 箭头上标注数据格式（“文本 & 图像 Embedding” / “ID 列表” / “Prompt + Context”）
· 颜色编码：
- 灰色：离线索引阶段
- 蓝色：在线检索阶段
- 绿色：外部调用

##### 绘图工具建议与细节
- 每个组件旁注明使用的主要库/模型（如“CLIP`openai/clip-vit-base-patch32`” / “Faiss IndexFlatIP” / “SQLite3” / “智谱AI `glm-4-flash`”）
- 确保：
· 组件名称清晰无歧义
· 箭头方向准确表达数据流向
· 在适当位置备注持久化文件名（`multimodal_rag_index.faiss`, `multimodal_rag_data.db`）

总结：将项目 按“离线索引阶段” 与 “在线查询阶段” 两大流程拆分，围绕 Encoder→Indexer→Storage 与 Retriever→Generator→ExternalAPI 两条主线，用色彩与形状区分模块职责，并在箭头上补充数据格式和调用顺序，便可快速绘制一张既清晰又涵盖所有关键技术细节的系统设计图。

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Offline Indexing Phase
    subgraph "Offline Indexing" 
        direction TB
        DSJson["data.json"]:::storage 
        Images["images/"]:::storage 
        Encoder["MultimodalEncoder\n(CLIP)"]:::offline 
        Indexer["Indexer\n(Faiss + SQLite)"]:::offline 
        Faiss["Faiss Index\n(multimodal_rag_index.faiss)"]:::storage 
        SQLite["SQLite DB\n(multimodal_rag_data.db)"]:::storage 

        DSJson -->|"raw data"| Encoder
        Images -->|"raw data"| Encoder
        Encoder -->|"embeddings"| Indexer
        Indexer -->|"persist"| Faiss
        Indexer -->|"persist"| SQLite
    end

    %% Online Query Phase
    subgraph "Online Query" 
        direction TB
        User["User CLI"]:::online 
        Retriever["Retriever"]:::online 
        Generator["Generator"]:::online 
        Zhipu["智谱AI API"]:::external 

        User -->|"query (text/image)"| Retriever
        Retriever -->|"encode"| Encoder
        Encoder -->|"query embeddings"| Retriever
        Retriever -->|"similarity search"| Faiss
        Faiss -->|"top-k IDs"| Retriever
        Retriever -->|"IDs lookup"| SQLite
        SQLite -->|"metadata"| Retriever
        Retriever -->|"context"| Generator
        Generator -->|"Prompt + Context"| Zhipu
        Zhipu -->|"LLM response"| Generator
        Generator -->|"answer"| User
    end

    %% Supporting Files
    subgraph "Supporting Files" 
        direction TB
        Env[".env"]:::config 
        Req["requirement.txt"]:::config 
        README["README.md"]:::config 
        NB1["MRAG0426-1.ipynb"]:::config 
        NB2["MRAG0426-2.ipynb"]:::config 
        NB3["MRAG0426-3.ipynb"]:::config 
        NB4["MultimodalRAG0425.ipynb"]:::config 
    end

    %% Click Events
    click DSJson "https://github.com/singularguy/multimodalrag/blob/main/data.json"
    click Images "https://github.com/singularguy/multimodalrag/tree/main/images/"
    click Env "https://github.com/singularguy/multimodalrag/blob/main/.env"
    click Req "https://github.com/singularguy/multimodalrag/blob/main/requirement.txt"
    click README "https://github.com/singularguy/multimodalrag/blob/main/README.md"
    click NB1 "https://github.com/singularguy/multimodalrag/blob/main/MRAG0426-1.ipynb"
    click NB2 "https://github.com/singularguy/multimodalrag/blob/main/MRAG0426-2.ipynb"
    click NB3 "https://github.com/singularguy/multimodalrag/blob/main/MRAG0426-3.ipynb"
    click NB4 "https://github.com/singularguy/multimodalrag/blob/main/MultimodalRAG0425.ipynb"

    %% Styles
    classDef offline fill:#f0f0f0,stroke:#999,stroke-width:1px;
    classDef online fill:#bbdefb,stroke:#1e88e5,stroke-width:1px;
    classDef external fill:#c8e6c9,stroke:#2e7d32,stroke-width:1px;
    classDef storage fill:#ffe0b2,stroke:#ef6c00,stroke-width:1px;
    classDef config fill:#e1bee7,stroke:#8e24aa,stroke-width:1px;
```
