# 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` 方法：

```python
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：
   ```bash
   python -m exp_multimodal.exp_multimodal_gui
   ```

2. 在"配置与运行"标签页选择 Provider：
   - **Ollama**: 配置 `OLLAMA_URL` 和 `MODEL`
   - **Kimi**: 配置 `API_KEY`、`BASE_URL`、`MODEL`

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

### 2. 代码调用

```python
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

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

### Kimi Provider

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

**获取 Kimi API Key**:
1. 访问 [Moonshot AI 开放平台](https://platform.moonshot.cn/)
2. 注册/登录账号
3. 在"API 密钥"页面创建新密钥

## 📦 依赖安装

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

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

## 🎯 扩展新 Provider

假设要添加 OpenAI GPT-4V：

1. 创建 `vlm_providers/openai_provider.py`:

```python
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` 中导出：

```python
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 文档](https://platform.moonshot.cn/docs)

### 依赖缺失
```
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: (您的仓库链接)