VLM Hybrid Gallery

这是当前 GitHub 仓库的总说明文件。

这个项目分成两层：

1. ai-engine/
   • 负责图片理解、摘要生成、embedding、FAISS 索引和 AI 搜索
2. Django Web
   • 计划直接在仓库根目录构建
   • 负责网页展示、AI 搜索交互、构建索引按钮和进度条

当前页面效果如下：

当前/规划中的关键结构如下：

.
├── manage.py
├── README.md
├── .gitignore
├── photos/
├── data/
├── ai-engine/
├── django_config_proj/
├── web/
├── django_prd.md
└── django_project_tree.md

其中：

• manage.py
  • Django 管理入口
• photos/
  • 原始图片目录
• data/
  • 生成的索引、向量和 FAISS 文件
• ai-engine/
  • AI 引擎目录
• test/unittest/
  • Django/Web 层单元测试目录
• django_config_proj/
  • Django 项目配置
• web/
  • Django app

ai-engine/ 负责：

• 扫描图片
• 生成图片描述、摘要、OCR
• 把摘要转成 embedding
• 构建 FAISS 索引
• 执行 AI 搜索

当前引擎已经按模块拆好：

• scan_and_caption.py
• build_embeddings.py
• build_faiss_index.py
• query_album.py
• rerank.py

根目录的 Django Web 负责：

• 展示全部图片
• 提供 AI 智能搜索页面
• 提供 构建索引 按钮
• 显示每一步构建进度条
• 在右上角显示 Ollama Health
• 支持点击图片后放大预览并查看详细信息

首页进入后至少包含两个标签：

1. 全部图片
2. AI 智能搜索

页面右上角建议包含：

• Ollama Health
• 构建索引 按钮

每张图片卡片还应支持：

• 点击后打开大图预览
• 背景自动变深
• 展示名称、元信息、摘要、描述、OCR 文本和 sha256

Web 页面右上角应显示 Ollama 服务状态：

• checking
• healthy
• unhealthy

这个状态用于快速判断：

• 本地 Ollama 是否在线
• AI 搜索和构建索引是否具备运行条件

Web 端统一使用 Bootstrap 5。

重点使用：

• 标签页
• 网格布局
• 卡片
• 按钮
• 进度条
• 状态徽标
• Modal

实现上尽量优先使用现成套件，而不是自己手写复杂 UI 机制。

优先建议：

• django-bootstrap5
• Bootstrap 5 Tabs / Modal / Progress
• htmx

Web API 统一建议使用 Django Ninja。

核心接口包括：

• 图片列表
• AI 搜索
• 创建构建索引任务
• 查询构建任务进度
• 查询 Ollama Health

这些接口默认面向仓库根目录的数据：

• photos/
• data/

其中构建索引任务状态建议返回：

• 百分比
• 当前进度值
• 总量
• ETA

目前与 Django 规划相关的文档有：

• django_prd.md
• django_project_tree.md

AI 引擎子目录说明在：

• README.md

测试目录分层如下：

• test/unittest/
  • Django/Web 层测试
• ai-engine/test/unittest/
  • AI 引擎层测试

建议后续按这个顺序推进：

1. 完善 django_config_proj/ 和 web/ 的页面骨架
2. 把 ai-engine 的进度回调完整接到 Django 任务状态
3. 完善 全部图片 页面分页与加载策略
4. 完善 AI 智能搜索 页面结果细节和无结果提示
5. 继续补 Django/Web 层 unittest
6. 运行并联调 Ollama Health、搜索、构建索引三条链路