사전 요구 사항
시작하기 전에 다음 항목이 준비되어 있는지 확인하세요.- Model Distillation에 액세스할 수 있는 팀의 W&B API 키. 예시에서는
WANDB_API_KEY환경 변수에서 이 키를 읽어Authorization헤더로 전달하고,Wandb-Entity헤더에 entity 이름을 지정합니다. - 해당 팀의 프로젝트. 프로젝트 별칭은 모든 요청 경로에 포함됩니다. 프로젝트를 만들려면 퀵스타트를 참조하세요.
- 파일 업로드에서 사용할 탭에 맞는 도구. 다음 구성 중 하나만 있으면 됩니다.
curl,jq,splitrequests패키지가 설치된 Python 3.9 이상- Node.js 18 이상(추가 패키지 불필요)
업로드 작동 방식
업로드는 프로젝트 범위의 임포트 세션입니다. 세션 하나에는 JSONL 파일이 정확히 하나만 포함되며, 이 파일을 여러 파트로 나누어 오브젝트 스토리지에 직접 전송합니다. 세션은 다음 상태를 거칩니다.
생성 후 7일이 지나도
uploading 상태인 세션은 만료됩니다. 만료된 세션에 대한 파트 요청과 완료 요청은 410 Gone을 반환하며, 매시간 실행되는 작업이 세션을 expired로 전환하고 파트를 폐기합니다. 업로드된 오브젝트와 완료되지 않은 멀티파트 업로드는 세션 완료 여부와 관계없이 작성 후 8일이 지나면 삭제됩니다.
entity는 Wandb-Entity 헤더에 지정된 팀 또는 개인 계정입니다. 각 entity는 세션을 동시에 두 개까지 진행할 수 있으며, 진행 중인 세션들의 선언된 파일 크기 합계는 최대 2 GiB입니다. 세션은 생성 시점부터 ready, failed, cancelled, expired 중 하나에 도달할 때까지 두 한도 모두에 포함됩니다. 두 한도 중 하나라도 초과하는 요청은 429 Too Many Requests를 반환합니다. 용량을 확보하려면 더 이상 필요 없는 세션을 취소하거나 실행 중인 세션이 끝날 때까지 기다리세요.
파일 준비
임포트 세션을 생성하기 전에 파일이 행 형식에 맞는지, 그리고 이 섹션에 설명된 제한을 넘지 않는지 확인하세요. 검증은 업로드를 완료한 후에만 실행되며, 실패한 세션은 다시 열 수 없습니다. 형식 문제를 해결하려면 새 세션을 생성하고 파일을 다시 업로드하세요. 파일은 UTF-8 JSONL 형식이어야 합니다. 즉, 한 줄에 JSON 객체가 하나씩 있어야 하며, 한 객체 안에 중복된 키가 없어야 합니다.행 형식
각 행은 OpenAI Chat Completions 요청이며, 마지막 메시지는 학습 목표로 삼을 assistant 응답입니다. Model Distillation은 앞선 메시지와tools, tool_choice, response_format(있는 경우)을 입력으로 저장하고, 마지막 assistant 메시지를 출력으로 저장합니다.
tools에는 함수 도구를 최대 128개까지, JSON을 최대 1MiB까지 지정할 수 있습니다. 마지막 메시지가 assistant 메시지가 아닌 행은 missing_assistant_target 오류로 실패합니다.
선택 필드
각 행에는 다음 선택 필드를 포함할 수 있습니다.
행에는 이 외의 최상위 필드를 포함할 수 없습니다.
제한
파일과 임포트 세션은 다음 제한을 넘지 않아야 합니다.파일 업로드
업로드는 세션 생성, 파일 분할 업로드, 업로드 완료, 데이터셋이 준비될 때까지 폴링의 단계로 진행됩니다. 다음 탭에서는 전체 플로우를 하나의 스크립트로curl, Python, JavaScript 버전별로 보여 줍니다. 번호가 매겨진 주석으로 각 단계를 표시했으며, 각 단계에 대한 설명은 스크립트 작동 방식을 참조하세요.
스크립트에서는 프로젝트 별칭으로 ticket-classifier를, 파일 이름으로 tickets.jsonl을 사용합니다. 스크립트를 실행하기 전에 entity, 별칭, 파일 이름을 자신의 값으로 바꾸고, 환경 변수 WANDB_API_KEY를 설정하세요. 서로 다른 업로드마다 새로운 idempotency_key를 사용하세요.
- curl
- Python
- JavaScript
스크립트 작동 방식
각 스크립트에서 번호가 매겨진 주석은 다음 단계에 해당합니다.1
임포트 세션 생성
스크립트는 파일 이름과 정확한 바이트 크기, 분할 정책, 그리고 선택 사항인 중복 정책을 전송합니다. 각 정책의 동작은 분할 및 중복을 참조하세요. 요청에는 고유한
idempotency_key도 필요합니다. 따라서 요청을 재시도하면 세션이 새로 생성되지 않고 기존 세션이 반환됩니다.응답은 세션 정보가 포함된 201 Created입니다. 스크립트는 응답에서 id, file.part_size_bytes, file.part_count를 저장해 둡니다. 다음은 해당 필드를 보여 주는 응답의 일부입니다.2
업로드 URL 요청
스크립트는 1부터
file.part_count까지 모든 파트 번호에 대해 서명된 URL을 요청합니다. 응답에는 각 part_number와 해당 url, 그리고 expires_in_seconds가 포함됩니다. 각 URL은 15분 동안 유효합니다. URL을 사용하기 전에 만료되었다면 다시 요청하세요.3
파트 업로드
스크립트는 파일을
file.part_size_bytes 크기의 청크 단위로 읽고, 각 청크를 해당 파트 번호의 URL로 PUT 요청을 보내 전송합니다. 파트 번호는 1부터 시작하므로 첫 번째 청크가 파트 1입니다. 마지막 파트를 제외한 모든 파트는 크기가 정확히 file.part_size_bytes여야 하며, 마지막 파트에는 남은 데이터가 담깁니다. 파트는 순서에 상관없이 병렬로 전송할 수 있습니다.서명된 URL에는 자체 인증 정보가 포함되어 있으므로, 스크립트는 이 요청에 Authorization 또는 Wandb-Entity 헤더를 추가하지 않습니다.4
선택: 업로드된 파트 확인
전송이 중단된 후 재개하려면 세션을 조회하세요.
file.parts에는 업로드된 각 파트와 그 크기가 나열되고, file.uploaded_bytes에는 그 합계가 표시됩니다. 누락된 파트가 있으면 새 URL을 요청해 다시 전송하세요. Python 및 JavaScript 스크립트는 누락된 파트 번호를 계산하고, curl 스크립트는 업로드된 파트 목록을 출력합니다. 중단 없이 한 번에 실행하면 누락된 파트가 생기지 않으므로, 누락된 파트를 재전송하는 스크립트는 없습니다.5
업로드 완료
모든 파트가 업로드되면 스크립트가 업로드를 완료합니다. Model Distillation은 파트가 선언된 크기와 일치하는지 확인하고, 다이제스트를 계산한 다음, 검증 및 데이터셋 생성 작업을 큐에 추가합니다.응답은
202 Accepted입니다. 누락된 파트가 있으면 유형이 upload_incomplete인 409 Conflict가 반환됩니다. 파트 크기가 잘못되었으면 유형은 upload_manifest_mismatch입니다. 두 경우 모두 세션이 uploading 상태로 유지되므로, 파트를 수정한 뒤 업로드 완료를 다시 요청할 수 있습니다. 이미 완료된 업로드에 완료를 다시 요청하면 오류 없이 현재 세션이 반환됩니다.6
데이터셋이 준비될 때까지 폴링
스크립트는
state가 ready 또는 failed가 될 때까지 10초마다 세션을 조회합니다. 검증이 진행되는 동안 validation.validated_rows에는 파싱된 행 수가 집계되고, counters에는 staged_rows, rejected_rows, rows_by_split이 표시됩니다.state가 ready이면 dataset_id로 새 데이터셋을 식별할 수 있습니다. 이 ID를 재레이블링, 파인튜닝, 평가에 사용하거나 UI에서 데이터셋을 열어 보세요. state가 failed이면 검증 결과 조회를 참조하세요.분할과 중복
split_policy는 행을 트레이닝 분할과 검증 분할로 나누는 방식을 결정합니다.
- **
preserve**는 각 행의split값을 그대로 유지합니다.split이 없는 행은missing_split오류와 함께 검증에 실패합니다. - **
automatic**은 행에 지정된split값을 모두 무시합니다. 각 행의group_id를 해시하며,group_id가 없으면 행 ID를 대신 해시합니다. 그런 다음val_fraction에 지정된 비율만큼의 행을 검증 분할에 할당합니다. 기본 비율은 0.2입니다.group_id가 같은 행은 항상 같은 분할에 할당됩니다.
duplicate_policy.split_overlap은 분할 할당 후 동일한 입력이 두 분할에 모두 존재할 때의 처리 방식을 결정합니다.
reject(기본값)는 겹치는 행마다 검증 오류를 기록하며, 임포트가 실패합니다.- **
drop_train**은 트레이닝 분할의 사본을 삭제하고 검증 분할의 사본을 유지합니다.
row_id가 두 번 이상 나타나면 어떤 정책을 사용하든 duplicate_row_id 오류와 함께 검증에 실패합니다.
검증 결과 확인
failed 세션은 error에 간단한 요약을 제공하고, 자세한 내용은 validation에 담습니다.
error_count는 발견된 문제의 총 개수입니다.errors는 최대 100개의 문제를 줄 순서대로 나열하며, 각 문제에는physical_line,code,message가 포함됩니다.errors_truncated는 목록에 표시된 것보다 문제가 더 많으면true입니다.
invalid_json, invalid_utf8, duplicate_json_key, row_too_large, missing_assistant_target, tools_too_large, missing_split, duplicate_row_id가 있습니다. 파일을 수정한 다음 새 세션을 생성하세요. 실패한 세션은 다시 열 수 없습니다.
업로드 취소
세션을 폐기하려면 세션을 삭제하세요. 취소는ready를 제외한 모든 상태에서 가능하므로, 아직 검증 중이거나 실패한 세션도 중단할 수 있습니다. 응답으로 204 No Content가 반환되고, 상태가 cancelled로 바뀌며, 업로드된 파트는 폐기되고 일부만 생성된 데이터셋도 모두 제거됩니다. 이미 취소된 세션에 같은 요청을 다시 보내도 204 No Content가 반환됩니다.
ready 상태에 도달한 세션에서는 유형이 dataset_import_ready인 409 Conflict가 반환됩니다. 이 세션에서 생성된 데이터셋을 제거하려면 대신 해당 데이터셋을 삭제하세요. 자세한 내용은 데이터셋 삭제를 참조하세요.
오류
임포트 세션 요청은 다음 오류를 반환할 수 있습니다.
요청 및 응답 스키마는 Management API 레퍼런스의 다음 페이지를 참조하세요.
다음 단계
재레이블링
원본 행은 그대로 둔 채, 더 강력한 모델로 업로드한 데이터셋의 assistant 응답을 다시 작성하세요.
파인튜닝
원본 출력이나 재레이블링된 출력 세트를 사용해 업로드한 데이터셋으로 지원되는 기본 모델을 학습시키세요.