# AI 模块 - 服务注册表模式

> **SQL文件**: `sql/ai.sql`  
> **旧版(废弃)**: `sql/ai-complete-deprecated.sql`

## 🎯 设计理念

**核心原则：配置驱动 + 抽象统一接口**

> ❌ 旧版：厂商表 → 模型表 → 配置表（三层实体 + 多张表 + 多步操作）  
> ✅ 简化版：**一个服务表 + 一个统一接口 + 一个服务ID**

**新增 AI = 插入一行配置 = 5分钟搞定！**

---

## 📦 架构对比

### 旧版（复杂）
```
ai_provider (厂商表)
    ↓
ai_model (模型表，关联厂商)
    ↓
ai_model_config (配置表，关联模型)
    ↓
ai_conversation / ai_message (对话表)
```

### 简化版
```
ai_service (服务表，合并厂商+模型+配置)
    ↓
ai_conversation / ai_message (对话表)
```

---

## 🗂️ 数据库结构

### ai_service 服务表（核心）

| 字段 | 类型 | 说明 |
|------|------|------|
| service_id | BIGINT | 服务ID |
| service_name | VARCHAR(100) | 服务名称（如：GPT-4o） |
| service_code | VARCHAR(50) | 服务代码（唯一，如：openai-gpt4o） |
| provider | VARCHAR(50) | 厂商标识（openai/zhipu/alibaba等） |
| provider_name | VARCHAR(50) | 厂商名称 |
| model_code | VARCHAR(100) | 模型代码（gpt-4o/glm-4等） |
| api_url | VARCHAR(500) | API地址 |
| api_key | VARCHAR(500) | API密钥 |
| temperature | DECIMAL(3,2) | 温度参数 |
| max_tokens | INT | 最大Token数 |
| system_prompt | TEXT | 系统提示词 |
| supports_stream | CHAR(1) | 支持流式：0=否 1=是 |
| supports_vision | CHAR(1) | 支持视觉：0=否 1=是 |
| enabled | CHAR(1) | 是否启用：0=否 1=是 |
| is_default | CHAR(1) | 是否默认：0=否 1=是 |

---

## 🚀 快速添加新 AI

### 方式一：SQL 插入

```sql
INSERT INTO ai_service (
  service_name, service_code, provider, provider_name, model_code,
  api_url, api_key, temperature, max_tokens, enabled, create_time
) VALUES (
  'Claude 3.5 Sonnet',           -- 服务名称
  'claude-sonnet',               -- 服务代码（唯一）
  'anthropic',                   -- 厂商标识
  'Anthropic',                   -- 厂商名称
  'claude-3-5-sonnet-20241022',  -- 模型代码
  'https://api.anthropic.com/v1/messages',  -- API地址
  'sk-xxx',                      -- API密钥
  0.7,                           -- 温度
  4096,                          -- 最大Token
  '1',                           -- 启用
  NOW()
);
```

### 方式二：管理界面

1. 进入 **AI助手 → 服务配置**
2. 点击 **新增**
3. 填写：服务名称、服务代码、选择厂商、模型代码、API地址、API密钥
4. 保存即可

---

## 📁 代码结构

### 后端
```
yushu-system/
├── domain/AiService.java          # 服务实体
├── mapper/AiServiceMapper.java    # Mapper接口
├── service/IAiServiceService.java # Service接口
└── service/impl/AiServiceServiceImpl.java

yushu-admin/controller/
└── AiServiceController.java       # 服务管理API
```

### 前端
```
src/api/system/ai/
└── service.js                     # 服务管理API

src/views/system/ai/
├── service/index.vue              # 服务配置页面
└── chat/index.vue                 # 对话页面（已更新）
```

---

## 🔧 API 接口

### 服务管理
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /system/ai/service/list | 查询服务列表 |
| GET | /system/ai/service/enabled | 查询已启用服务（下拉框） |
| GET | /system/ai/service/{id} | 获取服务详情 |
| POST | /system/ai/service | 新增服务 |
| PUT | /system/ai/service | 修改服务 |
| DELETE | /system/ai/service/{ids} | 删除服务 |
| PUT | /system/ai/service/default/{id} | 设为默认服务 |

### 对话（更新）
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /system/ai/chat/send | 发送消息（使用 serviceId） |
| POST | /system/ai/chat/conversation | 创建会话（使用 serviceId） |

---

## ✅ 预置服务

SQL 已包含以下 AI 服务配置（只需填入 API Key）：

| 服务名称 | 厂商 | 模型代码 |
|---------|------|---------|
| GPT-4o | OpenAI | gpt-4o |
| GPT-4o Mini | OpenAI | gpt-4o-mini |
| GPT-3.5 Turbo | OpenAI | gpt-3.5-turbo |
| GLM-4 | 智谱AI | glm-4 |
| GLM-4-Flash | 智谱AI | glm-4-flash |
| 通义千问-Max | 阿里云 | qwen-max |
| Kimi 128K | 月之暗面 | moonshot-v1-128k |
| DeepSeek Chat | DeepSeek | deepseek-chat |
| Claude 3.5 Sonnet | Anthropic | claude-3-5-sonnet |
| Ollama Llama3 | 本地部署 | llama3 |

---

## 🔄 迁移指南

如果从旧版迁移：

1. 执行 `sql/ai-service-simplified.sql`
2. 将旧的 `ai_model_config` 数据导入 `ai_service`
3. 更新前端代码使用新 API
4. （可选）删除旧表

---

## 🎉 好处总结

| 优势 | 说明 |
|------|------|
| **极简操作** | 新增AI只需一条SQL或填一个表单 |
| **统一抽象** | 所有AI共用相同接口，无需关心厂商差异 |
| **配置驱动** | 不改代码即可接入新模型 |
| **易于维护** | 单表设计，无复杂关联 |
| **支持本地部署** | Ollama、vLLM 等本地模型同样支持 |

---

**YuShu Team** © 2024