# Geoscience Model Hub > 地学模型注册、推荐与异步运行服务。提供 REST/OpenAPI、MCP(streamable HTTP 与 stdio)和 Web 控制台。 Base URL: https://model.ncdc.ac.cn Models: 43 ## 它解决什么问题 把地学模型打包成 `model.yaml + requirements.txt + 代码` 的独立模型包,统一完成: 注册与版本管理、参数校验、数据集解析、异步执行、产物归档、进度事件和智能体可读的模型卡片。 ## 推荐调用顺序 1. `GET /api/v1/models/recommend?goal=<自然语言目标>` 找到候选模型(可附 `dataset_id`)。 2. `GET /api/v1/models/{model_id}` 读取 `agent_spec`:`data_requirements`、`input_schema`、 `outputs[].schema`、`example_call`,以及 `when_to_use` / `when_not_to_use` / `limitations`。 `data_requirements[].role` 区分基础数据(base)、专题数据(thematic)和辅助数据(auxiliary), `required` 表示是否必须准备;需要在向用户索要数据前先检查。 先看 `runnable`:为 `false` 时表示这是仅编目的外部模型,只能读取 `external.official_version`、`external.source_url` 与 `external.runtime_environment`, 不要尝试在平台内运行。若 `runnable=true`,再看 `execution_mode`: `local_simplified` 表示平台提供该官方模型的 Python 简化实现,可直接运行, 但必须向用户说明它不是官方源码、结果不等同于官方模型;`official_container` 表示官方源码在 `environment_image` 声明并已构建的 Docker 镜像中执行, 可直接运行,结果来自官方引擎,平台只做输入输出格式适配。 3. `GET /api/v1/datasets?format=` 找到输入数据集 ID,并读取 `profile.columns` 的真实列名、类型和行数;CSV 列映射参数应设为这些列名。 4. `POST /api/v1/models/{model_id}/validate-inputs` 预检参数与文件结构, 返回 `checks[]` 和 `suggestions[]`,不会创建运行。需要新建 CSV 时可用 `GET /api/v1/models/{model_id}/input-template?param=` 下载表头模板。 5. `POST /api/v1/runs` 提交运行: `{"model_id": "...", "params": {...}, "file_inputs": {"table": {"dataset_id": "..."}}, "wait_seconds": 30}` 文件参数也可用顶层 `dataset_id` 自动匹配声明了 `dataset_default` 的输入。 6. 未在等待窗口内完成时,轮询 `GET /api/v1/runs/{id}`,或订阅 `GET /api/v1/runs/{id}/events`(SSE)。 7. 成功后读取 `result`(summary/metrics/preview/warnings/artifacts),并用 `GET /api/v1/runs/{id}/artifacts` 或 `.../artifacts/{name}` 下载产物。 8. 需要异步通知时,提交运行时可带 `callback_url`,完成后服务会 POST 事件。 若模型 `runnable=false`,`POST /api/v1/runs` 会返回 409;此时应引导用户访问官方源码和运行环境。 ## 外部官方模型 部分目录条目来自公开源码的官方上游模型(如 GLDAS、Noah-MP、CoLM、Alpine3D、CESM、 SURFEX/ISBA、MFDrouting)。`external` 始终给出官方版本、源码、语言、许可证和官方运行环境。 这些条目分为两类: - `runnable=true` 且 `execution_mode=local_simplified`:平台提供以 Python 编写的简化实现, 可通过 `run_model` 或 `POST /api/v1/runs` 本地执行,并返回 CSV/JSON 产物;结果只用于 演示和流程验证,不等同于官方模型,汇报时必须说明。 - `runnable=true` 且 `execution_mode=official_container`:官方上游代码在 `environment_image` 声明的 Docker 镜像内执行,平台只做输入输出适配;结果来自官方引擎。 - `runnable=false`:仅编目,平台不安装、不执行;提交运行返回 409。 ## MCP - HTTP endpoint: `https://model.ncdc.ac.cn/mcp`(transport: `streamable-http`) - stdio: `python -m model_hub.mcp.stdio` - Tools: `list_models`, `get_model`, `recommend_models`, `list_datasets`, `preview_dataset`, `find_models_for_dataset`, `validate_model_inputs`, `run_model`, `run_model_sweep`, `list_sweeps`, `get_sweep`, `get_sweep_analysis`, `get_sweep_csv`, `get_run`, `get_run_result`, `list_artifacts`, `get_artifact_preview`, `get_run_charts`, `compare_runs`, `get_run_log`, `cancel_run`, `rerun_run` - 推荐先 `recommend_models` → `get_model` → `list_datasets` → `validate_model_inputs` → `run_model` → `get_run`。 ## REST 关键端点 - `GET /api/v1/models`、`GET /api/v1/models/{model_id}`、`GET /api/v1/models/categories` - `GET /api/v1/models/recommend?goal=...` - `POST /api/v1/models/{model_id}/validate-inputs` - `GET /api/v1/models/{model_id}/input-template?param=...`(CSV 表头模板) - `GET/POST /api/v1/datasets`(详情包含 `profile`;Web 详情页 `/ui/datasets/{id}`) - `POST /api/v1/runs`、`GET /api/v1/runs/{id}`、`GET /api/v1/runs/{id}/events` - `POST /api/v1/runs/sweep`、`GET /api/v1/runs/sweeps`、`GET /api/v1/runs/sweeps/{sweep_id}` - `GET /api/v1/runs/{id}/artifacts`、`GET /api/v1/runs/{id}/artifacts/{name}` - `POST /api/v1/runs/{id}/cancel` - `DELETE /api/v1/runs/{id}`(仅已结束运行) - `POST /api/v1/datasets/{id}/refresh-profile`、`DELETE /api/v1/datasets/{id}` - `GET /api/v1/admin/overview`、`GET /api/v1/admin/system`(后台管理聚合数据) - `GET /openapi.json`、`GET /docs`、`GET /.well-known/model-hub.json`、后台管理 `GET /admin` ## 模型主题 - 积雪与冰川(`snow-glacier`,16 个):积雪过程、积雪遥感、融雪、冰川与海冰动力学 - 多年冻土(`permafrost`,5 个):活动层、地温、冻结指数与 n 因子 - 陆面模型(`land-surface`,9 个):陆面过程、陆气交换与地表数据同化 - 水文与洪水(`hydro-flood`,8 个):降雨径流、基流、明渠水力学、洪水频率与演进、水库调洪 - 地质灾害(`geohazard`,3 个):边坡稳定、泥石流预警与地面沉降 - 遥感与植被(`remote-sensing`,1 个):植被指数与地表遥感分析 - 示例与通用(`general`,1 个):平台示例与通用数据处理 其中 `HYDRO-GROUNDWATER-MODFLOW` 是 MODFLOW 风格的一维地下水教学模型(补给、抽水、 河流边界与水量平衡),不是 USGS MODFLOW 可执行程序;需要正式地下水模拟时请使用完整 MODFLOW 6。 ## 模型包契约 zip 包至少包含: ```text model.yaml requirements.txt /.py # entry: .:run ``` 模型入口为 `run(inputs, params, ctx) -> dict`。文件参数从 `inputs["files"][name]` 获取, 用 `ctx.output_path()` 创建输出、`ctx.add_file()` 登记产物,可选调用 `ctx.check()`、 `ctx.progress()`、`ctx.log()`。旧包无需修改;`metadata`、`documentation`、`environment`、 `category` 与参数语义字段均为可选扩展。 ## 限制与安全 - 单次上传上限 100 MB;队列上限 50;工作线程 2。 - `wait_seconds` 最大 600 秒;超时只返回当前状态,不会取消运行。 - 需要 `X-API-Key` 或 `Authorization: Bearer ` 访问 /api/v1 与 /mcp;管理员可为账号签发个人 API Key(`mhk_` 前缀,权限跟随账号角色,仅 REST;明文只在创建时返回一次,撤销或停用账号后立即失效):`POST/GET/DELETE /api/v1/users/{user_id}/api-keys`。浏览器登录访问 `/auth/oidc/login`,跳转到平台统一认证 https://id.ncdc.ac.cn(账号、图形验证码、双因素与密码策略由 platform_auth 负责);前台入口为 `/login`,后台入口为 `/admin/login`,登录后共用 HttpOnly `mh_session`。统一身份组映射为角色:admin=['platform-admins', 'model_hub-admins'],operator=['model_hub-operators'],其余授权账号为 viewer。启用统一身份后本地密码登录关闭,退出时会通过 platform_auth 的 end_session_endpoint 结束单点登录会话。 - 本地执行器不是安全沙箱;不可信模型代码应使用 Docker 执行器或独立主机。 - 回调仅支持 http/https;默认拒绝环回、私网和链路本地地址。SSRF 防护不能替代网络层隔离。 ## 更多 - OpenAPI: /openapi.json - Swagger UI: /docs - 平台文档: /ui/docs - 能力发现: /.well-known/model-hub.json