263 lines
8.0 KiB
Markdown
263 lines
8.0 KiB
Markdown
# 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. 重启应用
|
||
|