AI 模型

AI 模型是租户侧外部模型资源，用于保存 Soln 调用聊天、视觉、工具调用、图片生成或图片输入模型时需要的模型凭据和运行时配置。

打开 系统管理 > 资源管理，然后在资源菜单中选择 AI 模型。

页面结构

AI 模型页面包含三个主要区域：

区域	用途
顶部栏	搜索模型、新建模型分类、按全部、启用、停用状态筛选模型，并通过模型用量进入模型用量页面
分类列表	按提供方、用途或运行场景组织模型，并展示每个分类下的模型数量；列表底部提供模型计费入口
模型列表	展示当前分类下的模型，并提供编辑、启用、停用、删除和基于此配置创建操作

模型分类

模型分类用于按提供方、用途或运行场景整理模型。

字段	说明
模型 icon	分类图标；上传图片后，分类和模型列表更容易识别
模型分类名称	分类展示名称，例如 OpenAI、Gemini、图片模型、内部网关

分类操作：

操作	说明
新建模型分类	创建自定义分类
编辑	修改自定义分类的名称或图标
删除	删除自定义分类，并清空该分类下的模型
新增	在当前分类下新建模型

列表中可能会展示预置分类。预置分类可以选择并用于新建模型，但只有自定义分类可以编辑或删除。

新建 AI 模型

在选中的分类中点击新增，然后填写模型连接参数。

字段	是否必填	说明
模型类型	是	选择文本模型或图片生成模型；模型类型决定可选的协议范围，也决定运行时把该资源用于聊天还是图片生成
协议	是	选择 Soln 调用模型时使用的 API 协议；协议决定默认 Base URL、请求端点和自动写入的模型能力
Base URL	是	当前提供方使用的基础接口地址；切换协议时，如果当前地址为空或仍是已知默认地址，页面会自动填入匹配的默认地址；OpenAI 兼容网关应填写网关根地址，不要填写 `/chat/completions` 等完整路径
API Key	新建时必填	调用提供方的密钥；编辑已有模型时，如果不填写，会保留已保存的密钥
模型名	是	提供方模型标识，例如 `gpt-5.6`、`gpt-image-2`、`claude-opus-4-8`、`gemini-3.6-flash`，或内部网关要求的模型名；模型创建后不可修改，避免计费、用量统计和审计记录发生错配
模型显示名称	是	展示给管理员和运行时选择器的名称；建议体现提供方、账号和用途
配置 (JSON)	否	额外 JSON 对象，会合并到模型配置中；用于填写标准字段没有覆盖的提供方专属参数

协议

请选择与模型服务匹配的 API 协议。运行时会根据所选协议选择对应的 AI SDK provider。

协议	模型类型	默认 Base URL	典型用途
OpenAI Responses	文本模型	`https://api.openai.com/v1`	OpenAI Responses 兼容服务；Soln 向其 `/responses` 端点发送聊天与内置图片生成工具请求
OpenAI Chat Completions	文本模型	`https://api.openai.com/v1`	OpenAI Chat Completions 兼容服务；Soln 向其 `/chat/completions` 端点发送聊天请求
Anthropic Messages	文本模型	`https://api.anthropic.com/v1`	通过原生 `/messages` 端点调用 Claude 模型
Google Gemini GenerateContent	文本模型	`https://generativelanguage.googleapis.com/v1beta`	通过原生 GenerateContent API 调用 Gemini 模型
OpenAI Images	图片生成模型	`https://api.openai.com/v1`	OpenAI 图片接口；用于生成图片，并支持基于输入图片编辑图片
xAI Grok Images	图片生成模型	`https://api.x.ai/v1`	xAI Grok 图片接口；用于生成图片，并支持基于输入图片编辑图片
Google Imagen	图片生成模型	`https://generativelanguage.googleapis.com/v1beta`	Google Imagen 图片生成接口；只生成图片，不支持图片编辑
Google Gemini Images	图片生成模型	`https://generativelanguage.googleapis.com/v1beta`	Gemini 原生图片生成接口；用于生成图片，并支持基于输入图片编辑图片

切换协议时，如果当前 Base URL 为空或仍是已知默认地址，页面会自动替换成新协议的默认地址。OpenAI 兼容网关的实际地址以提供方部署为准。

模型能力

模型能力由 模型类型 和协议共同决定，保存时会自动写入模型资源的能力元数据，页面不需要单独选择。

能力	推导来源	说明
聊天	文本模型协议	资源用于 Luna 对话与文本生成
流式输出	文本模型协议	文本模型按流式方式返回增量内容
图片输入 / 识图	文本模型协议	对话消息可以包含图片；只有模型和网关接口都支持图片消息时才应使用
工具调用	文本模型协议	Luna 调用租户数据工具、表单工具、文件工具或其他运行时动作
图片生成	图片生成模型协议	资源用于生成图片
图片编辑	支持编辑的图片协议	OpenAI Images、xAI Grok Images、Google Gemini Images 支持基于输入图片编辑图片；Google Imagen 不支持

图片生成模型不会用于聊天，因此图片生成资源不会同时具备流式输出和工具调用能力。

识图能力需要与模型匹配
文本模型协议会写入图片输入能力标记。如果实际配置的是纯文本模型，用户发送图片提问时可能会被模型服务直接拒绝，无法得到识图结果；此时应改用支持视觉输入的模型。

图片生成与编辑

图片生成使用 图片生成模型 类型的资源，文本模型不会用于图片生成请求。只有支持图片编辑的协议才能在助手中修改已有图片。

协议	生成图片	编辑图片
OpenAI Images	支持	支持
xAI Grok Images	支持	支持
Google Gemini Images	支持	支持
Google Imagen	支持	不支持

在助手中选择 创建图片：只发送文本时生成新图片；同一条消息附带一张或多张 PNG、JPEG、WEBP 或非动画 GIF 图片时，该请求会按图片编辑处理。当前不提供蒙版上传。

配置 JSON

配置 (JSON) 必须是 JSON 对象。这里既可以填写通用生成参数，也可以填写表单没有提供的厂商专属请求参数。请先选择匹配的协议，再按照模型提供方或网关文档填写字段和值；Soln 不会根据模型名猜测参数。

保存时，配置 JSON 会和 protocol、baseUrl、model 等标准字段一起合并为模型配置，但不能覆盖表单和 Runtime 管理的字段。

保留字段：

字段	说明
`protocol`	来自协议字段，不要在配置 JSON 中填写
`baseUrl`	来自 Base URL 字段，不要在配置 JSON 中填写
`model`	来自模型名字段，不要在配置 JSON 中填写
`toolCalling`	由模型类型和协议推导，不要在配置 JSON 中填写
`toolDiscovery`	由 Assistant Runtime 控制，不要在配置 JSON 中填写
`contextWindowTokens`	不提供此配置，不要在配置 JSON 中填写

AI 模型资源不提供上下文窗口大小配置。租户 Runtime 自动维护会话检查点，保留用户原始要求和执行证据引用；近期消息完整保留，较早的执行详情可通过 Runtime 命令回读。检查点调度属于内部维护策略，不是可配置的模型容量限制。

通用生成参数

以下顶层参数会映射到 AI SDK 的模型调用参数：

参数	说明
`temperature`	采样温度，具体取值范围由提供方决定
`topP`	核采样参数
`maxTokens`	最大输出 token 数量
`presencePenalty`	对已经出现在生成文本中的主题增加惩罚
`frequencyPenalty`	按 token 重复频率增加惩罚

只填写当前提供方和模型真实支持的参数。流式输出、工具调用、图片输入、图片生成等能力由 模型类型 和协议推导，不要在配置 JSON 中配置。

示例：

{
  "temperature": 0.7,
  "topP": 0.9,
  "maxTokens": 4096
}

厂商专属参数

所选协议存在通用生成字段没有覆盖的参数时，使用以下配置：

字段	值类型	行为
`headers`	对象	增加提供方或网关请求头，字段值会转换为字符串
`requestBody`	对象	将协议专属字段合并到最终 JSON 请求体；嵌套对象会递归合并；除 Runtime 保留字段外，用户显式配置会覆盖 AI SDK 默认值
`providerTools`	对象数组	开启 Soln 已注册的厂商服务端工具；每一项包含已注册的 `id` 和可选的 `options` 对象

初次配置时，按下面的顺序判断字段放在哪里：

temperature、topP、maxTokens、presencePenalty、frequencyPenalty 直接放在最外层
厂商文档中定义的其他请求体字段，保持原字段名和嵌套结构，放到 requestBody 中
需要厂商服务端工具时，从下方表格选择已注册的工具 ID，放到 providerTools 中
headers 只用于额外的厂商或网关请求头。API Key 仍然填写在独立的 API Key 字段

字段位置速查：

配置需求	在配置 JSON 中的位置
通用采样参数或输出上限	最外层，例如 `temperature`、`maxTokens`
厂商额外的顶层请求体字段	`requestBody.<厂商字段>`
厂商额外的嵌套请求体字段	在 `requestBody` 下保留完整嵌套结构
厂商联网搜索或其他已注册服务端工具	`providerTools[].id` 和 `providerTools[].options`
额外 HTTP 请求头	`headers.<请求头名称>`

所有已支持协议共用这套请求体透传机制。Soln 不判断模型名、不在协议之间转换参数名，也不维护厂商请求字段白名单。请按照所选提供方或网关的文档，只配置该端点真实接受的字段。

requestBody 中的对象会递归合并，显式配置的标量和数组会替换 AI SDK 对应的默认值。请求身份、对话状态、凭据、流式传输和工具编排仍由 Soln Runtime 管理，不能覆盖。受保护字段包括 model、messages、input、contents、prompt、system、systemInstruction、instructions、stream、tools、tool_choice、toolConfig、store、conversation、previous_response_id、background、apiKey、api_key、baseUrl 和 base_url。

厂商工具

providerTools 是由模型提供方服务端执行的工具。调用 streamText() 前，Soln 会通过对应的 AI SDK provider tool factory 创建工具，并与 Assistant Runtime tools 一起交给模型。只有文本模型协议会推导出工具调用能力，因此该配置仅适用于文本模型。

providerTools 的每一项只允许以下字段：

字段	是否必填	说明
`id`	是	已注册的厂商工具标识，必须属于当前选择的协议
`options`	否	传给对应 AI SDK provider tool factory 的配置；可用字段取决于工具 ID

当前已注册工具：

工具 ID	协议	用途及选项
`openai.web_search`	OpenAI Responses	联网搜索；选项用于控制外部网络访问、允许访问的域名、搜索上下文大小和用户大致位置
`anthropic.web_search_20260209`	Anthropic Messages	联网搜索；选项用于控制最大使用次数、允许或屏蔽的域名和用户大致位置
`google.google_search`	Google Gemini GenerateContent	Google Search grounding；选项用于控制启用的搜索类型和可选时间范围

支持的 options 字段：

工具 ID	选项	类型	用途
`openai.web_search`	`externalWebAccess`	布尔值	选择访问外部实时网页，或使用提供方缓存、索引的内容
`openai.web_search`	`filters.allowedDomains`	字符串数组	将搜索结果限制在指定域名
`openai.web_search`	`searchContextSize`	`low`、`medium` 或 `high`	控制搜索上下文数量、延迟和成本
`openai.web_search`	`userLocation`	对象	提供大致国家、城市、地区和时区，使结果更符合用户位置
`anthropic.web_search_20260209`	`maxUses`	数字	限制一次对话内执行搜索的次数
`anthropic.web_search_20260209`	`allowedDomains`	字符串数组	将搜索限制在指定域名
`anthropic.web_search_20260209`	`blockedDomains`	字符串数组	从搜索中排除指定域名
`anthropic.web_search_20260209`	`userLocation`	对象	提供大致国家、城市、地区和时区，使结果更符合用户位置
`google.google_search`	`searchTypes`	对象	在所选模型支持时开启网页搜索、图片搜索或同时开启两者
`google.google_search`	`timeRangeFilter`	对象	使用必填的 ISO 8601 `startTime` 和 `endTime` 限制结果时间范围

以下内容是 Soln 配置 JSON 示例，不是厂商官方请求报文。只选择与当前模型资源协议一致的配置。

OpenAI Responses 联网搜索：

{
  "providerTools": [
    {
      "id": "openai.web_search",
      "options": {
        "externalWebAccess": true,
        "searchContextSize": "medium"
      }
    }
  ]
}

Anthropic Messages 联网搜索：

{
  "providerTools": [
    {
      "id": "anthropic.web_search_20260209",
      "options": {
        "maxUses": 5
      }
    }
  ]
}

Google Gemini GenerateContent 搜索 grounding：

{
  "providerTools": [
    {
      "id": "google.google_search",
      "options": {
        "searchTypes": {
          "webSearch": {}
        }
      }
    }
  ]
}

需要同时配置生成参数和厂商工具时，把它们放在同一个配置 JSON 对象中。例如，temperature 应与 providerTools 同级，不能写进 options。

这些工具不是 Soln 业务工具。租户数据和业务操作仍然通过 SL_COMMANDS、executeSlCommand 和 Runtime 领域实现执行，不经过 MCP。厂商工具也不能写入 requestBody.tools，因为工具注册和工具选择必须由 Soln Runtime 管理。

不要把密钥写进配置 JSON。凭据应填写在 API Key 字段中，作为资源密钥保存。

模型计费

模型计费用于给 AI 模型配置价格。调用日志和用量统计中的预估费用、用量控制中的费用上限，都依赖这里配置的计费模式。

打开 系统管理 > 资源管理 > AI 模型，然后在左侧分类列表底部点击 模型计费。

计费模式

页面左侧是当前空间已创建的计费模式，右侧是计费模式编辑器。

操作	说明
新增	创建一个新的计费模式
编辑	修改计费模式名称、币种、计费方式、计费价格和适用模型
删除	永久删除该计费模式

计费字段

字段	是否必填	说明
计费模式名称	是	计费模式的展示名称
币种	是	支持人民币（CNY）和美元（USD）
计费方式	是	决定需要填写哪些价格字段，以及费用如何按用量计算
计费价格	是	按计费方式填写每百万 Token 或每张图像的价格，最多 6 位小数
适用模型	是	按分类选择 AI 模型；一个模型只能绑定一个计费模式，已被其他计费模式使用的模型不能重复选择

计费方式

计费方式	适用场景	价格字段
输入/输出 Token 计费	只按输入和输出 Token 计费的模型	输入、输出（每百万 Token）
缓存输入 Token 计费	区分普通输入、缓存读取和缓存写入的模型	输入、缓存输入、缓存写入（可选）、输出（每百万 Token）
长上下文 Token 计费	超过阈值后使用另一套价格的模型	长上下文阈值（K Token）；普通上下文和长上下文各自的输入、缓存输入、缓存写入（可选）、输出（每百万 Token）
多模态 Token 计费	文本和图片共同按 Token 计费的模型	文本输入、缓存文本输入、图片输入 Token、缓存图片输入、文本输出、图片输出 Token、推理输出（每百万 Token）；至少填写一项
图像生成计费	按图片张数计费的图片生成模型	输入图像（可选），以及一条或多条输出图像价格（尺寸、质量、每张图像单价）

计费说明：

没有配置计费模式的模型仍然可以正常调用，但调用日志和用量统计中的费用会显示为 未配置价格
修改计费模式只影响之后的调用费用计算；历史调用日志保留当时的计费结果
计费模式区分币种。同一空间内可以同时存在人民币和美元计费模式，用量页面会按币种分别展示费用

模型用量

模型用量页面汇总当前空间的模型调用记录、Token 消耗、费用和用量控制。入口是 系统管理 > 资源管理 > AI 模型 顶部栏右侧的 模型用量。

左侧菜单：

菜单	用途
用量概览	按时间范围查看调用趋势、Token 构成、分类分布和模型用量排行
用量统计	按组织和部门统计 Token、图片数量和估算费用
调用日志	查看每一次模型调用明细
外部调用	管理成员用于外部调用模型服务的 API Key

具备资源编辑权限的成员还会在右上角看到 用量控制，用于配置用量上限规则和模型网关保护。

用量概览

区域	说明
筛选	时间范围（默认最近七天）、模型分类、模型；选择分类后才能进一步选择该分类下的模型
指标卡片	调用次数、Token 总量、活跃用户、成功率、任务平均耗时、缓存命中率、预估费用；费用按币种分别展示
图表	调用次数与 Token 趋势、输入/输出/缓存 Token、模型分类分布
模型用量排行	模型、调用次数、Token、费用、成功率、任务平均耗时

图表可以通过面板右上角的导出按钮保存为 PNG，模型用量排行可以导出为 Excel。费用为空或显示为 - 时，通常是该模型没有配置计费模式，或者调用日志缺少计算费用所需的用量数据。

用量统计

用量统计按成员当前所属的组织和部门归类，用于查看 Token、图片数量和估算费用在组织内的分布。

区域	说明
筛选	时间范围、模型分类、模型
指标卡片	Token、图片数量、人民币估算费用、美元估算费用，并显示各自的时间趋势
组织部门用量分布	以矩形树图展示各部门用量占比，可切换统计指标并导出 PNG
组织部门用量	组织、部门、Token、图片数量、人民币估算费用、美元估算费用；支持按组织或部门筛选、分页和导出 Excel
用户用量	用户、Token、图片数量、人民币估算费用、美元估算费用；支持按用户筛选、分页和导出 Excel

调用日志

调用日志按时间倒序展示每一次模型调用，用于排查失败调用和核对费用。

项目	说明
筛选	开始时间、结束时间、调用用户、模型分类、模型；刷新按钮会重新加载当前筛选结果
列	调用时间、调用用户、模型、分类、协议、Tokens、预估费用、耗时、状态
Tokens	分别展示输入、输出、缓存读取和缓存写入的 Token 数量
汇总	分页区展示当前筛选范围内的缓存命中率和 Token 总量
预估费用	按计费模式计算；无法计算时显示未配置价格、Usage 不完整、未匹配价格规则或价格规则无效

费用状态说明：

状态	含义	处理方式
未配置价格	该模型没有绑定任何计费模式	在模型计费中为模型配置价格
Usage 不完整	提供方返回的用量数据缺少当前计费方式需要的字段	检查协议、模型能力和提供方响应，或改用与返回数据匹配的计费方式
未匹配价格规则	计费模式存在，但调用用量没有命中任何价格档位	检查计费方式、长上下文阈值和图片尺寸、质量配置
价格规则无效	计费模式配置不合法	重新保存该计费模式的价格

外部调用

外部调用默认关闭。具有资源编辑权限的管理员可在此页打开 外部调用 开关。关闭时，成员账户设置隐藏 AI 密钥入口，模型网关拒绝外部请求（包括模型列表查询），返回 HTTP 403 和 MODEL_GATEWAY_EXTERNAL_CALL_DISABLED。开启后仍需有效密钥、成员状态及模型权限。

外部调用用于管理成员通过模型服务调用模型时使用的 API Key。

项目	说明
筛选	时间范围（默认本周）、调用用户
列	用户、Key、状态、调用时间、创建时间、更新时间
轮换	为指定成员生成新的 Key；旧 Key 立即失效，新 Key 明文只显示一次
停用 / 启用	停止或恢复该成员使用 Key 调用模型服务

外部调用产生的模型用量同样写入调用日志，并参与用量统计和用量控制。

调用前的准备

先确认管理员已开启当前租户的外部调用开关。

拿到 AI 密钥：侧边栏的 设置 > AI 密钥 可以生成当前成员的密钥，管理员也可以在 模型用量 > 外部调用 里为成员轮换密钥。密钥以 so. 开头，只显示一次
拿到要调用的模型资源 Key：系统管理 > 资源管理 > AI 模型，或调用 GET /api/soln.modelservice/v1/models
用资源的协议匹配下面的端点
带上密钥请求头发起调用

调用地址

外部调用走工作空间自己的模型服务网关，所以调用地址就是工作空间地址加上 soln.modelservice 前缀：

https://<工作空间域名>/api/soln.modelservice

网关沿用模型资源的协议，所以要按资源的协议选择对应端点。

协议	方法	端点	凭据请求头	必填请求体字段
OpenAI Chat Completions	POST	`/api/soln.modelservice/v1/chat/completions`	`Authorization: Bearer <AI 密钥>`	`model`、`messages`
OpenAI Responses	POST	`/api/soln.modelservice/v1/responses`	`Authorization: Bearer <AI 密钥>`	`model`、`input`
Anthropic Messages	POST	`/api/soln.modelservice/v1/messages`	`x-api-key: <AI 密钥>`	`model`、`messages`、`max_tokens`
Google GenerateContent	POST	`/api/soln.modelservice/v1beta/models/{model}:generateContent`	`x-goog-api-key: <AI 密钥>`	`contents`
Google 流式	POST	`/api/soln.modelservice/v1beta/models/{model}:streamGenerateContent?alt=sse`	`x-goog-api-key: <AI 密钥>`	`contents`
列出可用模型	GET	`/api/soln.modelservice/v1/models`	`Authorization: Bearer <AI 密钥>`	无

Anthropic 请求可以带 anthropic-version 和 anthropic-beta；不传 anthropic-version 时网关使用 2023-06-01。端点与模型资源的协议不一致时，网关会返回 MODEL_GATEWAY_PROTOCOL_INVALID。

模型资源的协议和端点是一一对应的：一个模型资源只能用自己协议对应的端点调用，不同协议的凭据请求头和请求体结构也不一样。同一个提供方需要同时用两种协议时（例如既用 OpenAI Responses，又用 OpenAI Chat Completions），要按协议分别建两个模型资源。

model 字段填什么

model 填模型资源的 资源 Key，不是提供方的模型名。获取方式有两种：

系统管理 > 资源管理 > AI 模型 的模型列表里可以查看每个模型的资源 Key
GET /api/soln.modelservice/v1/models 会返回该 Key 可用的模型，返回项的 id 就是资源 Key

转发到提供方之前，网关会把 model 替换成模型资源上配置的提供方模型名，所以调用方不需要知道提供方模型名。Google 的两个端点把资源 Key 放在地址里，而不是请求体里。GET /v1/models 还会返回模型当前是否可用以及剩余额度。

curl 调用示例

列出空间内可用的模型：

export SOLN_API_KEY="so.xxxxxxxxxxxxxxxx"
export SOLN_BASE_URL="https://<工作空间域名>/api/soln.modelservice"

curl "$SOLN_BASE_URL/v1/models" \
  -H "Authorization: Bearer $SOLN_API_KEY"

调用 OpenAI Chat Completions 模型：

curl "$SOLN_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $SOLN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-6-abc123",
    "messages": [
      { "role": "user", "content": "用一句话介绍 Soln" }
    ],
    "temperature": 0.7
  }'

流式返回：

curl -N "$SOLN_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $SOLN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-6-abc123",
    "messages": [
      { "role": "user", "content": "写一段 200 字的说明" }
    ],
    "stream": true
  }'

调用 OpenAI Responses 模型：

curl "$SOLN_BASE_URL/v1/responses" \
  -H "Authorization: Bearer $SOLN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-6-abc123",
    "input": "总结这条记录的要点"
  }'

调用 Anthropic Messages 模型：

curl "$SOLN_BASE_URL/v1/messages" \
  -H "x-api-key: $SOLN_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8-abc123",
    "max_tokens": 1024,
    "messages": [
      { "role": "user", "content": "用一句话介绍 Soln" }
    ]
  }'

调用 Google Gemini GenerateContent 模型，资源 Key 放在地址里：

curl "$SOLN_BASE_URL/v1beta/models/gemini-3-6-flash-abc123:generateContent" \
  -H "x-goog-api-key: $SOLN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      { "parts": [ { "text": "用一句话介绍 Soln" } ] }
    ]
  }'

请求与响应规则

规则	说明
内容类型	请求必须使用 `Content-Type: application/json`
请求体大小	请求体最大 8 MB
响应	提供方的响应原样返回，包括流式返回的 Server-Sent Events
请求 ID	每个响应都带 `x-request-id` 响应头，同一个 ID 会写入调用日志
流式	传 `stream: true` 即可获得流式内容；网关会自动补上 `stream_options.include_usage`，保证调用可计费
提供方字段	除 `model` 之外的请求体字段会原样转发给提供方，可以直接传厂商专属参数
超时	上游调用默认 120 秒后中断，返回 `MODEL_GATEWAY_UPSTREAM_TIMEOUT`

错误返回

网关自身的错误使用 OpenAI 的错误结构；提供方返回的错误则保留提供方的状态码和响应体：

{
  "error": {
    "code": "MODEL_GATEWAY_API_KEY_REQUIRED",
    "message": "MODEL_GATEWAY_API_KEY_REQUIRED",
    "param": null,
    "type": "authentication_error"
  }
}

HTTP	错误码	含义
400	`MODEL_GATEWAY_MODEL_REQUIRED`、`MODEL_GATEWAY_MESSAGES_REQUIRED`、`MODEL_GATEWAY_INPUT_REQUIRED`、`MODEL_GATEWAY_CONTENTS_REQUIRED`、`MODEL_GATEWAY_MAX_TOKENS_INVALID`	请求体缺少必填字段或字段值不合法
400	`MODEL_GATEWAY_PROTOCOL_INVALID`	端点与模型资源的协议不一致
400	`MODEL_GATEWAY_CONTENT_TYPE_INVALID`、`MODEL_GATEWAY_BODY_INVALID`	内容类型或 JSON 请求体不合法
401	`MODEL_GATEWAY_API_KEY_REQUIRED`、`MODEL_GATEWAY_API_KEY_INVALID`	AI 密钥未提供或不正确
403	`MODEL_GATEWAY_MEMBER_INACTIVE`、`MODEL_ACCESS_DENIED`	成员或密钥已停用，或该成员不能使用这个模型
404	以 `_NOT_FOUND` 结尾的错误码，例如 `MODEL_NOT_FOUND`	模型资源不存在
413	`MODEL_GATEWAY_BODY_TOO_LARGE`	请求体超过 8 MB
429	`MODEL_GATEWAY_RATE_LIMIT_EXCEEDED`、`MODEL_GATEWAY_CONCURRENCY_LIMIT_EXCEEDED`	被模型网关保护拦截
504	`MODEL_GATEWAY_UPSTREAM_TIMEOUT`	提供方在超时前没有返回

模型网关保护按 AI 密钥统计：每分钟请求数 默认 120，最大并发请求数 默认 8，都可以在 用量控制 里调整。

用量控制

用量控制用于限定空间、用户、角色、部门或组织可以使用的模型用量。点击 用量控制 后打开规则页面，左侧是规则列表，右侧是规则编辑区。

规则列表包含一条 空间全局规则 和若干自定义规则：

规则	说明
空间全局规则	作用于当前空间的全部用户，额度方式固定为共享额度，且作用于全部 AI 模型
自定义规则	按适用范围、适用模型和限制指标配置

规则字段：

字段	说明
规则名称	规则展示名称
额度方式	独立额度：每个适用成员分别拥有一份额度；共享额度：所有适用成员共同使用一份额度
适用范围	用户、角色、部门或组织；部门和组织可以选择是否包含下级
适用模型	选择规则覆盖的 AI 模型；不选择模型时规则作用于全部 AI 模型
周期	每日或每月
状态	启用或停用
限制指标	调用次数上限、Token 上限、人民币费用上限、美元费用上限、图片生成上限；只填写需要限制的指标，留空表示不限制

限制指标说明：

调用次数、Token 上限和图片生成上限使用整数，Token 上限的单位是百万（M）
人民币和美元费用上限直接填写金额，最多支持 6 位小数
自定义规则的适用范围为空时，该规则不会生效
一次请求命中多条规则时，按 命中匹配 决定每个指标取最严格还是最宽松的额度：最小命中 取各规则中的最小值，最大命中 取各规则中的最大值

同一页面右上角还提供 模型网关保护，用于限制模型网关的请求频率和并发：

字段	说明
每分钟请求数	固定 60 秒窗口内，每个 API Key 的请求上限
最大并发请求数	超过该并发数的请求会被拒绝，直到上游请求完成

状态和删除

启用中的模型可被运行时使用。停用模型会保留配置，但不应再被运行时选择。模型停用后可以删除。

常见流程

打开 系统管理 > 资源管理 > AI 模型
新建或选择模型分类
在分类中点击新增
选择模型类型和与提供方接口匹配的协议
填写 Base URL、API Key、模型名和模型显示名称
按需填写可选配置 JSON，用于提供方专属请求参数
保存模型
按需在模型列表中启用、停用、编辑或删除模型
在 模型计费 中为模型配置价格
通过顶部栏的 模型用量 查看调用日志、用量统计和预估费用
按需在 用量控制 中设置用量上限和模型网关保护

页面结构​

模型分类​

新建 AI 模型​

协议​

模型能力​

图片生成与编辑​

配置 JSON​

通用生成参数​

厂商专属参数​

厂商工具​

模型计费​

计费模式​

计费字段​

计费方式​

模型用量​

用量概览​

用量统计​

调用日志​

外部调用​

调用前的准备​

调用地址​

model 字段填什么​

curl 调用示例​

请求与响应规则​

错误返回​

用量控制​

状态和删除​

常见流程​