Skip to main content
トレーニング用のサンプルが project の外部にすでにある場合は、推論プロキシ経由でトラフィックを記録する代わりに、Management API を使用してデータセットに書き込めます。作成されたデータセットは、他のデータセットと同様に再ラベル付け、ファインチューニング、評価に使用できます。 アップロードは Management API からのみ実行できます。UI には作成されたデータセットが表示されますが、ファイルを選択してアップロードする機能はありません。 このページでは、空のデータセットを作成する方法、行をバッチ単位または 1 つの JSONL ファイルとして追加する方法、および評価用に取り分けておく行を選択する方法について説明します。

前提条件

開始する前に、以下を準備してください。
  • Model Distillation へのアクセス権を持つチームの W&B APIキー。サンプルでは、このキーを WANDB_API_KEY 環境変数から読み取って Authorization ヘッダーで渡し、entity を Wandb-Entity ヘッダーで指定します。
  • そのチーム内の project。project のエイリアスはすべてのリクエストパスに含まれます。project の作成方法については、クイックスタートを参照してください。
  • ファイルをアップロードするで使用するタブに応じたツール。以下のいずれか 1 つのセットがあれば十分です。
    • curl と jq。
    • Python 3.9 以降と requests パッケージ。
    • Node.js 18 以降 (追加パッケージは不要) 。

仕組み

アップロードはすべて既存のデータセットに対して行います。まず空のデータセットを一度作成し、次の 2 つの方法のいずれかで行を追加します。
  • エントリを書き込む は、1 回のリクエストで最大 5,000 行を送信し、結果をすぐに返します。小規模なデータセットや段階的な追加に適しています。
  • ファイルをアップロードする は、最大 1 GiB、100,000 行までの JSONL ファイル 1 つをオブジェクトストレージに直接送信します。Model Distillation はすべての行を検証したうえで、全行を一括でコミットします。
どちらの方法でも、行の形式とルールは共通です。書き込みでは、すべての行がコミットされるか、何も変更されないかのどちらかになります。書き込みが成功するたびに、データセットは新しいリビジョンに移行します。その時点で、そのデータセットに対する完了済みのリラベルと評価は古いものとしてマークされます。 新しい行は、特に指定しない限りトレーニング分割に追加されます。評価用に行を取り分けておくには、各行に split を設定するか、追加後に行の一部を移動します。詳しくは、検証用の行を選択するを参照してください。

行を準備する

各行は OpenAI Chat Completions リクエストで、その最後のメッセージがトレーニングの目標とするアシスタントの応答です。Model Distillation は、それより前のメッセージと、指定されている場合は tools、tool_choice、response_format を入力として保存し、最後のアシスタント メッセージを出力として保存します。
各行には 2 件以上のメッセージが必要で、最大 1,000 件まで含めることができます。メッセージのロールには system、developer、user、assistant、tool を指定でき、最後のメッセージはアシスタントのものである必要があります。tools には最大 128 個の関数ツールと 1 MiB までの JSON を指定できます。

オプションフィールド

行には、次のオプションフィールドを含めることができます。 行には、これら以外のトップレベルフィールドを含めることはできません。

Append または upsert

すべての書き込みは、次の 2 つのモードのいずれかで行われます。
  • append (デフォルト) は、row_id がデータセット内にすでに存在する行を拒否します。
  • upsert は既存のエントリを置き換えます。新しい行で group_id、split、metadata、provenance が省略されている場合は、保存済みの値がそのまま保持されます。置き換えられたエントリのリラベル済みの出力は破棄されます。
どちらのモードでも、1 つのリクエストまたはファイル内で同じ row_id が 2 回出現すると拒否されます。また、1 つのグループが両方の分割に属することになる書き込みは、group_split_conflict で失敗します。

空のデータセットを作成する

名前のみを送信してデータセットを作成します。params を指定しない場合、このリクエストでは空のデータセットが作成され、すぐに準備完了状態になります。応答は 201 Created です。
応答に含まれる id を控えておいてください。以降の例では、これを DATASET_ID と表記します。

エントリを書き込む

1 回のリクエストで最大 5,000 行を追加するには、行を JSON 配列にまとめて entries エンドポイントに送信します。Content-Type: application/x-ndjson を指定すれば、同じ行を NDJSON 形式 (1 行につき 1 行分のデータ) で送信することもできます。
応答は 200 OK で、created、updated、新しい revision、および分割ごとの entry_counts が返されます。無効な行が 1 つでもあるとリクエストは拒否され、エラーには該当する行がインデックスで示されます。NDJSON では、N 行目がインデックス N - 1 に対応します。 データセットを変更せずにバッチを検証するには、dry_run=true を追加します。Model Distillation は行を検証して変更内容を報告し、書き込みをロールバックします。

ファイルをアップロードする

1 回のリクエストで送信できるサイズを超えるファイルは、アップロードの開始、1 回の PUT によるファイルの送信、アップロードの完了、行がコミットされるまでのポーリングという 4 つの段階でアップロードします。以下のタブでは、一連の流れを 1 つのスクリプトにまとめて示しています。各段階は番号付きのコメントで示しており、それぞれの詳細は スクリプトの仕組み で説明しています。 スクリプトでは、project のエイリアスに ticket-classifier、ファイル名に tickets.jsonl を使用し、データセット ID を環境変数 DATASET_ID から読み取ります。スクリプトを実行する前に、entity、エイリアス、ファイル名をご自身の値に置き換え、環境変数 WANDB_API_KEY と DATASET_ID を設定してください。また、アップロードごとに一意の idempotency_key を新たに指定してください。

スクリプトの仕組み

各スクリプト内の番号付きコメントは、以下の各段階に対応しています。
1

アップロードを開始する

スクリプトは、ファイル名、その正確なバイトサイズ、および書き込みモードを送信します。リクエストには idempotency_key も必要です。これにより、リクエストを再試行しても 2 つ目のアップロードは開始されず、既存のアップロードが返されます。同じキーを異なるリクエストボディで再利用すると、タイプ idempotency_conflict の 409 Conflict が返されます。応答は 201 Created で、アップロードが含まれます。upload.url はファイル用の署名付き URL で、upload.expires_at はその URL が無効になる日時です。以下の抜粋はこれらのフィールドを示しています。
2

ファイルを送信する

スクリプトは、ファイル全体を 1 回の PUT リクエストで upload.url に送信します。URL は宣言されたサイズに紐付けられているため、ボディの長さは file.size_bytes と正確に一致している必要があります。URL 自体に認可情報が含まれているため、スクリプトはこのリクエストに Authorization ヘッダーや Wandb-Entity ヘッダーを追加しません。URL は 15 分以内に使用する必要があります。有効期限が切れた場合は、アップロードを再度読み取ってください。アップロードが 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 が返されます。また、1 時間ごとに実行されるジョブによって 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 が返されます。
すでにコミット済みのアップロードをキャンセルしようとすると、409 Conflict (タイプ dataset_upload_committed) が返されます。アップロード済みの行を削除するには、データセット自体を削除してください。詳しくは、データセットを削除するを参照してください。

検証用の行を選択する

split 値が設定されていない行はトレーニングに使用されます。アップロード後にデータセットの一部を評価用として確保しておくには、エントリを検証用の分割に移動します。
リクエストでは、filters と row_ids を使用してエントリを選択します。filters には、metadata を含め、エントリ一覧と同じフィルターを指定できます。どちらも指定しない場合は、すべてのエントリが選択されます。fraction を指定すると、選択されたグループのうち、その割合分のみが移動されます。グループはグループ ID のダイジェストに基づいて順位付けされるため、1 つのグループが分割されることはありません。また、後続のリクエストでは、残りのグループから割合分を取得できます。 特定のお客様など、母集団全体をホールドアウトするには、代わりにメタデータでフィルターします。これにより、トレーニング中にモデルが一度も見ていないユーザーを対象に、モデルを評価できます。
応答には、一致したエントリ数とグループ数、分割が変更された件数、新しい revision、および entry_counts が含まれます。データセットを変更せずに結果を確認するには、dry_run=true を追加します。

エラー

エントリとアップロードのリクエストでは、次のエラーが返される場合があります。 リクエストと応答のスキーマについては、Management API リファレンスの次のページを参照してください。

次のステップ

再ラベル付け

元の行は変更せずに、アップロードしたデータセット内のアシスタントの応答を、より高性能なモデルで書き直します。

ファインチューニング

元の出力またはリラベルした出力セットを使用して、サポートされるベースモデルをアップロードしたデータセットでトレーニングします。
最終更新日 2026年10月8日