# AI Router v2.0 — 多模型智能路由

一个智能的多模型协作程序：**图片 → 可切换的视觉模型看图 → DeepSeek 归纳总结 → 最终回答**。

纯文本问题直接交给 DeepSeek 处理。

## 🎯 为什么需要这个程序？

| 模型 | 优势 | 短板 |
|------|------|------|
| **DeepSeek** | 推理强、总结好、超便宜 | ❌ 不支持图片输入（纯文本模型） |
| **视觉模型** | 强大的视觉理解、看图说话 | 归纳总结不如 DeepSeek |

💡 **解决方案**：取长补短，视觉模型看图 → DeepSeek 总结 → 用户得到最佳回答。

**视觉模型可自由切换**：Kimi / OpenAI GPT-4o / 通义千问 VL / 智谱 GLM-4V / Google Gemini / 自定义端点。

## 🏗 架构

```
用户输入（文字 + 可选图片）
    │
    ▼
┌─────────────────┐
│   Input Router   │  检测输入类型
└─────┬───────────┘
      │
      ├── 有图片 ──→ [视觉模型] 看图 ──→ 文字描述
      │         (kimi/openai/qwen/glm/gemini/custom)
      │                                        │
      └── 无图片 ──────────────────────────────┤
                                               ▼
                                    ┌─────────────────┐
                                    │  DeepSeek Chat   │
                                    │  归纳总结 / 回答  │
                                    └────────┬────────┘
                                             │
                                             ▼
                                      最终回答 → 用户
```

## 🚀 快速开始

### 1. 安装依赖

```bash
cd ai-router
pip install -r requirements.txt

# 如果要用 Gemini 做视觉，额外安装：
# pip install google-genai
```

### 2. 配置 API Key

```bash
cp .env.example .env
# 编辑 .env，填入 API Key：
#   DEEPSEEK_API_KEY=sk-你的deepseek-key
#   VISION_API_KEY=sk-你的视觉模型-key
#   VISION_PROVIDER=kimi  （或 openai/qwen/glm/gemini/custom）
```

API Key 获取地址：
- DeepSeek: https://platform.deepseek.com
- Kimi: https://platform.moonshot.cn
- OpenAI: https://platform.openai.com
- 通义千问: https://dashscope.console.aliyun.com
- 智谱: https://open.bigmodel.cn
- Gemini: https://aistudio.google.com

### 3. 使用

#### 命令行

```bash
# 纯文本 → DeepSeek
python main.py "量子计算是什么？"

# 图片分析（默认 Kimi）
python main.py "这张图里有什么？" -i photo.jpg

# 切换到 OpenAI GPT-4o
python main.py "分析图表" -i chart.png --vision openai

# 切换到通义千问
python main.py "描述图片" -i img.jpg --vision qwen

# 查看所有供应商
python main.py --list-providers

# 交互模式（可动态切换）
python main.py
```

#### Web 界面

```bash
python server.py          # 启动后端
# 然后双击 web_ui.html    # 打开前端
```

#### Claude Code 集成（MCP）

AI Router 可以作为 Claude Code 的 MCP 工具使用，让 Claude 在处理图片问题时自动调用。

**配置方式：** 项目根目录已有 `.mcp.json`，Claude Code 重新打开后自动加载。

```bash
# 重启 Claude Code 后即可使用
# 在对话中直接说"帮我分析这张图片"即可触发
```

**可用的 MCP 工具：**

| 工具 | 说明 |
|------|------|
| `ai_router_chat` | 核心工具：发问 + 可选图片 → 管道处理 |
| `ai_router_list_providers` | 列出所有视觉供应商 |
| `ai_router_switch_provider` | 切换视觉供应商 |
| `ai_router_config_status` | 检查配置状态 |

**使用示例（在 Claude Code 对话中）：**

```
用户：帮我分析 C:/photos/screenshot.png 这张图片里有什么？

Claude 会自动：
1. 调用 ai_router_chat(question="这张图片里有什么？", image_paths=["C:/photos/screenshot.png"])
2. 图片 → Kimi 看图 → DeepSeek 总结 → 返回答案给用户
```

```
用户：切换到 OpenAI 做视觉理解

Claude 调用：
ai_router_switch_provider(provider_id="openai")
```

## 📁 文件说明

| 文件 | 说明 |
|------|------|
| `ai_router.py` | 核心引擎：视觉客户端、DeepSeek 客户端、路由器、Pipeline |
| `main.py` | CLI 命令行入口 |
| `server.py` | HTTP API 服务器（供 Web UI 调用） |
| `mcp_server.py` | MCP Server（供 Claude Code 集成） |
| `web_ui.html` | Web 界面（单文件，双击即用） |
| `.env.example` | API Key 配置模板 |
| `requirements.txt` | Python 依赖 |

## 🔧 API 端点

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/chat` | 对话接口，支持动态切换供应商 |
| GET | `/api/health` | 健康检查 |
| GET | `/api/config` | 获取配置状态 |
| GET | `/api/providers` | 列出所有视觉供应商 |

## 👁 视觉供应商

| ID | 名称 | 默认模型 | 获取 Key |
|----|------|----------|----------|
| `kimi` | Kimi (Moonshot) | kimi-k3 | platform.moonshot.cn |
| `openai` | OpenAI GPT-4o | gpt-4o | platform.openai.com |
| `qwen` | 通义千问 VL | qwen-vl-max | dashscope.console.aliyun.com |
| `glm` | 智谱 GLM-4V | glm-4v | open.bigmodel.cn |
| `gemini` | Google Gemini | gemini-2.5-flash | aistudio.google.com |
| `custom` | 自定义端点 | — | Ollama/vLLM/LiteLLM 等 |

## 📝 许可

MIT License