197 lines
5.1 KiB
Markdown
197 lines
5.1 KiB
Markdown
# 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: (您的仓库链接)
|