# AI 模型和存储配置指南

## 功能概述

本系统实现了完整的 AI 模型配置和存储管理功能，无需修改 `.env` 文件即可在系统设置中动态配置。

## 核心功能

### 1. AI 提供商配置

支持配置多个 AI 服务提供商，包括：
- **阿里云通义千问** (Alibaba)
- **OpenAI 兼容接口** (OpenAI)
- **自定义提供商** (Custom)

**访问路径**: `/admin/settings` → AI 模型 → AI 提供商

**配置项**:
- 提供商名称：自定义名称，如"阿里云通义千问"
- 提供商类型：选择类型
- API 地址：提供商的 API 基础 URL（例如：https://dashscope.aliyuncs.com/compatible-mode/v1）
- API Key：访问令牌（不回显已保存的密钥）
- 启用状态：勾选启用此提供商

**API 端点**: `/api/admin/ai-providers`
- `GET` - 获取所有提供商列表
- `POST` - 创建新提供商
- `PUT` - 更新提供商配置
- `DELETE?id={id}` - 删除提供商

### 2. AI 模型配置

为每个提供商配置具体的模型，支持设置视觉能力和图片生成能力。

**访问路径**: `/admin/settings` → AI 模型 → AI 模型

**配置项**:
- 所属提供商：选择已配置的提供商
- 模型 ID：提供商中的模型标识（例如：qwen-turbo, qwen-vl-plus）
- 显示名称：用户界面上显示的名称
- 描述：模型的简要说明
- 排序顺序：确定前端显示顺序
- 支持图片输入：模型是否支持视觉（图片识别）
- 支持图片生成：模型是否支持图片生成
- 启用：模型是否可用
- 设为默认：标记为默认使用的模型

**API 端点**: `/api/admin/ai-models`
- `GET` - 获取模型列表（可选 `providerId` 筛选）
- `POST` - 创建新模型
- `PUT` - 更新模型配置
- `DELETE?id={id}` - 删除模型

**用户端 API**: `/api/models`
- `GET` - 获取已启用的模型列表（用于前端选择）

### 3. S3 存储配置

配置 S3 兼容的对象存储服务，用于图片上传和多媒体处理。

**访问路径**: `/admin/settings` → 存储配置

**配置项**:
- 配置名称：自定义名称
- 存储类型：S3 兼容存储或本地存储
- 端点：S3 服务端点 URL
- 区域：地区代码
- 存储桶：目标存储桶名称
- Access Key ID：访问凭证
- Secret Access Key：秘密凭证（不回显）
- 公开访问 URL 前缀：文件的公开访问地址前缀
- 启用：是否启用此配置
- 设为默认：优先使用的存储配置

**API 端点**: `/api/admin/storage`
- `GET` - 获取存储配置列表
- `POST` - 创建新配置
- `PUT` - 更新配置
- `DELETE?id={id}` - 删除配置

### 4. 前端模型选择

用户在聊天界面选择模型时，系统会：
1. 首先加载数据库中配置的动态模型
2. 如果没有配置，则显示预定义的静态模型
3. 优先显示标记为"默认"的模型

**调用流程**:
- 前端组件：`components/model-selector.tsx`
- 调用 API：`/api/models` 获取可用模型列表
- 支持视觉模型标签显示
- 支持默认模型标签显示

## 数据库结构

### AiProvider 表
```sql
CREATE TABLE "AiProvider" (
  id uuid PRIMARY KEY,
  name varchar(128) NOT NULL,           -- 提供商名称
  type varchar NOT NULL,                -- 类型: alibaba, openai, custom
  baseUrl text NOT NULL,                -- API 基础 URL
  apiKey text NOT NULL,                 -- API Key
  isEnabled boolean DEFAULT true,       -- 是否启用
  createdAt timestamp DEFAULT now(),
  updatedAt timestamp DEFAULT now(),
  updatedBy uuid REFERENCES "User"(id)
);
```

### AiModel 表
```sql
CREATE TABLE "AiModel" (
  id uuid PRIMARY KEY,
  providerId uuid NOT NULL REFERENCES "AiProvider"(id) ON DELETE CASCADE,
  modelId varchar(128) NOT NULL,        -- 模型 ID
  displayName varchar(128) NOT NULL,    -- 显示名称
  description text,                     -- 描述
  supportsVision boolean DEFAULT false, -- 支持图片输入
  supportsImageGen boolean DEFAULT false, -- 支持图片生成
  isEnabled boolean DEFAULT true,
  isDefault boolean DEFAULT false,
  sortOrder json DEFAULT 0,
  createdAt timestamp DEFAULT now(),
  updatedAt timestamp DEFAULT now()
);
```

### StorageConfig 表
```sql
CREATE TABLE "StorageConfig" (
  id uuid PRIMARY KEY,
  name varchar(128) NOT NULL,           -- 配置名称
  type varchar DEFAULT 's3',            -- 类型: s3, local
  endpoint text,                        -- S3 端点
  region varchar(64),                   -- 区域
  bucket varchar(128),                  -- 存储桶
  accessKeyId text,                     -- Access Key
  secretAccessKey text,                 -- Secret Key
  publicUrl text,                       -- 公开访问 URL 前缀
  isDefault boolean DEFAULT false,
  isEnabled boolean DEFAULT true,
  createdAt timestamp DEFAULT now(),
  updatedAt timestamp DEFAULT now(),
  updatedBy uuid REFERENCES "User"(id)
);
```

## 配置优先级

### AI 模型使用顺序
1. **数据库配置优先** - 从 AiModel 表动态加载
2. **环境变量回退** - 使用 DASHSCOPE_API_KEY 等
3. **预定义模型** - 最后使用预定义的模型列表

### 存储服务优先级
1. **数据库配置** - 优先使用标记为默认的存储配置
2. **环境变量** - 使用 S3_* 系列环境变量
3. **Vercel Blob** - 最后回退到 Vercel Blob

## 实现示例

### 配置阿里云通义千问

1. **创建提供商**
   ```
   名称: 阿里云通义千问
   类型: Alibaba
   API 地址: https://dashscope.aliyuncs.com/compatible-mode/v1
   API Key: sk-xxxxxxxxxxxxxxxxxxxxxxxx
   ```

2. **创建模型**
   ```
   提供商: 阿里云通义千问
   模型 ID: qwen-turbo
   显示名称: 通义千问 Turbo
   支持图片输入: ☑
   设为默认: ☑
   ```

### 配置 S3 存储

```
配置名称: 阿里云 OSS
类型: S3 兼容存储
端点: https://oss-cn-hangzhou.aliyuncs.com
区域: cn-hangzhou
存储桶: my-chatbot-bucket
Access Key ID: LTAI5t...
Secret Access Key: xxxxxxxxxxxxxxxx
公开访问 URL 前缀: https://my-chatbot-bucket.oss-cn-hangzhou.aliyuncs.com
设为默认: ☑
```

## 关键代码位置

### 后端核心文件
- `lib/db/schema.ts` - 数据库表定义
- `lib/db/queries.ts` - 数据库查询函数
- `lib/ai/dynamic-provider.ts` - 动态模型加载
- `app/(admin)/api/ai-providers/route.ts` - 提供商 API
- `app/(admin)/api/ai-models/route.ts` - 模型 API
- `app/(admin)/api/storage/route.ts` - 存储 API
- `app/(chat)/api/models/route.ts` - 前端模型列表 API

### 前端核心文件
- `components/model-selector.tsx` - 模型选择组件
- `app/(admin)/settings/admin-settings-client.tsx` - 管理设置页面
- `app/(chat)/api/files/upload/route.ts` - 文件上传处理

## 环境变量（可选）

虽然不再需要配置这些，但如果设置了环境变量，系统会作为回退使用：

```env
# AI 配置回退
DASHSCOPE_API_KEY=your_key
DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

# S3 存储回退
S3_ENDPOINT=https://s3.amazonaws.com
S3_REGION=us-east-1
S3_BUCKET=my-bucket
S3_ACCESS_KEY_ID=your_access_key
S3_SECRET_ACCESS_KEY=your_secret_key
S3_PUBLIC_URL=https://my-bucket.s3.amazonaws.com
```

## 故障排除

### 模型不显示
- 检查 AiProvider 是否启用 (isEnabled = true)
- 检查 AiModel 是否启用 (isEnabled = true)
- 检查 API 密钥和地址是否正确
- 查看浏览器开发者工具中 `/api/models` 的响应

### 文件上传失败
- 确认 StorageConfig 已设置为默认 (isDefault = true)
- 验证 S3 凭证和端点
- 检查存储桶权限设置

### 默认模型不生效
- 确保只有一个模型设置为默认 (isDefault = true)
- 重启应用使缓存更新
- 检查前端是否正确读取 defaultModelId

## 安全考虑

- **API Key 保护** - API Key 在数据库中存储，不在响应中回显
- **权限控制** - 所有管理 API 需要 admin 权限
- **数据加密** - 建议在生产环境中加密存储的敏感信息
- **访问控制** - 限制对 `/admin/settings` 的访问

## 迁移说明

如果从旧版本升级：
1. 运行数据库迁移：`npm run db:migrate`
2. 访问管理设置重新配置 AI 模型和存储
3. 删除 `.env.local` 中的旧配置（可选）
4. 重启应用