上游和模型配置

MJ-Studio 通过灵活的上游和模型配置系统，支持多种 AI 服务的统一管理和调用。用户可以自由配置多个 API 上游，并为每个上游配置多个 AI 模型，实现一站式多模型 AI 创作。

功能概述

上游和模型配置是 MJ-Studio 的核心基础设施，通过两层架构实现灵活的多模型管理：

上游配置（Upstream）：管理 API 服务端点的连接信息（URL、密钥、平台类型等）
模型配置（Aimodel）：定义具体的 AI 模型及其调用参数（模型类型、API 格式、模型名称、能力等）

一个上游可以配置多个模型，支持图片生成、视频生成、对话和 TTS 四大类别的 AI 能力。

核心能力

多上游管理：支持配置多个 API 服务商（官方 API、第三方中转等）
多模型支持：每个上游可配置多个 AI 模型（绘图、对话、视频、TTS）
统一调用：通过模型选择器统一调用不同上游的不同模型
余额查询：支持主流平台的余额查询（OpenAI、Cloudflare AI 等）
多 Key 配置：单个上游支持配置多个 API Key 并指定使用
自定义显示名称：为模型设置自定义名称，简化长模型名或区分同类型模型
从上游导入模型：调用上游 API 获取模型列表，自动推断分类和能力
模型能力标记：标记模型的视觉、推理、工具调用、联网能力

数据结构

上游配置（Upstream）

上游配置存储 API 服务的连接信息和元数据。

字段	类型	说明
`id`	number	自增主键
`userId`	number	所属用户 ID
`name`	string	上游名称（用户自定义，如"我的 MJ"、"公司 API"）
`baseUrl`	string	API 请求前缀（如 `https://api.openai.com`）
`apiKey`	string	主 API Key
`apiKeys`	ApiKeyConfig[]	多 Key 配置（JSON 数组，可选）
`remark`	string	备注说明（可选）
`sortOrder`	number	排序顺序（0 表示置顶，默认 999）
`upstreamPlatform`	UpstreamPlatform	上游平台类型（用于余额查询，如 `openai`、`cloudflare-ai`）
`userApiKey`	string	用户在该平台的 Key（用于余额查询等）
`upstreamInfo`	UpstreamInfo	上游信息缓存（JSON 对象，存储余额、用户信息等）
`createdAt`	Date	创建时间

ApiKeyConfig 结构：

typescript

{
  keyName: string      // Key 名称（如 "生图专用"、"对话专用"）
  apiKey: string       // API Key 值
}

UpstreamInfo 结构：

typescript

{
  balance?: number     // 余额（美元）
  updatedAt?: string   // 余额更新时间
  // ... 其他平台特定信息
}

模型配置（Aimodel）

模型配置定义具体的 AI 模型及其调用参数，隶属于某个上游配置。

字段	类型	说明
`id`	number	自增主键
`upstreamId`	number	关联的上游配置 ID
`category`	ModelCategory	模型分类（`image` / `video` / `chat` / `tts`）
`modelType`	ModelType	模型类型（如 `midjourney`、`dalle`、`gpt` 等）
`apiFormat`	ApiFormat	API 请求格式（如 `mj-proxy`、`dalle`、`openai-chat`）
`modelName`	string	发送给上游的模型标识符（如 `gpt-4o`、`dall-e-3`）
`name`	string	显示名称（用户可自定义，用于 UI 显示）
`estimatedTime`	number	预计生成时间（秒，默认 60）
`keyName`	string	使用的 Key 名称（默认 `default` 表示使用主 Key）
`capabilities`	string[]	模型能力列表（`vision`/`reasoning`/`function_calling`/`web_search`）
`createdAt`	Date	创建时间
`deletedAt`	Date	软删除时间（null 表示未删除）

模型能力（Capabilities）

能力	说明	图标
`vision`	视觉能力，支持图片输入	👁
`reasoning`	推理能力，支持深度思考	🧠
`function_calling`	工具调用能力	🔧
`web_search`	联网能力，可访问实时信息	🌐

模型分类（ModelCategory）

分类	说明	支持的模型类型
`image`	图片生成模型	Midjourney、DALL-E、Flux、Gemini、豆包、GPT-4o 图像、抠抠图等
`video`	视频生成模型	即梦视频、Veo、Sora、Grok 视频
`chat`	对话模型	GPT、Claude、Gemini、DeepSeek、通义千问、Kimi 等
`tts`	语音合成模型	TTS、Suno、Audio 等

API 格式（ApiFormat）

API 格式决定了请求时使用的接口协议。

格式	说明	支持的模型
`mj-proxy`	Midjourney Proxy API	Midjourney
`gemini`	Google Generative Language API	Gemini 绘图
`dalle`	OpenAI Images API（兼容格式）	DALL-E、Flux、豆包绘图、Z-Image
`openai-chat`	OpenAI Chat Completions API	所有对话模型、部分绘图模型（GPT-4o 图像、Gemini 等）
`claude`	Anthropic Messages API	所有对话模型（通过适配层）
`koukoutu`	抠抠图 API	抠抠图
`video-unified`	统一视频生成 API	即梦视频、Veo、Sora、Grok 视频

配置页面

配置页面分为两个独立的管理入口：上游配置（/settings/upstreams）和模型配置（/settings/models）。

上游配置

上游配置页面（/settings/upstreams）管理 API 服务端点。

功能：

显示所有上游配置卡片（名称、URL、Key 状态、余额）
支持拖拽排序（调整在模型选择器中的显示顺序）
查询余额（支持平台：OpenAI、Cloudflare AI）
编辑/删除上游配置

卡片信息：

上游名称（可点击进入详情编辑）
Base URL（脱敏显示，如 https://api.open***.com）
API Key 状态（显示主 Key 和多 Key 数量）
余额（支持的平台显示美元余额，更新时间）
备注信息

新建上游

点击"新建上游"按钮，填写以下信息：

字段	必填	说明	示例
上游名称	✓	自定义名称，用于区分不同服务	"我的 OpenAI"、"公司中转 API"
Base URL	✓	API 请求地址前缀	`https://api.openai.com`
主 API Key	✓	默认使用的 API 密钥	`sk-...`
上游平台	-	用于余额查询（可选）	OpenAI、Cloudflare AI、None
用户 API Key	-	平台账号的 Key（用于查询余额）	`sk-...`
备注	-	说明信息	"用于生产环境"

多 Key 配置（可选）：

点击"添加 Key"可配置多个 API Key
每个 Key 需设置名称（如"生图专用"、"对话专用"）
配置模型时可指定使用哪个 Key

模型配置

模型配置页面（/settings/models）统一管理所有模型，采用列表视图。

列表功能：

显示所有模型（支持 Grid/Table 切换）
按分类筛选（对话/图片/视频/TTS）
关键词搜索
列表按分类分组显示

列表字段：

字段	说明
分类	对话/图片/视频/TTS
显示名称	默认为模型名称，可自定义
模型能力	视觉/联网/推理/工具（图标展示）

添加模型

有两种方式添加模型：

手动添加

点击"添加模型"按钮，打开模型编辑模态框：

字段	必填	说明
显示名称	✓	在模型选择器中显示的名称
模型名称	✓	发送给 API 的模型标识符
分类	✓	对话/图片/视频/TTS
API 格式	✓	请求接口格式
模型类型	✓	AI 模型类型
使用的 Key	✓	指定使用哪个 API Key
模型能力	-	视觉/推理/工具/联网（可多选）
预计时间	-	生成预计耗时（秒）

从上游导入

点击"从上游导入"按钮，系统会调用上游 /v1/models 接口获取模型列表：

选择目标上游配置
展示可选模型列表（支持搜索筛选，按分组显示）
点击模型旁的"+"添加到本地配置
添加时自动推断分类、能力和 API 格式

自动推断规则：

系统根据模型 ID 自动推断以下信息：

推断项	规则示例
分类	`dall-e`→图片, `kling`→视频, `tts`→TTS, 其他→对话
视觉能力	`gpt-4o`, `claude-3`, `qwen-vl` 等
推理能力	`o1`, `deepseek-r1`, `qwq` 等
工具调用	`gpt-4`, `claude`, `qwen` 等
API 格式	`midjourney`→mj-proxy, `gemini`→gemini, 其他→openai-chat

编辑模型

点击列表项的"编辑"按钮打开模型编辑模态框，可修改所有字段。

显示名称的作用

引入原因：

区分同类型模型：
- 同一上游的同一模型类型可能有多个模型（如两个 "Gemini 绘图"）
- 原有显示逻辑无法区分（都显示为"Gemini 绘图"）
- 通过自定义名称区分（如"Gemini Nano"、"Gemini Pro"）
简化长模型名：
- 对话模型名称通常很长（如 gpt-4o-search-preview-2025-03-11）
- 显示名称可设为简短名称（如 gpt-4o）
- 实际调用仍使用完整的模型名称

使用位置：

所有模型选择器（创作工作台、对话页面、设置页面）
任务卡片（显示使用的模型名称）
助手信息（对话右侧栏显示模型名称）

修改规则：

绘图/视频模型：选择模型类型时自动填充为 MODEL_TYPE_LABELS[modelType]（中文名称）
对话模型：输入模型名称时自动填充为 modelName（模型标识符）
所有情况下，用户都可以手动修改显示名称
每次修改模型类型/模型名称时，显示名称会被覆盖（不保留用户编辑）

模型选择器

模型选择器是 MJ-Studio 中统一的模型选择组件，在创作工作台和对话页面中使用。

组件位置

创作工作台：/studio - 绘图、视频表单顶部
对话页面：/chat - 消息输入框中的模型切换按钮
工作流页面：/workflow/[id] - 绘图节点中的模型选择
设置页面：/settings/general - 绘图相关设置（AI 优化模型、嵌入式绘画模型、工作台默认模型）

选择器样式

下拉列表样式（默认）：

按钮显示当前选择（上游名称 / 模型名称）
点击展开下拉菜单
菜单按上游分组，每个上游显示其所有模型

列表平铺样式（list-layout prop）：

不使用下拉菜单，直接显示为平铺列表
适用于表单场景（如设置页面）

选择逻辑

按分类筛选（category prop）：

image：仅显示绘图模型
video：仅显示视频模型
chat：仅显示对话模型

自动选择（默认开启）：

首次加载时自动选择第一个可用模型
可通过 no-auto-select prop 禁用

对齐方式（align-right prop）：

默认左对齐
设置 align-right 后下拉菜单右对齐（适用于页面右侧场景）

显示格式

按钮文本：

上游名称 / 模型显示名称

下拉菜单结构：

📦 上游名称 1
  └─ 模型显示名称 1
  └─ 模型显示名称 2
📦 上游名称 2
  └─ 模型显示名称 3

示例：

按钮：我的 OpenAI / gpt-4o

菜单：

📦 我的 OpenAI
  └─ gpt-4o
  └─ gpt-4o-mini
📦 公司 API
  └─ Claude Sonnet
  └─ DeepSeek

双向绑定

模型选择器通过 v-model 实现双向绑定：

vue

<ModelSelector
  :upstreams="upstreams"
  category="image"
  v-model:upstream-id="selectedUpstreamId"
  v-model:aimodel-id="selectedAimodelId"
/>

upstream-id：选中的上游 ID
aimodel-id：选中的模型 ID

使用场景

场景 1：配置多个官方 API

需求：使用 OpenAI 官方 API、Google Gemini API、Anthropic API

配置步骤：

新建上游"OpenAI 官方"
- Base URL: https://api.openai.com
- 配置 GPT-4o（对话）、DALL-E 3（绘图）
新建上游"Google AI"
- Base URL: https://generativelanguage.googleapis.com
- 配置 Gemini 2.5 Flash（对话）、Gemini 绘图（绘图）
新建上游"Anthropic"
- Base URL: https://api.anthropic.com
- 配置 Claude Sonnet 4（对话）

场景 2：配置第三方中转服务

需求：使用一个中转 API 访问多个模型（OpenAI、Claude、Gemini 等）

配置步骤：

新建上游"万能中转"
- Base URL: https://api.your-proxy.com
- 配置多个对话模型（GPT-4o、Claude Sonnet、Gemini Flash、DeepSeek）
- 配置多个绘图模型（DALL-E、Flux、Gemini 绘图）
为不同用途配置多个 Key（可选）
- 添加 Key"生图专用"
- 添加 Key"对话专用"
- 绘图模型指定使用"生图专用"，对话模型使用"对话专用"

场景 3：区分同类型模型

需求：同一上游有两个 Gemini 绘图模型（不同版本或配置）

配置步骤：

编辑上游"我的中转"
添加第一个 Gemini 绘图模型
- 模型类型：Gemini 绘图
- 模型名称：gemini-2.5-flash-image
- 显示名称：Gemini Flash
添加第二个 Gemini 绘图模型
- 模型类型：Gemini 绘图
- 模型名称：gemini-2.5-pro-image
- 显示名称：Gemini Pro

效果：

模型选择器显示"我的中转 / Gemini Flash"和"我的中转 / Gemini Pro"
清晰区分两个模型

场景 4：简化长模型名

需求：对话模型名称太长，希望简化显示

配置步骤：

配置对话模型
- 模型名称：gpt-4o-search-preview-2025-03-11（实际调用名称）
- 显示名称：gpt-4o（简化显示）
配置另一个模型
- 模型名称：gpt-4o-mini-search-preview-2025-03-11
- 显示名称：gpt-4o-mini

效果：

模型选择器显示"gpt-4o"和"gpt-4o-mini"（简洁清晰）
实际 API 调用使用完整模型名称

注意事项

API 格式兼容性：
- 不同模型类型支持的 API 格式不同
- 配置时系统会自动筛选可用格式
- 错误的格式会导致调用失败
模型名称规范：
- 模型名称必须与上游 API 接受的标识符完全一致
- 对话模型通常区分大小写（如 gpt-4o 不能写成 GPT-4O）
- 建议参考上游服务商的官方文档
显示名称规则：
- 显示名称仅用于 UI 展示，不影响 API 调用
- 修改模型类型/模型名称时会覆盖显示名称
- 建议使用简短、易识别的名称
多 Key 配置：
- 多 Key 配置主要用于区分不同用途或避免额度限制
- 每个模型可以指定使用哪个 Key
- 删除 Key 前确保没有模型正在使用
上游平台类型：
- 仅用于余额查询功能
- 如果不需要查询余额，可以不配置
- 目前支持：OpenAI、Cloudflare AI
预计时间：
- 预计时间用于进度条显示和用户体验优化
- 系统会根据实际耗时自动更新（仅绘图模型）
- 建议根据实际情况调整初始值
软删除机制：
- 删除模型配置不会立即删除数据库记录
- 系统使用 deletedAt 字段实现软删除
- 同步上游配置时，已删除的模型会被恢复（如果重新添加）
数据同步：
- 编辑上游配置时，系统会智能同步模型列表
- 已存在的模型会更新字段
- 新添加的模型会创建记录
- 删除的模型会标记为软删除

最佳实践

命名规范：
- 上游名称：使用业务场景命名（如"生产环境"、"测试 API"）
- 显示名称：简短清晰（如"GPT-4o"、"Claude Sonnet"）
Key 管理：
- 主 Key 用于通用场景
- 多 Key 配置用于区分用途（生图、对话、测试等）
- 定期轮换 API Key 提高安全性
模型分组：
- 将相同服务商的模型放在同一上游
- 或按业务场景分组（如"高质量生图"、"快速对话"）
余额监控：
- 配置上游平台类型和用户 Key
- 定期查询余额，避免欠费中断服务
- 设置多个上游作为备用
性能优化：
- 置顶常用上游（排序顺序设为 0）
- 删除不再使用的模型配置
- 合理设置预计时间（影响进度条显示）

上游和模型配置 ​

功能概述 ​

核心能力 ​

数据结构 ​

上游配置（Upstream） ​

模型配置（Aimodel） ​

模型能力（Capabilities） ​

模型分类（ModelCategory） ​

API 格式（ApiFormat） ​

配置页面 ​

上游配置 ​

新建上游 ​

模型配置 ​

添加模型 ​

手动添加 ​

从上游导入 ​

编辑模型 ​

显示名称的作用 ​

模型选择器 ​

组件位置 ​

选择器样式 ​

选择逻辑 ​

显示格式 ​

双向绑定 ​

使用场景 ​

场景 1：配置多个官方 API ​

场景 2：配置第三方中转服务 ​

场景 3：区分同类型模型 ​

场景 4：简化长模型名 ​

注意事项 ​

最佳实践 ​

上游和模型配置

功能概述

核心能力

数据结构

上游配置（Upstream）

模型配置（Aimodel）

模型能力（Capabilities）

模型分类（ModelCategory）

API 格式（ApiFormat）

配置页面

上游配置

新建上游

模型配置

添加模型

手动添加

从上游导入

编辑模型

显示名称的作用

模型选择器

组件位置

选择器样式

选择逻辑

显示格式

双向绑定

使用场景

场景 1：配置多个官方 API

场景 2：配置第三方中转服务

场景 3：区分同类型模型

场景 4：简化长模型名

注意事项

最佳实践