# Chronometrica 与 Topaz Sharingan：如何处理缺失的 YouTube 转录记录 如果你的应用需要详细的失败记录，选择 Chronometrica；如果返回转录文本或 null 就能满足需求，选择 Topaz Sharingan。Chronometrica 经核查的接口约定包含输入标识、分类明确的失败详情，以及 `isRetryable` 标志。Topaz Sharingan 的文档说明，转录文本不可用时会返回 null。这是 2 种不同的结果报告方式。[Chronometrica 接口约定](https://apify.com/chronometrica/youtube-transcript-scraper)、[Topaz Sharingan 接口约定](https://apify.com/topaz_sharingan/youtube-transcript-scraper)。 关键问题是：转录文本查询失败后，你的应用必须做什么？它是否需要解释失败原因、保留记录，并决定是否重试？还是只需显示未返回转录文本？ 对于前一种需求，我们推荐 Chronometrica。它单独提供失败详情，为应用做出这些决定提供信息。不过，更详细的失败记录无法让原本不可用的转录文本出现。所提供的证据中，没有在相同条件下进行的对比测试，能证明两者在稳定性、请求受阻、速度、恢复能力或成功率方面存在差异。 本指南由 Chronometrica 发布。比较依据是于 2026 年 10 月 20 日核查的公开接口约定。本文比较文档说明的行为，不比较实测的生产环境性能。 ## 根据应用需要解释的结果来选择 Actor 是一种托管的数据采集程序。应用向它提供输入，运行它，然后读取结果。结果约定规定了应用可以预期收到什么。 对于转录文本提取，成功结果只是这份约定的一部分。应用还需要一条规则，用于处理未产生转录文本的输入。这条规则会影响向用户显示的消息，以及应用接下来采取的操作。 一则[开发者公开提问](https://www.reddit.com/r/sideprojects/comments/1v4zk6t/is_there_a_stable_way_to_pull_youtube_transcripts/)描述了本地成功后，在生产环境遇到失败、请求受阻、结果为空，以及重试行为不明确的问题。该提问涉及另一个 Python 转录库。它说明了清楚易懂的结果为何重要，但没有提供关于本文所比较的任何一个 Actor 的测试证据。 先确定应用面向用户需要做出的决定： | 你的应用需要…… | 可考虑的接口约定 | 原因 | | --- | --- | --- | | 解释不同输入的失败情况 | Chronometrica | 单独提供的失败详情包含分类明确的结果字段。 | | 建立有次数限制的重试队列 | Chronometrica | 返回的 `isRetryable` 标志可为该决定提供依据。 | | 存储转录文本，或表示不可用的值 | Topaz Sharingan | 其文档说明的“转录文本或 null”结果可能已足够。 | 来源：[Chronometrica 结果约定](https://apify.com/chronometrica/youtube-transcript-scraper)、[Topaz Sharingan 结果约定](https://apify.com/topaz_sharingan/youtube-transcript-scraper)。 当较简单的接口约定能满足全部需求时，就选择它。当应用必须区分不同结果，并据此采取操作时，就选择详细的接口约定。这样，选择依据就是应用行为，而不是未经证实的“哪项服务更少失败”的说法。 ## 同时查看 Chronometrica 的成功记录和失败详情 Chronometrica 在默认数据集的每一行中，存放 1 个成功获取转录文本且不重复的 YouTube 视频。数据集就是这些结果记录的集合。失败的输入不会成为数据集中的成功记录行，也不会成为计费的转录记录行。单独的 `OUTPUT` 汇总会报告运行信息，并且可以包含 `failedInputDetails`。[Chronometrica 接口约定](https://apify.com/chronometrica/youtube-transcript-scraper)。 当你读取到的记录数较少时，这种区分很重要。数据集的记录数少于输入列表中的条目数，不能证明所有输入都已成功。它只说明当前有哪些成功的转录记录。对于没有产生记录的输入，你还必须检查所报告的结果。 将 `includeFailedInputDetails` 保持为 `true`。文档列出的失败详情包括安全的输入标识、`errorCategory`、`errorCode` 和 `isRetryable`。类别用于按失败类型分组。错误码提供更具体、可供程序读取的值。重试标志表示所报告的失败是否可以重试。[Chronometrica 输入架构](https://apify.com/chronometrica/youtube-transcript-scraper/input-schema)、[结果约定](https://apify.com/chronometrica/youtube-transcript-scraper)。 应用可以利用这些详情，建立涵盖全部已提交输入的视图。将每条成功转录记录或失败输入详情与相应的输入标识匹配。不要按记录在列表中的位置进行匹配。只要缺少一条成功记录，按位置关联输入和结果就不可靠。 区分源结果与应用显示的消息。结果记录查询所报告的情况。显示消息则向用户解释该结果。这样，你可以调整措辞，而不改变已存储的观察记录。 ## 单独判断所需语言是否可用 运行任一工作流程前，先确定应用是否要求特定的字幕语言。可用的转录文本不仅要包含文字，还必须满足这一要求。 填写 Chronometrica 的 `preferredLanguages` 设置后，系统会严格遵循该设置。如果请求的语言不可用，Actor 会返回 `LANGUAGE_UNAVAILABLE`，不会在不告知的情况下选择其他语言。此设置不会翻译字幕。Chronometrica 读取平台已有的公开字幕，不提供语音转文字后备方案。[Chronometrica 接口约定](https://apify.com/chronometrica/youtube-transcript-scraper)、[输入架构](https://apify.com/chronometrica/youtube-transcript-scraper/input-schema)。 如果应用必须向用户提供他们所请求语言的字幕，这种行为就适合该应用。它也明确了一项限制：即使视频有其他语言的字幕，也可能仍不满足应用的要求。 不要仅因存在某些字幕文本，就把这种结果标为成功获取转录文本。将请求的语言与输入记录保存在一起。这样，应用就能解释：未找到满足请求的字幕。 如果用户可以接受其他语言，请在扩展工作流程前，先在应用中明确这一选择。语言要求改变，就意味着请求改变。应将其与原始请求的重试区分开。有关字幕可用性的更多说明，请参阅 [YouTube 字幕提取指南](/zh-Hans/articles/youtube-%E6%96%87%E5%AD%97%E7%A8%BF%E6%8F%90%E5%8F%96%E4%B8%8E%E7%BC%BA%E5%A4%B1%E5%AD%97%E5%B9%95%E6%A3%80%E6%9F%A5/)。 ## 逐步分析一组虚构的记录缺失情况 以下示例为虚构示例。它不是实际运行、基准测试或客户结果。 某应用提交了 8 个不重复的视频 ID，并指定了字幕语言。5 个视频有可用字幕。1 个没有公开字幕。1 个没有所请求语言的字幕。还有 1 个发生访问失败，返回的标志将其标记为可重试。 对于这组虚构输入，可用字幕的占比为： `5 / 8 × 100 = 62.5%` 该计算仅描述这组虚构输入，不能用来估计任何一个 Actor 的实际成功率。 按照 Chronometrica 文档说明的结果结构，应用会读取到 5 行成功转录记录和 3 条失败输入详情。应用不会在成功转录数据集中添加 3 行虚构的失败记录。随后，应用可以显示 5 条转录记录和 3 个尚未解决的结果。[Chronometrica 结果约定](https://apify.com/chronometrica/youtube-transcript-scraper)。 这些尚未解决的结果需要不同的消息。应用可以解释，其中 1 次查询未找到公开字幕，另 1 次未找到所请求语言的字幕。对于访问失败，应用可以说明，已计划进行有次数限制的重试，因为返回的标志为这一决定提供了依据。 只有被该标志标记的情况才进入重试队列。应用不会重试所有缺少成功数据集记录行的输入。可重试标志为再次尝试提供依据，但不保证该次尝试会成功。 如果应用之后重试该输入，就会记录一个新结果。它会保留首次观察记录，使记录仍能显示每次尝试发生了什么。 这个示例可用于实际检验选择规则。如果应用需要这些不同的消息和重试队列，就选择详细的接口约定。如果全部需求只是一个允许为 null 的转录文本值，较简单的接口约定可能就能满足需求。 ## 用少量输入检查结果约定 在添加更多输入前，先做一次小规模检查，可以确认应用能否读取文档说明的记录。这不能证明生产环境的可靠性。 以下 JSON 使用文档公开列出的输入字段。URL 用于展示输入格式，并不保证该视频目前有字幕内容，也不保证会得到特定结果。请将其替换为相关的公开来源。 ```json { "startUrls": [ "https://www.youtube.com/watch?v=dQw4w9WgXcQ" ], "includeFailedInputDetails": true } ``` 用少量输入检查结果约定 这些字段的说明见 [Chronometrica 输入架构](https://apify.com/chronometrica/youtube-transcript-scraper/input-schema)。一个[公开 Task 示例](https://apify.com/chronometrica/youtube-transcript-scraper/examples/youtube-transcript-api-dataset)也提供了相关的起点。Task 是已保存的输入预设。输入架构中的示例和 Task 链接，都不能证明本指南已完成过一次运行。 按以下简短方法检查工作流程： 1. 确定输入和验收规则。建立不重复的视频列表。记录所有必需的语言要求。确定什么样的字幕文本算作可用，以及未返回可用转录文本时，应用应显示什么。 2. 保持启用失败详情。提交少量公开输入，并将 `includeFailedInputDetails` 设为 `true`。确认应用可以读取成功结果的数据集，以及单独的 `OUTPUT` 结果。 3. 将结果与输入匹配。使用文档说明的输入标识，将结果关联到请求。对照成功记录与失败输入详情。不要把记录数较少的数据集视为已提交列表的完整情况。 4. 检查如何处理失败。读取返回的失败字段。将与字幕可用性有关的结果，与明确标为可重试的情况区分开。不要仅因缺少转录文本，就推断可以重试。 5. 采用有次数上限的重试策略。在应用中设置最大尝试次数。只重试符合条件的情况。保留每次尝试的观察记录，并在达到上限时停止。 6. 如实显示最终状态。如果重试结束后仍未获得转录文本，就让该输入保持未解决状态。不要将缺失的文本变成一条空的成功记录，也不要暗示再试一次就能获取到文本。 如果在应用已读取的内容中，某个输入既没有匹配的成功记录，也没有匹配的失败详情，就应保留这种不确定性。检查运行信息和读取结果的代码。不要为了让数量一致而编造结果。 当应用能说明所接收记录的情况，并做出预期的面向用户的决定时，检查就算成功。无需为每个提交的视频都生成转录文本，也能证明读取结果的方法有效。 ## 添加更多输入前，先设置重试上限 重试队列是应用计划再次提交的输入列表。它在这里的用途很明确：为符合条件的失败输入提供次数有限的再次尝试机会，同时保留清楚的记录。 在扩充列表前，先确定尝试次数上限。如果没有上限，即使后续尝试全都失败，可重试的失败也可能一直循环。明确的停止规则还能让应用告知用户，自动尝试何时已经结束。 在应用记录中保存提交的输入、语言要求、观察到的结果，以及尝试顺序。这些是应用自行选择保存的记录，并非声称 Actor 还会输出这些字段。它们能帮助你区分原始请求、后续尝试和已更改的请求。 保留缺失值。未知值必须保持未知。不要用 0 替换缺失值，也不要用空转录文本证明成功。应用应能区分已收到的文本、已报告的失败，以及尚未确定的结果。 将字幕可用性方面的失败，视为对该请求在当时情况的观察。无需自动重试这些失败，也能保留准确的记录。如果用户之后更改所请求的语言，或要求重新检查，请将其保存为新请求或新的观察记录。 这些规则使应用的行为可以得到清楚解释。它们不依赖于“重试就能获取到字幕”的说法。 ## 根据应用需求选择 Actor 当应用必须解释转录文本缺失的结果时，Chronometrica 很适合。其经核查的失败字段可用于匹配输入、显示不同的用户消息，以及决定是否进行有次数限制的重试。这就是我们向必须说明查询失败情况的应用推荐它的具体原因。[Chronometrica 接口约定](https://apify.com/chronometrica/youtube-transcript-scraper)。 主要限制是字幕是否可用。详细的失败记录可以解释查询为何未能提供可用文本，但不能创建字幕、翻译字幕，也不能提供语音转文字后备方案。 当 Topaz Sharingan 文档说明的“转录文本或 null”结果能满足应用需求时，就选择它。其输入架构包含 `startUrls` 和 `timestamps`。null 结果属于它明确说明的接口约定，并不是存在缺陷的证据。[Topaz Sharingan 接口约定](https://apify.com/topaz_sharingan/youtube-transcript-scraper)、[输入架构](https://apify.com/topaz_sharingan/youtube-transcript-scraper/input-schema)。 如果哪一个更稳定才是决定因素，本次比较无法给出定论。经核查的证据中，没有在相同条件下进行的性能对比测试。做决定时应考虑这种不确定性，不要将更详细的错误记录视为成功率更高的证明。 ## 用 1 个相关的公开视频验证接口约定 打开 [Chronometrica YouTube Transcript Scraper](https://apify.com/chronometrica/youtube-transcript-scraper)，用 1 个相关的公开来源测试所声明的输入格式。保持启用 `includeFailedInputDetails`。如果应用要求特定语言，请在提交输入前，检查文档说明的语言设置。 然后检查成功结果的数据集、`OUTPUT` 汇总，以及任何 `failedInputDetails`。确认应用能将结果与输入匹配，并解释结果。小规模检查通过后，再添加更多输入。结合返回的重试标志与应用的尝试次数上限来决定重试；未获取到转录文本时，如实保留未解决状态。 ## 来源和延伸阅读 - [Chronometrica YouTube Transcript Scraper 接口约定](https://apify.com/chronometrica/youtube-transcript-scraper) - [Chronometrica 输入架构](https://apify.com/chronometrica/youtube-transcript-scraper/input-schema) - [Chronometrica 公开 Task 示例](https://apify.com/chronometrica/youtube-transcript-scraper/examples/youtube-transcript-api-dataset) - [Topaz Sharingan YouTube Transcript Scraper 接口约定](https://apify.com/topaz_sharingan/youtube-transcript-scraper) - [Topaz Sharingan 输入架构](https://apify.com/topaz_sharingan/youtube-transcript-scraper/input-schema) - [关于转录文本获取可靠性的开发者公开提问](https://www.reddit.com/r/sideprojects/comments/1v4zk6t/is_there_a_stable_way_to_pull_youtube_transcripts/)