前提条件
開始する前に、以下を準備してください。- 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 を入力として保存し、最後のアシスタント メッセージを出力として保存します。
system、developer、user、assistant、tool を指定でき、最後のメッセージはアシスタントのものである必要があります。tools には最大 128 個の関数ツールと 1 MiB までの JSON を指定できます。
オプションフィールド
行には、次のオプションフィールドを含めることができます。
行には、これら以外のトップレベルフィールドを含めることはできません。
Append または upsert
すべての書き込みは、次の 2 つのモードのいずれかで行われます。append(デフォルト) は、row_idがデータセット内にすでに存在する行を拒否します。upsertは既存のエントリを置き換えます。新しい行でgroup_id、split、metadata、provenanceが省略されている場合は、保存済みの値がそのまま保持されます。置き換えられたエントリのリラベル済みの出力は破棄されます。
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 を新たに指定してください。
- curl
- Python
- JavaScript
スクリプトの仕組み
各スクリプト内の番号付きコメントは、以下の各段階に対応しています。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 リファレンスの次のページを参照してください。
- データセットを作成する
- データセットのエントリを追加または置換する
- データセットのエントリを分割に移動する
- データセットへの JSONL アップロードを開始する
- データセットのアップロードを取得する
- データセットのアップロードを完了する
- データセットのアップロードをキャンセルする
次のステップ
再ラベル付け
元の行は変更せずに、アップロードしたデータセット内のアシスタントの応答を、より高性能なモデルで書き直します。
ファインチューニング
元の出力またはリラベルした出力セットを使用して、サポートされるベースモデルをアップロードしたデータセットでトレーニングします。