Python Versions

codecov

</div>

Lhotse

Lhotse는 멀티모달(speech, audio, video, image, text) 데이터 준비를 유연하고 폭넓은 커뮤니티가 접근할 수 있도록 목표로 하는 Python 라이브러리입니다.
k2와 함께 다음 세대 Kaldi 음성 처리 라이브러리의 일부입니다.

튜토리얼 발표 및 자료

(Interspeech 2023) 튜토리얼 노트북
Interspeech 2023 Tutorial
(Interspeech 2023) 튜토리얼 슬라이드
(Interspeech 2021) 녹화 강의 (3시간)

소개

주요 목표 (2025년 업데이트)

오디오, 텍스트, 이미지, 비디오 모달리티를 포함한 멀티모달 데이터 파이프라인으로 확장할 수 있습니다.
데이터셋 블렌딩(dataset blending) 및 효율적인 온-더-플라이 버케팅(on-the-fly bucketing)과 같은 최첨단 데이터 로딩 알고리즘을 제공합니다.
분산 멀티노드 학습을 위한 데이터 무작위화(data randomization) 또는 중복 제거(de-duplication)를 처리합니다.
Python 중심의 디자인으로 더 넓은 커뮤니티가 멀티모달 처리 작업에 참여하도록 유도합니다.
일반적으로 사용되는 코퍼스에 대한 표준 데이터 준비 레시피를 제공합니다.
오디오/비디오 컷(audio/video cuts) 개념을 사용하여 모델 학습을 위한 유연한 데이터 준비가 가능합니다.
Lhotse Shar와 같이 순차적 I/O 데이터 형식(webdataset과 유사)을 지원합니다.

튜토리얼 (Tutorials)

examples 디렉터리에서 다음 튜토리얼들을 제공합니다:

기본적인 Lhotse 워크플로우
Colab
컷(Cuts)을 사용한 데이터 변환
Colab
WebDataset 통합
Colab
여러 데이터셋 결합 방법
Colab
Lhotse Shar: 순차적 I/O 및 모듈성을 위해 최적화된 저장 형식
Colab
Lhotse에서의 이미지 및 비디오 지원
Colab

사용 예시 (Examples of use)

Lhotse가 어떻게 활용되고 있는지 확인하려면 다음 링크들을 참고하세요:

Icefall recipes: k2와 Lhotse가 만나는 곳.
최소 ESPnet+Lhotse 예시:
Colab

주요 개념 (Main ideas)

Kaldi처럼 Lhotse는 표준 데이터 준비 레시피를 제공하지만, 작업별 Dataset 클래스를 통해 원활한 PyTorch 통합으로 이를 확장합니다. 데이터와 메타데이터는 사람이 읽을 수 있는 텍스트 매니페스트로 표현되며 편리한 Python 클래스를 통해 사용자에게 노출됩니다.

image

Lhotse는 오디오 커트(audio cuts) 개념을 도입하여, 혼합(mixing), 자르기(truncation), 패딩(padding)과 같은 작업을 온-더-플라이(on-the-fly)로 수행함으로써 훈련 데이터 구성을 용이하게 합니다. 이는 필요한 저장 공간의 양을 최소화합니다. 데이터 증강(Data augmentation) 및 특징 추출(feature extraction)은 디스크에 특징 행렬을 저장하는 사전 계산 모드(pre-computed mode)(더 나은 저장 효율성을 위해 lilcom-compressed 백엔드를 선택적으로 사용)와 요청 시 변환을 계산하는 온-더-플라이 모드 모두를 지원합니다. 또한, Lhotse는 두 가지 장점을 결합하기 위해 특징 공간 커트 혼합(feature-space cut mixing)을 도입합니다.

image

설치 (Installation)

Lhotse는 Python 버전 3.10 이상을 지원합니다.

Pip

Lhotse는 PyPI에서 사용할 수 있습니다:

pip install lhotse

최신, 미출시 버전을 설치하려면 다음을 수행하십시오:

pip install git+https://github.com/lhotse-speech/lhotse

개발 환경 설치 (Development installation)

개발 환경 설치를 위해 GitHub 저장소를 포크(fork)/클론(clone)하고 pip으로 설치할 수 있습니다:

git clone https://github.com/lhotse-speech/lhotse
cd lhotse
pip install -e '.[dev]'
pre-commit install  # 스타일 검사를 위한 pre-commit 훅을 설치합니다.

# 단위 테스트 실행 (Running unit tests)
pytest test

# 린터 검사 실행 (Running linter checks)
pre-commit run

이것은 편집 가능한 설치(editable installation)(-e 옵션)로, 소스 코드에 대한 변경 사항이 lhotse를 가져올 때 자동으로 반영된다는 의미입니다(재설치 불필요). [dev] 부분은 테스트 실행, 문서 빌드 또는 jupyter 노트북을 시작하는 데 사용되는 추가 종속성(dependencies)을 설치한다는 의미입니다.

환경 변수 (Environment variables)

Lhotse는 동작을 사용자 정의하기 위해 여러 환경 변수를 사용합니다. 해당 변수는 다음과 같습니다:

LHOTSE_REQUIRE_TORCHAUDIO: 이 변수가 설정되었고 값이 1|True|true|yes 중 어느 것도 아닐 경우, Lhotse가 torchaudio 설치 여부를 확인하지 않고 요구 사항에서 제거합니다. 이렇게 하면 Lhotse의 많은 기능이 비활성화되지만, 기본적인 기능(예: soundfile을 사용한 오디오 읽기)은 유지됩니다.
LHOTSE_AUDIO_DURATION_MISMATCH_TOLERANCE: 파일에서 오디오를 로드할 때 선언된 Recording.num_samples와 다른 샘플 수를 받는 경우에 사용됩니다. 이는 서로 다른 코덱(또는 심지어 동일한 코덱의 다른 버전)이 압축된 오디오를 디코딩할 때 다른 패딩을 사용할 수 있기 때문에 때때로 필요합니다. 일반적으로 0.1 이하, 또는 0.3 (초)까지의 값은 여전히 합리적이며, 그 이상은 심각한 문제를 나타냅니다.
LHOTSE_AUDIO_BACKEND: CLI 명령어 lhotse list-audio-backends에서 반환되는 값 중 하나로 설정하여 임시방편적인(trial-and-error) 기본 동작을 재정의하고 항상 특정 오디오 백엔드를 사용하도록 할 수 있습니다.
LHOTSE_IO_BACKEND: CLI 명령어 lhotse list-io-backends에서 반환되는 값 중 하나로 설정하여 Lhotse가 open_best()를 통해 경로(paths), URL, URI를 여는 방식을 재정의할 수 있습니다 (예: 매니페스트를 읽거나 URL 기반의 AudioSource를 처리할 때). 동일한 목록은 Python에서도 lhotse.available_io_backends()를 통해 사용할 수 있습니다.
LHOTSE_S3_LOCAL_MIRROR_ROOTS: 선택적이며, URL 기반 오디오를 해결하는 데 사용되는 os.pathsep으로 구분된 로컬 루트 경로입니다 (Unix에서는 : , Windows에서는 ;). 이 변수는 매니페스트에서 s3://bucket/key 경로를 재작성하지 않고도 오디오를 처리할 수 있게 합니다. 루트는 <root>/<bucket>/<key> 레이아웃 순서로 검색됩니다. 아카이브 멤버 URL의 경우 로컬 아카이브가 존재하기만 하면 됩니다. 누락된 객체는 원래 URI를 유지하고 구성된 원격 백엔드를 사용합니다. AISBatchLoader는 성공적으로 미러링된 오디오를 AIStore 요청에서 제외합니다.
LHOTSE_RESAMPLING_BACKEND: CLI 명령어 lhotse list-resampling-backends에서 반환되는 값 중 하나로 설정하여 기본 동작을 재정의할 수 있습니다.
LHOTSE_FEATURES_STORAGE_BACKEND: 기본 피처 저장소 백엔드(기본값은 numpy_files)를 재정의하기 위해 유효한 피처 저장소 백엔드 이름(예: numpy_files, lilcom_chunky)으로 설정할 수 있습니다. 현재 사용 가능한 선택 사항을 확인하려면 lhotse.available_storage_backends()를 사용하거나, 전체 목록과 설치되지 않은 백엔드를 표시하는 더 자세한 정보가 필요하면 lhotse.storage_backend_statuses() 또는 CLI의 lhotse list-storage-backends를 사용하십시오. lilcom이 설치되어 있고 더 작은 피처 아카이브를 원한다면, lilcom_chunky가 선호되는 선택지입니다.
LHOTSE_AUDIO_LOADING_EXCEPTION_VERBOSE: 이 값을 1로 설정하면, 사용 가능한 모든 오디오 백엔드가 주어진 파일을 로드하는 데 실패할 때 전체 예외 스택 트레이스를 출력합니다 (파일이 매우 클 수 있습니다).
LHOTSE_DILL_ENABLED: 이 값이 1|True|true|yes로 설정되면, 프로세스 간에 CutSet과 Sampler의 dill-기반 직렬화(serialization)가 활성화됩니다 (설치되어 있어도 기본적으로 비활성화되어 있습니다).
LHOTSE_LEGACY_OPUS_LOADING: (=1) 각 OPUS 파일에 대해 새로운 ffmpeg 서브프로세스를 트리거하는 레거시 OPUS 로딩 메커니즘으로 되돌아갑니다.
LHOTSE_PREPARING_RELEASE: Lhotse의 새 버전을 릴리스할 때 개발자가 내부적으로 사용합니다.
TORCHAUDIO_USE_BACKEND_DISPATCHER: 이 값을 1로 설정하고 torchaudio 버전이 2.1 미만일 경우, torchaudio의 실험적인 ffmpeg 백엔드가 활성화됩니다.
AIS_ENDPOINT: AIStore 클라이언트가 AIStore 엔드포인트 URL을 결정하는 데 사용합니다. AIStore 데이터 로딩에 필수적입니다.
AIS_CONNECT_TIMEOUT: AIStore SDK에서 연결 시간 초과(초 단위)를 설정하는 데 사용됩니다. 비활성화하려면 0으로 설정하십시오 (시간 초과 없음). 설정하지 않으면 SDK 기본값(3초)이 사용됩니다.
AIS_READ_TIMEOUT: AIStore SDK에서 읽기 시간 초과(초 단위)를 설정하는 데 사용됩니다. 비활성화하려면 0으로 설정하십시오 (시간 초과 없음). 설정하지 않으면 SDK 기본값(20초)이 사용됩니다.
RANK, WORLD_SIZE, WORKER, 그리고 NUM_WORKERS는 Lhotse Shar 데이터 로딩 서브프로세스에 정보를 제공하기 위해 내부적으로 사용됩니다.
READTHEDOCS는 문서 빌드용으로 내부적으로 사용됩니다.
LHOTSE_MSC_OVERRIDE_PROTOCOLS - 설정할 경우, MSCIOBackend에 전달되기 전에 입력 프로토콜을 재정의합니다. 기존 URL 형식을 변경하고 싶지 않지만 MSCIOBackend를 사용하고 싶을 때 유용합니다. 예를 들어, s3://s3-bucket/path/to/my/object와 gs://gs-bucket/path/to/my/object가 있고, LHOTSE_MSC_OVERRIDE_PROTOCOLS=s3,gs를 설정하면 URL이 msc://s3-bucket/path/to/my/object와 msc://gs-bucket/path/to/my/object로 재정의됩니다.
LHOTSE_MSC_PROFILE - 설정할 경우, MSCIOBackend에 전달되기 전에 버킷 이름을 재정의합니다. msc 프로필이 버킷 이름과 같지 않을 때 유용합니다. 예를 들어, s3://s3-bucket/path/to/my/object가 있고, LHOTSE_MSC_OVERRIDE_PROTOCOLS=s3와 LHOTSE_MSC_PROFILE=msc-s3-profile를 설정하면 URL이 msc://msc-s3-profile/path/to/my/object로 재정의됩니다.
LHOTSE_MSC_BACKEND_FORCED - True로 설정할 경우, Lhotse가 모든 URL에 대해 MSCIOBackend를 사용하도록 강제합니다. MSC가 제공된 URL 형식을 지원하지 않을 수 있으므로 주의해서 사용하십시오.

Lhotse: 멀티모달 데이터 처리를 위한 Python 라이브러리

요약

핵심 포인트