Instructions For Model Inference Interface Configuration In Details

本文档提供模型推理界面配置文件 mada_api.json 的完整字段说明和使用指南。

配置文件结构

完整的配置文件结构如下：

{
"schema_version": "0.1",
"description": "模型描述信息",
"endpoint": {
"method": "POST",
"mode": "stream",
"stream": {
"transport": "sse",
"chunk_schema": "text"
}
},
"request": {
"content_type": "json",
"inputs": [
/* FieldDefSchema 数组 */
],
"params": [
/* FieldDefSchema 数组 */
],
"rules": {
"required_group": ["field1", "field2"],
"mutually_exclusive": [
["field1", "field2"],
["field3", "field4"]
]
}
},
"response": {
"mode": "json_any",
"error_shape": {
"path_code": "error.code",
"path_message": "error.message",
"canonical_codes": ["400", "500"]
}
}
}

详细字段说明

根级别字段

endpoint 对象

配置API端点的基本信息。

stream 对象（可选）

当 endpoint.mode 为 "stream" 时使用的流式配置。

request 对象

配置请求的参数和规则。

rules 对象（可选）

定义参数之间的关系和验证规则。

| 名称 | 类型 | 必填 | 说明 | 示例 | | ------------------ | ----- | ---- | ------------------------------------------ | -------------------------------------------- | | required_group | array | ✗ | 必须同时填写的参数组 | ["field1", "field2"] | | mutually_exclusive | array | ✗ | 互斥参数组，每个子数组内的参数不能同时存在 | [["field1", "field2"], ["field3", "field4"]] |

response 对象（可选）

配置响应处理方式。

error_shape 对象（可选）

定义错误响应的解析规则。

FieldDefSchema 对象

定义单个参数的配置，用于 inputs 和 params 数组中。

基础字段

类型系统

type 支持的参数类型及其说明：

| 类型 | 说明 | 适用场景 | 示例 | | -------- | ---------------------------------------------- | --------------------------------------------------- | ------------------- | | string | 字符串类型 | 文本输入 | 用户名、描述等 | | number | 数字类型（含小数） | 数值输入 | 温度、重量等 | | integer | 整数类型 | 整数输入 | 年龄、数量等 | | boolean | 布尔类型 | 开关选择 | 是否启用某功能 | | array | 数组类型 | 多选输入 | 标签列表 | | object | 对象类型 | 复杂结构 | 配置对象 | | file | 文件类型 | 文件上传 | 文档、数据文件 | | image | 图像类型 | 图像上传 | 照片、图表 | | video | 视频类型 | 视频上传 | 视频文件 | | base64 | API输入为图像的 base64编码 | 图像上传 | 照片 | | raw_body | 原始请求体字符串，直接作为整个请求的 body 发送 | 需要自行构造完整请求体的场景（JSON、XML、Prompt等） | {"input":"hello"} |

source 字段说明

仅适用于文件类型（file、image、video），指定文件的来源方式：

• "file": 通过文件上传组件选择本地文件
• "url": 通过URL输入框指定网络文件
• "base64": 通过文本框输入base64编码的文件内容

accept 字段说明

仅适用于文件类型，定义接受的MIME类型列表。常用值：

• 图片: ["image/jpeg", "image/png", "image/gif", "image/webp"]
• 视频: ["video/mp4", "video/avi", "video/mov"]
• 文档: ["application/pdf", "text/plain", "application/json"]

原始请求体模式（raw_body）

当字段类型设置为 raw_body 时，界面会渲染一个大文本框用于输入原始请求体字符串：

前端会校验该字段不能为空，同时在界面中提示“原始请求体模式”提醒用户注意格式。

完整示例

示例1：图像分类模型

{
"schema_version": "0.1",
"description": "基于深度学习的植物病害识别模型",
"endpoint": {
"method": "POST",
"mode": "sync"
},
"request": {
"content_type": "multipart",
"inputs": [
{
"name": "images",
"title": "植物图片",
"description": "上传待识别的植物叶片图片，支持多张上传",
"type": "image",
"required": true,
"multiple": true,
"source": "file",
"accept": ["image/jpeg", "image/png"]
}
],
"params": [
{
"name": "model_version",
"title": "模型版本",
"description": "选择使用的模型版本",
"type": "string",
"required": false,
"default": "v2.1",
"enum": ["v1.0", "v2.0", "v2.1"]
},
{
"name": "confidence_threshold",
"title": "置信度阈值",
"description": "识别结果的最低置信度要求",
"type": "number",
"required": false,
"default": 0.8,
"min": 0.0,
"max": 1.0
},
{
"name": "enable_preprocessing",
"title": "启用图像预处理",
"description": "是否对输入图像进行自动增强处理",
"type": "boolean",
"required": false,
"default": true
}
]
},
"response": {
"mode": "json_any",
"error_shape": {
"path_code": "error.code",
"path_message": "error.message",
"canonical_codes": ["400", "422", "500"]
}
}
}

示例2：流式文本生成

{
"schema_version": "0.1",
"description": "大语言模型文本生成API",
"endpoint": {
"method": "POST",
"mode": "stream",
"stream": {
"transport": "sse",
"chunk_schema": "json"
}
},
"request": {
"content_type": "json",
"inputs": [
{
"name": "prompt",
"title": "输入提示",
"description": "请输入您的问题或需要生成的内容提示",
"type": "string",
"required": true
}
],
"params": [
{
"name": "max_tokens",
"title": "最大输出长度",
"description": "生成文本的最大token数量",
"type": "integer",
"required": false,
"default": 1000,
"min": 1,
"max": 4000
},
{
"name": "temperature",
"title": "创造性程度",
"description": "控制生成文本的随机性，值越高越有创造性",
"type": "number",
"required": false,
"default": 0.7,
"min": 0.0,
"max": 2.0
},
{
"name": "system_message",
"title": "系统消息",
"description": "设置AI的角色和行为准则",
"type": "string",
"required": false,
"default": "你是一个有用的AI助手"
}
],
"rules": {
"required_group": ["prompt"]
}
},
"response": {
"mode": "stream_text"
}
}