Monitoring¶

特征监控、模型监控和报警摘要。

mars.monitoring.MarsMonitor ¶

Bases: MarsBaseEstimator

特征/模型监控器。

监控器复用分箱评估链路，生成 PSI、缺失率、分箱占比和已表现样本上的风险指标。它提供通用指标计算能力，不承担调度、看板和业务处置职责。

示例：

>>> import polars as pl
>>> from mars.monitoring import MarsMonitor
>>> df = pl.DataFrame(
...     {
...         "month": ["2026-01", "2026-01", "2026-02", "2026-02"],
...         "score": [0.1, 0.8, 0.2, 0.9],
...         "target": [0, 1, 0, 1],
...     }
... )
>>> report = MarsMonitor(binner_params={"n_bins": 2}).monitor(
...     df,
...     features=["score"],
...     target="target",
...     group_col="month",
... )
>>> report.features
['score']

init ¶

__init__(*, binning_type: Literal['native', 'optimal', 'lite_opt'] = 'native', binner_params: Dict[str, Any] | None = None, bin_stat_metrics: List[str] | None = None, psi_include_missing: bool = False, psi_include_special: bool = False) -> None

初始化监控器。

参数：

名称	类型	描述	默认
`binning_type`	`Literal['native', 'optimal', 'lite_opt']`	未显式传入分箱器时使用的分箱策略。`"lite_opt"` 需要标签；无标签分布监控建议使用 `"native"`。	`'native'`
`binner_params`	`Dict[str, Any] \| None`	构造默认分箱器时使用的参数。	`None`
`bin_stat_metrics`	`List[str] \| None`	需要展开为分箱趋势表的统计指标。	`None`
`psi_include_missing`	`bool`	计算 PSI 时是否包含缺失值箱。	`False`
`psi_include_special`	`bool`	计算 PSI 时是否包含特殊值箱。	`False`

引发：

类型	描述
`ValueError`	当 `binning_type` 不是 `native`、`optimal` 或 `lite_opt` 时抛出。

monitor ¶

monitor(df: FrameLike, *, features: List[str], target: str | None, binner: MarsBinnerBase | None = None, benchmark_df: FrameLike | None = None, feature_data_source: Dict[str, List[str]] | None = None, group_col: str | None = None, time_col: str | None = None, time_grain: str | None = None, weights_col: str | None = None, batch_size: int = 100, trend_column_order: TrendColumnOrder = 'asc', psi_include_missing: bool | None = None, psi_include_special: bool | None = None) -> MarsMonitoringReport

执行一次特征或模型分监控。

参数：

名称	类型	描述	默认
`df`	`FrameLike`	待监控样本表。	必需
`features`	`List[str]`	本次监控的特征、模型分或概率列。	必需
`target`	`str \| None`	目标变量列名。传入时非空值必须为 `0`、`1`、`True` 或 `False`；空值表示尚未到表现期。为 `None` 时只输出无标签分布监控。	必需
`binner`	`MarsBinnerBase \| None`	显式复用的分箱器。	`None`
`benchmark_df`	`FrameLike \| None`	外部 benchmark 样本。	`None`
`feature_data_source`	`Dict[str, List[str]] \| None`	特征来源映射。	`None`
`group_col`	`str \| None`	已存在的分组列名。	`None`
`time_col`	`str \| None`	原始日期列名。	`None`
`time_grain`	`str \| None`	时间聚合粒度。	`None`
`weights_col`	`str \| None`	样本权重列名。	`None`
`batch_size`	`int`	批量评估时的特征批大小。	`100`
`trend_column_order`	`TrendColumnOrder`	趋势宽表中时间或分组取值列的展示顺序；`"asc"` 保持从早到晚， `"desc"` 则从晚到早。`Total` 列如存在会固定在最后。	`'asc'`
`psi_include_missing`	`bool \| None`	本次监控计算 PSI 时是否纳入缺失值箱；`None` 表示沿用实例默认值。	`None`
`psi_include_special`	`bool \| None`	本次监控计算 PSI 时是否纳入特殊值箱；`None` 表示沿用实例默认值。	`None`

返回：

类型	描述
`MarsMonitoringReport`	单次监控结果对象。

引发：

类型	描述
`ValueError`	当特征列、target 列或 target 取值不满足监控要求时抛出。

mars.monitoring.MarsMonitoringReport `dataclass` ¶

单次特征或模型监控结果。

该对象不承担文件导出职责，只保存可二次加工的结构化数据。模型分、概率列或评分列会作为特殊特征进入同一套监控链路。

属性：

名称	类型	描述
`summary_table`	`DataFrame`	特征级监控汇总表。
`detail_table`	`DataFrame`	分箱明细表。
`trend_tables`	`dict of str to DataFrame`	PSI、缺失率、坏账率等指标趋势表。
`missing_by_day_table`	`DataFrame or None`	按日缺失率趋势表。
`bin_stat_table`	`DataFrame`	全量分箱统计表。
`bin_stat_trend_tables`	`dict of str to DataFrame`	每个分箱随时间或分组变化的统计趋势。
`target_observation_table`	`DataFrame or None`	target 表现覆盖情况表。
`binner`	`MarsBinnerBase`	本次监控使用的分箱器。
`features`	`list of str`	本次监控覆盖的特征列表。
`target`	`str or None`	本次监控使用的目标变量列名。
`metadata`	`dict`	本次运行的上下文信息。

get_monitoring_data ¶

get_monitoring_data() -> MarsMonitoringData

返回监控报告的底层结构化数据。

返回：

类型	描述
`MarsMonitoringData`	汇总、明细、趋势、分箱统计和 target 表现覆盖表集合。

示例：

>>> import polars as pl
>>> from mars.feature import MarsNativeBinner
>>> report = MarsMonitoringReport(
...     summary_table=pl.DataFrame(),
...     detail_table=pl.DataFrame(),
...     trend_tables={},
...     missing_by_day_table=None,
...     bin_stat_table=pl.DataFrame(),
...     bin_stat_trend_tables={},
...     target_observation_table=None,
...     binner=MarsNativeBinner(),
...     features=[],
...     target=None,
...     metadata={},
... )
>>> report.get_monitoring_data().trends
{}

mars.monitoring.MarsMonitoringData ¶

Bases: NamedTuple

监控报告底层数据对象集合。

属性：

名称	类型	描述
`summary`	`DataFrame`	特征级监控汇总表。
`detail`	`DataFrame`	分箱明细表。
`trends`	`dict of str to DataFrame`	指标趋势表字典。
`missing_by_day`	`DataFrame or None`	按日缺失率趋势表。
`bin_stat`	`DataFrame`	全量分箱统计表。
`bin_stat_trends`	`dict of str to DataFrame`	分箱统计指标趋势表字典。
`target_observation`	`DataFrame or None`	target 表现覆盖情况表。

mars.monitoring.MarsMonitoringAlertConfig `dataclass` ¶

监控报警阈值配置。

属性：

名称	类型	描述
`psi_warn`	`float`	PSI 警告阈值。
`psi_critical`	`float`	PSI 严重阈值。
`missing_delta_warn`	`float`	缺失率跨期变化警告阈值。
`missing_delta_critical`	`float`	缺失率跨期变化严重阈值。
`bin_pct_delta_warn`	`float`	分箱占比跨期变化警告阈值。
`bin_pct_delta_critical`	`float`	分箱占比跨期变化严重阈值。
`bad_rate_delta_warn`	`float`	坏账率跨期变化警告阈值。
`bad_rate_delta_critical`	`float`	坏账率跨期变化严重阈值。
`risk_corr_warn`	`float`	风险趋势相关性警告阈值。
`risk_corr_critical`	`float`	风险趋势相关性严重阈值。
`target_observed_rate_warn`	`float`	target 表现覆盖率警告阈值。
`target_observed_rate_critical`	`float`	target 表现覆盖率严重阈值。
`score_mean_relative_delta_warn`	`float`	模型分均值相对变化警告阈值。
`score_mean_relative_delta_critical`	`float`	模型分均值相对变化严重阈值。
`max_items_per_priority`	`int`	每个优先级最多输出的报警条数。

mars.monitoring.MarsMonitoringAlerter ¶

Bases: MarsBaseEstimator

监控报警文本生成器。

该组件只消费 MarsMonitoringReport 中已有的结构化数据，不重新计算分箱。若报告缺少某类表或字段，对应检查会跳过并写入文本末尾的数据跳过说明。报警器会读取报告元数据中的趋势列顺序，用于识别模型分均值趋势和 target 覆盖率的基准期、最新期。

示例：

>>> import polars as pl
>>> from mars.feature import MarsNativeBinner
>>> from mars.monitoring import MarsMonitoringReport, generate_monitoring_alert
>>> report = MarsMonitoringReport(
...     summary_table=pl.DataFrame({"feature": ["score"], "psi_max": [0.0]}),
...     detail_table=pl.DataFrame(),
...     trend_tables={},
...     missing_by_day_table=None,
...     bin_stat_table=pl.DataFrame(),
...     bin_stat_trend_tables={},
...     target_observation_table=None,
...     binner=MarsNativeBinner(),
...     features=["score"],
...     target=None,
...     metadata={},
... )
>>> "MARS 监控报警摘要" in generate_monitoring_alert(report, score_key="score", model_features=[])
True

init ¶

__init__(config: MarsMonitoringAlertConfig | None = None) -> None

初始化监控报警器。

参数：

名称	类型	描述	默认
`config`	`MarsMonitoringAlertConfig \| None`	报警阈值配置；不传时使用默认阈值。	`None`

generate ¶

generate(report: MarsMonitoringReport, *, score_key: str, model_features: List[str]) -> str

基于监控报告生成中文报警文本。

参数：

名称	类型	描述	默认
`report`	`MarsMonitoringReport`	监控模块生成的结构化报告。	必需
`score_key`	`str`	模型分、概率或评分字段名。	必需
`model_features`	`List[str]`	模型使用的特征列表。	必需

返回：

类型	描述
`str`	按优先级排序的中文报警文本。

mars.monitoring.generate_monitoring_alert ¶

generate_monitoring_alert(report: MarsMonitoringReport, *, score_key: str, model_features: List[str], config: MarsMonitoringAlertConfig | None = None) -> str

生成监控报警文本的轻量函数入口。

参数：

名称	类型	描述	默认
`report`	`MarsMonitoringReport`	监控模块生成的结构化报告。	必需
`score_key`	`str`	模型分、概率或评分字段名。	必需
`model_features`	`List[str]`	模型使用的特征列表。	必需
`config`	`MarsMonitoringAlertConfig \| None`	报警阈值配置；不传时使用默认阈值。	`None`

返回：

类型	描述
`str`	按优先级排序的中文报警文本。

示例：

>>> import polars as pl
>>> from mars.feature import MarsNativeBinner
>>> from mars.monitoring import MarsMonitoringReport, generate_monitoring_alert
>>> report = MarsMonitoringReport(
...     summary_table=pl.DataFrame({"feature": ["score"], "psi_max": [0.2]}),
...     detail_table=pl.DataFrame(),
...     trend_tables={},
...     missing_by_day_table=None,
...     bin_stat_table=pl.DataFrame(),
...     bin_stat_trend_tables={},
...     target_observation_table=None,
...     binner=MarsNativeBinner(),
...     features=["score"],
...     target=None,
...     metadata={},
... )
>>> "警告" in generate_monitoring_alert(report, score_key="score", model_features=[])
True

Monitoring¶

mars.monitoring.MarsMonitor ¶

__init__ ¶

monitor ¶

mars.monitoring.MarsMonitoringReport dataclass ¶

get_monitoring_data ¶

mars.monitoring.MarsMonitoringData ¶

mars.monitoring.MarsMonitoringAlertConfig dataclass ¶

mars.monitoring.MarsMonitoringAlerter ¶

__init__ ¶

generate ¶

mars.monitoring.generate_monitoring_alert ¶

init ¶

mars.monitoring.MarsMonitoringReport `dataclass` ¶

mars.monitoring.MarsMonitoringAlertConfig `dataclass` ¶

init ¶