Pandas groupby.apply调用不稳定导致reset_index报列已存在错误

根因说明 #

• 该问题触发的核心是Pandas 1.3.0~1.5.x版本的已知不稳定bug，和分类变量的observed=True参数逻辑相关：你用来分组的A/B/C列都是分类变量，当分类变量的元数据（比如类别列表）存在极轻微的对齐异常（常见于批量读取parquet等二进制格式、或并行加载数据的场景）时，Pandas会误判所有分组均为空，此时apply不会调用你写的fn函数，而是直接返回一个继承了原DF所有列名（包含A/B/C/X）的空DF。
• 后续执行reset_index(level=cols)时，你尝试把索引中的A/B/C列恢复为普通列，但空DF中已经存在同名的A/B/C列，直接触发cannot insert C, already exists报错。
• 随机复现的原因是分类变量元数据的对齐异常本身是极小概率事件，所以相同输入会出现有时成功、有时失败的表现。

解决方案 #

你可以根据自己的业务需求任选一种方案修复：

1. 最稳妥的兼容方案：先把所有分组用的分类变量转成字符串类型，彻底消除分类元数据的不稳定影响，修改后代码如下：

def do_things(df: pd.DataFrame):
  cols = ["A","B","C"]
  df = df.copy()
  # 统一转分组列为字符串，规避分类变量元数据问题
  for col in cols:
    df[col] = df[col].astype(str)
  return (
    df.groupby(cols, observed=True)
      .apply(fn)
      .reset_index(level=cols)
  )

2. 保留分类变量的兼容方案：在apply执行后先判断结果是否为空，手动构造符合预期结构的空DF再执行reset_index，代码如下：

def do_things(df: pd.DataFrame):
  cols = ["A","B","C"]
  grouped = df.groupby(cols, observed=True)
  res = grouped.apply(fn)
  if res.empty:
    # 手动构造空DF，仅保留fn返回的统计列，避免列名冲突
    res = pd.DataFrame(columns=["mean", "sd", "median"], index=pd.MultiIndex.from_tuples([], names=cols))
  return res.reset_index(level=cols)

3. 版本升级方案：把Pandas升级到2.0及以上版本，该空组误判的bug已经在2.0版本正式修复，升级后不会再随机出现fn不调用的问题。

内容的提问来源于stack exchange，提问作者Jess The Witch