데이터셋 처음부터 끝까지 (v1.2.1+)

학습 데이터셋을 만들고, 올리고, 버전으로 고정하고, 내려받는 한 바퀴를 순서대로 따라갑니다. 화면 캡처는 모두 실제 운영 환경에서 이 순서를 그대로 밟으며 찍은 것입니다.

각 절의 기능 설명은 학습 데이터셋 과 CLI·Python 가이드 에 있습니다. 이 문서는 순서를 다룹니다.

준비물

필요한 것	확인 방법
GenD 계정 (analyst 이상)	로그인 후 사이드바에 학습 데이터셋 이 보이면 됩니다
워크스페이스 소속	소속이 없으면 데이터셋을 만들 수 없습니다
Python 3.10+ (CLI 를 쓸 경우)	python3 --version

:::info 권한을 새로 받았다면 2~3분 기다리세요 워크스페이스에 새로 추가됐다면 쿼리 엔진에 반영되기까지 동기화 주기가 있습니다. 그 전에는 적재가 실패할 수 있습니다 — 잠시 뒤 다시 시도하세요. :::

1단계 — 데이터셋 만들기 (UI)

사이드바 학습 데이터셋 으로 들어갑니다. 이미 있는 데이터셋 목록과 스토리지 사용량이 보입니다.

오른쪽 위 새 데이터셋 을 누릅니다.

이름과 모달리티를 정합니다. 모달리티는 나중에 바꿀 수 없으니 올릴 데이터에 맞게 고르세요.

고를 것	올릴 데이터
텍스트	instruction JSONL — chat / prompt-response / DPO
이미지	이미지 파일 또는 zip (HF imagefolder 구조)
비디오	MP4 · WebM 개별 파일
이미지+텍스트	아직 데이터를 넣을 수 없습니다 — #3258

:::warning 이미지+텍스트는 지금 고르지 마세요 생성은 되지만 어떤 경로로도 데이터를 넣을 수 없습니다. 업로드를 시도하면 400 이 납니다. 이미지와 캡션을 함께 다루려면 지금은 이미지 로 만들고 zip 안에 metadata.jsonl 로 캡션을 주세요. :::

생성 을 누르면 상세 화면으로 이동합니다. 화면 상단에 Iceberg 테이블 좌표 (iceberg.ws_<워크스페이스>.ds_...)가 표시됩니다 — SQL 편집기에서 그대로 조회할 수 있는 이름입니다.

2단계 — 데이터 올리기

UI 의 업로드 버튼으로도 되고, 스크립트에서는 CLI 가 편합니다.

CLI 설치

pip install "gend-cli @ git+https://github.com/genonai/DataX.git@main#subdirectory=apps/cli"
gend auth login          # 브라우저 SSO

외부 학습 서버처럼 브라우저가 없는 곳은 개인 트래킹 키 를 씁니다.

텍스트 — 먼저 미리보기

텍스트는 적재 전에 --dry-run 으로 파싱 결과를 확인할 수 있습니다. 서브포맷을 잘못 추론했거나 파싱 오류가 있으면 여기서 드러납니다.

gend dataset upload <데이터셋ID> data.jsonl --dry-run
#   data.jsonl: +0 rows (subformat=prompt_response, dup=0, parse_err=0)
#   dry-run (미적재) 완료: rows +0 · 중복 스킵 0 · 파싱 오류 0

이상 없으면 --dry-run 을 빼고 실행합니다.

gend dataset upload <데이터셋ID> data.jsonl
#   data.jsonl: +5 rows (subformat=prompt_response, dup=0, parse_err=0)
#   적재 완료: rows +5 · 중복 스킵 0 · 파싱 오류 0
#   snapshot: 7763663159512757041   ← 3단계에서 씁니다

snapshot 값을 적어 두세요. 버전을 고정할 때 필요합니다.

:::tip HF TRL 형식을 그대로 받습니다 prompt+completion 으로 올려도 됩니다 — 저장 시 response 로 정규화되고 원본 키는 meta 에 보존됩니다. 키를 바꿔 쓸 필요가 없습니다. :::

이미지 — zip 폴더 구조가 split·label 이 됩니다

images.zip
├── train/cat/1.png     → split=train, label=cat
├── train/dog/1.png     → split=train, label=dog
└── valid/cat/1.png     → split=validation (valid 는 자동 정규화)

gend dataset upload <데이터셋ID> images.zip
#   배치 1/1 — 1개 (1,509B)
#   업로드 완료: accepted 3 · rows +3 · 중복 스킵 4 · 거부 0

중복 스킵은 손실이 아닙니다. 같은 바이트의 이미지는 content_hash 로 한 번만 저장됩니다. 그래서 같은 명령을 다시 돌려도 안전합니다(멱등).

비디오 — 개별 파일로

gend dataset upload <데이터셋ID> clip.mp4
#   업로드 완료: accepted 1 · rows +1 · 중복 스킵 0 · 거부 0

:::warning 비디오는 zip 으로 올릴 수 없습니다 서버의 zip 추출 경로는 이미지 확장자만 훑습니다. 비디오 zip 은 오류 없이 0건으로 끝나 "올렸는데 아무것도 없는" 상태가 됩니다. 개별 파일로 올리세요. :::

확장자만 바꾼 파일은 거부됩니다 — 서버가 컨테이너 시그니처를 검사합니다.

gend dataset upload <데이터셋ID> fake.mp4
#   거부: fake.mp4: mp4 컨테이너 시그니처(ftyp)가 아닙니다

3단계 — 올라간 데이터 확인 (UI)

데이터셋 상세의 데이터 탭입니다.

텍스트는 표로 보입니다. split, content_hash, 각 필드가 그대로 나옵니다.

이미지·비디오는 갤러리 보기가 기본입니다. 카드 아래에 라벨(없으면 split 배지)이 붙습니다. 오른쪽 위 토글로 표 보기로 바꿀 수 있고, 행 선택·삭제는 표 보기에서만 됩니다.

비디오는 목록을 스크롤하는 동안 원본을 내려받지 않습니다 — 재생 버튼을 누른 클립만 로드됩니다.

4단계 — 버전 고정

데이터가 나중에 추가·삭제돼도 그 시점 그대로 조회되는 스냅샷을 만듭니다. "이 모델이 어느 데이터로 학습됐는지" 를 재현하려면 이 단계가 필요합니다.

UI 의 버전 탭에서 2단계의 snapshot ID 를 넣거나, API 로:

curl -X POST "$GEND_API_URL/api/v1/datasets/<데이터셋ID>/versions" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"snapshot_id":"7763663159512757041","note":"1차 학습용"}'

gend dataset versions <데이터셋ID>
#   Version 1 · Snapshot 77636631… · Rows 10 · Note 1차 학습용

:::caution 새 행이 0건이면 snapshot 이 없습니다 올린 데이터가 전부 중복이면 서버가 새 snapshot 을 만들지 않습니다. CLI 가 snapshot 없음 — 새 행이 0건이라… 로 알려줍니다. 이때는 고정할 시점이 없는 것이 정상입니다. :::

5단계 — 내려받기

버전 번호로 내려받습니다. S3 자격증명은 필요 없습니다 — API 를 경유합니다.

gend dataset download <데이터셋ID> --version 1 -o ./out
#   저장 완료: ./out/<데이터셋이름>-v1.jsonl (3,747B, parts=1)

이미지·비디오 원본까지 받으려면 --with-blobs 를 붙이면 blobs/ 아래에 저장됩니다.

올린 것이 그대로 돌아오는지 확인

wc -l ./out/<데이터셋이름>-v1.jsonl     # 10

내려받은 JSONL 은 저장된 스키마 그대로입니다 — record_id, content_hash, split, meta 와 각 필드가 함께 나옵니다. 업로드할 때 completion 으로 보냈다면 response 로 정규화되어 있습니다.

막혔을 때

증상	원인과 대처
생성이 403	워크스페이스 소속이 없거나 write 바인딩이 없습니다. 관리자에게 요청하세요
적재가 502	권한이 엔진에 아직 반영되지 않았을 수 있습니다 — 2~3분 뒤 재시도, 그래도 실패하면 관리자 문의
적재가 400 ("modality")	데이터셋 모달리티와 파일 종류가 다릅니다. image_text 는 현재 적재 경로가 없습니다
업로드는 성공인데 0건	비디오를 zip 으로 올렸을 수 있습니다 — 개별 파일로 올리세요
중복 스킵이 많다	같은 바이트는 한 번만 저장됩니다(정상). 라벨만 바꿔 다시 올려도 반영되지 않습니다
버전 생성이 422	snapshot ID 가 비었거나 형식이 틀렸습니다. 업로드 출력의 snapshot: 값을 문자열로 넣으세요

이 문서의 검증 범위

2026-08-08 운영 환경에서 analyst 권한 계정으로 위 순서를 그대로 실행해 캡처했습니다. 확인한 것:

• UI 로그인 → 4개 모달리티 데이터셋 생성
• CLI 로 텍스트(JSONL) · 이미지(zip) · 비디오(mp4) 적재
• UI 에서 행·갤러리 표시 확인
• 버전 고정 → 다운로드 → 업로드분 10건과 대조(누락 0 · 예상밖 0)
• 위장 파일(확장자만 mp4) 거부 확인

image_text 는 적재 경로가 없어 생성까지만 확인했습니다(#3258).