Prepare transcrições do YouTube para RAG com marcações de tempo da fonte

Obtenha 1 transcrição com marcações de tempo

JSON é um formato de dados em texto. Ele representa dados estruturados como texto. Um índice de linha de legenda é um rótulo atribuído pelo leitor a uma posição original no array segments. Não há garantia de que o Actor forneça um campo com esses índices. As tabelas didáticas numeram as posições a partir de 1. A primeira posição é 1. Mantenha o registro original intacto. Armazene esses rótulos e seu histórico de origem na cópia de trabalho.

Um Actor é um programa de coleta de dados que é executado online para você. Uma Task é uma configuração de entrada salva para um Actor. Você pode seguir este método sem o Actor se já tiver legendas. Se ainda precisar de legendas, siga o guia de extração de legendas do YouTube. Esta página não repete esse trabalho.

O coletor público verificado em 13 de outubro de 2026 usava a versão 0.1.43 do Actor. Quando a leitura das legendas é bem-sucedida, essa versão fornece segmentos com marcações de tempo. Um segmento é uma linha de legenda em json. Uma versão posterior pode ser diferente. A data da verificação é a data da observação. Não é a data de publicação de um vídeo. A página do Actor é YouTube Transcript Scraper. A Task salva é YouTube Transcripts for RAG Pipelines.

Este é o limite. Granularidade significa o que cada registro representa. Na saída do Actor, cada registro do conjunto de dados representa 1 vídeo único coletado com sucesso. Um registro do conjunto de dados é um registro salvo. Na tabela de blocos criada pelo leitor, cada linha representa 1 bloco. Um bloco não é um registro do conjunto de dados. Todas as colunas dos blocos são criadas pelo leitor. O Actor recebe uma URL direta de vídeo ou um ID de vídeo que você já conhece. Ele não encontra vídeos para você. A Task retorna json, text e llm. Use json para as citações. Uma citação identifica o vídeo e o intervalo de tempo de uma afirmação. O resultado de llm é llmText. llmText é texto pronto para um prompt. Um prompt é a mensagem que você envia a um modelo. llmText não substitui os tempos dos segmentos.

O Actor não cria blocos. Ele não cria embeddings. Ele não cria um índice. Um índice é uma estrutura armazenada para busca. O Actor não recupera passagens. Ele não responde a perguntas. Ele não atribui pontuações às respostas. Você faz a limpeza, o agrupamento e os testes manualmente.

Mantenha estes campos da fonte no registro intacto.

Uma faixa é uma versão das legendas em determinado idioma. Mantenha estes campos em cada segmento.

Se preferredLanguages estiver vazio, a execução seleciona uma faixa de legendas disponível. Verifique transcriptLanguageCode. Uma lista vazia não significa que você escolheu o idioma. Defina uma regra de idioma antes de adicionar um segundo vídeo. Mantenha isAutoGenerated junto ao registro. Automática significa que a faixa está marcada como gerada por máquina. Legendas geradas por máquina podem repetir linhas. Essa marcação, por si só, não comprova que as palavras estão erradas.

Os detalhes das entradas que falharam ficam em OUTPUT. Configure includeFailedInputDetails para que esses detalhes continuem visíveis. Uma entrada que falhou não é uma transcrição com 0 linhas de legenda. Não escreva 0 para um tempo desconhecido. Uma linha de legenda real pode começar em 0 segundos. Desconhecido e zero não são a mesma coisa. scrapedAt indica quando você coletou o registro. Não indica quando o vídeo foi publicado.

Uma única verificação das legendas não comprova que as palavras correspondem à fala. Também não comprova que as legendas continuarão disponíveis depois. A Task verificada é apenas um ponto de partida. Ela inclui vídeos de exemplo. Substitua-os por 1 vídeo público que você escolheu. A Task não faz limpeza, agrupamento nem testes.

Siga 7 ações

Execute as ações na ordem. Se você agrupar antes de limpar, uma repetição pode parecer 2 fatos. Se você atribuir pontuações antes de escrever as perguntas, poderá favorecer um agrupamento cedo demais. Escreva as perguntas primeiro. Depois use essas mesmas perguntas nos 2 agrupamentos.

1. Salve o registro bruto do coletor exatamente como ele chegou. Não edite esse registro. Não altere a fonte bruta. Faça uma cópia de trabalho para limpeza e agrupamento. Armazene na cópia de trabalho os rótulos das posições originais do array atribuídos pelo leitor. Preserve o ID do vídeo, a URL do vídeo, o código de idioma e scrapedAt. Preserve status e isAutoGenerated.
2. Leia as linhas de legenda vizinhas quando seus tempos se sobrepuserem. As mesmas palavras podem fazer parte de uma legenda progressiva. Uma legenda progressiva escreve uma mesma fala novamente na linha seguinte. Remova a linha extra somente quando as linhas de legenda e a reprodução mostrarem uma única ocorrência da fala. Reproduza esse momento em um vídeo real com a navegação por linhas de legenda do YouTube. As mesmas palavras, por si só, não são prova. Preserve uma ênfase que foi falada novamente. Preserve uma instrução repetida. Não exclua todas as frases idênticas do vídeo. Registre os números originais das linhas de legenda que deram origem à alteração.
3. Agrupe uma afirmação com sua condição. Agrupe um exemplo com a afirmação que ele ilustra. Agrupe um contraponto com a afirmação que ele limita. Mantenha uma pergunta junto de sua resposta. Prefira uma passagem curta e completa. Não corte em uma quantidade aleatória de segundos. Não corte em uma quantidade aleatória de palavras. Você pode dividir uma passagem muito longa em uma mudança real de assunto. Depois verifique se algum limite necessário ficou de fora.
4. Crie 1 linha por bloco. As colunas são chunk_id, source_video_id, source_url, language, start_seconds, end_seconds, original_cue_indices, text e cleaned_text_version. start_seconds é o início mais antigo entre as linhas de legenda do bloco. end_seconds é o fim mais tardio entre as linhas de legenda do bloco. Chame esse par de intervalo da passagem. Um intervalo da passagem pode incluir silêncio ou uma lacuna. Uma lacuna não significa que houve fala em cada segundo. Se você sobrepuser blocos para preservar o contexto, registre essa sobreposição. Conte a evidência repetida 1 vez.
5. Antes de qualquer busca, escreva de 3 a 5 perguntas. Escreva uma resposta fundamentada na fonte para cada pergunta. Marque cada parte necessária para a resposta. Uma parte é um componente necessário da resposta. Uma palavra-chave em comum não basta. Inclua 1 pergunta sem evidência nas legendas.
6. Use as mesmas perguntas nos 2 agrupamentos. Anote a quantidade de blocos selecionados antes de examinar os resultados. Use a mesma quantidade nos 2 agrupamentos. Este exemplo didático usa 1 bloco. Registre o ID do bloco que você selecionar. Registre se esse bloco contém a resposta completa e suas condições. Registre se a citação aponta para a passagem correta. Uma pessoa pode fazer isso pela leitura. Não afirme que executou uma busca por embeddings se apenas leu o texto.
7. Mantenha o agrupamento mais simples que ainda preserve o contexto necessário. Ele também deve manter os tempos claros. Um bloco mais curto não é melhor quando falta uma parte necessária. Não relate um ganho geral com base em um conjunto muito pequeno. Se a fonte não tiver evidência, diga que ela não pode responder. Não preencha a lacuna com uma história provável.

Aplique as ações a linhas de legenda fictícias

As linhas de legenda desta seção são textos didáticos fictícios. VID-DEMO-01 não é um ID real do YouTube. Não o procure. As linhas estão em português do Brasil, por isso a célula de idioma contém pt-BR. Um registro real deve copiar transcriptLanguageCode da fonte. Não há uma URL real nem uma data de publicação.

A linha de legenda 1 vai de 0 a 6 segundos. Esse 0 é um início real. Ele não substitui um valor desconhecido. A linha de legenda 2 vai de 5 a 9 segundos. Os 2 intervalos se sobrepõem. As palavras são iguais. Palavras iguais ainda não comprovam uma única ocorrência da fala. Neste exemplo inventado, uma verificação da reprodução comprova isso. A linha de legenda 2 repete a mesma fala da linha de legenda 1. Remova a linha de legenda 2 do texto de trabalho. Preserve os números 1 e 2 das linhas de legenda no registro dessa alteração. Mantenha as 6 linhas de legenda no registro original intacto.

A linha de legenda 6 não representa a mesma ocorrência da linha de legenda 2. A linha de legenda 6 dá um motivo para preservar versões diferentes. Ela permanece. Não apague todas as ideias repetidas do vídeo.

Os 2 agrupamentos abaixo usam essa cópia de trabalho. A limpeza é a mesma. A comparação trata dos pontos de divisão, não de 2 regras de limpeza. cleaned_text_version é um rótulo seu. Não é um campo do Actor. Aqui, o rótulo é clean-1. A linha de legenda 2 permanece na lista de números das linhas de legenda sempre que seu antigo intervalo estiver incluído. Sua frase não é digitada novamente.

O agrupamento por tempo divide o texto nos limites das linhas de legenda curtas.

T1 abrange as linhas de legenda 1, 2 e 3, de 0 a 15 segundos. Seu texto após a limpeza é: "Armazene os documentos pelo ID de sua fonte. Preserve uma versão quando a fonte mudar."

T2 é a linha de legenda 4, de 15 a 22 segundos. Seu texto é: "Uma nova versão não é uma nova fonte."

T3 é a linha de legenda 5, de 22 a 29 segundos. Seu texto é: "Remova uma importação repetida idêntica somente quando o ID da fonte e a versão coincidirem."

T4 é a linha de legenda 6, de 29 a 36 segundos. Seu texto é: "Preserve versões diferentes porque o texto pode mudar."

O agrupamento por sentido mantém cada afirmação com seu limite. M1 trata do que identifica um documento e do que uma mudança significa. M2 trata de quando uma importação repetida pode ser removida. Essa é uma mudança real de assunto.

M1 abrange as linhas de legenda 1, 2, 3 e 4, de 0 a 22 segundos. A linha de legenda 2 serve apenas para rastrear a origem. As frases preservadas são: "Armazene os documentos pelo ID de sua fonte. Preserve uma versão quando a fonte mudar. Uma nova versão não é uma nova fonte."

M2 abrange as linhas de legenda 5 e 6, de 22 a 36 segundos. As frases preservadas são: "Remova uma importação repetida idêntica somente quando o ID da fonte e a versão coincidirem. Preserve versões diferentes porque o texto pode mudar."

O intervalo de 0 a 22 segundos é um intervalo da passagem. Ele usa o início mais antigo e o fim mais tardio. Isso não significa que houve fala em cada segundo. M1 termina em 22 segundos. M2 começa em 22 segundos. Eles compartilham um limite. Não compartilham uma frase. Se você sobrepuser blocos de propósito depois, registre essa sobreposição. Conte a evidência repetida 1 vez.

Estas 2 linhas agrupadas por sentido formam a tabela de blocos aprovada no teste fictício abaixo.

As linhas agrupadas por tempo formam o conjunto de comparação. Elas não são a tabela selecionada.

As perguntas foram definidas antes de avaliar qualquer um dos agrupamentos. A quantidade de blocos selecionados também foi definida. É 1 bloco. A escolha é manual. Nenhuma busca por embeddings foi executada. Nenhum banco de dados foi usado.

Pergunta 1: O que identifica um documento e o que acontece quando ele muda? A resposta precisa de 3 partes. O documento está vinculado a um ID de fonte. Uma mudança significa que você preserva uma versão. Uma nova versão não é uma nova fonte.

Pergunta 2: Quando uma importação repetida pode ser removida e por que preservar outras versões? A resposta precisa de 2 partes. Remova-a somente quando o ID da fonte e a versão coincidirem. Preserve outras versões porque o texto pode mudar.

Pergunta 3: Quantos dólares custa o armazenamento? Nenhuma linha de legenda informa um custo em dólares. A fonte não pode responder.

A escolha manual inventada para a pergunta 1 é T1 no agrupamento por tempo e M1 no agrupamento por sentido. T1 contém o ID da fonte e a parte sobre preservar uma versão. T1 termina em 15 segundos, por isso não contém a linha de legenda 4. Sem a linha de legenda 4, uma nova versão pode ser interpretada como um novo documento. Esse contraponto é a condição. M1 preserva as 3 partes. A linha de legenda 4 sozinha também falharia, pois não contém o ID da fonte nem a parte sobre preservar uma versão. Nenhum bloco por tempo contém as 3 partes. Unir T1 e T2 reuniria as partes, mas isso usaria uma regra de 2 blocos. Este teste não usa uma regra de 2 blocos.

A escolha manual inventada para a pergunta 2 é T3 no agrupamento por tempo e M2 no agrupamento por sentido. T3 contém a regra de remoção. Falta o motivo. O motivo é que o texto pode mudar. Sem esse motivo, a regra de remoção parece ter um alcance maior do que o ensinado. T4 contém o motivo e não contém a regra de coincidência. Nenhum bloco por tempo contém as 2 partes. M2 contém ambas.

A pergunta 3 não tem nenhuma parte que a fundamente em nenhum bloco. Um bloco que menciona armazenamento ainda não informa um preço. Os 2 agrupamentos devem ser marcados como sem evidência. A resposta informa que a fonte não pode responder.

Há momentos distintos dentro desses intervalos de citação.

Uma pontuação aqui é uma contagem de verificações aprovadas. A fundamentação completa considera apenas as perguntas que podem ser respondidas.

Fundamentação completa = perguntas que podem ser respondidas e cujo bloco selecionado contém todas as partes necessárias / perguntas que podem ser respondidas

Agrupamento por tempo = 0/2

Agrupamento por sentido = 2/2

Abstenção significa que você não responde. A contagem de abstenções considera apenas a pergunta sem evidência nas legendas.

Abstenção = recusas corretas / perguntas sem evidência = 1/1

Não some 1/1 ao 2. A verificação da pergunta sem evidência é separada.

Essas frações pertencem apenas a esta comparação manual inventada. Elas não são um benchmark de embeddings. Um benchmark seria uma pontuação medida em um teste. Elas não são uma melhoria de qualidade medida. Uma melhoria de qualidade seria um ganho comprovado em buscas reais. Não deduza um ganho para outros vídeos. Em outro vídeo, um bloco curto por tempo pode já conter todas as partes. Nesse caso, o agrupamento mais simples aprovado poderia ser o agrupamento por tempo.

Uma resposta fictícia deve citar um momento dentro do intervalo preservado. Um revisor verifica a reprodução depois. VID-DEMO-01 não tem uma página real, por isso a etapa de reprodução também é fictícia. Em um vídeo real, use a navegação por linhas de legenda do YouTube.

Resposta fictícia à pergunta 1: "O ID da fonte identifica o documento. Quando a fonte mudar, preserve uma versão. Uma nova versão não é uma nova fonte." Citação: VID-DEMO-01, 0-22 segundos, linhas de legenda 1, 2, 3 e 4. As partes faladas estão nas linhas de legenda 1, 3 e 4. A linha de legenda 2 é apenas o registro da remoção.

Resposta fictícia à pergunta 2: "Remova uma importação repetida idêntica somente quando o ID da fonte e a versão coincidirem. Preserve versões diferentes porque o texto pode mudar." Citação: VID-DEMO-01, 22-36 segundos, linhas de legenda 5 e 6.

Resposta fictícia à pergunta 3: "A fonte não pode responder. Nenhuma linha de legenda informa um custo de armazenamento em dólares." Não há intervalo de citação.

Pela regra de 1 bloco, o agrupamento por sentido é o que contém o contexto necessário. Cada resposta cabe em 1 bloco, e os tempos permanecem claros. O agrupamento por tempo tem blocos mais curtos, mas deixa uma parte de fora. Para este caso inventado, preserve M1 e M2. Não trate essa escolha como uma regra para todos os vídeos. Execute as mesmas 7 ações no seu próprio arquivo antes de adicionar mais vídeos.