Chronometrica 与 Topaz Sharingan：如何处理缺失的 YouTube 转录记录

根据应用需要解释的结果来选择

Actor 是一种托管的数据采集程序。应用向它提供输入，运行它，然后读取结果。结果约定规定了应用可以预期收到什么。

对于转录文本提取，成功结果只是这份约定的一部分。应用还需要一条规则，用于处理未产生转录文本的输入。这条规则会影响向用户显示的消息，以及应用接下来采取的操作。

一则开发者公开提问描述了本地成功后，在生产环境遇到失败、请求受阻、结果为空，以及重试行为不明确的问题。该提问涉及另一个 Python 转录库。它说明了清楚易懂的结果为何重要，但没有提供关于本文所比较的任何一个 Actor 的测试证据。

先确定应用面向用户需要做出的决定：

来源：Chronometrica 结果约定、Topaz Sharingan 结果约定。

当较简单的接口约定能满足全部需求时，就选择它。当应用必须区分不同结果，并据此采取操作时，就选择详细的接口约定。这样，选择依据就是应用行为，而不是未经证实的“哪项服务更少失败”的说法。

同时查看 Chronometrica 的成功记录和失败详情

Chronometrica 在默认数据集的每一行中，存放 1 个成功获取转录文本且不重复的 YouTube 视频。数据集就是这些结果记录的集合。失败的输入不会成为数据集中的成功记录行，也不会成为计费的转录记录行。单独的 `OUTPUT` 汇总会报告运行信息，并且可以包含 `failedInputDetails`。Chronometrica 接口约定。

当你读取到的记录数较少时，这种区分很重要。数据集的记录数少于输入列表中的条目数，不能证明所有输入都已成功。它只说明当前有哪些成功的转录记录。对于没有产生记录的输入，你还必须检查所报告的结果。

将 `includeFailedInputDetails` 保持为 `true`。文档列出的失败详情包括安全的输入标识、`errorCategory`、`errorCode` 和 `isRetryable`。类别用于按失败类型分组。错误码提供更具体、可供程序读取的值。重试标志表示所报告的失败是否可以重试。Chronometrica 输入架构、结果约定。

应用可以利用这些详情，建立涵盖全部已提交输入的视图。将每条成功转录记录或失败输入详情与相应的输入标识匹配。不要按记录在列表中的位置进行匹配。只要缺少一条成功记录，按位置关联输入和结果就不可靠。

区分源结果与应用显示的消息。结果记录查询所报告的情况。显示消息则向用户解释该结果。这样，你可以调整措辞，而不改变已存储的观察记录。

单独判断所需语言是否可用

运行任一工作流程前，先确定应用是否要求特定的字幕语言。可用的转录文本不仅要包含文字，还必须满足这一要求。

填写 Chronometrica 的 `preferredLanguages` 设置后，系统会严格遵循该设置。如果请求的语言不可用，Actor 会返回 `LANGUAGE_UNAVAILABLE`，不会在不告知的情况下选择其他语言。此设置不会翻译字幕。Chronometrica 读取平台已有的公开字幕，不提供语音转文字后备方案。Chronometrica 接口约定、输入架构。

如果应用必须向用户提供他们所请求语言的字幕，这种行为就适合该应用。它也明确了一项限制：即使视频有其他语言的字幕，也可能仍不满足应用的要求。

不要仅因存在某些字幕文本，就把这种结果标为成功获取转录文本。将请求的语言与输入记录保存在一起。这样，应用就能解释：未找到满足请求的字幕。

如果用户可以接受其他语言，请在扩展工作流程前，先在应用中明确这一选择。语言要求改变，就意味着请求改变。应将其与原始请求的重试区分开。有关字幕可用性的更多说明，请参阅 YouTube 字幕提取指南。

逐步分析一组虚构的记录缺失情况

以下示例为虚构示例。它不是实际运行、基准测试或客户结果。

某应用提交了 8 个不重复的视频 ID，并指定了字幕语言。5 个视频有可用字幕。1 个没有公开字幕。1 个没有所请求语言的字幕。还有 1 个发生访问失败，返回的标志将其标记为可重试。

对于这组虚构输入，可用字幕的占比为：

`5 / 8 × 100 = 62.5%`

该计算仅描述这组虚构输入，不能用来估计任何一个 Actor 的实际成功率。

按照 Chronometrica 文档说明的结果结构，应用会读取到 5 行成功转录记录和 3 条失败输入详情。应用不会在成功转录数据集中添加 3 行虚构的失败记录。随后，应用可以显示 5 条转录记录和 3 个尚未解决的结果。Chronometrica 结果约定。

这些尚未解决的结果需要不同的消息。应用可以解释，其中 1 次查询未找到公开字幕，另 1 次未找到所请求语言的字幕。对于访问失败，应用可以说明，已计划进行有次数限制的重试，因为返回的标志为这一决定提供了依据。

只有被该标志标记的情况才进入重试队列。应用不会重试所有缺少成功数据集记录行的输入。可重试标志为再次尝试提供依据，但不保证该次尝试会成功。

如果应用之后重试该输入，就会记录一个新结果。它会保留首次观察记录，使记录仍能显示每次尝试发生了什么。

这个示例可用于实际检验选择规则。如果应用需要这些不同的消息和重试队列，就选择详细的接口约定。如果全部需求只是一个允许为 null 的转录文本值，较简单的接口约定可能就能满足需求。

用少量输入检查结果约定

在添加更多输入前，先做一次小规模检查，可以确认应用能否读取文档说明的记录。这不能证明生产环境的可靠性。

以下 JSON 使用文档公开列出的输入字段。URL 用于展示输入格式，并不保证该视频目前有字幕内容，也不保证会得到特定结果。请将其替换为相关的公开来源。

{
  "startUrls": [
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  ],
  "includeFailedInputDetails": true
}

这些字段的说明见 Chronometrica 输入架构。一个公开 Task 示例也提供了相关的起点。Task 是已保存的输入预设。输入架构中的示例和 Task 链接，都不能证明本指南已完成过一次运行。

按以下简短方法检查工作流程：

1. 确定输入和验收规则。建立不重复的视频列表。记录所有必需的语言要求。确定什么样的字幕文本算作可用，以及未返回可用转录文本时，应用应显示什么。
2. 保持启用失败详情。提交少量公开输入，并将 `includeFailedInputDetails` 设为 `true`。确认应用可以读取成功结果的数据集，以及单独的 `OUTPUT` 结果。
3. 将结果与输入匹配。使用文档说明的输入标识，将结果关联到请求。对照成功记录与失败输入详情。不要把记录数较少的数据集视为已提交列表的完整情况。
4. 检查如何处理失败。读取返回的失败字段。将与字幕可用性有关的结果，与明确标为可重试的情况区分开。不要仅因缺少转录文本，就推断可以重试。
5. 采用有次数上限的重试策略。在应用中设置最大尝试次数。只重试符合条件的情况。保留每次尝试的观察记录，并在达到上限时停止。
6. 如实显示最终状态。如果重试结束后仍未获得转录文本，就让该输入保持未解决状态。不要将缺失的文本变成一条空的成功记录，也不要暗示再试一次就能获取到文本。

如果在应用已读取的内容中，某个输入既没有匹配的成功记录，也没有匹配的失败详情，就应保留这种不确定性。检查运行信息和读取结果的代码。不要为了让数量一致而编造结果。

当应用能说明所接收记录的情况，并做出预期的面向用户的决定时，检查就算成功。无需为每个提交的视频都生成转录文本，也能证明读取结果的方法有效。

添加更多输入前，先设置重试上限

重试队列是应用计划再次提交的输入列表。它在这里的用途很明确：为符合条件的失败输入提供次数有限的再次尝试机会，同时保留清楚的记录。

在扩充列表前，先确定尝试次数上限。如果没有上限，即使后续尝试全都失败，可重试的失败也可能一直循环。明确的停止规则还能让应用告知用户，自动尝试何时已经结束。

在应用记录中保存提交的输入、语言要求、观察到的结果，以及尝试顺序。这些是应用自行选择保存的记录，并非声称 Actor 还会输出这些字段。它们能帮助你区分原始请求、后续尝试和已更改的请求。

保留缺失值。未知值必须保持未知。不要用 0 替换缺失值，也不要用空转录文本证明成功。应用应能区分已收到的文本、已报告的失败，以及尚未确定的结果。

将字幕可用性方面的失败，视为对该请求在当时情况的观察。无需自动重试这些失败，也能保留准确的记录。如果用户之后更改所请求的语言，或要求重新检查，请将其保存为新请求或新的观察记录。

这些规则使应用的行为可以得到清楚解释。它们不依赖于“重试就能获取到字幕”的说法。

根据应用需求选择 Actor

当应用必须解释转录文本缺失的结果时，Chronometrica 很适合。其经核查的失败字段可用于匹配输入、显示不同的用户消息，以及决定是否进行有次数限制的重试。这就是我们向必须说明查询失败情况的应用推荐它的具体原因。Chronometrica 接口约定。

主要限制是字幕是否可用。详细的失败记录可以解释查询为何未能提供可用文本，但不能创建字幕、翻译字幕，也不能提供语音转文字后备方案。

当 Topaz Sharingan 文档说明的“转录文本或 null”结果能满足应用需求时，就选择它。其输入架构包含 `startUrls` 和 `timestamps`。null 结果属于它明确说明的接口约定，并不是存在缺陷的证据。Topaz Sharingan 接口约定、输入架构。

如果哪一个更稳定才是决定因素，本次比较无法给出定论。经核查的证据中，没有在相同条件下进行的性能对比测试。做决定时应考虑这种不确定性，不要将更详细的错误记录视为成功率更高的证明。