# VisionRAG：完全本地运行的多模态RAG系统，让图像也能被语义检索

> 基于FastAPI和Next.js的本地多模态RAG系统，支持Ollama和PaliGemma视觉模型，通过两阶段检索（向量搜索+CrossEncoder重排序）实现图像语义搜索和自然语言问答。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-05-24T06:50:19.000Z
- 最近活动: 2026-05-24T07:28:00.988Z
- 热度: 157.4
- 关键词: VisionRAG, 多模态RAG, 视觉模型, Ollama, PaliGemma, 本地部署, ChromaDB
- 页面链接: https://www.zingnex.cn/forum/thread/visionrag-rag
- Canonical: https://www.zingnex.cn/forum/thread/visionrag-rag
- Markdown 来源: ingested_event

---

## 原作者与来源

- **原作者/维护者**: tanmay-devhub
- **来源平台**: GitHub
- **原项目名**: VisionRAG
- **原始链接**: https://github.com/tanmay-devhub/VisionRAG
- **发布时间**: 2026年5月24日

---

## 项目概述：图像的语义检索革命

在RAG（检索增强生成）领域，绝大多数方案专注于文本。但现实世界中的大量信息以图像形式存在——图表、截图、照片、设计稿。**如何让这些视觉内容也能被语义检索？**

VisionRAG提供了一个优雅的解决方案：一个完全本地运行的多模态RAG系统。它允许你上传图像（PNG/JPG/WEBP），通过视觉模型生成语义描述，存储在本地向量数据库中，然后回答关于这些图像的自然语言问题——答案会引用原始图像并在UI中以内联缩略图形式展示。

### 核心特性

- **图像摄取**：上传图像，视觉模型生成描述，描述成为可搜索的语义块
- **双视觉后端**：支持Ollama（完全本地）或PaliGemma（HuggingFace）
- **两阶段检索**：SentenceTransformer向量搜索 + CrossEncoder重排序
- **内联来源**：答案引用源图像，以缩略图形式渲染在UI中
- **实时进度**：摄取任务报告完成状态
- **零外部依赖**：完全在本地机器上运行

---

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端 | FastAPI + Uvicorn (Python 3.11+) |
| 向量存储 | ChromaDB（持久化、本地） |
| 嵌入模型 | all-MiniLM-L6-v2 (SentenceTransformers) |
| 文本LLM | Ollama (llama3.2) via langchain-ollama |
| 视觉模型 | Ollama / PaliGemma 2 |
| 重排序器 | cross-encoder/ms-marco-MiniLM-L-6-v2 |
| 前端 | Next.js 14 App Router + TypeScript + Tailwind CSS |

---

## 工作原理

### 数据流

```
上传图像 (PNG/JPG/WEBP)
    │
    └──► 视觉模型
            └──► 描述 + figure_type + 标题
                    │
                    └──► ChromaDB 存储 (all-MiniLM-L6-v2 嵌入)
                         图像保存到 static/figures/

查询
    │
    ├──► ChromaDB 向量搜索 (top_k × 4 候选)
    ├──► CrossEncoder 重排序 (top_k 最终结果)
    └──► Ollama LLM (基于图像描述生成答案)
            └──► 答案 + 来源 (带内联图像缩略图)
```

### 关键设计决策

**两阶段检索策略**

1. **第一阶段 - 向量搜索**：使用轻量级SentenceTransformer快速召回4倍于最终需求的候选
2. **第二阶段 - 重排序**：使用CrossEncoder对候选进行精确排序，返回最终结果

这种设计平衡了效率（快速召回）和准确性（精确排序）。

**视觉描述生成**

视觉模型不仅生成图像的文本描述，还提取：
- `description`：详细语义描述
- `figure_type`：图像类型（如图表、照片、截图）
- `caption`：简短标题

这些元数据共同构成可搜索的语义块。

---

## 快速开始

### 本地运行

**前置条件**
- Python 3.11+
- Node.js 18+
- Ollama已安装并运行

```bash
# 拉取Ollama模型
ollama pull llama3.2

# 后端
cd backend
cp .env.example .env
pip install -r requirements.txt
uvicorn app.main:app --reload

# 前端
cd frontend
npm install
npm run dev
```

### Docker运行

```bash
cp backend/.env.example backend/.env
docker compose up --build
docker exec visionrag-ollama ollama pull llama3.2
```

---

## 视觉后端配置

### Ollama后端（默认，完全免费本地运行）

需要本地运行Ollama。任何支持视觉的Ollama模型都可以使用。

```env
VISION_BACKEND=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_VISION_MODEL=<your-vision-model>
```

### PaliGemma后端（免费，本地HuggingFace下载约3GB）

运行google/paligemma2-3b-ft-docci-448模型，通过transformers本地执行。

**设置步骤**：
1. 在HuggingFace接受模型许可
2. 获取访问令牌

```env
VISION_BACKEND=paligemma
PALIGEMMA_MODEL=google/paligemma2-3b-ft-docci-448
HF_TOKEN=your_hf_token_here
```

模型首次摄取时自动下载，缓存于`~/.cache/huggingface/`。

---

## 项目结构

```
./
├── backend/
│   ├── app/
│   │   ├── main.py              # FastAPI应用、CORS、静态文件挂载
│   │   ├── schemas.py           # Pydantic请求/响应模型
│   │   ├── routers/
│   │   │   ├── ingest.py      # POST /ingest, GET /ingest/status/{id}
│   │   │   ├── query.py       # POST /query
│   │   │   └── graph.py       # 图谱可视化端点
│   │   └── services/
│   │       ├── vision.py      # VisionService (Ollama/PaliGemma)
│   │       ├── graph_store.py # ChromaDB包装器
│   │       ├── llm.py         # Ollama LLM答案生成
│   │       ├── reranker.py    # CrossEncoder重排序
│   │       └── job_store.py   # 内存摄取任务追踪
│   ├── .env.example
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/
│   ├── app/
│   │   ├── page.tsx             # 根布局（聊天/文件标签页）
│   │   └── components/
│   │       ├── ChatWindow.tsx   # 聊天界面+来源渲染
│   │       ├── UploadPanel.tsx  # 文件上传+摄取进度
│   │       └── SourcePanel.tsx  # 内联来源展示
│   ├── lib/api.ts               # 类型化的后端API封装
│   └── Dockerfile
├── static/figures/              # 上传的图像（由后端服务）
├── docker-compose.yml
└── README.md
```

---

## API参考

| 方法 | 端点 | 描述 |
|------|------|------|
| POST | /ingest | 上传图像，返回job_id |
| GET | /ingest/status/{job_id} | 查询摄取进度 |
| GET | /ingest/jobs | 列出所有摄取任务 |
| POST | /query | 提问，返回答案+来源 |
| GET | /graph | 区块图谱可视化 |
| GET | /graph/files | 列出已摄取文件及区块数 |
| GET | /graph/stats | 所有内容的聚合统计 |
| DELETE | /graph | 清除ChromaDB中的所有数据 |
| GET | /health | 服务健康检查 |
| GET | /figures/{filename} | 提供上传的图像 |

---

## 应用场景

### 适用场景

- **技术文档管理**：上传架构图、流程图、API文档截图，通过自然语言查询
- **设计资产管理**：设计师上传作品，团队成员通过描述搜索相关设计
- **研究资料整理**：研究人员上传论文图表、实验结果，建立可搜索的知识库
- **个人知识库**：个人用户整理截图、照片，构建私有图像搜索引擎

### 优势

1. **完全本地**：数据不出机器，隐私完全可控
2. **零成本**：使用开源模型，无API调用费用
3. **可扩展**：模块化设计，易于替换组件
4. **可视化**：答案直接展示源图像，验证方便

---

## 与云端方案的对比

| 特性 | VisionRAG | 云端多模态RAG |
|------|-----------|--------------|
| 数据隐私 | 完全本地 | 需上传至云端 |
| 成本 | 零运行成本 | 按调用付费 |
| 网络依赖 | 无 | 需要网络连接 |
| 模型选择 | 受限于本地硬件 | 通常更多选择 |
| 延迟 | 依赖本地硬件 | 通常更快 |
| 可定制性 | 完全可控 | 受限于服务商 |

---

## 技术亮点

### 模块化服务设计

每个核心功能封装为独立服务：
- `VisionService`：统一接口，支持Ollama/PaliGemma两种后端
- `GraphStore`：ChromaDB封装，提供高级查询接口
- `RerankerService`：CrossEncoder重排序逻辑
- `LLMService`：Ollama文本生成

这种设计使得替换组件变得简单——例如，可以轻松添加对GPT-4V或其他视觉模型的支持。

### 异步任务处理

图像摄取是耗时操作，系统采用异步设计：
- 上传立即返回job_id
- 客户端轮询`/ingest/status/{job_id}`获取进度
- 支持并发摄取多个图像

### 类型安全

前端使用TypeScript，API调用有完整类型定义：
- `lib/api.ts`封装所有后端端点
- Pydantic模型确保前后端数据一致性

---

## 局限性与未来方向

### 当前局限

1. **硬件要求**：视觉模型需要GPU才能获得良好性能
2. **单用户设计**：当前实现面向单用户场景
3. **视觉模型能力**：开源视觉模型的描述质量可能不如商业模型
4. **无多模态生成**：仅支持基于图像的问答，不支持图像生成

### 潜在改进

1. **多用户支持**：添加用户认证和隔离
2. **增量更新**：支持图像更新而非重新摄取
3. **更多视觉后端**：集成GPT-4V、Claude 3等商业模型选项
4. **图像生成**：扩展为完整的多模态对话系统

---

## 结论

VisionRAG展示了多模态RAG的一个可行路径：**完全本地、零成本、隐私优先**。

在技术文档管理、设计资产管理、研究资料整理等场景中，这种方案可能比云端服务更合适——尤其是当数据隐私是首要考虑时。

项目的模块化设计和清晰架构也为进一步扩展提供了良好基础。对于希望探索多模态RAG但又担心数据隐私和成本的开发者，VisionRAG是一个值得尝试的起点。

最重要的是，它证明了：**即使不依赖云端API，也能构建功能完整的多模态AI应用。**