LLM API 요청 추적하기
코드에서 시작한 LLM API 요청 하나가 GPU까지 갔다가 돌아오는 과정을 따라가며, 각 단계에 시간이 얼마나 걸리는지 살펴보는 시각 자료다.
이 자료가 무엇을 누구에게 가르치고 어떤 내용을 전달해야 하는지는 아래 브리프에 담겼다. 구현은 src/에 있다.
코딩 에이전트를 사용한다면 저장소 루트의 AGENTS.md에 있는 작업 규칙을 먼저 읽어야 한다.
완성된 영상은 전체 영상과 짧은 홍보 영상에서 볼 수 있다.
구성과 실행 조건
자료는 각자 브리프와 코드, 렌더링 스크립트를 갖춘 두 부분으로 나뉜다.
- 전체 설명 영상은 16:9 비율에 4~5분 분량이다. 브리프는 brief-full.md, 코드는
src/full/, 렌더링 스크립트는./render-full.sh다. 현재 상태는 v15(5:18)다. 짧은 영상은 홍보 영상이며, 썸네일은thumbnails/…-full-…에 있다. 게시 안내는 YouTube 게시 안내와 소셜 게시 안내에서 확인할 수 있다. - 홍보 영상은 16:9 비율의 2D·3D 버전으로 구성되며, 3D 버전은 9:16 짧은 영상도 제공한다. 브리프는 brief-promo.md, 코드는
src/promo/, 렌더링 스크립트는./render-promo.sh다. 상태는 승인됨이다.
두 부분은 페이지 캡처 코드와 3D 세계를 src/shared/에서 공유한다. 각 부분에는 별도의 렌더링 스크립트가 있으며, 두 부분을 한꺼번에 렌더링하는 스크립트는 없다.
프로젝트는 macOS 26(Apple silicon)에서 테스트됐다. Node.js 20 이상과 npm, ffmpeg가 필요하다. Playwright용 Chromium은 npm ci를 실행한 뒤 한 번 설치한다. 영상은 헤드리스 Chromium에서 웹페이지를 프레임 단위로 캡처해 만들며, 3D 버전은 소프트웨어 렌더링(SwiftShader)을 사용해 어느 컴퓨터에서나 프레임이 동일하게 나오도록 한다.
brew install node
brew install ffmpeg
npx playwright install chromium
렌더링 스크립트는 package-lock.json에 버전이 고정된 Playwright와 three.js를 위해 npm ci를 직접 실행한다. JetBrains Mono 글꼴(OFL)은 assets/fonts/에 들어 있다.
직접 실행하기
./render-full.sh # final: 전체 영상, 음악 포함 4K + 무음 4K + 음악 포함 1080p
# -> workspace/full/preview/<timestamp>/, workspace/full/export/에도 하드 링크로 생성
./render-full.sh draft # 720p 초안(음악 포함 및 무음) -> workspace/full/preview/<timestamp>/
./render-full.sh draft v2 # 동일한 초안, 지정한 버전 이름 사용 -> workspace/full/preview/v2/
./render-full.sh final v2 # 최종 화질, 지정한 버전 이름 사용 -> workspace/full/preview/v2/
./render-promo.sh [draft|final] [version] # 홍보 영상도 같은 방식으로 렌더링(workspace/promo/preview/, workspace/promo/export/): 두 버전 모두 16:9, 3D는 9:16도 제공
PROMOS=promo3d ./render-promo.sh draft v2 # 3D 홍보 영상만 렌더링(2D만 렌더링하려면 PROMOS=promo2d)
PROMO_FORMATS=16x9 ./render-promo.sh … # 세로형 짧은 영상 생략(PROMO_VERTICAL="promo2d promo3d"로 설정하면 두 영상 모두 세로형으로 렌더링)
파일 이름은 전체 영상의 경우 tracing-llm-api-request-<version>-16x9-4k.mp4, 2D 홍보 영상은 tracing-llm-api-request-promo2d-<version>-16x9-4k.mp4, 3D 홍보 영상은 …-promo3d-… 형식이다. 짧은 영상 파일에는 …-9x16-…이 붙고, 각 영상에는 -silent와 -1080p 변형 파일도 있다.
렌더링할 때마다 YouTube 썸네일을 thumbnails/에 생성하고 저장소에서 추적한다. 최종 렌더링은 썸네일을 workspace/full/export/thumbnails/ 또는 workspace/promo/export/thumbnails/에도 복사한다. 3D 영상을 최종 렌더링하는 데는 시간이 걸리며, 4K 소프트웨어 WebGL 렌더링이 그 이유다.
수정 방법
코딩 에이전트(Claude Code, Codex, OpenCode 등)를 사용하려면 이 프로젝트 디렉터리에서 시작한다. 먼저 전체 영상은 brief-full.md, 홍보 영상은 brief-promo.md를 수정한다. 방법을 지시하기보다 원하는 결과를 적는다. 예를 들어 Deliverables 아래에 “홍보 영상 음악: 차분한 솔로 피아노”라고 쓸 수 있다.
그다음 에이전트에 초안 제작을 요청한다. 예를 들면 “브리프에 맞춰 홍보 영상을 수정하고 초안을 렌더링해 줘”라고 한다. 에이전트는 src/를 수정하고 홍보 영상은 workspace/promo/preview/v1/, 전체 영상은 workspace/full/preview/v1/에 렌더링한다. 이후 초안은 각각 v2, v3 등으로 저장하며 두 영상의 버전 번호는 서로 별도로 관리한다.
초안을 확인한 뒤에는 가능하면 타임스탬프를 붙여 의견을 전달한다. 예를 들어 “0:13: 라우터 장면이 너무 급하게 지나간다”라고 할 수 있다. 에이전트가 의견을 반영해 다음 초안을 렌더링하며, 만족할 때까지 이 과정을 반복한다. 승인한 뒤에는 “v3 승인, 최종 화질로 렌더링해 줘”라고 요청하거나 ./render-full.sh final v3 또는 ./render-promo.sh final v3를 직접 실행한다.
코드를 직접 수정하는 방법도 있다. 수정 후 전체 영상은 ./render-full.sh draft <next version>을, 홍보 영상은 ./render-promo.sh를 실행한다.
전체 설명 영상의 src/full/full2d.html은 seek(t)라는 시간 함수에 따라 장면을 표시한다. 전체 경로를 보여주는 2D 지도와 줌 카메라, 전환 장면과 제목 카드, 프롬프트 캐싱·배칭·KV 캐시·분리형 프리필(disaggregated prefill)·추측 디코딩(speculative decoding)·스트리밍·요약 장면, 엔드 카드와 자막이 포함된다. src/full/full.html은 같은 영상의 초기 3D 실험본이다. 다음 명령으로 이를 렌더링할 수 있다.
PAGE=src/full/full.html ./render-full.sh
src/full/thumbnails.mjs는 영상 프레임을 바탕으로 16:9 YouTube 썸네일을 만든다. 디자인은 question, optimize, time이다. src/full/youtube.mjs는 페이지의 window.CHAPTERS를 바탕으로 youtube-publishing-full.md에 챕터를 작성하며, 최종 렌더링 때 실행돼 YouTube 규칙도 확인한다. src/full/music.mjs는 영상 음악을 만든다. 기본 옵션 u2는 경쾌하면서 차분한 칼림바 아르페지오에 따뜻한 패드와 베이스를 더한 구성이다. 다른 --option 값은 비교하거나 리믹스할 수 있는 변형이다. 최적화 슬라이드에서는 음악이 커지고 장면이 복잡할 때는 작아지며, 페이지의 window.MUSIC_CUES가 이를 조절한다.
홍보 영상의 src/promo/promo.html도 seek(t)에 따라 움직인다. 프롬프트, 토큰, 응답, 예시별 시간, 2D 장면, 스톱워치, 단계 제목과 타임라인, 속도 조절 값 PACE가 담겼다. 브라우저에서 열어 장면을 살펴볼 수 있으며, 주소에 ?3d를 더하면 3D 버전, ?portrait를 더하면 세로형 레이아웃이 나온다. src/promo/music.mjs에는 홍보 영상의 컷에 맞춘 음악이 있고, 각 부분은 capture.mjs --print-cues로 확인할 수 있다. src/promo/thumbnails.mjs는 깔끔한 3D 프레임 위에 제목을 얹은 YouTube 썸네일을 만든다. 디자인은 promo.html?3d&clean의 DESIGNS에 있으며, path 썸네일은 클라이언트에서 GPU까지의 이동 경로와 각 단계의 시간을 보여준다.
공유 코드인 src/shared/world3d.js는 두 페이지에서 사용하는 three.js 기반 3D 여정을 구현한다. 카메라 경로를 따라 각 단계의 위치를 두고 추적 카메라를 조절하는 camAt도 포함한다. src/shared/capture.mjs는 Playwright로 페이지를 영상으로 렌더링한다. --page로 페이지를 지정하며, 기본값은 홍보 영상이다. --segments 10 --cache <dir>를 사용하면 페이지의 window.SCENE_STARTS를 기준으로 장면을 나눠 캐시하고, --plan은 다시 렌더링할 부분을 표시한다.
src/shared/clip.mjs는 렌더링 전체를 거치지 않고 페이지의 짧은 영상이나 한 프레임을 만든다.
node src/shared/clip.mjs --page src/full/full2d.html --range 45-50 --out workspace/tmp/clip.mp4
정지 화면을 만들 때는 --range 대신 --at 78.5를 사용한다. src/shared/render-common.sh에는 두 렌더링 스크립트가 공유하는 인자 처리, 출력 폴더, npm ci, 내보내기 기능이 있다.
검증
변경 내용을 커밋하기 전에 코딩 에이전트에 새 복제본 테스트 또는 재현 테스트를 요청한다. 이 테스트는 Git이 추적하는 파일만 복사한 뒤 렌더링하고, 결과물이 승인된 버전과 일치하는지 확인한다. 전체 영상을 최종 화질로 한 번 렌더링해야 하므로 시간이 걸린다.
댓글 (0)
로그인하면 이 기사에 내 생각을 남길 수 있어요