Chronometrica 與 Topaz Sharingan：如何處理缺漏的 YouTube 逐字稿記錄

依應用程式需要說明的結果來選擇

Actor 是託管執行的資料收集程式。應用程式向它提供輸入、執行它，再讀取結果。結果規格定義了應用程式可以預期收到的內容。

對逐字稿擷取來說，成功結果只是規格的一部分。應用程式也需要規則，處理未產生逐字稿的輸入。這項規則會影響向使用者顯示的訊息，以及應用程式接下來的動作。

一則開發者的公開提問描述了本機執行成功，到了正式環境卻失敗、請求遭到封鎖、結果為空，以及重試行為不明確等問題。該問題涉及另一個 Python 逐字稿函式庫。它說明了為什麼結果必須容易理解，但沒有提供本次比較中任一 Actor 的測試證據。

先從需要向使用者呈現的結果著手：

資料來源：Chronometrica 結果規格、Topaz Sharingan 結果規格。

如果較簡單的規格能滿足完整需求，就選擇它。如果應用程式必須區分結果並採取相應動作，就選擇較詳細的規格。這樣能依應用程式的行為來選擇，而不是依據缺乏證據的說法，認定哪個服務較少失敗。

一併讀取 Chronometrica 的成功記錄與失敗詳情

Chronometrica 的預設資料集，每列對應 1 部成功取得逐字稿且不重複的 YouTube 影片。資料集就是這些結果記錄的集合。失敗的輸入不會成為資料集中的成功記錄，也不會成為計費的逐字稿記錄。獨立的 `OUTPUT` 摘要會回報執行資訊，並可能包含 `failedInputDetails`。Chronometrica 規格。

當資料集的記錄數較少時，這種區分很重要。資料集的記錄數少於輸入清單的項目數，不能證明所有輸入都成功。它只表示資料集中有哪些成功的逐字稿記錄。對於未產生記錄的輸入，你也必須檢查它們所回報的結果。

請將 `includeFailedInputDetails` 保持設為 `true`。文件記載的失敗詳情包含可安全使用的輸入識別資訊、`errorCategory`、`errorCode` 和 `isRetryable`。類別用來區分失敗類型。代碼提供更明確、可由程式讀取的值。重試旗標指出回報的失敗是否可以重試。Chronometrica 輸入結構定義、結果規格。

應用程式可利用這些詳情，自行整理所有已提交輸入的狀態。請將每筆成功逐字稿或失敗輸入詳情，與對應的輸入識別資訊配對。不要按記錄在清單中的位置來配對。只要缺少 1 筆成功記錄，依位置連結輸入與結果就不再可靠。

請區分來源結果與應用程式顯示的訊息。結果記錄查詢所回報的內容。顯示訊息則向使用者解釋該結果。這樣你就能修改措辭，而不必變更已儲存的觀察記錄。

另行判斷所需語言是否可用

執行任一工作流程之前，先決定應用程式是否要求特定字幕語言。可用的逐字稿除了必須包含文字，也必須符合這項要求。

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 使用文件記載的公開輸入欄位。網址用來說明輸入格式，不保證目前存在字幕內容，也不保證特定結果。請將它換成相關的公開來源。

{
  "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 規格、輸入結構定義。

如果兩者的相對穩定性是決定因素，本次比較無法替你確定選擇。經查核的證據中，沒有在相同條件下進行的效能對照測試。請將這項不確定性納入決策，不要將更詳細的錯誤記錄視為成功率更高的證明。