Python 库 aequitas-lib 详解

一、功能概述

aequitas-lib 是一个专注于算法公平性（Algorithmic Fairness）评估与审计的 Python 库，旨在帮助开发者和研究者检测机器学习模型在不同人口统计学群体（如性别、种族、年龄等）中的偏见，量化公平性指标，并提供可视化分析工具。其核心功能包括：

• 计算多种公平性指标（如统计 parity、均等机会、均等准确率等）。
• 支持对模型预测结果按敏感属性（如性别、种族）分组分析。
• 提供公平性评估报告和可视化图表（如群体差异热力图、指标对比图）。
• 兼容常见的机器学习工作流（与 scikit-learn、pandas 等库无缝集成）。

二、安装方法

aequitas-lib 可通过 PyPI 安装，命令如下：

pip install aequitas

注意：部分功能依赖 plotly 进行可视化，若需绘图功能，需额外安装：

pip install plotly

三、核心语法与参数

aequitas-lib 的核心工作流围绕 Aequitas 类展开，主要步骤包括：数据准备 → 公平性指标计算 → 结果分析与可视化。

1. 数据准备

输入数据需包含以下关键列：

• score：模型预测分数或标签（如分类结果）。
• label_value：真实标签（用于计算准确率等指标）。
• 敏感属性列（如 gender、race 等，用于分组）。

2. 核心类与方法

• Aequitas().analyze()：计算公平性指标。

  • 参数：
    • df：包含 score、label_value 和敏感属性的 DataFrame。
    • score_cols：预测分数列名（默认 'score'）。
    • label_col：真实标签列名（默认 'label_value'）。
    • sensitive_attrs：敏感属性列表（如 ['gender', 'race']）。
  • 返回：包含各群体公平性指标的 DataFrame。

• Aequitas().visualize()：可视化公平性结果。

  • 参数：
    • metrics：需可视化的指标（如 ['statistical_parity', 'equal_opportunity']）。
    • group_metrics：是否按群体分组显示（默认 True）。

四、8个实际应用案例

案例1：基础公平性指标计算

检测二分类模型在“性别”维度上的公平性：

import pandas as pd
from aequitas.preprocessing import preprocess_input_df
from aequitas.group import Group
from aequitas.bias import Bias

# 准备数据：包含score（预测）、label_value（真实标签）、gender（敏感属性）
data = pd.DataFrame({
    'score': [1, 0, 1, 0, 1, 1],
    'label_value': [1, 0, 1, 1, 0, 1],
    'gender': ['M', 'F', 'M', 'F', 'M', 'F']
})

# 预处理
processed_df = preprocess_input_df(data)

# 计算群体指标（如准确率、召回率）
g = Group()
group_metrics = g.get_group_metrics(processed_df, ['gender'])

# 计算公平性指标（如统计 parity 差异）
b = Bias()
bias_metrics = b.get_disparity_metrics(group_metrics, original_df=data, ref_group_names={'gender': 'M'})

print(bias_metrics[['attribute_name', 'attribute_value', 'statistical_parity_disparity']])

案例2：多敏感属性联合分析

同时分析“性别”和“种族”对模型公平性的影响：

data = pd.DataFrame({
    'score': [1,0,1,0,1,1,0,1],
    'label_value': [1,0,1,1,0,1,0,0],
    'gender': ['M','F','M','F','M','F','M','F'],
    'race': ['A','B','A','B','B','A','A','B']
})

processed_df = preprocess_input_df(data)
g = Group()
group_metrics = g.get_group_metrics(processed_df, ['gender', 'race'])  # 多敏感属性
print(group_metrics[['gender', 'race', 'precision']])  # 查看各群体准确率

案例3：统计 parity 公平性评估

统计 parity 要求不同群体的阳性预测率（PPR）相等：

# 接案例1的group_metrics
b = Bias()
# 以男性（M）为参考群体，计算女性（F）的统计 parity 差异
disparity = b.get_disparity_metrics(
    group_metrics, 
    ref_group_names={'gender': 'M'},
    metrics=['ppr']  # 阳性预测率
)
print(disparity[['attribute_value', 'ppr', 'ppr_disparity']])

案例4：均等机会公平性评估

均等机会要求不同群体的真阳性率（TPR）相等：

# 接案例1的group_metrics
disparity = b.get_disparity_metrics(
    group_metrics,
    ref_group_names={'gender': 'M'},
    metrics=['tpr']  # 真阳性率
)
print(disparity[['attribute_value', 'tpr', 'tpr_disparity']])

案例5：公平性可视化（热力图）

用热力图展示不同群体的公平性指标差异：

from aequitas.plotting import Plot

# 接案例2的group_metrics
p = Plot()
fig = p.disparity(
    bias_metrics,
    metrics=['precision', 'recall'],
    attribute_name='gender'
)
fig.show()  # 显示热力图（需plotly支持）

案例6：模型对比（不同模型的公平性差异）

比较两个模型在“年龄”维度上的公平性：

# 模型1数据
model1 = pd.DataFrame({'score': [1,0,1,0], 'label_value': [1,0,0,1], 'age': ['<30', '>=30', '<30', '>=30']})
# 模型2数据
model2 = pd.DataFrame({'score': [1,1,0,0], 'label_value': [1,0,0,1], 'age': ['<30', '>=30', '<30', '>=30']})

# 分别计算公平性指标
g1 = Group().get_group_metrics(preprocess_input_df(model1), ['age'])
g2 = Group().get_group_metrics(preprocess_input_df(model2), ['age'])

# 对比TPR差异
b1 = Bias().get_disparity_metrics(g1, ref_group_names={'age': '<30'}, metrics=['tpr'])
b2 = Bias().get_disparity_metrics(g2, ref_group_names={'age': '<30'}, metrics=['tpr'])

print("模型1 TPR差异：\n", b1[['age', 'tpr_disparity']])
print("模型2 TPR差异：\n", b2[['age', 'tpr_disparity']])

案例7：阈值调整对公平性的影响

分析分类阈值变化如何影响不同群体的公平性：

# 生成不同阈值下的预测结果
data = pd.DataFrame({
    'prob': [0.8, 0.6, 0.3, 0.7, 0.2, 0.9],  # 模型概率输出
    'label_value': [1,1,0,1,0,1],
    'race': ['A','B','A','B','A','B']
})

thresholds = [0.5, 0.6, 0.7]
for thresh in thresholds:
    data['score'] = (data['prob'] >= thresh).astype(int)  # 按阈值生成标签
    processed = preprocess_input_df(data)
    group_metrics = Group().get_group_metrics(processed, ['race'])
    disparity = Bias().get_disparity_metrics(group_metrics, ref_group_names={'race': 'A'}, metrics=['ppr'])
    print(f"阈值={thresh}时的PPR差异：\n", disparity[['race', 'ppr_disparity']])

案例8：公平性报告生成

生成包含所有指标的完整公平性报告：

from aequitas.report import Report

# 接案例1的bias_metrics
r = Report()
# 生成HTML报告（保存到本地）
r.generate_report(
    bias_metrics,
    group_metrics,
    output_path='fairness_report.html',
    title='模型公平性审计报告'
)

五、常见错误与使用注意事项

常见错误

1. 数据格式错误

   • 错误：输入DataFrame缺少score或label_value列。
   • 解决：确保数据包含模型预测结果（score）和真实标签（label_value）。

2. 敏感属性值为空

   • 错误：敏感属性列存在NaN值，导致分组失败。
   • 解决：用df.dropna(subset=['sensitive_attr'])处理缺失值。

3. 参考群体不存在

   • 错误：ref_group_names指定的群体在数据中不存在。
   • 解决：通过df['sensitive_attr'].unique()确认群体值。

4. 可视化依赖缺失

   • 错误：调用visualize()时提示plotly未安装。
   • 解决：安装plotly：pip install plotly。

注意事项

1. 敏感属性定义：需明确哪些属性属于敏感信息（如法律规定的种族、性别等），避免遗漏关键维度。
2. 群体样本量：若某一群体样本量过小，公平性指标可能不可靠，需在报告中注明。
3. 公平性指标选择：不同场景需关注不同指标（如贷款模型需关注均等机会，招聘模型需关注统计 parity）。
4. 参考群体选择：参考群体应具有代表性（如多数群体），且需在分析中明确说明选择依据。
5. 结果解读：公平性指标差异需结合业务场景解读，并非“差异为0”就是最优解（需权衡公平性与模型性能）。

通过 aequitas-lib，开发者可以系统地评估模型偏见，为公平性优化提供数据支持，尤其适用于金融、医疗、招聘等对公平性要求严格的领域。

《AI提示工程必知必会》为读者提供了丰富的AI提示工程知识与实战技能。《AI提示工程必知必会》主要内容包括各类提示词的应用，如问答式、指令式、状态类、建议式、安全类和感谢类提示词，以及如何通过实战演练掌握提示词的使用技巧；使用提示词进行文本摘要、改写重述、语法纠错、机器翻译等语言处理任务，以及在数据挖掘、程序开发等领域的应用；AI在绘画创作上的应用，百度文心一言和阿里通义大模型这两大智能平台的特性与功能，以及市场调研中提示词的实战应用。通过阅读《AI提示工程必知必会》，读者可掌握如何有效利用AI提示工程提升工作效率，创新工作流程，并在职场中脱颖而出。