FoodClassifier/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

本项目采用**度量学习（Metric Learning）**的方式进行菜品识别和食材识别。核心思路是用 ResNet50 提取图像嵌入向量，配合 FAISS 向量库进行相似度检索，而非传统的端到端分类，从而支持无需重新训练即可快速添加新类别。

三个并行识别任务：

• DishClassification — 菜品识别
• WholeIngredientRecognition — 整体食材识别（未处理）
• ProcessedIngredientRecognition — 处理后食材识别（切块等）

常用命令

训练嵌入模型（CosFace 损失，主要方案）：

python train/train_cosface_embedding.py

CosFace 超参数网格搜索（scale × margin 组合）：

python train/grid_search_cosface.py

训练嵌入模型（Triplet + Center Loss，备用方案,目前没使用这个了，主要是未采集的图片和现有分类的相似度太高了）：

python train/train_triplet_embedding.py

基于训练好的模型构建 FAISS 索引：

python faiss_vector_db/build_faiss_index.py

启动主识别界面（嵌入向量方案）：

python classifier/embedding_food_classifier_app.py

启动数据管理与下载界面：

python data_management/app.py

训练 SegFormer 食物区域分割模型：

python SegFormer/training/train_minimal.py

测试 SegFormer 推理效果：

python SegFormer/inference/test_model.py

架构说明

度量学习流水线

输入图像 → ResNet50 主干网络（ImageNet1K_V2 预训练）
         → 512 维嵌入向量 → L2 归一化
         → FAISS IndexFlatIP（余弦相似度检索）
         → 返回 Top-K 相似食物及置信度分数

训练损失函数：

• CosFace（train_cosface_embedding.py）：大间距余弦损失；scale ≈ 64，margin ≈ 0.35–0.40（因任务而异）。泛化能力更强，为首选方案。
• Triplet + Center Loss（train_triplet_embedding.py）：在线难样本挖掘，margin = 0.5，Center Loss 权重因任务而异（0.5–20）。

关键模块

路径	功能说明
net/resnet_embedding.py	ResNet50 嵌入主干网络（512 维，L2 归一化）
net/food_net.py	遗留的自定义 CNN，用于端到端分类（4 类）
faiss_vector_db/faiss_manager.py	FAISS 索引的增删查存核心类
faiss_vector_db/build_faiss_index.py	遍历数据集、提取嵌入、构建索引
classifier/embedding_food_classifier_app.py	主 GUI（CustomTkinter，支持拖拽上传）
exp_multimodal/vlm_classifier.py	实验性：VLM（Ollama/Kimi）+ FAISS 开放集识别
data_management/app.py	数据采集 GUI，从 MySQL 后端下载图片
settings/settings.py	全局配置（NUM_CLASSES、MODEL_DIR、DEVICE 等）

FAISS 索引存储结构

每个任务在 faiss_vector_db/<任务名>/faiss_index/ 下独立存储：

• food_embeddings.index — FAISS 二进制索引文件
• labels.json / food_labels.json — 标签到食物名称的映射
• embeddings.npy — 原始向量的 numpy 数组

数据集目录结构

dataset/<任务名>/
├── train/<类别名>/  （图片）
├── val/<类别名>/
└── test/<类别名>/

VLM 多模态集成（实验性）

exp_multimodal/ 包含一套绕过封闭类别列表的开放集识别流水线：

• vlm_providers/ollama_provider.py — 本地 Ollama 服务（Qwen2.5-VL、LLaVA），地址：http://192.168.1.250:11434
• vlm_providers/kimi_provider.py — Kimi/Moonshot API（moonshot-v1-128k-vision-preview）
• build_dish_name_index.py — 使用 bge-large-zh-v1.5 为菜品名称构建文本向量索引
• VLM 配置保存在 vlm_config.json（提供商选择、API Key、候选菜品列表）

SegFormer 食物分割

SegFormer/ 包含用于提取食物区域的微调 SegFormer：

• 两阶段训练：先冻结编码器训练，再全量微调
• 损失函数：CrossEntropy + 0.5 × Dice Loss
• 数据以 COCO 格式存放于 SegFormer/data/

模型文件

训练好的模型保存在 model/ 下的版本子目录中：

• best_cosface_model.pth — CosFace 训练的嵌入模型
• best_embedding_model.pth — Triplet/Center Loss 训练的嵌入模型
• grid_search_<时间戳>/best_model_s<scale>_m<margin>.pth — 网格搜索最优结果

当前使用的模型路径通过 settings/settings.py 中的 MODEL_DIR 指定。

依赖安装

pip install -r requirements.txt

核心依赖：torch==2.7.0、torchvision==0.22.0、faiss-cpu>=1.7.0、customtkinter==5.2.2、tkinterdnd2==0.4.3、opencv-python==4.11.0.86。

数据管理界面连接远端 MySQL 数据库（192.168.1.250:3308）获取图片元数据，同时使用本地 SQLite 记录下载历史。