Skip to main content
트레이닝 예시가 이미 프로젝트 외부에 있다면 inference proxy로 트래픽을 기록하는 대신 Management API를 통해 데이터셋에 작성하세요. 이렇게 생성된 데이터셋은 다른 데이터셋과 마찬가지로 재라벨링, 파인튜닝, 평가에 사용할 수 있습니다. 업로드는 Management API를 통해서만 할 수 있습니다. UI에는 생성된 데이터셋이 표시되지만, 파일 선택기는 제공되지 않습니다. 이 페이지에서는 빈 데이터셋을 생성하는 방법, 배치 단위 또는 하나의 JSONL 파일로 행을 추가하는 방법, 평가용으로 따로 남겨 둘 행을 선택하는 방법을 설명합니다.

사전 요구 사항

시작하기 전에 다음 항목이 준비되어 있는지 확인하세요.
  • Model Distillation에 액세스할 수 있는 팀의 W&B API 키. 예시에서는 WANDB_API_KEY 환경 변수에서 이 키를 읽어 Authorization 헤더로 전달하고, Wandb-Entity 헤더에 entity 이름을 지정합니다.
  • 해당 팀의 프로젝트. 프로젝트 별칭은 모든 요청 경로에 포함됩니다. 프로젝트를 만들려면 퀵스타트를 참조하세요.
  • 파일 업로드에서 사용할 탭에 맞는 도구. 다음 구성 중 하나만 있으면 됩니다.
    • curl, jq
    • requests 패키지가 설치된 Python 3.9 이상
    • Node.js 18 이상(추가 패키지 불필요)

작동 방식

모든 업로드는 기존 데이터셋에 추가됩니다. 먼저 빈 데이터셋을 한 번 만든 다음, 다음 두 가지 방법 중 하나로 행을 추가하세요.
  • 항목 쓰기는 한 번의 요청으로 최대 5,000개의 행을 전송하고 결과를 즉시 반환합니다. 소규모 데이터셋이나 증분 추가에 적합합니다.
  • 파일 업로드는 최대 1 GiB, 100,000개 행까지의 JSONL 파일 하나를 객체 저장소로 직접 전송합니다. Model Distillation은 모든 줄을 검증한 후 모든 행을 한 번에 커밋합니다.
두 방법 모두 동일한 행 형식과 규칙을 따릅니다. 쓰기 작업은 모든 행을 커밋하거나 아무것도 변경하지 않으며, 쓰기에 성공할 때마다 데이터셋은 새 리비전으로 바뀝니다. 이때 해당 데이터셋에서 완료된 재라벨링과 평가는 stale 상태로 표시됩니다. 별도로 지정하지 않으면 새 행은 트레이닝 분할에 추가됩니다. 평가용 행을 따로 떼어 두려면 각 행에 split을 설정하거나, 나중에 행의 일부를 옮기세요. 자세한 내용은 검증 행 선택을 참조하세요.

행 준비하기

각 행은 OpenAI Chat Completions 요청이며, 마지막 메시지는 학습 목표로 삼을 assistant 응답입니다. Model Distillation은 앞선 메시지와 tools, tool_choice, response_format(있는 경우)을 입력으로 저장하고, 마지막 assistant 메시지를 출력으로 저장합니다.
각 행에는 최소 2개에서 최대 1,000개의 메시지가 포함되어야 합니다. 메시지 역할은 system, developer, user, assistant, tool 중 하나여야 하며, 마지막 메시지는 assistant 메시지여야 합니다. tools에는 함수 도구를 최대 128개까지, JSON을 최대 1MiB까지 지정할 수 있습니다.

선택 필드

행에는 다음 선택 필드를 포함할 수 있습니다. 행에는 이 외의 최상위 필드를 포함할 수 없습니다.

Append 또는 upsert

모든 쓰기 작업은 다음 두 모드 중 하나로 수행됩니다.
  • 기본값인 append 는 row_id가 데이터셋에 이미 있는 행을 거부합니다.
  • upsert 는 기존 항목을 대체합니다. 새 행에 group_id, split, metadata 또는 provenance가 없으면 기존에 저장된 값이 유지됩니다. 대체된 항목의 재라벨링된 출력은 삭제됩니다.
어느 모드에서든 하나의 요청이나 파일에 같은 row_id가 두 번 나오면 거부되며, 하나의 그룹이 두 분할에 모두 배치되는 쓰기 작업은 group_split_conflict 오류로 실패합니다.

빈 데이터셋 생성

이름만 전송하여 데이터셋을 생성하세요. params 없이 요청하면 바로 사용할 수 있는(ready) 빈 데이터셋이 생성되고, 201 Created 응답이 반환됩니다.
응답에 포함된 id를 기록해 두세요. 다음 예시에서는 이 값을 DATASET_ID로 표기합니다.

항목 쓰기

한 번의 요청으로 최대 5,000개의 행을 추가하려면 행을 JSON 배열로 묶어 entries 엔드포인트로 보내세요. 같은 행을 NDJSON 형식(한 줄에 행 하나)으로 Content-Type: application/x-ndjson과 함께 보낼 수도 있습니다.
응답은 200 OK이며, created, updated, 새 revision, 분할별 entry_counts가 포함됩니다. 유효하지 않은 행이 하나라도 있으면 요청이 거부되며, 오류 메시지에 해당 행의 인덱스가 표시됩니다. NDJSON에서 N번째 줄은 인덱스 N - 1에 해당합니다. 데이터셋을 변경하지 않고 배치를 검사하려면 dry_run=true를 추가하세요. Model Distillation이 행을 검증하고 어떤 내용이 변경될지 알려 준 다음, 쓰기 작업을 롤백합니다.

파일 업로드

한 번의 요청으로 허용되는 크기보다 큰 파일은 업로드 열기, 한 번의 PUT으로 파일 전송, 업로드 완료, 행이 커밋될 때까지 폴링의 네 단계로 업로드하세요. 다음 탭에서는 전체 플로우를 하나의 스크립트로 보여 줍니다. 번호가 매겨진 주석으로 각 단계를 표시했으며, 각 단계에 대한 설명은 스크립트 작동 방식을 참조하세요. 스크립트에서는 프로젝트 별칭으로 ticket-classifier를, 파일 이름으로 tickets.jsonl을 사용하며, 데이터셋 ID는 DATASET_ID 환경 변수에서 읽습니다. 스크립트를 실행하기 전에 entity, 별칭, 파일 이름을 자신의 값으로 바꾸고, 환경 변수 WANDB_API_KEY와 DATASET_ID를 설정하세요. 서로 다른 업로드마다 새로운 idempotency_key를 사용하세요.

스크립트 작동 방식

각 스크립트에서 번호가 붙은 주석은 다음 단계에 해당합니다.
1

업로드 열기

스크립트는 파일 이름, 정확한 바이트 크기, 쓰기 모드를 전송합니다. 요청에는 idempotency_key도 필요하므로, 요청을 재시도하면 업로드를 새로 열지 않고 기존 업로드가 반환됩니다. 같은 키를 다른 요청 본문과 함께 재사용하면 유형이 idempotency_conflict인 409 Conflict가 반환됩니다.응답은 201 Created이며 업로드 정보를 포함합니다. upload.url은 파일용 서명된 URL이고, upload.expires_at은 이 URL이 만료되는 시점입니다. 다음은 해당 필드를 보여 주는 응답의 일부입니다.
2

파일 전송

스크립트는 upload.url에 단일 PUT 요청으로 파일 전체를 전송합니다. 이 URL은 선언된 크기에 바인딩되어 있으므로 본문 길이는 정확히 file.size_bytes와 같아야 합니다. URL 자체에 권한 부여 정보가 포함되어 있으므로 스크립트는 이 요청에 Authorization 또는 Wandb-Entity 헤더를 추가하지 않습니다.URL은 15분 이내에 사용해야 합니다. URL이 만료되면 업로드를 다시 조회하세요. 업로드가 uploading 상태인 동안에는 조회할 때마다 새 URL이 반환됩니다.
3

업로드 완료

파일이 저장되면 스크립트가 업로드를 완료합니다. Model Distillation은 저장된 파일이 선언된 크기와 일치하는지 확인한 후 검증 작업을 큐에 추가합니다. 응답은 202 Accepted입니다.파일이 아직 도착하지 않았다면 유형이 upload_incomplete인 409 Conflict가 반환됩니다. 크기가 일치하지 않으면 유형은 upload_size_mismatch이며 저장된 파일은 폐기됩니다. 두 경우 모두 업로드는 uploading 상태로 유지되므로 파일을 다시 전송한 후 업로드를 다시 완료할 수 있습니다. 이미 완료된 업로드를 다시 완료하면 오류 없이 현재 상태가 반환됩니다.
4

행이 커밋될 때까지 폴링

스크립트는 업로드가 최종 상태에 도달할 때까지 10초마다 업로드를 조회합니다. 검증이 진행되는 동안에는 validation.validated_lines 및 validation.validated_bytes로 진행 상황을 확인할 수 있습니다.state가 committed이면 counters에 rows, created, updated, 새 revision, 분할별 entry_counts가 표시됩니다. state가 failed이면 검증 결과 조회를 참조하세요.데이터셋에서 재라벨링, 평가 또는 미세 조정이 실행 중이면 커밋은 실패하지 않고 해당 작업이 종료될 때까지 대기합니다.

업로드 상태

업로드는 다음 상태를 거칩니다. 생성 후 24시간이 지나도 uploading 상태인 업로드는 더 이상 완료할 수 없습니다. 이 업로드를 완료하려고 하면 유형이 dataset_upload_expired인 410 Gone이 반환되며, 매시간 실행되는 작업이 해당 업로드를 expired 상태로 전환합니다. 업로드가 어떤 상태로 종료되든 저장된 파일은 삭제됩니다.

제한

파일과 업로드에는 다음 제한이 적용됩니다. entity는 Wandb-Entity 헤더에 지정된 팀 또는 개인 계정입니다. 업로드는 uploading, queued, validating 상태인 동안 해당 entity의 제한에 포함됩니다. 두 제한 중 하나라도 초과하는 요청은 429 Too Many Requests를 반환합니다. 여유 용량을 확보하려면 더 이상 필요하지 않은 업로드를 취소하거나 진행 중인 업로드가 종료될 때까지 기다리세요.

검증 결과 확인

failed 업로드는 error에 간단한 요약을 제공하고, 자세한 내용은 validation에 담습니다.
  • error_count는 발견된 문제의 총 개수입니다.
  • errors는 최대 100개의 문제를 줄 순서대로 나열하며, 각 문제에는 line, code, message가 포함됩니다. 커밋 충돌처럼 업로드 전체에 관한 문제의 경우 line은 null입니다.
  • errors_truncated는 목록에 표시된 것보다 문제가 더 많으면 true입니다.
줄 수준 코드로는 invalid_json, invalid_utf8, duplicate_json_key, json_too_deep, row_too_large, empty_line, duplicate_row_id, row_limit_exceeded, validation_failed가 있으며, validation_failed는 행 형식과 일치하지 않는 행에 해당합니다. 업로드 수준 코드로는 entry_exists(append 업로드에 데이터셋에 이미 있는 row_id가 포함된 경우)와 group_split_conflict가 있습니다. 실패한 업로드는 다시 열 수 없습니다. 파일을 수정한 다음 새 업로드를 여세요.

업로드 취소

아직 커밋되지 않은 업로드를 폐기하려면 해당 업로드를 삭제하세요. 그러면 204 No Content 응답이 반환되고, 상태가 cancelled로 바뀌며, 저장된 파일이 삭제됩니다. 이미 취소된 업로드에 같은 요청을 다시 보내도 204 No Content가 반환됩니다.
이미 커밋된 업로드를 취소하면 dataset_upload_committed 유형의 409 Conflict가 반환됩니다. 이 경우 업로드된 행을 제거하려면 데이터셋을 삭제하세요. 자세한 내용은 데이터셋 삭제를 참조하세요.

검증 행 선택

split 값이 없는 행은 트레이닝용으로 사용됩니다. 데이터셋을 업로드한 후 그중 일부를 평가용으로 따로 떼어 두려면 해당 항목을 검증 분할로 옮기세요.
요청은 filters와 row_ids로 항목을 선택합니다. filters는 metadata를 포함해 항목 목록 조회와 동일한 필터를 지원합니다. 둘 다 지정하지 않으면 모든 항목이 선택됩니다. fraction을 지정하면 선택된 그룹 중 해당 비율만큼만 이동합니다. 그룹은 그룹 ID의 다이제스트를 기준으로 순위가 매겨지므로 하나의 그룹이 나뉘는 일이 없으며, 이후 요청에서는 남은 그룹에서 해당 비율을 가져갈 수 있습니다. 특정 고객처럼 하나의 모집단 전체를 홀드아웃하려면 메타데이터로 필터링하세요. 이렇게 하면 모델이 트레이닝 중 한 번도 보지 못한 사용자를 대상으로 평가할 수 있습니다.
응답에는 조건에 일치한 항목 및 그룹 수, 분할이 변경된 항목 수, 새 revision, entry_counts가 포함됩니다. 데이터셋을 변경하지 않고 결과만 확인하려면 dry_run=true를 추가하세요.

오류

항목 요청과 업로드 요청은 다음 오류를 반환할 수 있습니다. 요청 및 응답 스키마는 Management API 레퍼런스의 다음 페이지를 참조하세요.

다음 단계

재레이블링

원본 행은 그대로 둔 채, 더 강력한 모델로 업로드한 데이터셋의 assistant 응답을 다시 작성하세요.

파인튜닝

원본 출력이나 재레이블링된 출력 세트를 사용해 업로드한 데이터셋으로 지원되는 기본 모델을 학습시키세요.
마지막 수정일 2026년 10월 8일