spark-optimization

spark-optimization 技能概览

spark-optimization 是用来做什么的

spark-optimization 是一个专门用于诊断和提升 Apache Spark 作业性能的技能。它最适合用在这样的场景：你的 pipeline 在功能上已经跑通，但执行速度过慢、频繁 spill、shuffle 过多、存在数据倾斜，或者在数据规模上来后成本迅速升高。它不是给出一套泛泛的“如何让 Spark 更快”的建议，而是围绕 Spark 的执行模型来组织优化思路：jobs、stages、tasks、partitions、memory，以及 shuffle 行为。

谁适合使用这个 spark-optimization 技能

这个 skill 很适合数据工程师、分析工程师、平台团队，以及需要对 Spark SQL 或 PySpark 做性能调优的 agent 用户。尤其当你能提供一些 workload 上下文时，它的效果会更好，比如 join 模式、数据规模、partition 数量、executor 配置，或者来自 Spark UI 的异常现象。如果你是初学者，它同样有帮助，但前提是最好能结合具体作业细节，而不是只给一个空泛的请求。

用户真正想解决的问题

大多数用户并不是抽象地想“优化 Spark”，他们真正想回答的问题通常是：

• 为什么这个 join stage 明显比其他 stage 慢得多？
• 为什么 executors 一直 spill，或者直接因为 OOM 挂掉？
• 为什么数据量上来之后，这条 pipeline 变慢了？
• 我到底该 repartition、cache、broadcast，还是调整 executor 配置？
• 在不改业务逻辑的前提下，怎样降低 shuffle 成本？

spark-optimization 的价值在于，它会把这些问题当成可以诊断的性能问题来分析，而不是停留在代码风格层面的泛泛建议。

它和通用 prompt 有什么不同

通用模型 prompt 往往会一次性罗列所有常见 Spark 调优技巧。相比之下，spark-optimization skill 更适合一种更收敛的工作流：先理解执行行为，再选择正确的调优杠杆。它最突出的差异在于，强调 partition 策略、shuffle 缩减、内存调优，以及用 Spark 执行模型解释“为什么这个改动会有效”。

如何使用 spark-optimization 技能

spark-optimization 的安装上下文

这个 skill 位于 wshobson/agents 仓库中的：

plugins/data-engineering/skills/spark-optimization

如果你的 skill runner 支持直接从 GitHub 安装，常见方式是：

npx skills add https://github.com/wshobson/agents --skill spark-optimization

如果你的环境使用别的安装方式，就从该仓库添加这个 skill，并选择 spark-optimization 这个 slug。根据仓库里目前能看到的内容，只有 SKILL.md，因此可以预期它主要是文档驱动的指导，而不是依赖辅助脚本或参考文件。

先读这个文件

先从这里开始：

• plugins/data-engineering/skills/spark-optimization/SKILL.md

由于这个 skill 看不到额外的脚本、规则或参考资料，大部分价值都在于认真阅读它的主优化框架。不要期待它会自动帮你检查 Spark UI 或集群状态；运行时事实需要你自己提供。

让这个技能发挥作用需要哪些输入

spark-optimization usage 的输出质量，非常依赖你提供的信息是否足够具体。高价值输入包括：

• 使用的 Spark API：PySpark DataFrame、Spark SQL、Scala Spark、streaming、batch
• 数据规模：行数、文件数、partition 大小、增长趋势
• 集群形态：executor memory、cores、executor 数量、autoscaling 行为
• 症状：task 倾斜、shuffle read 很长、spill、OOM、straggler、GC pause
• 查询模式：joins、aggregations、UDFs、window functions、repartitioning
• 存储格式：Parquet、Delta、Iceberg、CSV、JSON
• Spark UI 观察结果：慢 stage 的 ID、shuffle 大小、task 分布、输入规模
• 当前配置：spark.sql.shuffle.partitions、broadcast 阈值、serializer

如果缺少这些信息，模型基本就只能退回到泛化建议。

如何把模糊目标变成高质量 prompt

较弱的 prompt：

Optimize my Spark job.

更强的 prompt：

Use the spark-optimization skill to diagnose a slow PySpark batch job. It reads 1.2 TB of Parquet, joins a 1.2 TB fact table with a 20 MB dimension table and a 40 GB history table, then aggregates by customer and day. The slowest stage shows high shuffle read and a few tasks run 10x longer than others. Cluster: 20 executors, 8 cores each, 32 GB memory each. Current spark.sql.shuffle.partitions=200. Suggest likely bottlenecks, code-level fixes, and config changes in priority order, with tradeoffs.

这个 prompt 给了 skill 足够多的证据，能够围绕 broadcast join、数据倾斜、partition 大小和 shuffle 压力进行推理。

一套实用的 spark-optimization 工作流

一套更稳妥的使用方式是：

1. 描述 workload 和症状。
2. 提供 Spark UI 里慢 stage 的特征。
3. 让它输出“瓶颈优先级排序”，而不是随机罗列调优建议。
4. 按层次请求修改建议：
   • query/code 改动
   • partitioning 改动
   • join strategy 改动
   • memory/config 改动
5. 先应用最小、且置信度最高的修复。
6. 重新运行，并按 stage 级别对比行为变化。

这样可以让 spark-optimization guide 始终围绕可度量的结果展开，而不是陷入“别人都这么调”的经验主义。

这个技能最擅长什么

从仓库文本来看，这个 skill 的重点非常明确，主要集中在：

• partitioning strategy
• caching choices
• shuffle optimization
• memory tuning
• scaling Spark pipelines
• reducing data skew

落到实际使用上，这意味着它最适合处理 batch 性能问题，尤其是那些主要成本来自 stage 结构和数据移动的场景。

你应该明确要求它输出什么

建议直接让这个 skill 产出便于落地的内容，例如：

• 一张 bottleneck hypothesis table
• 推荐的配置改动及其预期效果
• 可能存在的数据倾斜点和验证方法
• 是否适合使用 broadcast join
• repartition 和 coalesce 哪个更合适
• cache 或 persist 建议，并说明理由
• 你的 transformations 中有哪些 anti-pattern

这比单纯要求一份通用的“best practices list”要有效得多。

基于仓库内容，prompt 应重点聚焦哪些主题

从可见源码来看，在 prompt 里优先点名以下主题，通常最容易得到对路的输出：

• Spark execution model
• key performance factors
• shuffle minimization
• data skew handling
• serialization choices
• memory pressure reduction
• partition right-sizing

这些都是该 skill 明确围绕的核心概念，因此在提问时直接点出来，更容易得到结构一致、方向对口的回答。

用于 Performance Optimization 的 spark-optimization 实用 prompt 模板

可以使用这样的 prompt：

Use the spark-optimization skill for Performance Optimization. Analyze this Spark job for shuffle, skew, memory, and partition issues. Here is the job summary: [pipeline description]. Here are the slow stages and Spark UI symptoms: [details]. Here is current cluster config: [details]. Here is a simplified code excerpt: [code]. Recommend the