Youtu-Parsing-Omni로 문서·음성·영상을 JSON으로 정리하기

모델 카드의 작업 표에는 문서 페이지 document, 차트 graphics_chart, 음성 audio, 일반 영상 natural_video, 글자가 많은 영상 textrich_video 등 task가 나뉘어 있어요. 문서 JSON에는 요소별 텍스트나 LaTeX, 표, 좌표, 읽기 순서가 들어갈 수 있고 오디오·비디오는 타임스탬프가 있는 segments를 반환해요.

모든 입력을 한 종류의 OCR로 취급하지 마세요. 차트는 표·주석·캡션, 음성은 발화와 비발화 구간·ASR, 글자가 많은 영상은 OCR과 ASR 및 전체 보고서를 요청하는 작업이에요. 선택한 task가 입력과 다르면 해당 구조가 결과에 빠질 수 있어요.

공식 quick start는 Python 3.10 이상과 CUDA⁴ GPU⁵를 전제로 해요. vLLM 서버용은 설치 스크립트가 vllm==0.19.0, transformers==5.2.0과 vllm-plugin-vita-omni 경로를 준비해요. 직접 Transformers 추론은 transformers==5.10.2를 쓰므로 같은 가상환경⁶에 두 설정을 섞지 말고 별도로 만들어요.

플러그인은 모델 구현 코드를 포함하므로 움직이는 기본 브랜치 대신 리뷰한 commit에 고정하세요. 2026년 10월 13일 확인한 공식 저장소 main은 421cfad7acf8f0f80f5bd6dfa03b5ce3916224eb였어요. 설치 전에 Hugging Face의 youtu-parsing 라이선스를 읽고, 실행 스크립트가 미디어를 읽을 수 있는 디렉터리도 제한해요.

mkdir -p "$HOME/projects"
cd "$HOME/projects"
git clone https://github.com/TencentCloudADP/youtu-parsing.git
cd youtu-parsing
git checkout 421cfad7acf8f0f80f5bd6dfa03b5ce3916224eb
cd youtu_parsing_omni

모델 서버용 Python 가상환경을 따로 만들고 설치 스크립트를 실행해요. 실행 스크립트의 MODEL은 Hugging Face 모델 ID를 그대로 내려받거나 로컬 체크포인트⁷ 경로를 받을 수 있고, 기본 캐시는 HF_HOME 아래에 놓여요. DATA_ROOT는 모델 저장 위치가 아니라 서버가 읽을 수 있는 미디어 파일 경로예요.

python3 -m venv .venv
source .venv/bin/activate
bash scripts/setup_env.sh

새 터미널을 열고 $HOME/projects/youtu-parsing/youtu_parsing_omni로 이동해요. media/page.png, media/speech.wav, media/clip.mp4를 해당 폴더 안에 준비해요. 아래 예시 입력은 youtu_parsing_omni/media/에 두고, infer_vllm.py를 실행해요.

infer_vllm.py는 결과를 파일로 저장하지 않고 fenced JSON을 터미널에 출력해요. 필요하면 출력을 텍스트 편집기로 복사해 앞뒤 코드 펜스를 제거하고 .json으로 저장해요. 문서의 제목·본문·표 요소와 읽기 순서, 음성의 구간·화자·ASR 텍스트, 영상의 시간대별 OCR·ASR 내용을 원본과 대조해요.

mkdir -p media
MODEL=tencent/Youtu-Parsing-Omni DATA_ROOT="$PWD/media" GPU=0 bash scripts/vllm.sh

cd "$HOME/projects/youtu-parsing/youtu_parsing_omni"
source .venv/bin/activate
python examples/infer_vllm.py --task document --media media/page.png
python examples/infer_vllm.py --task audio --media media/speech.wav
python examples/infer_vllm.py --task natural_video --media media/clip.mp4

{
  "modality": "image",
  "subtype": "document",
  "elements": [],
  "reading_order": [],
  "global_description": {}
}

문서에서는 원본 표의 행·열, 작은 글자, 읽기 순서를 추출 JSON과 대조해요. 음성은 화자 이름과 타임스탬프에 맞는 재생 구간을 확인하고, 영상은 OCR·ASR이 같은 시간대의 내용을 가리키는지 살펴봐요.

서버가 파일을 찾지 못하면 해당 미디어가 DATA_ROOT 안에 있는지 먼저 확인해요. 음성·영상에서 ffmpeg가 없다는 메시지가 나오면 설치 경로에서 실행 가능한지 확인하고, 추론 환경의 패키지 버전이 vLLM 조합인지도 살펴봐요. 출력 구조가 요청과 다르면 작업 task와 프롬프트⁸ 선택을 다시 맞춰요.