FoodClassifier/exp_multimodal/VLM_PROVIDER_README.md

VLM Provider 架构说明

📖 概述

本项目支持多种视觉语言模型（VLM）后端，通过统一的 Provider 接口实现：

• Ollama Provider: 本地/自建 Ollama 服务
• Kimi Provider: Moonshot AI 的 Kimi 1.5 厂商 API

🏗️ 架构设计

exp_multimodal/
├── vlm_providers/
│   ├── __init__.py           # 导出接口
│   ├── base.py               # VLMProvider 抽象基类
│   ├── ollama_provider.py    # Ollama 实现
│   └── kimi_provider.py      # Kimi 实现
├── vlm_classifier.py         # 使用 provider 进行分类
└── exp_multimodal_gui.py     # GUI 界面（支持 provider 切换）

抽象接口

所有 Provider 都继承 VLMProvider 基类并实现 chat_vision 方法：

from exp_multimodal.vlm_providers import VLMProvider

class MyCustomProvider(VLMProvider):
    def chat_vision(self, prompt, image_paths, temperature, timeout_sec):
        # 调用自定义 API
        ...
        return response_text

🚀 使用方法

1. GUI 界面使用

1. 启动 GUI：

   python -m exp_multimodal.exp_multimodal_gui
   

2. 在"配置与运行"标签页选择 Provider：

   • Ollama: 配置 OLLAMA_URL 和 MODEL
   • Kimi: 配置 API_KEY、BASE_URL、MODEL

3. 点击"保存当前配置"自动保存到 vlm_config.json，下次启动自动加载

2. 代码调用

from exp_multimodal.vlm_providers import OllamaProvider, KimiProvider
from exp_multimodal.vlm_classifier import classify_image

# 方式1: 使用 Ollama
provider = OllamaProvider(
    ollama_url="http://192.168.1.250:11434",
    model="qwen2.5vl:32b"
)

# 方式2: 使用 Kimi
provider = KimiProvider(
    api_key="sk-xxx",
    base_url="https://api.moonshot.cn/v1",
    model="moonshot-v1-32k-vision-preview"
)

# 进行分类
result = classify_image(
    image_path="test.jpg",
    labels=["宫保鸡丁", "麻婆豆腐", "红烧肉"],
    provider=provider,
    fewshot_hints=None,
    ingredient_only=False
)

print(result)  # {'label': '宫保鸡丁', 'confidence': 0.95}

🔧 配置说明

Ollama Provider

OllamaProvider(
    ollama_url="http://192.168.1.250:11434",  # Ollama 服务地址
    model="qwen2.5vl:32b"                      # 模型名称
)

Kimi Provider

KimiProvider(
    api_key="sk-JFxKmZnkkd1krxK4WsivcjdaAX36j0lu8tBdq3kL9OwHkdin",  # 必填
    base_url="https://api.moonshot.cn/v1",                          # 可选
    model="moonshot-v1-32k-vision-preview"                          # 可选
)

获取 Kimi API Key:

1. 访问 Moonshot AI 开放平台
2. 注册/登录账号
3. 在"API 密钥"页面创建新密钥

📦 依赖安装

# 基础依赖（Ollama）
pip install -r requirements.txt

# Kimi Provider 额外依赖
pip install openai>=1.0.0

🎯 扩展新 Provider

假设要添加 OpenAI GPT-4V：

1. 创建 vlm_providers/openai_provider.py:

from .base import VLMProvider
from openai import OpenAI

class OpenAIProvider(VLMProvider):
    def __init__(self, api_key, model="gpt-4-vision-preview"):
        self.client = OpenAI(api_key=api_key)
        self.model = model
    
    def chat_vision(self, prompt, image_paths, temperature, timeout_sec):
        # 实现调用逻辑
        ...
        return response.choices[0].message.content

2. 在 vlm_providers/__init__.py 中导出：

from .openai_provider import OpenAIProvider
__all__ = ["VLMProvider", "OllamaProvider", "KimiProvider", "OpenAIProvider"]

3. 在 GUI 中添加新选项（exp_multimodal_gui.py）

📊 性能对比

Provider	优点	缺点	推荐场景
Ollama	本地部署，数据安全，无API费用	需要GPU资源，推理速度受硬件限制	对数据隐私要求高，有本地GPU
Kimi	云端推理快，无需本地资源，遵循指令能力强	需要付费，依赖网络	快速验证，大规模识别

⚠️ 注意事项

1. Kimi API Key 保密: 不要将 API Key 提交到版本控制
2. 配置文件: vlm_config.json 已加入 .gitignore（建议）
3. 超时设置: 菜品数量超过 1 万时，建议增大 timeout_sec
4. Prompt 长度: Kimi 支持 32k token，Ollama 根据模型而定

🐛 故障排查

Ollama 连接失败

[Ollama][Error] Connection refused

• 检查 OLLAMA_URL 是否正确
• 确认 Ollama 服务是否启动
• 检查防火墙设置

Kimi API 错误

[Kimi][Error] 401 Unauthorized

• 检查 API Key 是否正确
• 确认账户余额是否充足
• 查看 Kimi API 文档

依赖缺失

ImportError: No module named 'openai'

• 安装缺失依赖：pip install openai>=1.0.0

📝 更新日志

• 2025-11-10: 初始版本，支持 Ollama 和 Kimi Provider
• 未来计划：支持 OpenAI、Claude、Gemini 等更多厂商

📞 支持

如有问题，请查看：

• Ollama 文档: https://ollama.ai/docs
• Kimi API 文档: https://platform.moonshot.cn/docs
• 项目 Issue: (您的仓库链接)