本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 呼叫缓存的工作原理
<a name="how-run-cache"></a>

要使用呼叫缓存，您需要创建运行缓存并将其配置为与缓存数据关联的 Amazon S3 位置。开始运行时，需要指定运行缓存。运行缓存不是专用于一个工作流程的。从多个工作流程运行可以使用同一个缓存。

在运行的导出阶段，系统会将已完成的任务输出导出到 Amazon S3 位置。要导出中间任务文件，请在工作流定义中将这些文件声明为任务输出。呼叫缓存还会在内部保存元数据，并为每个缓存条目创建唯一的哈希值。

对于运行中的每个任务，工作流引擎都会检测该任务是否有匹配的缓存条目。如果没有匹配的缓存条目，则 HealthOmics 计算任务。如果有匹配的缓存条目，引擎将检索缓存的结果。

要匹配缓存条目，请 HealthOmics 使用本机工作流引擎中包含的哈希机制。 HealthOmics扩展了这些现有的哈希实现以考虑 HealthOmics 变量，例如 S3 ETag 和 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 由于任务输出不确定，可能找不到本应匹配的任务的匹配缓存条目。如果找不到有效的缓存条目，则运行会不必要地重新计算任务，从而降低使用呼叫缓存节省成本的好处。

以下是已知的任务行为，这些行为可能导致影响呼叫缓存结果的不确定性结果：
+ 使用随机数生成器。
+ 依赖于系统时间。
+ 使用并发（竞争条件可能导致输出差异）。
+ 获取超出任务输入参数中指定范围的本地或远程文件。

有关可能导致非确定性行为的其他场景，请参阅 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. 在缓存保留设置为 “始终缓存” 的情况下开始运行一次。此运行会创建新的缓存条目。

1. 对于后续运行，请将缓存保留期设置为以前的设置（“始终缓存” 或 “失败时缓存”）。

要清理不再有效的缓存条目，您可以从 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 存储成本并保持运行缓存大小易于管理。您可以直接删除文件或在运行缓存存储桶上设置数据 retention/replication 策略。

例如，您可以将 Amazon S3 生命周期策略配置为在 90 天后使对象过期，也可以在每个开发项目结束时手动清理缓存数据。

以下信息可以帮助您管理缓存数据大小：
+ 您可以通过查看 Amazon S3 来查看缓存中有多少数据。 HealthOmics 不监控或报告缓存大小。
+ 如果删除有效的缓存条目，则后续运行不会失败。 HealthOmics 重新计算任务及其相关任务。
+ 如果您修改了缓存名称或目录结构， HealthOmics 导致找不到任务的匹配条目，则会 HealthOmics 重新计算任务。

如果您需要检查缓存条目是否仍然有效，请检查缓存清单版本号。有关更多信息，请参阅 [清单版本更新和数据新鲜度](#workflow-cache-data-versions)。