快速开始
从零启动服务并跑通第一个模型
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。
模型包契约
一个 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 层
| 方法 | 路径 | 说明 |
|---|---|---|
| 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}/events | SSE:状态变化与日志增量 |
| 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 或浏览器会话。
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 / PORT | 127.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_EXECUTOR | local | local 或 docker |
| MODEL_HUB_UNTRUSTED_EXECUTOR | local | 上传包的强制执行器;生产设为 docker,内置模型不受影响 |
| MODEL_HUB_UNTRUSTED_DOCKER_IMAGE | 空 | 上传包固定使用的镜像;空则用 MODEL_HUB_DOCKER_IMAGE,上传 manifest 不能自选镜像 |
| MODEL_HUB_RUN_RETENTION_DAYS | 0 | model-hub prune 的默认保留天数 |
| MODEL_HUB_USE_MODEL_VENV | true | 是否创建每模型独立 venv |
| MODEL_HUB_MAX_WORKERS | 2 | 并发运行数;请以单进程 uvicorn 运行 |
| MODEL_HUB_MIN_FREE_DISK_MB | 512 | 上传后数据盘至少保留的空闲空间;不足时 API 返回 507 |
| MODEL_HUB_API_KEY | 空 | 部署级 Key;设置后 REST 与 MCP 需要 Key(个人 Key 仅 REST);后台也可用账号会话 |
| MODEL_HUB_DOCKER_NETWORK | 空 | 仅由运维显式指定时才给容器联网 |
故障排查
从健康检查到模型日志的排查顺序
- 先看健康检查。 /api/v1/health 会返回数据库、执行器、模型/数据集/运行计数;status 不是 ok 时先修服务。
- 再看依赖状态。 模型详情会显示 deps_status;安装失败时先检查 requirements.txt 版本和运行时是否匹配。
- 检查参数与字段映射。 输入表缺列、日期无法解析、参数超出范围都会在提交前或运行初期返回明确错误。
- 读运行日志。 运行详情页和 /api/v1/runs/{id}/log 保留完整 stdout/stderr;模型内部的 ctx.log() 也会写进去。
- 确认产物路径。 模型只能写 ctx.output_path() 或工作区 outputs;写到其他位置不会进入产物列表。
- 需要隔离时切 Docker。 设置 MODEL_HUB_EXECUTOR=docker 并确认 Docker 可用;启动时会 fail fast。
如果要复现问题,请记录模型 ID、版本、参数、数据集哈希、运行 ID 和日志尾部;这些信息足以定位大多数失败。