aisky 0.1.0

aisky 系列子模型的云端预报数据读取与缓存工具

aisky

aisky 是一个面向 aisky 系列子模型 的云端预报数据读取与缓存 Python 包。不同子模型的起报时制、步长规则、变量集合、URL 规则可能不同，因此以“模型客户端”形式提供能力。

from aisky import aisky

client = aisky(model="aisky-aerosol")
print(client.info().to_dict())

da = client.get_forecast(
    init_time="20260101_0130",
    step_hours=3,
    count=8,
    variable="TOTEXTTAU",
)
print(da)

一次取多个变量（返回 xarray.Dataset）：

from aisky import aisky

client = aisky("aisky-aerosol")
ds = client.get_forecast(
    "20260101_0130",
    step_hours=3,
    count=8,
    variable=["TOTEXTTAU", "DUEXTTAU"],
)
print(ds)

安装

pip install aisky

依赖：xarray, netCDF4, numpy, pandas, scipy。

快速开始（以 aisky-aerosol 为例）

1) 查看可用模型

import aisky

print(aisky.available_models())

2) 查看模型信息（时制/变量/规则）

from aisky import aisky

client = aisky("aisky-aerosol")
info = client.info()

print(info.cycle_times)
print(info.variables)

3) 读取预报

from aisky import aisky

client = aisky("aisky-aerosol")
da = client.get_forecast("20260101_0130", step_hours=3, count=8, variable="TOTEXTTAU")

4) 缓存到本地目录

store_dir 会以起报时刻创建子目录（例如 ./data/20260101_0130/）：

from aisky import aisky

client = aisky("aisky-aerosol")
da = client.get_forecast(
    "20260101_0130",
    count=8,
    variable="TOTEXTTAU",
    store_dir="./data",
)

API

aisky(model=...)

返回一个模型客户端对象，支持：

• client.info()：返回该子模型的元信息（起报时制、变量、规则、默认值等）
• client.get_forecast(...)：下载/缓存/读取该子模型数据

client.get_forecast(...)

• init_time: 起报时刻，支持 "YYYYMMDD_HHMM" 字符串、datetime、pandas.Timestamp
• step_hours: 步长（小时），由子模型规则约束（aisky-aerosol 必须是 3 的倍数）
• count: 预报场数量（>= 1；1 表示只取一个预报时刻）
• store_dir: 可选；如果提供，则以 store_dir/init_time/ 的形式落盘
• cache_dir: 可选；默认使用系统缓存目录（Windows 为 %LOCALAPPDATA%\\aisky\\cache）
• variable: 可选；要返回的变量名或变量列表（对 aisky-aerosol 必须来自 client.info().variables）
• engine: xarray.open_dataset 的引擎（默认 netcdf4）
• timeout: 下载超时（秒）
• retries: 下载重试次数
• overwrite: 是否覆盖已缓存的文件
• return_dataset: 是否直接返回 xarray.Dataset

更多示例见 docs/usage.md。

数据来源与 URL 规则

云端数据 URL 模板为（外部产品名称不依赖该路径命名）：

https://obs.cstcloud.cn/s/ai-gamfs/AI-GAMFS/forecast_data/{init}/AI_GAMFS.{init}+{valid}.V01.nc

其中 init 与 valid 都是 YYYYMMDD_HHMM。

许可证

MIT License，详见 LICENSE。