Video Learning Agent

Video Learning Agent는 '영상으로 배우기'를 자동화된 엔지니어링 파이프라인으로 만듭니다.

B站/YouTube 영상 링크, 컬렉션 링크, 또는 영상 목록 파일을 제공하면 됩니다. 먼저 자막을 가져오려고 시도하고, 자막이 없으면 임대한 GPU 클라우드 호스트에서 ASR을 실행합니다. 전사가 완료되면 결과를 로컬로 가져와 Markdown 학습 문서를 생성하고 로컬 검색 인덱스를 구축합니다.

B站 / YouTube 链接或列表
-> 优先获取字幕
-> 无字幕时上传任务到 GPU 云主机
-> GPU 下载音频并跑 faster-whisper ASR
-> 拉回 transcript.md / segments.jsonl
-> 生成可学习、可操作的 Markdown 总结
-> 建 SQLite / Chroma 搜索索引

대상

• 강좌 영상을 대량으로 소화하려는 사람

• 공개 영상을 학습 문서로 만들려는 사람

• '지식 포인트 + 예시 + 도구 명령어 + GitHub 프로젝트 + AI 실습 프로젝트'를 자동으로 생성하려는 사람

• Claude, Codex, WorkBuddy가 MCP를 통해 이 워크플로우를 호출하게 하려는 사람

Related MCP server: Open CLAW Knowledge Distiller

기능

• B站 및 YouTube 지원

• 단일 영상, 컬렉션, 재생목록, TSV/CSV 영상 목록 지원

• 자막을 우선 가져오고, 자막을 사용할 수 없을 때만 ASR 실행

• GPU 클라우드 호스트를 직접 임대한 후 SSH 정보를 Agent에 넘겨 자동 처리 지원

• 원격 ASR은 faster-whisper 사용

• 기본 모델 medium

• 기본 GPU 모드 cuda + float16

• 기본 배치당 20개 영상

• 기본 4090에서 ASR worker 3개 동시 실행 가능

• 다운로드/ASR 진행 상황 실시간 확인

• 결과를 로컬로 가져온 후 Markdown 학습 문서 생성

• 로컬 SQLite 검색, Chroma 의미 검색 선택 가능

• MCP server 제공

설치

git clone https://github.com/hahahng/video-learning-agent.git
cd video-learning-agent
python3 -m pip install -e '.[remote,mcp,test,yaml]'

시스템에 다음이 필요합니다:

ffmpeg
yt-dlp
python >= 3.10

macOS에서는 이렇게 설치할 수 있습니다:

brew install ffmpeg yt-dlp

가장 간단한 사용법: 자막이 있는 영상

영상에 자막이 있으면 GPU가 필요 없습니다.

video-agent ingest "https://www.bilibili.com/video/BVxxx"

명령어가 작업 디렉터리를 생성합니다:

work/jobs/<job_id>/

상태 확인:

video-agent status <job_id>

요약 생성:

video-agent digest <job_id> --index

검색:

video-agent search "文件系统"

자막이 없으면: GPU를 임대해 ASR 실행

영상에 자막이 없거나 자막 품질이 너무 낮으면 NVIDIA GPU가 장착된 클라우드 호스트를 임대해 ASR을 실행합니다.

이 프로젝트는 자동으로 머신을 구매하지 않습니다. 클라우드 플랫폼에서 GPU 인스턴스를 직접 생성한 후 SSH 정보를 설정에 입력하세요.

권장 구성:

• GPU: RTX 4090 / A10 / A100 / L40S 모두 가능

• 시스템: Ubuntu 20.04 / 22.04

• 디스크: 최소 50GB, 배치 실행 시 100GB+ 권장

• 네트워크: B站 / YouTube / Hugging Face 모델 다운로드 주소 접근 가능

• 로그인 방식: SSH 비밀번호 또는 SSH 키

1. GPU 클라우드 호스트 임대

SSH를 지원하는 GPU 클라우드 플랫폼을 선택하세요. 예: AutoDL 콘솔:

https://www.autodl.com/console/instance/list

일반적인 절차는 다음과 같습니다:

1. GPU 인스턴스를 선택합니다(예: 4090).

2. Ubuntu 이미지를 선택합니다.

3. 전원을 켭니다.

4. 콘솔에서 SSH 연결 정보를 찾습니다:

   host
   port
   user
   password 或 private key

5. 로컬에서 먼저 로그인 가능한지 확인합니다:

   ssh -p <port> <user>@<host>

이 단계에서 로그인만 가능하면 Agent가 이후의 의존성 설치, 작업 업로드, ASR 실행, 결과 가져오기를 처리할 수 있습니다.

자세한 내용은 GPU ASR 사용 설명을 참조하세요.

AutoDL 예시

AutoDL을 사용하는 경우:

1. AutoDL 인스턴스 목록을 엽니다.

2. GPU 인스턴스를 새로 만들거나 시작합니다.

3. 4090을 선택하고 시스템 이미지는 Ubuntu를 선택하는 것을 권장합니다.

4. 인스턴스 상세 페이지로 이동해 SSH 로그인 정보를 복사합니다.

5. 다음과 같은 정보를 받게 됩니다:

   host: connect.xxx.autodl.com 或平台提供的连接地址
   port: 具体端口
   user: root
   password: 实例密码

6. 먼저 로컬에서 테스트합니다:

   ssh -p <port> root@<host>

7. 로그인할 수 있으면 host/port/user를 video-agent.config.yaml에 작성하고 비밀번호는 환경 변수에 넣습니다.

2. GPU SSH 구성

구성 파일을 복사합니다:

cp video-agent.config.example.yaml video-agent.config.yaml

video-agent.config.yaml을 편집합니다:

jobs_root: work/jobs
data_root: data

gpu_profiles:
  my_4090:
    host: your.gpu.ssh.host
    port: 22
    user: root
    remote_root: /root/autodl-tmp/video-learning-agent
    password_env: VIDEO_GPU_PASSWORD

비밀번호는 구성 파일에 작성하지 마세요. 환경 변수에 넣습니다:

export VIDEO_GPU_PASSWORD='你的 GPU SSH 密码'

SSH 키를 사용하는 경우:

gpu_profiles:
  my_4090:
    host: your.gpu.ssh.host
    port: 22
    user: root
    remote_root: /root/autodl-tmp/video-learning-agent
    key_filename: /Users/you/.ssh/id_ed25519

3. 영상 목록 일괄 처리

TSV 형식 예시:

index	bv	title	url	duration
1	BVxxxx	第一节	https://www.bilibili.com/video/BVxxxx	
2	BVyyyy	第二节	https://www.bilibili.com/video/BVyyyy	

시작:

video-agent ingest ./videos.tsv \
  --gpu-profile my_4090 \
  --batch-size 20 \
  --asr-workers 3

job을 이미 생성했지만 원격 ASR을 아직 시작하지 않은 경우:

video-agent run-remote-asr <job_id> \
  --gpu-profile my_4090 \
  --batch-size 20 \
  --asr-workers 3

4. 진행 상황 실시간 확인

video-agent status <job_id> --gpu-profile my_4090 --watch

출력 예시:

进度：ASR 中
音频：51 / 73
转写：18 / 73
当前：BVxxxx
GPU：82%，显存 17.4G / 24.0G
音频占用：3.9G
数据盘剩余：46G
错误：无

5. 결과 가져오기

video-agent pull <job_id> --gpu-profile my_4090

로컬 결과는 다음 위치에 있습니다:

work/jobs/<job_id>/transcripts/

각 영상에는 다음이 포함됩니다:

transcript.md
segments.jsonl

6. 학습 문서 생성

video-agent digest <job_id> --index

출력:

work/jobs/<job_id>/digests/
data/video_learning.sqlite

OPENAI_API_KEY가 설정되어 있으면 대형 언어 모델을 호출해 더 풍부한 요약을 생성합니다:

export OPENAI_API_KEY='你的 OpenAI API Key'
video-agent digest <job_id> --index

API Key가 없으면 구조가 완전한 로컬 초안을 생성합니다.

요약 문서 템플릿

각 영상에 대해 Markdown 문서가 생성됩니다:

# 编号｜总结标题

## 0. 这节课的主线流程图
## 1. 知识点
## 2. 老师例子
## 3. 中间用了什么工具、命令、工作流，我们可以学什么
## 4. GitHub 可复现项目
## 5. 我们利用 AI 可以做什么项目
## 6. 今天可以动手做什么
## 7. 学完这节应该留下什么

7번 섹션은 최대한 다음 항목을 포함합니다:

落地产物
输入
步骤
命令
验收标准
效率提升

MCP 사용법

MCP server 시작:

video-agent-mcp

제공 도구:

• ingest_url

• job_status

• run_remote_asr

• pull_transcripts

• digest_transcripts

• search_notes

Claude, Codex, WorkBuddy는 MCP를 지원하기만 하면 이러한 도구를 호출할 수 있습니다.

선택적 Chroma 벡터 저장소

기본 검색은 SQLite 중국어 n-gram이며 오프라인에서 실행할 수 있습니다.

의미 검색을 원하는 경우:

python3 -m pip install chromadb
video-agent index --docs work/jobs/<job_id>/digests --chroma
video-agent search "能做什么 AI 项目" --chroma

보안 안내

• SSH 비밀번호를 video-agent.config.yaml에 작성하지 마세요.

• .env, video-agent.config.yaml, work/jobs/를 커밋하지 마세요.

• GPU 클라우드 호스트는 오디오 다운로드와 ASR만 담당하며, 요약은 기본적으로 로컬에서 실행됩니다.

• 현재 프로젝트는 클라우드 호스트를 자동으로 구매, 중지, 삭제하지 않습니다.

개발 테스트

python3 -m compileall video_learning_agent tests
python3 -m pytest -q