本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 呼叫快取的運作方式
<a name="how-run-cache"></a>

若要使用呼叫快取，您可以建立執行快取，並將其設定為具有快取資料的關聯 Amazon S3 位置。當您開始執行時，您可以指定執行快取。執行快取並非專用於一個工作流程。從多個工作流程執行的 可以使用相同的快取。

在執行的匯出階段，系統會將完成的任務輸出匯出至 Amazon S3 位置。若要匯出中繼任務檔案，請在工作流程定義中將這些檔案宣告為任務輸出。呼叫快取也會在內部儲存中繼資料，並為每個快取項目建立唯一的雜湊。

對於執行中的每個任務，工作流程引擎會偵測此任務是否有相符的快取項目。如果沒有相符的快取項目，HealthOmics 會計算任務。如果有相符的快取項目，引擎會擷取快取的結果。

為了符合快取項目，HealthOmics 使用原生工作流程引擎中包含的雜湊機制。HealthOmics 延伸這些現有的雜湊實作，以考量 HealthOmics 變數，例如 S3 eTags 和 ECR 容器摘要。

HealthOmics 支援這些工作流程語言版本的呼叫快取：
+ WDL 1.0、1.1 版和開發版本
+ Nextflow 23.10 和 24.10 版
+ 所有 CWL 版本

**注意**  
HealthOmics 不支援 Ready2Run 工作流程的呼叫快取。

**Topics**
+ [共同責任模型](#run-cache-srm)
+ [任務的快取需求](#workflow-cache-task-prereqs)
+ [執行快取效能](#run-cache-performance)
+ [快取資料保留和失效事件](#workflow-cache-data)

## 共同責任模型
<a name="run-cache-srm"></a>

使用者和 之間的共同責任 AWS 是判斷任務和執行是否為呼叫快取的良好候選者。當所有任務都是等冪時，呼叫快取會獲得最佳結果 （使用相同輸入重複執行任務會產生相同的結果）。

不過，如果任務包含非確定性元素 （例如隨機數產生或系統時間），則使用相同輸入重複執行任務可能會導致不同的輸出。這可能會以下列方式影響呼叫快取的有效性：
+ 如果 HealthOmics 使用的快取項目 （由先前的執行所建立） 與任務執行為目前執行所產生的輸出不同，則執行可能會產生與相同執行不同的結果，而沒有快取。
+ HealthOmics 可能會因為非確定性任務輸出，而找不到應相符任務的相符快取項目。如果找不到有效的快取項目，則執行會不必要的重新計算任務，進而降低使用呼叫快取的成本節省效益。

以下是已知的任務行為，可能導致影響呼叫快取結果的非確定性結果：
+ 使用隨機數字產生器。
+ 取決於系統時間。
+ 使用並行 (race-conditions 可能會導致輸出差異）。
+ 擷取超出任務輸入參數中指定範圍的本機或遠端檔案。

如需可能導致非確定性行為的其他案例，請參閱 Nextflow 文件網站上的[非確定性程序輸入](https://www.nextflow.io/docs/latest/cache-and-resume.html#non-deterministic-process-inputs)。

如果您懷疑任務產生非確定性的輸出，請考慮使用工作流程引擎功能，以避免快取非確定性的特定任務。如需如何針對每個支援的工作流程語言中的個別任務選擇退出快取的說明，請參閱 [引擎特定的快取功能](workflow-cache-per-engine.md)。

我們建議您先徹底檢閱特定工作流程和任務需求，再在任何無效呼叫快取或輸出與預期不同的環境中啟用呼叫快取，這可能會帶來風險。例如，在判斷呼叫快取是否適合臨床使用案例時，應仔細考慮呼叫快取的潛在限制。

## 任務的快取需求
<a name="workflow-cache-task-prereqs"></a>

HealthOmics 會快取符合下列需求之任務的任務輸出：
+ 任務必須定義容器。HealthOmics 不會快取沒有容器之任務的輸出。
+ 任務必須產生一或多個輸出。您可以在工作流程定義中指定任務輸出。
+ 工作流程定義不得使用動態值。例如，如果您將參數傳遞給具有隨每次執行遞增值的任務，HealthOmics 不會快取任務輸出。

**注意**  
如果執行中的多個任務使用相同的容器映像，HealthOmics 會為所有這些任務提供相同的映像版本。HealthOmics 提取映像後，會在執行期間忽略容器映像的任何更新。此方法提供可預測且一致的體驗，並防止因中期部署的容器映像更新而產生的潛在問題。

## 執行快取效能
<a name="run-cache-performance"></a>

當您開啟執行的呼叫快取時，您可能會注意到下列對執行效能的影響：
+ 在第一次執行期間，HealthOmics 會儲存執行中任務的快取資料。此執行的匯出時間可能較長，因為呼叫快取會增加匯出資料的數量。
+ 在後續執行中，從快取繼續執行時，可能會縮短處理步驟的數量並縮短執行時間。
+  如果您也選擇將中繼檔案宣告為輸出，則匯出時間可能會更長，因為這些資料可能更為詳細。

## 快取資料保留和失效事件
<a name="workflow-cache-data"></a>

執行快取的主要目的是最佳化執行中任務的運算。如果任務有有效的相符快取項目，HealthOmics 會使用快取項目，而不是重新計算任務。否則，HealthOmics 會還原為預設服務行為，也就是重新計算任務及其相依任務。透過使用此方法，快取遺漏不會導致執行失敗。

我們建議您管理執行快取大小。隨著時間的推移，由於工作流程引擎或 HealthOmics 服務更新，或是您在執行或執行任務中所做的變更，快取項目可能不再有效。下列各節提供其他詳細資訊。

**Topics**
+ [資訊清單版本更新和資料新鮮度](#workflow-cache-data-versions)
+ [執行快取行為](#run-cache-behavior)
+ [控制執行快取大小](#workflow-cache-manage)

### 資訊清單版本更新和資料新鮮度
<a name="workflow-cache-data-versions"></a>

HealthOmics 服務可能會定期引入新功能或工作流程引擎更新，使部分或全部執行快取項目失效。在這種情況下，您的執行可能會遇到一次性快取遺漏。

HealthOmics 會為每個快取項目建立 [JSON 資訊清單檔案](workflow-cache-contents.md)。對於 2025 年 2 月 12 日之後開始的執行，資訊清單檔案包含版本參數。如果服務更新使任何快取項目失效，HealthOmics 會遞增版本編號，讓您可以識別要移除的舊版快取項目。

下列範例顯示 版本設定為 2 的資訊清單檔案：

```
{
     "arn": "arn:aws:omics:us-west-2:12345678901:runCache/0123456/cacheEntry/1234567-195f-3921-a1fa-ffffcef0a6a4",
     "s3uri": "s3://example/1234567-d0d1-e230-d599-10f1539f4a32/1348677/4795326/7e8c69b1-145f-3991-a1fa-ffffcef0a6a4",
     "taskArn": "arn:aws:omics:us-west-2:12345678901:task/4567891",
     "workDir": "/mnt/workflow/1234567-d0d1-e230-d599-10f1539f4a32/workdir/call-TxtFileCopyTask/5w6tn5feyga7noasjuecdeoqpkltrfo3/wxz2fuddlo6hc4uh5s2lreaayczduxdm",
     "files": [
         {
             "name": "output_txt_file",
             "path": "out/output_txt_file/outfile.txt",
             "etag": "ajdhyg9736b9654673b9fbb486753bc8"
         }
     ],
     "nextflowContext": {},
     "otherOutputs": {},
     "version": 2,       
  }
```

對於具有不再有效的快取項目的執行，請重建快取以建立新的有效項目。在每次執行時執行下列步驟：

1. 在快取保留設定為 CACHE ALWAYS 的情況下啟動一次執行。此執行會建立新的快取項目。

1. 對於後續執行，請將快取保留設定為其先前的設定 （一律為 CACHE 或 CACHE ON FAILURE)。

若要清除不再有效的快取項目，您可以從快取 Amazon S3 儲存貯體中刪除這些快取項目。HealthOmics 永遠不會重複使用這些快取項目。如果您選擇保留無效的項目，則不會影響執行。

**注意**  
呼叫快取會將任務輸出資料儲存在為快取指定的 Amazon S3 位置，這會產生 費用 AWS 帳戶。

### 執行快取行為
<a name="run-cache-behavior"></a>

您可以設定執行快取行為，為失敗的執行 （失敗時的快取） 或所有執行 （一律快取） 儲存任務輸出。當您建立執行快取時，您可以為使用此快取的所有執行設定預設快取行為。您可以在開始執行時覆寫預設行為。

**Cache on failure** 如果您要偵錯在數個任務成功完成後失敗的工作流程，則 很有用。如果雜湊考慮的所有唯一變數與先前執行相同，則後續執行會從上次成功完成的任務繼續。

**Cache always** 如果您在成功完成的工作流程中更新任務， 會很有用。我們建議您遵循下列步驟：

1. 建立新的執行。將**快取行為**設定為**一律快取**，然後開始執行。

1. 執行完成後，請更新工作流程中的任務，並**一律**以行為集快取開始新的執行。此執行會處理更新的任務，以及任何與更新任務相依的後續任務。所有其他任務都會使用快取的結果。

1. 視需要重複步驟 2，直到更新任務的開發完成為止。

1. 視需要在未來執行時使用更新的任務。如果您計劃在這些執行中使用新的或不同的輸入，請記得在**失敗時切換後續執行至快取**。

**注意**  
我們建議在使用相同測試資料集時**一律快取**模式，但不適用於執行批次。如果您針對大量執行設定此模式，系統可以將大量資料匯出至 Amazon S3，進而增加匯出時間和儲存成本。

### 控制執行快取大小
<a name="workflow-cache-manage"></a>

HealthOmics 不會刪除或自動封存任何執行快取資料，也不會套用 Amazon S3 清除規則來管理快取資料。我們建議您執行定期快取清除，以節省 Amazon S3 儲存成本，並保持您的執行快取大小可管理。您可以直接刪除檔案，或在執行快取儲存貯體上設定資料保留/複寫政策。

例如，您可以將 Amazon S3 生命週期政策設定為 90 天後使物件過期，也可以在每個開發專案結束時手動清除快取資料。

下列資訊可協助您管理快取資料大小：
+ 您可以檢查 Amazon S3 來檢視快取中有多少資料。HealthOmics 不會監控或報告快取大小。
+ 如果您刪除有效的快取項目，後續執行不會失敗。HealthOmics 會重新計算任務及其相依任務。
+ 如果您修改快取名稱或目錄結構，讓 HealthOmics 找不到任務的相符項目，HealthOmics 會重新計算任務。

如果您需要檢查快取項目是否仍然有效，請檢查快取資訊清單版本號碼。如需詳細資訊，請參閱[資訊清單版本更新和資料新鮮度](#workflow-cache-data-versions)。