spark-optimization

spark-optimization 技能總覽

spark-optimization 是做什麼用的

spark-optimization 技能是一份專門用來診斷並改善 Apache Spark 工作效能的聚焦指南。它最適合用在：你的 pipeline 功能上已經能正常運作，但執行速度太慢、spill 很嚴重、shuffle 過多、出現資料傾斜，或是在規模放大後成本明顯升高的情況。它不是提供泛泛的「讓 Spark 變快」建議，而是依照 Spark 的執行模型來組織優化思路：jobs、stages、tasks、partitions、memory，以及 shuffle 行為。

哪些人適合用這個 spark-optimization 技能

這個技能很適合資料工程師、分析工程師、平台團隊，以及需要實際協助處理 Spark SQL 或 PySpark 效能調校的 agent 使用者。若你能提供一些 workload 背景資訊，例如 join 型態、資料量、partition 數、executor 設定，或 Spark UI 中觀察到的症狀，效果會特別好。即使你是初學者，它仍然有幫助；只是相較於空泛提問，它更適合搭配具體的 job 細節一起使用。

真正要解決的工作問題

多數使用者其實不是抽象地想「優化 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 的安裝背景

這個技能位於 wshobson/agents repository 的：

plugins/data-engineering/skills/spark-optimization

如果你的 skill runner 支援直接從 GitHub 安裝，常見做法是：

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

如果你的環境使用的是其他安裝方式，就從該 repository 加入 skill，並選擇 spark-optimization 這個 slug。從 repository 目前可見的內容來看，只有 SKILL.md，所以你可以預期這個技能是以文件指引為主，而不是由輔助 script 或參考檔案支撐。

先讀這個檔案

先從這裡開始：

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

由於這個技能看不到額外的支援 scripts、rules 或 references，多數價值都在於把主要的優化框架仔細讀懂。不要預期它會自動幫你檢查 Spark UI 或叢集狀態；執行期的事實與觀察，還是要由你提供。

這個技能要吃到哪些輸入才會發揮效果

spark-optimization 的使用品質，很大程度取決於你提供的細節。以下這些輸入都很有幫助：

• 使用的 Spark API：PySpark DataFrame、Spark SQL、Scala Spark、streaming、batch
• 資料規模：row counts、file counts、partition sizes、成長模式
• 叢集規模：executor memory、cores、executor 數量、autoscaling 行為
• 症狀：task skew、shuffle read 很長、spill、OOM、stragglers、GC pauses
• 查詢型態：joins、aggregations、UDFs、window functions、repartitioning
• 儲存格式：Parquet、Delta、Iceberg、CSV、JSON
• Spark UI 觀察：慢的 stage IDs、shuffle size、task 分布、input size
• 目前設定：spark.sql.shuffle.partitions、broadcast thresholds、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 能讓技能有足夠證據去推理 broadcast joins、資料傾斜、partition sizing，以及 shuffle 壓力等問題。

一套實用的 spark-optimization 工作流程

一個好的工作流程通常是：

1. 描述 workload 與症狀。
2. 分享 Spark UI 中慢速 stage 的特徵。
3. 要求先做 bottleneck 排序，而不是隨機丟一串 tuning tips。
4. 要求分層提出修改建議：
   • query/code changes
   • partitioning changes
   • join strategy changes
   • memory/config changes
5. 先套用最小、但高信心的修正。
6. 重新執行並比較 stage-level 行為。

這樣可以讓 spark-optimization guide 保持在可量測的結果上，而不是落入照單全收的 cargo-cult tuning。

這個技能最擅長的地方

從 repository 文字內容來看，它明顯聚焦在這幾個面向：

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

實務上，這代表它特別適合拿來處理 batch 效能問題，尤其是當 stage 結構與資料搬移才是真正主要成本來源時。

有哪些內容值得你明確要求它輸出

你可以直接要求這個技能產出容易落地的結果，例如：

• bottleneck hypothesis table
• 建議的 config changes 與預期效果
• 可能的 skew 點，以及怎麼驗證
• 是否適合使用 broadcast join
• repartition 還是 coalesce 比較適合
• cache 或 persist 建議，並附上理由
• transformations 中的 anti-patterns

這比起要求一份泛用的「best practices list」要有效得多。

根據 repository 內容，最值得聚焦的主題

根據目前可見的 source，最值得在 prompt 中點名的方向包括：

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

這些都是這個技能明確圍繞的核心概念，所以在提問時直接點出來，通常更容易得到對齊的輸出。

用於 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 top 3 changes by expected impact, explain why each helps in Spark’s execution model, and note any tradeoffs or validation steps.

這種寫法通常比單純說「improve performance」更能產出可做決策的內容。

spark-optimization 技能 FAQ

沒有 Spark UI 資料，spark-optimization 還有用嗎

有用，但結果的可靠性會比較低。這個技能仍然可以根據程式碼結構、join 規模、檔案布局與叢集設定來推理。不過，如果你想對資料傾斜、shuffle 熱點或記憶體壓力得到更有把握的建議，Spark UI 的證據會顯著提升回答品質。

這個 spark-optimization 技能適合初學者嗎

適合，前提是你已經懂 Spark 的基本概念。這個技能會透過 jobs、stages、tasks、partitions 與 shuffle 行為來解釋優化邏輯，對中階使用者特別有助於快速進階。若是完全初學者，可能還是需要先補一點 Spark 入門知識，後續建議才會更容易實作。

什麼情況不該用 spark-optimization

如果問題本質其實是下面這些，就不建議把 spark-optimization 當成主要工具：

• 商業邏輯錯誤
• 上游來源資料品質不佳
• orchestration 失敗
• storage layer 故障
• 引擎外部、與 Spark 無關的瓶頸

如果你完全無法提供任何執行期事實，只是想拿一份泛用 tuning checklist，它也不是很適合。

這和一般 Spark 建議有什麼差別

一般 prompt 常常只會吐出很寬泛的建議，例如「多用 cache」、「增加 partitions」或「使用 broadcast joins」。如果你想要的是一套以診斷為核心的流程，先判斷哪個槓桿最該優先處理、原因是什麼，並用 Spark 執行概念來串起來，而不是零散技巧，那麼 spark-optimization install 是值得考慮的選擇。

這個技能能取代 benchmarking 嗎

不能。它可以提升你提出假設與建議修改的品質，但你仍然需要做前後測試。Spark 優化高度依賴 workload；某些改動可能改善某個 stage，卻讓另一個 stage 變差。

如何改善 spark-optimization 技能的使用效果

提供症狀，不要只給目標

要提升 spark-optimization 的使用效果，最快的方法就是把抽象目標換成具體症狀，例如：

• 「stage 14 有 2 個 tasks 跑了 12 分鐘，其他 tasks 40 秒就結束」
• 「groupBy 之後 shuffle read 來到 600 GB」
• 「executors 在 sortMergeJoin 期間 spill 到磁碟」
• 「每日輸入量從 200 GB 增加到 900 GB 後，job 明顯變慢」

這些線索能讓技能直接對應到資料傾斜、partitioning、memory 或 shuffle 等可能原因。

提供造成瓶頸的程式碼形狀

你不需要把整個專案都貼上來。通常只要一小段能看出以下內容的摘錄就夠了：

• joins
• aggregations
• repartition calls
• cache 或 persist usage
• Python UDFs
• file reads and writes

Spark 效能問題很多時候從 transformation 的形狀就看得出來，不只是 config 的問題。

要求依優先順序排序建議

一種很常見的失敗情況，是你收到十個建議，卻完全不知道先做哪個。你可以要求技能依下列標準排序修正方案：

1. 預期效能影響
2. 實作成本
3. 營運風險

這會迫使輸出更聚焦，也更容易實際採納。

對每個建議都要求驗證步驟

好的 spark-optimization guide 使用方式，一定包含驗證。你可以要求技能說明如何確認每個修正是否真的有效，例如：

• shuffle read/write 是否下降
• task durations 是否更平均
• spills 是否減少
• GC time 是否降低
• stages 是否變少
• input partition balance 是否更好

這能避免落入「憑經驗傳說調參」的情況。

先講清楚限制條件，建議才會實際

請明確說出你的限制，例如：

• 不能增加 cluster size
• 不能改寫成 Scala
• 必須保留目前 table format
• latency target 已固定
• broadcast join 可用記憶體有限
• 這個 sprint 只能做 config changes

當技能知道哪些事情不能動，它給出的建議會實用得多。

拿到第一輪 spark-optimization 輸出後要再迭代

第一輪分析之後，請帶著以下資訊再回來一次：

• 哪些地方改了
• 哪些地方改善了
• 哪些地方變差了
• 更新後的 Spark UI 觀察

這時候這個技能才會真正變得有價值。Spark 優化本來就是迭代式過程；下一步最好的動作，往往取決於前一個改動帶來的副作用。

留意 spark-optimization 常見失準情況

最常見的低品質結果，通常都發生在使用者：

• 問優化問題時完全沒提供 workload 細節
• 忽略資料傾斜，只盯著 executor memory
• 在沒有重複使用證據時過度 cache 大型資料集
• 盲目修改 partition 數量
• 把每個 join 都當成 broadcast 候選
• 還沒處理昂貴的 transformations，就先調 config

如果你想得到更好的結果，請讓技能根據證據推理，而不是根據泛用偏好下結論。