本地文件查找（旧 API）

本地文件查找（旧 API）#

:::{important} 本页属于**旧 API（兼容层）**文档，介绍 reki.data_finder 命名空间下的 接口。这些接口保持可用，旧代码无需修改；新代码请使用 local 数据源 （见 CMA-HPC 业务文件查找（local 数据源））。新旧接口的对应关系见 新旧 API 对照。 :::

reki.data_finder.find_local_file() 按内置 YAML 配置文件，在多种存储 （CMA-HPC 主存储、二级存储、CEMC 共享存储）中依次查找业务系统产品 文件，找到即返回 pathlib.Path，全部目录都未找到时返回 None。

:::{note} 本页功能依赖 CMA-HPC 的共享文件系统与业务目录结构（或挂载了相应存储 的机器，如 CMADAAS 挂载盘），仅能在相应环境中运行。除 get_local_file_name() 示例外，本页代码块不参与文档构建执行， 输出为示意。 :::

基本用法#

from reki.data_finder import find_local_file

file_path = find_local_file(
    "cma_gfs_gmf/grib2/orig",
    start_time="2023122000",
    forecast_time="3h",
)
# PosixPath('/g1/COMMONDATA/OPER/NWPC/GRAPES_GFS_GMF/Prod-grib/2023122000/ORIG/gmf.gra.2023122000003.grb2')

常用参数：

  • data_type：数据类型，配置文件相对于配置根目录的路径（不含后缀）， 如 "cma_gfs_gmf/grib2/orig" 对应配置文件 {config_dir}/{data_class}/cma_gfs_gmf/grib2/orig.yaml

  • start_time：起报时次，字符串格式 YYYYMMDDHH，也接受 pd.Timestamp / datetime

  • forecast_time：预报时效，字符串（如 "3h"，由 pd.to_timedelta 解析）或 pd.Timedelta

  • data_level：存储级别过滤，默认 ("archive", "storage")，见下文

  • data_class：数据类别，选择配置子目录，默认 "od"（业务系统）

  • config_dir：自定义配置根目录，默认使用 reki 内置配置 （reki/data_finder/conf/）

  • obs_time：观测资料时间（观测类 data_type 使用）

  • debug：True 时打印模板渲染与逐级目录查找过程

  • **kwargs：配置文件模板中声明的自定义变量（如 storage_base、 number）

内置配置覆盖 CMA-GFS、CMA-MESO、CMA-GEPS、CMA-TYM、CMA-REPS 等业务 系统的 GRIB2 产品及中间文件，完整清单见 reki/data_finder/conf/ 目录。配置文件格式见 data_finder 配置文件。

存储级别（data_level）#

配置文件的 paths 列表中，每个目录条目都带有 level 字段 （archive / storage / runtime 等）。data_level 参数过滤参与 查找的目录条目，默认 ("archive", "storage") 即按配置顺序在归档与 二级存储中查找；传入 None 表示不过滤。

CMADAAS 挂载盘与 data_class#

在挂载了 CMADAAS 存储的机器上，使用 data_class="cmadaas" 选择 CMADAAS 配置，并用 storage_base 指定挂载根目录：

file_path = find_local_file(
    "cma_gfs_gmf/grib2/orig",
    start_time="2026072500",
    forecast_time="24h",
    data_class="cmadaas",
    storage_base="/CMADAAS",
)
# PosixPath('/CMADAAS/DATA/NAFP/NMC/GRAPES-GFS-GLB/2026/20260725/Z_NAFP_C_BABJ_20260725000000_P_NWPC-GRAPES-GFS-GLB-02400.grib2')

集合预报成员（number）#

配置文件模板中声明的自定义变量以关键字参数传入。CMA-GEPS 集合预报 需要用 number 指定成员编号（0 为控制预报，1–31 为集合成员）：

file_path = find_local_file(
    "cma_geps/grib2/orig",
    start_time="2026072500",
    forecast_time="24h",
    number=14,
    data_class="cmadaas",
    storage_base="/CMADAAS",
)

中间文件与其他产品#

data_type 不限于 GRIB2 产品，内置配置也包含模式输出的中间文件。 下面的示例查找 CMA-GFS 240 时效的模式面二进制文件：

file_path = find_local_file(
    "cma_gfs_gmf/bin/modelvar",
    start_time="2026072500",
    forecast_time="240h",
)

类似的还有 postvar（GrADS 格式后处理文件，配套 *_ctl 描述文件）、 观测准备文件（cma_gfs_gmf/obs/*）等。

仅渲染文件名：get_local_file_name()#

reki.data_finder.get_local_file_name() 只按配置渲染文件名， 不检查文件是否存在，因此不依赖任何数据环境：

import pandas as pd

from reki.data_finder import get_local_file_name

file_name = get_local_file_name(
    "cma_gfs_gmf/grib2/orig",
    start_time="2026081800",
    forecast_time=pd.to_timedelta("24h"),
)
file_name

'gmf.gra.2026081800024.grb2'

:::{note} get_local_file_name() 的 forecast_time 参数需要 pd.Timedelta 类型（不解析字符串），且不会把额外关键字参数注入模板变量—— 文件名模板中使用自定义变量（如 number）的配置会报错。 :::

调试（debug=True）#

传入 debug=True 打印渲染后的文件名与逐个尝试的目录路径， 用于排查配置或存储问题：

file_path = find_local_file(
    "cma_gfs_gmf/grib2/orig",
    start_time="2026072500",
    forecast_time="24h",
    data_class="cmadaas",
    storage_base="/CMADAAS",
    debug=True,
)

多文件查找：find_local_files()#

reki.data_finder.find_local_files() 与 find_local_file() 参数相近， 但按 glob 模式匹配，返回所有匹配文件的列表（无匹配时返回 None）：

from reki.data_finder import find_local_files

file_paths = find_local_files(
    "cma_gfs_gmf/grib2/orig",
    start_time="2026072500",
    forecast_time="24h",
)