Как собрать WebVTT из JSON-сегментов AI-расшифровки

Перед запуском запишите, какие данные считаются входом, что является ожидаемым результатом, что именно означает отказ и кому предстоит разбирать расхождение. Для такой проверки храните тестовый вход, ожидаемый результат и фактический исход раздельно: если они смешаны, тест может подтверждать сам себя. Используйте стабильные синтетические ID, чтобы видеть ошибку в журнале, не раскрывая содержимое клиентских обращений.

Сначала прогоните тест на маленьком входе, где правильное поведение известно вручную. Затем внесите одну контролируемую ошибку и убедитесь, что код её замечает. После этого верните корректный набор и только тогда расширяйте проверку до реальных данных. Не переносите демонстрационные численные значения или пороги в производство без отдельного обоснования: они выбраны для наглядности, а не рассчитаны по вашей аудитории.

Вход и ожидаемый результат

JSON: [{"id":"a","start_ms":0,"end_ms":1200,"text":"Добрый день"},{"id":"b","start_ms":1300,"end_ms":2400,"text":"Начинаем"}]. Вывод начинается с WEBVTT, затем ID a и b, интервалы 00:00:00.000 --> 00:00:01.200 и 00:00:01.300 --> 00:00:02.400, русский текст сохранён. Перед тем как применять правило к закрытым данным, обсудите пограничные случаи, которые могут поменять интерпретацию входа. Запись в документации о границах теста не менее важна, чем зелёный check.

Пошаговые действия

1. Создайте scripts/check.py в корне репозитория и вставьте код из блока ниже. Он использует названия функций стандартной библиотеки, указанные в официальных ссылках в конце статьи.
2. Выполните python scripts/check.py локально. Не продолжайте, если уже демонстрационная фикстура даёт иной результат: сначала проверьте копирование кода и кодировку файла.
3. Согласуйте поля JSON и единицы времени до обработки файла. Примените строгий json.loads к входу, затем сохраните исходный JSON для ревью. Запустите сериализатор на демонстрационных сегментах: убедитесь, что порядок cues сохранён и длительности не обнулились. В производственном пайплайне проверяйте последовательность стартов отдельно, если вашему видеоплееру требуется порядок; сама задача экспортера прежде всего проверяет каждый интервал. Откройте готовый трек вместе с исходным видео, исправьте ошибки распознавания и только после этого публикуйте.
4. Создайте .github/workflows/ai-corpus-check.yml из YAML-шаблона. Событие pull_request полезно для проверки данных до слияния; чтение репозитория ограничено permissions: contents: read. Скрипт не должен получать ключ внешней модели или реальные секреты.
5. В разделе Actions откройте job check, сопоставьте его код завершения с локальным прогоном и зафиксируйте ссылку на проверенный коммит в PR. Не принимайте зелёный результат на старой ревизии за проверку последнего изменения.

# scripts/check.py
import json
def stamp(ms):
    h,r=divmod(ms,3600000)
    m,r=divmod(r,60000)
    s,ms=divmod(r,1000)
    return f'{h:02d}:{m:02d}:{s:02d}.{ms:03d}'
def export(rows):
    seen=set()
    blocks=['WEBVTT']
    for row in rows:
        ident,start,end,content=(row[k] for k in ('id','start_ms','end_ms','text'))
        if not isinstance(ident,str) or not ident or '-->' in ident or '\n' in ident or ident in seen:
            raise ValueError('bad cue ID')
        if type(start) is not int or type(end) is not int or start<0 or end<=start:
            raise ValueError('bad cue time')
        if not isinstance(content,str) or not content.strip() or '-->' in content:
            raise ValueError('bad cue text')
        seen.add(ident)
        blocks.append(f'{ident}\n{stamp(start)} --> {stamp(end)}\n{content}')
    return '\n\n'.join(blocks)+'\n'
rows=json.loads('[{"id":"a","start_ms":0,"end_ms":1200,"text":"Добрый день"},{"id":"b","start_ms":1300,"end_ms":2400,"text":"Начинаем"}]')
out=export(rows)
assert out.startswith('WEBVTT\n\n')
assert '00:00:01.300 --> 00:00:02.400' in out
print(out)

name: AI corpus checks
on:
  pull_request:
permissions:
  contents: read
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-python@v7
        with:
          python-version: '3.13'
      - run: python scripts/check.py

Ошибки интерпретации и границы

Код намеренно отклоняет сложный WebVTT markup, NOTE и metadata; его нужно расширить и проверить отдельно, если такие функции нужны. Это форматный экспорт, не доказательство качества расшифровки. Если вы расширяете набор случаев, добавляйте не только новые примеры, но и отрицательные случаи, на которых тест обязан упасть. Проверяйте, что изменение expected прошло ревью отдельно от изменения кода: иначе можно незаметно изменить правило под текущий ответ системы. Избегайте вывода полного приватного набора в CI и не сохраняйте в артефактах ответ закрытой модели без решения о доступе и хранении.

Ошибка выполнения самого Python, нераспознанный формат входа и обнаруженный бизнес-дефект — разные ситуации. В сообщении теста указывайте тип проблемы и безопасный ID. Если тест требует внешний сервис, вынесите его из PR с недоверенным кодом и явно ограничьте доступ к токенам; этот пример намеренно работает локально. Перед публикацией каких-либо результатов опишите методику, область применения и происхождение примеров, иначе читатель воспримет демонстрационную арифметику как характеристику продукта.

Практический разбор именно этого контроля

Получить воспроизводимый WebVTT из структурированных сегментов AI-расшифровки перед ручной вычиткой. Для самостоятельной проверки сначала выпишите три наблюдаемых состояния: допустимый вход, намеренно недопустимый вход и видимый сигнал отказа. В данной фикстуре это выглядит так: JSON: [{"id":"a","start_ms":0,"end_ms":1200,"text":"Добрый день"},{"id":"b","start_ms":1300,"end_ms":2400,"text":"Начинаем"}]. При успешном тесте ожидается: Вывод начинается с WEBVTT, затем ID a и b, интервалы 00:00:00.000 --> 00:00:01.200 и 00:00:01.300 --> 00:00:02.400, русский текст сохранён. Не превращайте это в числовой KPI: здесь проверяется контракт на конкретных примерах, а не поведение модели на пользовательском трафике.

Код намеренно отклоняет сложный WebVTT markup, NOTE и metadata; его нужно расширить и проверить отдельно, если такие функции нужны. Это форматный экспорт, не доказательство качества расшифровки. Подключая проверку к продукту, расположите её до той операции, ради которой она написана: парсинга, сохранения, отображения или экспорта. Для каждого нового формата добавляйте отдельный негативный пример и письменное решение, почему он отклоняется. Отдельно просмотрите обработку ошибок: система должна отличать невалидный ответ AI от сбоя тестовой инфраструктуры, а пользователь не должен видеть сырой стек или приватное содержимое.