北京时间 API 文档 ↗
Platform documentation

平台文档

模型包契约、REST API、MCP 接入、扩展字段与部署方式。模型自身的运行原理在“模型 → 文档”中查看。

快速开始

从零启动服务并跑通第一个模型

cd /var/www/DEV/model_hub
uv venv --python 3.13 .venv
uv pip install --python .venv/bin/python -e ".[dev,geo]"
.venv/bin/python scripts/make_sample_data.py

MODEL_HUB_USE_MODEL_VENV=false .venv/bin/python scripts/demo.py --model MP-ROLLING-MEAN
.venv/bin/uvicorn model_hub.main:app --host 127.0.0.1 --port 8000

打开 http://127.0.0.1:8000/ 进入控制台;接口文档在 /docs,MCP 端点在 /mcp。外部系统可先读 /.well-known/model-hub.json 或 /llms.txt。生产或内网共享时把 MODEL_HUB_HOST 改为监听地址,并设置 MODEL_HUB_API_KEY。

建议顺序 先看模型详情里的“文档”,确认输入、参数和输出;再在“运行”页上传数据并试跑;最后用 REST 或 MCP 接入外部程序。

模型包契约

一个 zip 包 = manifest + 依赖 + 代码

模型包根目录必须包含 model.yaml 和可导入的 Python 模块。平台从 manifest 生成注册信息、参数表单、校验规则、MCP schema 和文档页面。

model.yaml
requirements.txt
my_model/
  __init__.py
  model.py

最小 manifest

model_id: GEO-EXAMPLE
name: 示例模型
version: 1.0.0
description: 一句话说明模型做什么
model_type: 栅格模型
framework: Python / numpy
domains: [遥感, 生态]
runtime: python3.12
entry: my_model.model:run

params:
  - name: table
    type: file
    formats: [csv]
    required: true
    dataset_default: true
  - name: window
    type: integer
    default: 3
    minimum: 1
    maximum: 365

outputs:
  - name: result.csv
    title: 计算结果
    media_type: text/csv
    preview: table

# 可选:运行详情页图表(CSV 时间序列 / ARC 网格 ZIP)
visualization:
  title: 计算结果图表
  charts:
    - key: trend
      title: 指标趋势
      unit: m
      artifact: result.csv
      index: date
      index_label: 日期
      series:
        - column: value
          label: 指标
  grids:
    artifact: grids.zip
    time: all
    stats: true
    variables:
      - key: ta
        member: ta
        title: 气温
        unit: °C
        convert: kelvin_to_celsius

声明 visualization 后,平台按 manifest 读取产物并生成折线图、网格热图、悬停读数与表格视图;每个折线图最多 4 个序列,charts 与 grids 至少声明一个。网格 ZIP 的成员名需为 <YYYYMMDDHHMM>.<member>,time: latest 取每个变量的最后时次,time: all 让所有变量显示同一时次并提供页面下拉框、上一/下一时次与连续播放,以及 grid_time 参数(只列出所有变量共有的时次);stats: true 会逐时次计算区域平均/最小/最大值并生成统计时序图(最多 366 个时次),convert 支持 none / kelvin_to_celsius / metres_to_centimetres。未声明时回退到内置的 Alpine3D / SHUD / OGGM 图表规则,该声明也出现在 agent_spec.visualization 中。

运行详情页的“时序曲线”支持 time_from / time_to 时间范围筛选(接受 YYYY-MM-DD、YYYY-MM-DD HH:MM、YYYY-MM、YYYY,结束日期按整日包含;无法解析的边界会提示并忽略),筛选同时作用于普通折线和区域统计。每张图提供“导出 CSV”,通过 GET /api/v1/runs/{id}/charts.csv?chart=<key>&time_from=...&time_to=...(页面路径为 /ui/runs/{id}/charts.csv)下载筛选范围内的完整时次,而不是图上的采样点;导出仍受 32 MB / 行数 / 366 时次的读取预算限制。JSON 图表接口与 MCP get_run_charts 同样接受这两个参数,并返回 time_filter 回显;每张图表附带 csv_endpoint,可直接下载对应 CSV。

运行列表页可勾选同一模型的 2–4 个已结束运行进行对比,或访问 /ui/runs/compare?ids=...&ids=...。REST 为 GET /api/v1/runs/compare?ids=...&ids=...,MCP 为 compare_runs(run_ids=[...])。对比按解析后的时间对齐同名变量,缺失时次留空使折线断开;颜色按运行顺序固定,跨图保持一致;多列变量按列拆分,区域统计只对比区域平均。模型未声明 visualization 时,自动识别带时间列的 CSV 时序产物(最多 3 个 CSV、每个 6 列);显式声明时仍以清单为准。响应中的 differing_params / shared_params 列出参数差异;最多 24 张时序图、12 张区域统计图,超出时标记 series_truncated / grid_stats_truncated。

入口函数

入口固定为 run(inputs, params, ctx) -> dict。文件参数从 inputs["files"][name] 读取,不能直接访问宿主路径。

对象用途
inputs["files"]平台物化后的文件描述,含 path/name/format/size/sha256
params已按 manifest 校验和类型转换的参数
ctx.output_path(name)在工作区 outputs 下创建产物路径,只接受文件名
ctx.add_file(path, format, title, **meta)登记产物;未登记的 outputs 文件也会自动归档
ctx.check()检查超时与取消标记,长循环中应定期调用
ctx.progress(percent, message)可选:上报进度;同时写入运行日志、SSE 与时间线
ctx.log(message)可选:写入运行日志(建议分阶段输出输入、参数、检查与结果)

返回值可以是任意 JSON 可序列化 dict。平台会归一化为 summary / metrics / preview / warnings / artifacts 信封,原始返回值保留在 raw_result。

运行模型

控制台、Python 与 curl 三种方式

控制台最直接:进入模型详情,点击“运行模型”,选择数据集并填写参数。下面是通过 REST 提交的等价调用:

如果部署设置了 MODEL_HUB_API_KEY,下面每个 /api/v1 请求都要带 -H 'X-API-Key: …'(或 Authorization: Bearer …);浏览器控制台通过登录会话访问,不需要 Key。

# 1. 上传数据集
DS=$(curl -s -H "X-API-Key: $MODEL_HUB_API_KEY" \
  -F file=@examples/datasets/rolling_sample.csv \
  -F name=rolling-sample http://127.0.0.1:8000/api/v1/datasets \
  | python -c 'import sys,json;print(json.load(sys.stdin)["id"])')

# 2. 提交运行(wait_seconds=0 立即返回)
curl -s -X POST http://127.0.0.1:8000/api/v1/runs \
  -H "X-API-Key: $MODEL_HUB_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"model_id\":\"MP-ROLLING-MEAN\",\"params\":{\"value_column\":\"value\",\"window\":3},\"dataset_id\":\"$DS\",\"wait_seconds\":0}"

# 3. 查询状态与产物
curl -s -H "X-API-Key: $MODEL_HUB_API_KEY" http://127.0.0.1:8000/api/v1/runs/<run_id>
curl -s -H "X-API-Key: $MODEL_HUB_API_KEY" http://127.0.0.1:8000/api/v1/runs/<run_id>/artifacts

运行是异步的:提交后立即返回 run_id,通过轮询、SSE 或 MCP 工具获取状态。文件输入也可以写成 file_inputs 的显式映射。

REST API

所有能力都走同一套 Service 层

完整 OpenAPI ↗
方法路径说明
GET/api/v1/models模型列表,支持 query、domain 与 category
GET/api/v1/models/categories目录主题定义(key、中文名、说明、顺序)
POST/api/v1/models上传 zip 模型包并注册新版本(不会执行 requirements.txt)
POST/api/v1/models/{id}/versions/{version}/install-deps审核后显式安装该版本依赖(管理员 / API Key)
GET/api/v1/models/recommend按目标、数据集格式做确定性推荐
GET/api/v1/models/{id}manifest、agent_spec、数据需求与文档元数据
POST/api/v1/models/{id}/validate-inputs无副作用输入预检,返回 checks[] 与修正建议
GET/api/v1/models/{id}/input-template下载 CSV 表头模板(默认列名)
POST/api/v1/datasets上传并登记数据文件
GET/api/v1/datasets数据集列表,支持格式过滤;详情含 profile
GET/api/v1/datasets/{id}/compatible-models按文件格式、表格必需列与压缩包必需文件匹配;用 runnable/input_status 区分可运行与缺少列/文件的模型
POST/api/v1/datasets/{id}/refresh-profile重新生成 CSV/栅格/图片/ZIP 的 profile
DELETE/api/v1/datasets/{id}删除数据集记录与受管目录内的文件
POST/api/v1/runs提交运行,可等待至完成或超时;支持 callback_url 终态回调
POST/api/v1/runs/sweep参数网格扫描:笛卡尔积展开为多次运行,返回持久化 sweep_id、运行 ID 与对比链接
GET/api/v1/runs/sweeps最近扫描批次,可按 model_id 过滤;含网格、运行状态计数与创建时间
GET/api/v1/runs/sweeps/{sweep_id}按批次回访扫描;默认同时返回分析,include_analysis=false 时只取状态
GET/api/v1/runs/{id}/eventsSSE:状态变化与日志增量
POST/api/v1/runs/{id}/cancel取消排队或运行中的任务
GET/api/v1/runs/{id}/artifacts产物列表与下载地址
GET/api/v1/runs/{id}/charts结果图表数据(折线/热图、坐标轴、采样点与表格视图);运行未结束时 available=false
GET/api/v1/runs/compare?ids=...&ids=...对比同一模型 2–4 个已结束运行:对齐叠加时序、区域平均与参数差异
DELETE/api/v1/runs/{id}删除已结束的运行及其工作区、事件和产物
GET/login统一登录页;启用统一身份时只显示前往 platform_auth 的入口,本地密码登录关闭
GET/auth/oidc/login发起 platform_auth 授权码 + PKCE 登录,跳转到统一认证页完成验证码与双因素
GET/auth/oidc/callback校验 ID Token(签发者/受众/有效期/nonce),按统一身份组映射角色并建立 mh_session
GET/admin/login后台独立登录页,保留 next=/admin;启用统一身份时只显示 platform_auth 入口
GET/admin/setup首次初始化页;数据库无用户时创建第一个管理员
POST/api/v1/auth/setup首次创建管理员并建立统一会话;已初始化或启用统一身份时返回 409
POST/api/v1/auth/login邮箱密码登录,设置前台与后台共用的 HttpOnly 会话 Cookie;启用统一身份后返回 403
GET/api/v1/auth/status初始化、登录状态、当前用户、API Key 与会话策略
POST/api/v1/auth/logout撤销当前会话并清除 Cookie;启用统一身份时返回 logout_url,用于结束 platform_auth 单点登录
POST/api/v1/auth/password修改自己的密码,并撤销其他会话;启用统一身份后返回 409,由 platform_auth 管理密码
GET/POST/PATCH/DELETE/api/v1/users[/{id}]管理员管理本地账号、角色与启停;启用统一身份后不设本地密码,密码由 platform_auth 管理
GET/POST/api/v1/users/{id}/api-keys管理员列出或签发个人 API Key;创建响应中的明文令牌只出现一次
DELETE/api/v1/users/{id}/api-keys/{key_id}撤销个人 API Key;撤销后立即失效,审计记录 api_key.revoke
GET/api/v1/admin/overview后台概览:模型、数据集、运行、用户、队列、存储与服务状态
GET/api/v1/admin/system系统快照:健康检查、认证统计、运行时、脱敏配置、路径与存储
GET/api/v1/admin/audit管理员审计日志,支持 action / actor / q / limit / offset
GET/.well-known/model-hub.json能力发现:接口、MCP 工具、主题、限制与鉴权说明
GET/llms.txt面向 LLM/智能体的精简接入说明与调用顺序
GET/api/v1/health服务、数据库、执行器与计数

错误统一返回 {"detail": "..."}。设置 MODEL_HUB_API_KEY 后,/api/v1/* 与 /mcp 需要 X-API-Key 或 Bearer Token。

后台管理

独立 SPA:模型、数据、运行与系统状态

打开后台 ↗

后台管理是位于 /admin 的独立单页应用,与前台模型中心共用同一套 REST API 和 Service 层。侧边栏包含概览、模型管理、数据集管理、运行管理与系统状态,支持刷新、上传、启停、取消、删除与下载。

页面主要功能
概览 #/dashboard模型/数据集/运行/存储指标,最近运行、状态分布、队列与服务状态;12 秒自动刷新
模型管理 #/models搜索与主题筛选、上传 zip、查看版本、启停最新版本
数据集管理 #/datasets上传、搜索、格式筛选、下载、刷新 profile、删除
运行管理 #/runs状态筛选、自动刷新、取消活动运行、删除已结束运行、查看详情与日志
用户管理 #/users管理员创建/编辑/停用/删除账号,分配只读、操作员、管理员角色;启用统一身份时隐藏密码字段,账号在首次统一认证登录时自动绑定
审计日志 #/audit管理员按操作、操作者或关键字筛选登录、用户与数据/运行变更记录
系统状态 #/system健康检查、执行器、存储占用、认证统计、运行时、脱敏配置与受管路径

前台工作区与后台控制台各有登录入口:前台 /login,后台 /admin/login;两者使用同一平台身份,登录后共用同一个 mh_session HttpOnly 会话,权限由账号角色决定。启用统一身份后,退出登录会先撤销本地会话,再跳转 platform_auth 的 end_session_endpoint 结束单点登录,然后回到对应登录页。旧版 mh_admin_session / mh_frontend_session Cookie 在升级后仍可解析,不会强制退出。

配置 MODEL_HUB_OIDC_ISSUER 与 MODEL_HUB_OIDC_CLIENT_SECRET 后,登录页会跳转到 platform_auth 统一认证,账号、图形验证码、双因素与密码策略均由该服务负责;本平台只作为 OIDC 客户端校验 ID Token(签发者、受众、有效期、nonce),并按 groups 声明映射为 viewer / operator / admin。启用统一身份后不保留本地密码登录:/login 与 /admin/login 只显示平台统一认证入口,本地登录接口、匿名首次初始化、自助改密与用户密码重置均被关闭;后台新建账号只预置邮箱与角色,首次统一认证登录时自动绑定。未配置统一身份时,访问任一入口仍会引导到 /admin/setup 创建第一个管理员。

设置 MODEL_HUB_API_KEY 后,机器客户端仍可使用 X-API-Key 或 Bearer;登录/初始化页面与接口始终豁免,浏览器会话也可直接访问 API,无需把部署密钥放进前端。未配置 API Key 时,模型/数据集/运行的旧版 REST 写接口为兼容机器客户端仍允许匿名请求;Web 界面的写操作要求操作员或管理员会话。生产部署请设置 API Key 或在反向代理层限制写接口。

除部署级 MODEL_HUB_API_KEY 外,管理员可在「用户管理 → 编辑用户」的 API Key 面板为账号签发个人令牌(mhk_ 前缀,可设置 1–3650 天有效期)。个人 Key 通过 X-API-Key 或 Bearer 调用 /api/v1/*,权限继承所属账号角色,停用账号或撤销 Key 后立即失效;数据库只保存 SHA-256 摘要,明文令牌仅在创建响应中出现一次。为保证审计与最小权限,个人 Key 只用于 REST;/mcp 仍使用部署级 Key 或浏览器会话。

角色与审计 只读角色可登录前台并查看后台概览、模型、数据集、运行与系统页面,但不能写操作,用户管理与审计日志也不可见;操作员可上传、启停、取消、删除数据与运行;管理员额外拥有用户管理、审计日志和系统管理权限。登录、退出、改密、用户变更、模型/数据集/运行写操作都会写入审计日志,前后台会话分别记录范围,API Key 操作记为 API Key。
删除边界 数据集删除只允许移除 data/datasets 受管目录内的路径;运行删除只允许已结束(成功/失败/已取消)的任务,活动任务需先取消。

MCP 接入

让智能体发现模型、运行模型并读取结果

HTTP 模式直接连接服务端点:

{
  "mcpServers": {
    "model-hub": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

stdio 模式由客户端拉起本地进程,适合桌面环境:

.venv/bin/python -m model_hub.mcp.stdio
工具用途
list_models按关键词或领域搜索模型
get_model读取 manifest、agent_spec、数据需求、输入 schema 与示例调用
recommend_models根据自然语言目标和数据集推荐模型
list_datasets查看可用数据、格式与 profile 列结构
find_models_for_dataset按格式匹配,列出能直接接受某个数据集的模型与输入参数
validate_model_inputs运行前预检参数与文件结构,返回修正建议
run_model提交运行,可短等待
run_model_sweep / list_sweeps / get_sweep提交参数扫描并持久化批次;按 sweep_id 回访状态、分析、折线或热力图
get_sweep_analysis / get_sweep_csv按运行 ID 分析扫描或导出扫描 CSV
get_run / get_run_result查询状态、标准结果信封与原始返回值
list_artifacts / get_artifact_preview列出产物、读取 CSV/JSON 小样本
get_run_charts读取运行结果图表数据(优先 manifest visualization 声明;内置 Alpine3D / SHUD / OGGM 规则兜底)
compare_runs对比同一模型 2–4 个已结束运行,返回时间对齐的叠加曲线、区域平均与参数差异
cancel_run取消运行

智能体应先调用 recommend_models 或 get_model 获取参数 schema,再提交运行。每个工具结果都带 status 和 next_steps,便于闭环。

扩展字段

全部可选,旧模型包无需修改

category:目录主题

category: hydro-flood          # 也可写中文:水文与洪水

主题用于模型目录导航,一个模型只有一个主主题;domains 仍保留为跨主题的自由标签。内置主题为 snow-glacier、permafrost、land-surface、hydro-flood、geohazard、remote-sensing、general。不写时平台按模型 ID 前缀和领域标签推断,无法识别则归入“其他”;旧包无需修改。

metadata:推荐、适用性与引用

metadata:
  license: CC-BY-4.0
  citation: "作者等 (年份). 标题. 期刊."
  doi: "10.xxxx/..."
  keywords: [积雪, 遥感]
  spatial: {bbox: [100.0, 39.7, 100.3, 40.0], crs: EPSG:4326}
  temporal: {start: "2000-01-01", end: "2025-12-31", resolution: 日}
  when_to_use: ["需要从多波段影像提取积雪时"]
  when_not_to_use: ["缺少短波红外波段时"]
  limitations: ["云和地形阴影会造成误判"]

data_requirements:基础数据与专题数据

data_requirements:
  - role: thematic          # base 基础数据 / thematic 专题数据 / auxiliary 辅助数据
    name: 多波段遥感栅格
    required: true
    formats: [tif, tiff]
    param: raster           # 可选,关联到已声明的文件参数
    fields: [red, nir]
    spatial: 与目标区域一致
    resolution: 由输入栅格决定
    source: Landsat / Sentinel-2 等光学影像
    description: 至少包含红光和近红外两个波段。
  - role: auxiliary
    name: 土地覆盖或云掩膜
    required: false
    description: 用于解释异常像元;当前模型不直接读取。

role 区分多个模型可共用的基础底图/驱动数据、当前模型特有的专题观测,以及用于率定或验证的辅助数据。required 表示应用该模型时是否必须准备;param 把数据需求映射到运行表单中的文件参数。data_requirements 会显示在模型概览、文档页和 agent_spec 中,不写入则不改变旧模型行为。

documentation:模型文档页

documentation:
  overview: 一段面向使用者的原理说明
  illustration: snow-ndsi        # 内置示意图键,不接受上传的 HTML/SVG
  concepts:
    - title: 核心概念
      body: 解释文字
      formula: "NDSI = (Green - SWIR) / (Green + SWIR)"
  flow:
    - title: 读取栅格
      kind: input
      detail: 选择多波段 GeoTIFF
  notes:
    - 使用边界和容易误读的地方

illustration 必须是平台内置的可信模板键;上传包不能注入原始 HTML/SVG。未知键会显示占位说明,不影响模型运行。

environment:运行时与依赖

environment:
  lockfile: requirements.lock     # 存在则优先于 requirements.txt
  image: ghcr.io/org/model:1.0.0  # Docker 执行器可覆盖基础镜像
  system_packages: [zlib1g, libgomp1]
  gpu: false
  network: false

input_schema:文件输入契约

params:
  - name: table
    type: file
    formats: [csv]
    required: true
    input_schema:
      kind: table
      min_rows: 30
      columns:
        - {role: date, label: 日期, type: date, required: true,
           aliases: [date, 日期]}
        - {role: air_temp, label: 气温, type: number, required: true,
           unit: °C, aliases: [air_temp_c, tmean], range: [-80, 60]}
  - name: temperature_column
    type: string
    default: air_temp_c
    semantic: {table: table, column_role: air_temp}

sample:
  files:
    table: cryo_snow_energy_sample.csv

数据集上传时自动生成 profile。Web 运行表单据此显示列匹配结果、把字段映射参数变成列名下拉框,并支持“使用示例数据”;文件参数旁可直接下载 CSV 模板。POST /api/v1/models/{model_id}/validate-inputs 和 MCP validate_model_inputs 提供无副作用预检。数据集页的“详情”展示列类型、样例、数据预览、栅格波段/CRS 与压缩包条目。未声明 input_schema 的旧模型行为不变。

压缩包参数可声明 preflight: alpine3d_case:预检会只读解析 ZIP 中央目录、io.ini 与引用文件头,返回 case 摘要(DEM 网格、气象站与时段、土地覆盖率类别、初始雪覆盖、输出目录与 TS_WRITE),并报告缺失的输入或初始雪类别。该过程不解压到磁盘,也不推断坐标系或物理参数。

external:外部官方模型编目、本地简化实现与官方容器执行

external:
  official_version: HRLDAS v5.2.1 + Noah-MP v5.2.1
  source_version: "5.2.1"
  source_url: https://github.com/NCAR/hrldas
  homepage_url: https://www.ral.ucar.edu/projects/hap/approach/noahmp
  docs_url: https://github.com/NCAR/hrldas/tree/main/docs
  language: Fortran
  license: Apache-2.0
  release_date: "2026-06-09"
  runtime_environment: gfortran 11 + NetCDF-Fortran 4.7.4(官方容器)
  local_implementation: false
  container_implementation: true
  implementation_note: 官方 hrldas.exe 由平台包装器调用,源码未修改…
  note: 官方版本与编目说明

只声明 external 而不设 local_implementation 或 container_implementation 时,条目不要求 entry,也不创建 venv 或安装依赖;列表和详情返回 runnable=false、execution_mode=catalog,POST /api/v1/runs 返回 409。

设置 local_implementation: true 后,条目同时保留官方版本/源码元数据,并像普通模型一样声明 entry、runtime、params 与 outputs;平台安装依赖并可本地执行。列表和详情返回 runnable=true、execution_mode=local_simplified,运行结果必须说明是简化实现、不等同于官方模型。

设置 container_implementation: true 则要求同时声明 environment.image:官方源码在该镜像内编译运行,entry 只是负责输入输出适配的 Python 包装器。该版本强制使用 Docker 执行器(即使部署配置为 local),返回 runnable=true、execution_mode=official_container、environment_image。镜像缺失时运行失败并提示构建命令,不会静默退回简化实现。

执行器与部署

本地子进程用于可信模型,Docker 用于隔离不可信代码

本地执行器(默认)

  • 每个模型版本独立 venv
  • 工作区隔离输入、代码与产物
  • 超时、取消、资源限制尽力而为
  • 不是安全沙箱

Docker 执行器

  • 默认无网络、只读根文件系统
  • 非 root 用户、丢弃 capabilities
  • 内存、CPU、PID 与临时目录限额
  • 适合同步运行不可信上传代码

常用环境变量

变量默认值说明
MODEL_HUB_HOST / PORT127.0.0.1 / 8000监听地址与端口
MODEL_HUB_SSL_CERTFILE / SSL_KEYFILE空可选直连 TLS;生产建议由反向代理终止 TLS
MODEL_HUB_DATA_DIR./data数据集、运行工作区、模型 venv
MODEL_HUB_DATABASE_URL空PostgreSQL 连接串;为空时回退到 data/hub.db(SQLite)
MODEL_HUB_EXECUTORlocallocal 或 docker
MODEL_HUB_UNTRUSTED_EXECUTORlocal上传包的强制执行器;生产设为 docker,内置模型不受影响
MODEL_HUB_UNTRUSTED_DOCKER_IMAGE空上传包固定使用的镜像;空则用 MODEL_HUB_DOCKER_IMAGE,上传 manifest 不能自选镜像
MODEL_HUB_RUN_RETENTION_DAYS0model-hub prune 的默认保留天数
MODEL_HUB_USE_MODEL_VENVtrue是否创建每模型独立 venv
MODEL_HUB_MAX_WORKERS2并发运行数;请以单进程 uvicorn 运行
MODEL_HUB_MIN_FREE_DISK_MB512上传后数据盘至少保留的空闲空间;不足时 API 返回 507
MODEL_HUB_API_KEY空部署级 Key;设置后 REST 与 MCP 需要 Key(个人 Key 仅 REST);后台也可用账号会话
MODEL_HUB_DOCKER_NETWORK空仅由运维显式指定时才给容器联网
安全边界 本地执行器面向可信模型和演示。生产环境设置 MODEL_HUB_UNTRUSTED_EXECUTOR=docker 后,所有上传包都会强制在 Docker 中运行(install-deps 也在容器内执行),内置模型不受影响;Docker 不可用时直接拒绝运行,不会退回本地。上传包也不能自选镜像,只能使用运维配置的 MODEL_HUB_UNTRUSTED_DOCKER_IMAGE。

故障排查

从健康检查到模型日志的排查顺序

  1. 先看健康检查。 /api/v1/health 会返回数据库、执行器、模型/数据集/运行计数;status 不是 ok 时先修服务。
  2. 再看依赖状态。 模型详情会显示 deps_status;安装失败时先检查 requirements.txt 版本和运行时是否匹配。
  3. 检查参数与字段映射。 输入表缺列、日期无法解析、参数超出范围都会在提交前或运行初期返回明确错误。
  4. 读运行日志。 运行详情页和 /api/v1/runs/{id}/log 保留完整 stdout/stderr;模型内部的 ctx.log() 也会写进去。
  5. 确认产物路径。 模型只能写 ctx.output_path() 或工作区 outputs;写到其他位置不会进入产物列表。
  6. 需要隔离时切 Docker。 设置 MODEL_HUB_EXECUTOR=docker 并确认 Docker 可用;启动时会 fail fast。

如果要复现问题,请记录模型 ID、版本、参数、数据集哈希、运行 ID 和日志尾部;这些信息足以定位大多数失败。

相关入口