Pandas API on Spark性能调优：从配置到索引的实战指南

我第一次把一段跑得好好的pandas代码搬到Spark集群上时，心里想的是“API兼容就行，改动应该不大”。结果一段groupby加join的任务，本地一分钟出头，在集群上跑完愣是用了二十多分钟。翻Spark UI才发现，问题根本不在API兼容性，而是Pandas API on Spark——也就是pyspark.pandas，从Koalas演进过来并并入PySpark的那套接口——有自己的一套配置选项系统、默认索引机制，以及跟单机pandas完全不同的性能调优逻辑。

这篇文章就围绕这三个点，把我这几年在Spark上跑pandas代码踩过的坑、调过的参数、以及可以直接抄作业的配置清单完整分享出来。适合三类人看：想把单机pandas脚本迁移到Spark集群上的数据分析师，正在用Pandas API on Spark但经常遇到慢查询或OOM的工程师，以及准备Spark面试想补一补pandas-on-Spark底层原理的同学。

1. 迁移前的账要算清：pandas代码上Spark，本质是在换执行引擎

很多人一开始接触Pandas API on Spark，都会被“几乎不用改代码”这个卖点吸引。确实，pyspark.pandas在API上做了大量兼容，groupby、merge、apply这些常用操作基本都能直接跑。但越是用得深，越要清楚一件事：你写出来的还是pandas风格，底层执行的却已经是Spark的分布式执行引擎。很多在单机pandas里理所当然的假设，到了分布式环境下都成了性能陷阱。

1.1 三条路线：PySpark原生DF、Pandas API on Spark、Spark SQL加toPandas

把一份原本跑在单机上的数据分析代码迁移到Spark，大体有三条路。

第一条是直接用PySpark原生DataFrame API，代码风格跟pandas有点接近但又不完全一样，比如df.groupBy("key").sum()、df.join(other, "key")。这条路性能最好，因为所有算子都映射到Spark的物理执行计划上，没有额外的兼容层。但缺点是重写成本高，尤其是有大量自定义函数、复杂切片、循环处理的脚本，改起来让人想放弃。

第二条就是Pandas API on Spark。它把Spark DataFrame包了一层pandas兼容的壳，让你继续写psdf.groupby("key").sum()、psdf[psdf["col"] > 0]这种代码。好处是迁移成本低，坏处是这个壳本身会引入额外的索引管理、隐式shuffle和计算开销。如果不懂底层机制，很容易写出“看起来没问题但跑起来很慢”的任务。

第三条是Spark SQL加toPandas()混合模式：核心数据清洗、聚合、join全部用SQL或原生DataFrame完成，只在最后把已经收敛得很小的结果集用toPandas()拉回本地做可视化或二次分析。这也是我最近两年最推荐给数据分析团队的模式。

1.2 一个典型场景：看似相同的API，性能为什么天差地别

举一个我实际遇到过的例子。某天线上跑一个任务，逻辑很简单：从一张5亿行的事件表里筛选出某个事件类型，按用户分组求和，再和用户维度表做关联。单机pandas跑1亿行已经够呛，所以一开始就放在Spark上跑，用的是Pandas API on Spark。

代码差不多是这样：

python复制import pyspark.pandas as ps

events = ps.read_parquet("hdfs://nameservice/data/events")
filtered = events[events["event_type"] == "click"]
agg = filtered.groupby("uid")["value"].sum().reset_index()
result = agg.merge(user_dim, on="uid", how="left")

本地小数据量测试一切正常，一上全量数据就卡死，跑了二十多分钟还没结束。当时我第一反应是“是不是groupby太慢了”，但后来看Spark UI，发现最耗时的根本不是groupby那个stage，而是前面一个和业务逻辑无关的mapPartitions阶段，里面还藏着一个collect动作。

这个collect就是默认索引机制在作祟。后面第三章我会细讲，但这里先给个结论：Pandas API on Spark为了模拟pandas的行索引语义，在创建DataFrame时会默认生成一个全局单调递增索引，而这个索引的生成过程会触发额外的Spark作业，在全量数据场景下代价极高。

所以你看，同一个API，在本地是pandas的向量化实现，在Spark上会变成一组分布式物理算子。真正需要调优的，往往不是API本身，而是API背后被隐藏起来的那些执行细节。

2. 配置选项系统：控制Pandas API on Spark行为的关键开关

Pandas API on Spark的性能调优，第一步不是改代码，而是搞清楚配置选项系统。它比原生Spark多了一层控制面，很多问题其实都是配置没设对导致的。

2.1 入口先分清：Spark conf与ps.set_option两套体系

这里要特别强调，pandas-on-Spark存在两套配置体系，作用范围和生效机制完全不一样。

第一套是Spark SQL的运行时配置，通过spark.conf.set()或spark-submit --conf传入，影响的是整个SparkSession的所有任务。比如Arrow开关、shuffle分区数、AQE这些，都属于这一层。

第二套是pandas-on-Spark自己的选项系统，通过ps.set_option()设置，只影响当前Python进程中pandas API层的执行逻辑。比如默认索引类型、shortcut_limit、是否允许跨DataFrame直接运算，都属于这一层。

我见过很多同事只调spark.sql.shuffle.partitions，完全没有意识到ps.set_option("compute.default_index_type", "distributed-sequence")这个选项对性能的影响更大。下面这张表可以帮助快速分清两套配置的职责：

这个区分为什么重要？因为如果你只是在spark-defaults.conf里配了Spark参数，而pandas API层的默认索引选项没动，性能瓶颈依然在。反过来也一样。

2.2 Arrow开关：SQL执行引擎与pandas之间最快的桥

在Pandas API on Spark的使用中，有一个配置对性能的影响立竿见影：spark.sql.execution.arrow.pyspark.enabled。

这个配置项默认是false。在默认情况下，PySpark把pandas DataFrame转成Spark内部的二进制行，走的是逐行Pickle序列化，效率低得可怜。而开启Arrow之后，Python和JVM之间传输的是一整块列式内存数据，相当于把“零散搬运”变成了“一卡车拉走”。

实际使用中，我建议在Session初始化时就打开：

python复制spark.conf.set("spark.sql.execution.arrow.pyspark.enabled", "true")
spark.conf.set("spark.sql.execution.arrow.pyspark.fallback.enabled", "true")

第一个参数开启Arrow优化，第二个参数设置当Arrow转换失败时回退到普通模式，避免因为个别不兼容类型导致整个任务失败。

什么时候这个配置影响最大？两种场景：一是用spark.createDataFrame(pandas_df)把大量pandas数据灌进Spark，二是用psdf.to_pandas()把结果拉回本地。这两条路径上，开启Arrow后性能提升往往在2到5倍甚至更高，因为省去了逐行反序列化的开销。

还要注意，Arrow模式下，列的数据类型映射和普通模式不完全一样。比如pandas的datetime64[ns]、category类型，在转换时可能会有精度或类型差异。我在生产环境就遇到过object类型列里有混合结构导致Arrow转换失败的情况，所以fallback.enabled一定要开，否则一个脏数据就能让整个任务挂掉。

2.3 compute下的选项：shortcut_limit、ops_on_diff_frames与pyarrow

除了Spark层配置，ps.set_option()下的几个compute选项也值得花时间理解。

compute.shortcut_limit默认是1000。这个选项的含义是：当DataFrame的行数小于等于该阈值时，pandas-on-Spark的某些操作会直接调用pandas本地执行，不启动Spark任务。这样做的原因是Spark任务本身有调度开销，小数据量走分布式反而更慢。

看起来这个值越大越好？不是的。我见过有人把这个值调到100万，结果某个操作触发了本地pandas执行，把所有数据拉到了driver端，直接把内存打爆。这个值要结合你的driver内存和数据量来定，一般建议保持默认，或者最多调到5000到10000，并且确保该路径下的数据量可控。

compute.ops_on_diff_frames默认是False，控制的是“两个不同的DataFrame直接进行算术运算或比较”是否被允许。比如df1 + df2这种操作，在pandas里是天然支持的，但在分布式环境下，两个DataFrame可能存储在不同的分区布局中，直接运算需要做隐式的行对齐，代价非常高。默认关闭这个选项，其实就是强制开发者写成显式的join/merge，避免写出看似简单实则爆炸的代码。

compute.use_pyarrow则是在pandas-on-Spark内部使用Arrow加速某些操作的开关。和Spark层的Arrow配置不同，它影响的是API层内部的实现。如果前置环境已经安装并启用了Arrow，可以打开它来加速concat、类型转换等操作。

另外提一下环境版本问题。如果你用的是Python 3.10，建议pandas用1.5.x以上版本，pyarrow用12以上的版本，PySpark用3.4或3.5，这样兼容性比较稳。我踩过一个坑：pyarrow版本升级到14之后，和PySpark 3.4的Cython扩展出现ABI不兼容，to_pandas()时直接崩溃。后来固定pyarrow版本才解决。所以别在一开始就把所有依赖都升到最新，稳定比新版本更重要。

3. 默认索引机制：最容易被忽视的性能拐点

这一章是整个配置系统里最隐蔽、也最影响性能的部分。可以这么说，十个pandas-on-Spark慢查询里，至少有三个和默认索引有关。

3.1 三种默认索引类型是怎么生成的

pandas DataFrame自带一个整数索引，用来定位行。单机环境下，这个索引就是数组的下标，不需要额外计算。但分布式环境下，数据被切分到了多个executor上，Spark本身没有“全局行号”这个天然概念。为了模拟pandas的索引语义，Pandas API on Spark必须人为地给每一行生成一个索引。

目前compute.default_index_type有三种可选值：sequence、distributed-sequence、distributed。

sequence是默认值，生成的是0、1、2这种全局单调递增的整数索引。这种索引最接近pandas原生的语义。但问题是，在分布式环境下生成全局连续整数，通常需要额外的Spark作业来统计每个分区的行数、分配ID区间，这个过程可能伴随大量的shuffle甚至collect。

distributed-sequence生成的是全局唯一、但不保证跨分区单调连续的索引。它的实现思路是用分区ID和分区内偏移量组合成一个唯一标识。这样避免了大规模收集和重排，生成代价小得多，绝大多数业务场景根本不需要索引在全局范围内连续。

distributed更轻量，只保证每个分区内部索引唯一递增，不保证全局唯一。相当于每个分片各自从0开始编号。

设置方法：

python复制import pyspark.pandas as ps

ps.set_option("compute.default_index_type", "distributed-sequence")

这个设置会全局影响当前Python进程中所有pandas-on-Spark DataFrame的索引生成方式。

3.2 sequence与distributed-sequence的实际开销差异

上面那段5亿行事件表的例子，我后来用不同索引类型做了对比。sequence默认模式下，任务额外多了一个stage，完成一次全量的索引分配，整体耗时增加了大约30%到40%。而改成distributed-sequence之后，那个多余的stage直接消失，任务时间回到了正常水平。

为什么sequence这么贵？因为它要生成一个全局连续的整数序列，而数据分布在几百个分区上，每个分区有多少行必须先统计出来，然后driver端统一分配区间，再分发回去。这个过程中只要有任何一个stage需要把所有数据凑到一起，整个任务的瓶颈就出现了。

更麻烦的是，sequence索引的维护是脆弱的。一旦你对DataFrame做了过滤、join或者重分区，索引可能需要重新生成，代价随之翻倍。

而distributed-sequence用分区ID加分区内序号的方式，天然不依赖全局协调，所以数据量再大，索引生成的额外开销也基本可控。

当然，如果你确实需要全局连续的行号，比如要把结果导出后按行号精确对账，那sequence语义是必要的。但那种场景建议用原生Spark的monotonically_increasing_id()自己控制，而不是依赖pandas API的默认行为。

3.3 索引与分组、排序、去重的联动关系

索引不只是创建DataFrame时的一次性开销，它和后续很多操作都有联动关系，这是新手比较容易忽略的。

举个例子，sort_index()在单机pandas里是一个轻量操作，但在分布式环境下，如果当前索引是sequence类型，执行全局排序就要把数据重新shuffle一遍，开销很大。如果索引类型是distributed-sequence，跨分区本来就没有全局顺序，sort_index()的语义会变得很模糊，执行效果和你预期的可能完全不同。

再比如drop_duplicates()。pandas的去重默认保留第一个出现的行，但在分布式环境下，哪个“第一个”取决于数据在哪个分区先被处理，结果可能不稳定。如果你用了非全局唯一的distributed索引，“第一个”的语义就更不可控了。所以做去重场景，我建议明确指定subset列，并且换成distributed-sequence索引，让结果具备良好的可预期性。

还有groupby之后的reset_index()，这是一个高频操作。你会发现，当索引类型是sequence时，reset_index()往往伴随着一次全局重新编号，耗时明显。这也是为什么很多人在做groupby(...).sum().reset_index()的时候觉得慢——里面藏了两次索引处理。

我现在的经验是，涉及索引敏感的操作，尽早显式处理索引列。比如可以先psdf.reset_index()把索引变成普通列，再按业务键去重或排序，别让默认索引的语义干扰你的业务逻辑。

4. 性能调优实操：从读取到shuffle的整条链路

配置和索引是底子，底子打好了，再谈具体的调优链路。我一般把一条pandas-on-Spark任务的性能分成四段：数据读取、分区与shuffle、算子选择、内存与序列化。每一段都有对应的调优手段。

4.1 读入优化：parquet与feather该怎么选，谓词下推与列裁剪

数据读取是整条链路的起点，也是很多人忽视的地方。

先说文件格式。Parquet是分布式场景下的首选，这个结论基本没有争议。原因有三：一是自带schema，Spark可以直接利用；二是列式存储天然支持列裁剪，只读取你需要的列；三是文件内嵌统计信息，filter条件能下推到文件扫描层面，跳过大量无关数据块。

还有一个关键点，Parquet在Spark里是原生数据源，有专门的优化reader，配合向量化读取，性能很稳。

Feather（也就是Arrow IPC格式）的优势在于单机场景的读写极快，内存映射方式让pandas、polars这些工具之间的数据交换非常高效。但它不适合作为Spark上的主要存储格式：Spark没有原生的feather数据源，你需要先用pandas读进来，再spark.createDataFrame()灌入Spark，这一步会受到driver内存限制，而且feather文件在分布式文件系统上缺失谓词下推所需的统计信息，全量读入的成本很高。

有同事问过我：“那我在pandas里用feather快，在Spark里也用feather行不行？”我的回答是，如果数据量在百万行以下，怎么折腾都行；到亿级别，feather这条路基本走不通，除非你只是把parquet读成feather做单机分析。

实际代码建议这样写：

python复制# 分布式场景：直接读parquet，并做列裁剪
psdf = ps.read_parquet(
    "hdfs://nameservice/data/events",
    columns=["uid", "event_type", "value", "dt"]
)

# 单机feather数据，需要先转成Spark DataFrame再转pandas-on-Spark
import pandas as pd
pdf = pd.read_feather("data.feather")
psdf = spark.createDataFrame(pdf).to_pandas_on_spark()

读取时尽量用columns参数做列裁剪，配合后续的过滤条件，让Spark在文件扫描层面就跳过不必要的列和数据块。比如events[events["event_type"] == "click"]这种条件，Spark会对parquet文件做谓词下推，大幅减少读取的数据量。

4.2 分区与AQE：让Spark自己学会合并和拆分

分区数的设置直接影响shuffle阶段的性能。spark.sql.shuffle.partitions默认是200，这个值不是万能的。数据量小的时候，200个reduce端分区会产生大量小任务，调度开销占比过高；数据量大的时候，200个分区又可能让单个分区处理几GB数据，内存压力大。

处理这类问题，我现在的首选方案是开AQE，也就是Adaptive Query Execution。Spark 3.0之后默认开启，它会根据运行时的实际数据量动态调整shuffle分区数、自动合并小分区、甚至把倾斜的join动态拆分成多个任务。

在pandas-on-Spark场景下，AQE的价值尤其明显。因为pandas API层很多操作会触发隐式shuffle，比如set_index、reset_index、groupby、merge，这些shuffle的阶段性结果你很难提前预估分区数是否合理。AQE能帮你兜底。

建议显式打开以下配置：

python复制spark.conf.set("spark.sql.adaptive.enabled", "true")
spark.conf.set("spark.sql.adaptive.coalescePartitions.enabled", "true")
spark.conf.set("spark.sql.adaptive.skewJoin.enabled", "true")

coalescePartitions会在reduce阶段结束后，自动把过小的分区合并，减少小文件数量。skewJoin专门处理数据倾斜——比如某个用户ID的行数特别多，导致单个reduce任务处理几亿条数据，其他任务都在空转。这个开关打开之后，Spark会把倾斜的分区拆成多个小任务分别处理，再合并结果，对长尾任务的改善非常明显。

另外，中间结果如果会被多次复用，可以考虑缓存：

python复制psdf.spark.cache()
# 用完之后记得释放
psdf.spark.unpersist()

我在实际项目中见过一种情况：同一个过滤后的DataFrame，后面被join了三次、groupby了两次，每次都在重复计算前面的链路。这个时候spark.cache()能省下的时间非常可观。

4.3 算子优化：什么时候用apply_batch，什么时候该回退到Spark原生算子

pandas代码迁移到Spark后，最容易出性能问题的就是各种apply调用。

在单机pandas里，df.apply(func, axis=1)是逐行处理，虽然慢，但数据量小还能忍。在Spark里，逐行apply意味着每个分区、每一行都要经过一轮Python函数回调，再加上序列化和数据传输，性能直接跳崖。

如果非要用apply，优先考虑apply_batch。它和逐行apply的区别是，每个分区只调用一次函数，函数收到的是一个pandas DataFrame，你在这个DataFrame上做批量逻辑，再返回结果。这样能大幅减少Python和JVM之间的往返次数。

比如这样：

python复制def add_ratio(pdf):
    pdf["ratio"] = pdf["value"] / pdf["value"].sum()
    return pdf

psdf = psdf.groupby("key").apply_batch(add_ratio)

但这里要泼一盆冷水：apply_batch虽然比逐行apply快，但本质上还是一个自定义的groupby-apply过程，会触发shuffle。能用内置聚合解决的问题，永远优先用内置聚合，比如psdf.groupby("key").value.mean()、cumsum()、rank()这些，底层都有优化过的物理执行计划。

还有一种情况，某个复杂操作在pandas API层怎么写都别扭，性能也上不去。这时候我的做法是回退到Spark原生算子：psdf.to_spark()转成Spark DataFrame，用原生groupBy、join、selectExpr处理完，再to_pandas_on_spark()转回来。不要觉得这样“不优雅”，在性能面前，混用是正常的工程手段。

4.4 内存与序列化：避免OOM的最后一公里

内存问题几乎是每个把pandas代码搬上Spark的人都会遇到的。我见过的OOM大致分两类。

第一类是driver端OOM，最常见的原因是to_pandas()把全量数据拉回本地。比如一个亿级别的DataFrame，你直接to_pandas()，driver就废了。正确处理方式是：能聚合先聚合，能过滤先过滤，只把结果集拉回来。如果确实需要全量数据，比如导出一张宽表给运营跑报表，那也应该按分区或按日期分批拉取，用pd.concat拼装，而不是一次collect到位。

第二类是executor端OOM。常见诱因包括sequence索引生成时的全局协调、groupby聚合时单个value的列表特别大、apply_batch返回了超大对象。遇到executor OOM，首先看Spark UI里哪个stage的shuffle read最大，找到数据倾斜或数据量集中的点。

针对数据倾斜，AQE的skewJoin能解决一部分问题，但如果是groupby本身倾斜，可能还需要从业务上拆key。我处理过一个案例：某头部用户ID占全表30%的数据，导致聚合阶段单个executor被打爆，后来把key加上一个随机后缀进行两阶段聚合，先部分聚合再汇总，问题才解决。

还有序列化层。Spark默认的Java序列化性能一般，建议开启Kryo：

python复制spark.conf.set("spark.serializer", "org.apache.spark.serializer.KryoSerializer")

对于pandas-on-Spark来说，Kryo主要优化的是Spark内部对象传输，配合Arrow优化Python侧的转换路径