lunanting/lovart3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
lovart3/AI_MODEL_CONFIG_GUIDE.md
Your Name 53ddb7e585 Initial commit - clean repository
2025-12-17 20:15:18 +08:00

8.0 KiB
Raw Blame History

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 表

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 表

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 表

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 - 文件上传处理

环境变量（可选）

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

# 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. 重启应用