Kats-量化框架--0922

评论
10 views

Facebookresearch/Kats 完整项目架构设计文档

一、项目基础概述

1.1 项目定位

Kats（Kits to Analyze Time Series）是Meta（原Facebook）基础设施数据科学团队开源的一站式全流程时序分析Python框架，定位轻量、易上手、高可扩展，覆盖时序全链路任务：预测、异常/突变点检测、时序特征提取、多元时序分析，是业界首个打通时序多领域标准化API的综合库。 - 开源地址：https://github.com/facebookresearch/Kats - 许可证：MIT开源协议 - 开发语言：Python(59.4%) + Jupyter Notebook(40.4%)，少量辅助脚本 - 稳定版本：v0.2.0（2022-03-15），持续迭代兼容Python3.12 - 核心设计思想：统一数据抽象层 + 分层模块化解耦 + 标准化统一API + 元学习自动化调参

1.2 顶层分层架构总览

Kats采用五层垂直分层架构，自上而下依赖单向、低耦合，所有业务模块统一基于底层核心数据结构运行：

┌─────────────────────────────────────────────────────────┐
│  应用层：Tutorials、可视化、业务Demo、外部集成脚本        │
├─────────────────────────────────────────────────────────┤
│  业务能力层（四大核心模块）                              │
│   1. models 时序预测套件  2. detectors 时序检测器套件    │
│   3. tsfeatures 时序特征提取  4. multivariate 多元时序    │
├─────────────────────────────────────────────────────────┤
│  工具支撑层：utils通用工具、graphics绘图、simulator模拟器 │
├─────────────────────────────────────────────────────────┤
│  核心抽象层：consts 基础数据结构、通用常量、基类定义     │
├─────────────────────────────────────────────────────────┤
│  底层依赖层：Pandas/Numpy/Matplotlib/Prophet/Scikit-learn│
└─────────────────────────────────────────────────────────┘

二、源码目录结构完整拆解（仓库根目录）

facebookresearch/Kats/
├── .github/          # CI流水线、Issue模板、自动化配置
├── sphinx/           # 官方文档构建源码（API文档）
├── tutorials/        # 应用层：全场景可运行Jupyter教程
├── kats/             # 核心源码包（所有业务逻辑）
│   ├── consts/       # 核心抽象层：基础数据结构、全局基类
│   ├── models/       # 预测模块：所有时序预测模型集合
│   ├── detectors/    # 检测模块：异常、突变点、季节性检测器
│   ├── tsfeatures/   # 时序特征提取模块
│   ├── graphics/     # 绘图可视化工具
│   ├── multivariate/ # 多元时序分析工具
│   └── utils/        # 通用工具集（回测、调参、分解、模拟等）
├── .gitignore        # 版本忽略配置
├── CITATION.cff      # 论文引用规范
├── CODE_OF_CONDUCT.md # 社区行为规范
├── CONTRIBUTING.md   # 代码贡献指南
├── LICENSE           # MIT协议
├── README.md         # 项目总介绍
├── requirements.txt  # 完整依赖清单
├── test_requirements.txt # 测试依赖
├── setup.cfg/setup.py # Python包打包、安装配置（支持极简安装MINIMAL_KATS）

三、分层模块深度架构详解

3.1 第一层：核心抽象层 kats.consts（架构基石）

全局唯一标准数据入口，所有上层模块必须依赖此层，统一屏蔽Pandas底层差异，实现单变量/多变量时序标准化封装。

核心类与数据结构

  1. TimeSeriesData（最核心）
    • 作用：统一封装时序数据，兼容pd.DataFrame、pd.Series、DatetimeIndex
    • 约束：必须包含time时间列，其余列为观测值（单变量/多变量自动区分）
    • 内置能力：时间对齐、数据切片、时序拼接extend()、缺失值填充、绘图.plot()、转DataFrame、时间频率识别
    • 设计优势：全框架通用输入输出，任意模型/检测器只接收该对象，统一接口降低学习成本
  2. TimeSeriesChangePoint
    • 检测器输出标准结构体：存储突变点时间、置信度、变化幅度、对应检测器元信息
  3. 基础抽象基类
    • BaseModel：所有预测模型父类，强制统一fit()/predict()标准化API
    • BaseDetector：所有检测器父类，强制统一detector()检测接口
    • BaseParams：模型参数基类，统一超参数序列化、校验逻辑

3.2 第二层：四大核心业务能力层（框架核心功能）

模块1：kats.models 时序预测套件（17+预测模型，分层子包）

采用模型-参数分离设计：每个模型拆分为XXXModel（训练预测逻辑）+ XXXParams（超参数配置），完全解耦，支持批量调参。

models/
├── prophet/        # Facebook Prophet 分解预测模型
├── holtwinters/    # Holt-Winters 指数平滑
├── sarima/         # SARIMA季节性自回归
├── linear_model/   # 线性回归时序模型
├── lstm/           # 基础LSTM神经网络
├── theta/          # Theta平滑预测
├── stlf/           # STL时序分解预测
├── var/            # VAR向量自回归（多元时序预测）
├── harmonic_regression/ # 谐波回归
├── globalmodel/    # 大规模全局神经网络模型（架构核心亮点）
├── ensemble/       # 集成学习模块
│   ├── median_ensemble.py  # 中位数融合
│   ├── weighted_avg_ensemble.py # 加权平均融合
│   └── ensemble.py # 集成基类
├── metalearner/    # 元学习/自监督自动调参模块（工业级大规模优化）
│   ├── metalearner_hpt.py   # 自监督超参数调优（配套顶会论文）
│   ├── metalearner_modelselect.py # 自动推荐最优模型
│   └── get_metadata.py      # 并行时序元特征采集
└── reconciliation/ # 分层时序预测修正（层级数据对齐）
关键架构亮点
  1. GlobalModel 全局模型 专为大规模千万级时序设计，单个神经网络同时学习多条时序共享模式，解决传统单序列训练资源开销大的痛点，支持RNN/Seq2Seq两种网络结构。
  2. MetaLearner 元学习自监督调参 基于自研自监督框架，自动批量调优所有预测模型超参，并行执行，大幅降低工业场景大规模时序调参成本，配套40届国际预测研讨会收录论文。
  3. 统一预测流程规范（全模型通用5步标准Pipeline） ① 构造TimeSeriesData → ② 实例化XXXParams配置超参 → ③ 初始化XXXModel(ts_data, params) → ④ model.fit()训练 → ⑤ model.predict(steps, freq)预测输出

模块2：kats.detectors 时序检测套件（异常/突变/季节性识别）

统一继承BaseDetector基类，输出标准化TimeSeriesChangePoint结果，支持单变量/多变量时序检测。 核心检测器分类： 1. 突变点检测：CUSUMDetector（均值偏移）、MKDetector（曼肯德尔趋势突变） 2. 异常值检测：OutlierDetector（极值异常） 3. 趋势/季节性检测：ProphetTrendDetector、StatSigDetector（季节显著性检测） 4. 相似度检测：DTWDetector（动态时间规整匹配时序模式） 5. 高级工具：检测器评估器、检测结果优化器、人工合成异常注入模拟器

通用调用范式：

detector = CUSUMDetector(TimeSeriesData实例)
change_points = detector.detector() # 统一检测入口
detector.plot(change_points) # 统一可视化

模块3：kats.tsfeatures 时序特征提取引擎

核心类TsFeatures，一键输出65个具备严格统计定义的时序特征，分为趋势、季节性、分布、周期、时域统计五大类，输出字典可直接接入传统机器学习分类/回归模型，用于时序嵌入、样本筛选、元学习。 - 支持批量多条时序并行提取特征 - 可自定义开启/关闭指定特征计算，减少算力消耗

模块4：kats.multivariate 多元时序专用模块

针对多变量耦合时序（如多指标业务监控）提供专属工具：多元CUSUM检测、VAR建模、变量相关性分析、多变量时序分解。

3.3 第三层：工具支撑层 kats.utils + kats.graphics

3.3.1 kats.utils 通用底层工具（全框架共享依赖）

  1. backtesters.py：时序回测框架，统一MAE/MSE/RMSE、区间覆盖度等评估指标
  2. simulator.py：时序模拟器，生成带趋势/季节/突变/噪声的合成数据，用于算法验证
  3. decomposition.py：STL时序分解工具，拆分趋势项、季节项、残差项
  4. parameter_tuning_utils.py：通用网格/随机搜索调参工具，为MetaLearner提供底层能力
  5. emp_confidence_int.py：经验预测区间计算，补充模型概率输出
  6. cupik.py：分布式并行执行封装，适配大规模批量时序任务

3.3.2 kats.graphics 可视化层

统一封装Matplotlib绘图逻辑，为预测结果、突变点、特征分布提供开箱即用绘图API，无需手动处理坐标、时间轴、标注。

3.4 第四层：应用层 tutorials

面向终端用户的落地示例，覆盖全模块完整流程，是架构能力的落地验证： - kats_101_forecasting：基础预测入门 - kats_202_detection：异常突变检测全教程 - kats_203_tsfeatures：时序特征工程 - globalmodel_tutorial：大规模全局神经网络预测 - metalearner_hpt_tutorial：自动超参调参实战

四、核心架构设计特性与优势

4.1 统一抽象隔离，降低使用门槛

全框架仅一种输入数据结构TimeSeriesData，屏蔽Pandas时间处理、格式转换细节，预测、检测、特征提取共用一套数据标准，学习成本远低于Darts、Prophet等单一功能库。

4.2 完全模块化、可插拔扩展

  • 新增预测模型：仅需继承BaseModel、BaseParams，实现fit/predict方法即可无缝接入集成、元学习模块
  • 新增检测器：继承BaseDetector，实现detector()接口，自动支持绘图、评估工具
  • 极简安装模式：MINIMAL_KATS=1 pip install kats，裁剪测试/神经网络依赖，轻量部署

4.3 面向工业大规模时序的架构优化

  1. 元学习自动流水线：自监督超参调参+自动模型选择，解决海量时序人工调参难题
  2. GlobalModel全局神经网络：单模型批量拟合多条时序，降低分布式训练资源开销
  3. 并行工具封装：utils内置多进程执行，特征提取、模型调参支持并行加速
  4. 标准化回测评估：统一指标体系，批量对比多模型效果，适配生产监控迭代

4.4 全链路闭环设计

覆盖时序完整工作流：数据输入 → 特征分析 → 异常监控 → 多模型预测 → 集成融合 → 回测评估 → 批量自动调参，一站式完成业务时序分析，无需拼接多个第三方库。

五、完整数据流流转示例（标准预测Pipeline，体现分层调用关系）

graph LR
A[原始CSV/Pandas DataFrame] --> B[consts.TimeSeriesData 核心封装层]
B --> C1[utils.simulator/tsfeatures 工具层：特征探索/数据模拟]
B --> C2[detectors 检测层：突变/异常识别]
B --> D[models.XXXParams 超参数配置]
D --> E[models.XXXModel 预测业务层]
E --> E1[model.fit() 训练]
E1 --> E2[model.predict() 预测结果]
E2 --> F[utils.backtesters 回测评估工具]
E2 --> G[graphics 可视化绘图层]
E + B --> H[models.metalearner 元学习自动调参]
H --> E[优化后模型重新训练]

六、架构局限与版本设计取舍

  1. 轻量化取舍：不提供分布式存储、流数据实时计算能力，专注离线时序分析，需搭配Spark/Flink做实时流预处理
  2. 神经网络支持有限：内置LSTM、GlobalModel，不支持Transformer、DeepAR等复杂深度学习模型，复杂深度时序需额外集成
  3. v0.2.0稳定版后迭代节奏放缓：核心架构无大改动，以兼容性修复、Python新版本适配为主，底层分层架构长期稳定不变
  4. 依赖较重：完整安装包含Prophet、TensorFlow等，因此提供MINIMAL极简安装方案适配轻量化服务部署

Github

论文-Self-supervised learning for fast and scalable time series hyper-parameter tuning