# album-rag

**Repository Path**: r1Way/album-rag

## Basic Information

- **Project Name**: album-rag
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-03
- **Last Updated**: 2026-05-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 📷 图像知识库 RAG

基于多模态大模型描述 + 向量检索的图像知识库系统。

## 流程

1. **图像描述**：将图片发给多模态大模型（如 GPT-4o），生成详细的中文描述（情景描述 + 文字内容）。
2. **向量化**：使用本地嵌入模型（`BAAI/bge-small-zh-v1.5`）将描述文本转为向量。
3. **存储**：将向量与描述存入本地 Qdrant 向量数据库。
4. **检索**：用户用自然语言提问，系统将问题向量化后在数据库中检索最相关的图片。

## 目录结构

```
rag/
├── src/rag/              # 源代码
│   ├── config.py         # 配置管理
│   ├── image_descriptor.py  # 多模态大模型图像描述
│   ├── embedder.py       # 文本向量化
│   ├── vector_store.py   # Qdrant 向量数据库封装
│   ├── ingest.py         # 图片导入流程
│   ├── search.py         # 检索与问答
│   ├── cli.py            # 命令行交互入口
│   └── main.py           # FastAPI 服务入口（可选）
├── .env                  # 环境变量配置（需自行创建）
├── .env.example          # 环境变量模板
├── pyproject.toml        # uv 项目配置
└── qdrant_data/          # 本地向量数据库（自动创建）
```

## 环境准备

### 1. 配置大模型 API

复制模板文件并填入你的 API Key：

```powershell
copy .env.example .env
```

编辑 `.env`：

```env
# 必须：OpenAI 兼容的 API Key
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# 可选：API 基础地址（如果使用第三方代理或国内兼容接口）
OPENAI_BASE_URL=https://api.openai.com/v1

# 可选：模型名称（需要支持 vision）
OPENAI_MODEL=gpt-4o
```

支持任意 OpenAI 兼容接口，例如：
- Moonshot (Kimi)
- Zhipu (GLM)
- 通义千问
- Azure OpenAI
- 本地 vLLM / Ollama（需支持 vision）

### 2. HuggingFace 镜像（国内环境）

如果无法直连 HuggingFace，请在运行命令前设置镜像：

```powershell
$env:HF_ENDPOINT="https://hf-mirror.com"
```

嵌入模型会在首次运行时自动下载到本地缓存。

## 使用方式

所有命令均在 `rag/` 目录下通过 `uv run python -m rag.cli <command>` 执行。

### 查看知识库状态

```powershell
uv run python -m rag.cli status
```

### 导入图片

将 `G:\project\2026\photo\information` 中的图片导入知识库：

```powershell
$env:HF_ENDPOINT="https://hf-mirror.com"
uv run python -m rag.cli ingest
```

首次导入会：
1. 逐张调用大模型生成描述（需消耗 API Token）
2. 下载嵌入模型到本地（首次约 100MB）
3. 将向量写入本地 Qdrant

重复运行会自动跳过已导入的图片。

### 交互式提问

```powershell
$env:HF_ENDPOINT="https://hf-mirror.com"
uv run python -m rag.cli chat
```

输入你的问题，系统会返回最相关的图片及其描述。输入 `q` 退出。

### 单次搜索

```powershell
$env:HF_ENDPOINT="https://hf-mirror.com"
uv run python -m rag.cli search 红色的花
```

## 配置项说明

| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `OPENAI_API_KEY` | *(必填)* | 大模型 API Key |
| `OPENAI_BASE_URL` | `https://api.openai.com/v1` | API 基础地址 |
| `OPENAI_MODEL` | `gpt-4o` | 多模态模型名称 |
| `EMBEDDING_MODEL` | `BAAI/bge-small-zh-v1.5` | 本地嵌入模型 |
| `EMBEDDING_DEVICE` | `cpu` | 运行设备（cpu / cuda） |
| `QDRANT_PATH` | `./qdrant_data` | 本地向量数据库路径 |
| `COLLECTION_NAME` | `image_knowledge` | Qdrant Collection 名 |
| `IMAGE_DIR` | `G:\project\2026\photo\information` | 图片来源目录 |

## 技术栈

- **Python 3.12** + **uv** 虚拟环境管理
- **OpenAI SDK**：调用多模态大模型生成图像描述
- **SentenceTransformers**：本地文本嵌入（`bge-small-zh-v1.5`）
- **Qdrant**：本地向量数据库
- **Rich**：终端交互美化
- **FastAPI**（可选）：提供 HTTP API 服务

## 注意事项

1. **API 费用**：导入图片时会调用大模型 Vision API，按图片数量计费，请确保余额充足。
2. **模型下载**：首次运行需要下载约 100MB 的嵌入模型，请保持网络畅通。
3. **Windows 编码**：如遇中文乱码，可在运行前执行 `$env:PYTHONIOENCODING="utf-8"`。
4. **Qdrant 关闭警告**：程序退出时可能出现的 `msvcrt` 警告是 Qdrant 本地客户端的已知问题，不影响数据完整性。