前提条件
開始する前に、以下を準備してください。- Model Distillation へのアクセス権を持つチームの W&B APIキー。サンプルでは、このキーを
WANDB_API_KEY環境変数から読み取ってAuthorizationヘッダーで渡し、entity をWandb-Entityヘッダーで指定します。 - そのチーム内の project。project のエイリアスはすべてのリクエストパスに含まれます。project の作成方法については、クイックスタートを参照してください。
- ファイルをアップロードするで使用するタブに応じたツール。以下のいずれか 1 つのセットがあれば十分です。
curl、jq、split。- Python 3.9 以降と
requestsパッケージ。 - Node.js 18 以降 (追加パッケージは不要) 。
アップロードの仕組み
アップロードとは、project 単位のインポートセッションです。1 つのセッションが扱う JSONL ファイルは 1 つだけで、このファイルはパートに分割してオブジェクトストレージに直接送信します。セッションは次の状態を遷移します。
作成から 7 日経過しても
uploading のままのセッションは期限切れになります。期限切れのセッションに対するパートリクエストや完了リクエストは 410 Gone を返します。また、1 時間ごとに実行されるジョブによってセッションは expired に移行し、パートは破棄されます。アップロードされたオブジェクトと未完了のマルチパートアップロードは、セッションが完了したかどうかにかかわらず、書き込みから 8 日後に削除されます。
entity とは、Wandb-Entity ヘッダーで指定されたチームまたは個人アカウントです。各 entity で同時に進行できるセッションは 2 つまでで、宣言されたファイルサイズの合計は最大 2 GiB です。セッションは、作成時から ready、failed、cancelled、expired のいずれかに達するまで、これら両方の制限の対象としてカウントされます。いずれかの制限を超えるリクエストは 429 Too Many Requests を返します。キャパシティを空けるには、不要になったセッションをキャンセルするか、実行中のセッションが終了するまでお待ちください。
ファイルを準備する
インポートセッションを作成する前に、ファイルが行形式に準拠し、このセクションで説明する制限の範囲内に収まっていることを確認してください。検証はアップロードが完了した後にのみ実行されます。また、失敗したセッションを再度開くことはできません。形式の問題を修正するには、新しいセッションを作成してファイルを再アップロードしてください。 ファイルは UTF-8 の JSONL 形式である必要があります。1 行につき 1 つの JSON オブジェクトを記述し、1 つのオブジェクト内でキーが重複しないようにしてください。行の形式
各行は OpenAI Chat Completions リクエストで、その最後のメッセージがトレーニングの目標とするアシスタントの応答です。Model Distillation は、それより前のメッセージと、指定されている場合はtools、tool_choice、response_format を入力として保存し、最後のアシスタント メッセージを出力として保存します。
tools には最大 128 個の関数ツールと 1 MiB までの JSON を指定できます。最後のメッセージがアシスタントのものでない行は、missing_assistant_target エラーで失敗します。
オプションフィールド
各行には、次のオプションフィールドを含めることができます。
行には、これ以外のトップレベルのフィールドを含めることはできません。
制限
ファイルとインポートセッションには、次の制限が適用されます。ファイルをアップロードする
アップロードは、セッションの作成、ファイルの分割アップロード、アップロードの完了、データセットが準備完了になるまでのポーリングという段階を経て進みます。以下のタブでは、一連の流れを 1 つのスクリプトにまとめ、curl、Python、JavaScript で示しています。各段階は番号付きのコメントで示しており、それぞれの詳細は スクリプトの仕組み で説明しています。
スクリプトでは、project のエイリアスに ticket-classifier、ファイル名に tickets.jsonl を使用しています。スクリプトを実行する前に、entity、エイリアス、ファイル名をご自身の値に置き換え、環境変数 WANDB_API_KEY を設定してください。また、アップロードごとに一意の idempotency_key を新たに指定してください。
- curl
- Python
- JavaScript
スクリプトの仕組み
各スクリプト内の番号付きコメントは、以下の各段階に対応しています。1
インポートセッションを作成する
スクリプトは、ファイル名と正確なバイトサイズ、分割ポリシー、および任意で重複ポリシーを送信します。各ポリシーの動作については、分割と重複を参照してください。リクエストには一意の
idempotency_key も必要です。これにより、リクエストを再試行しても 2 つ目のセッションは作成されず、既存のセッションが返されます。応答は 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 スクリプトはアップロード済みパートの一覧を出力します。中断なく 1 回で実行すれば不足パートは発生しないため、いずれのスクリプトも不足パートの再送信は行いません。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がない場合は行のアイデンティティ) をハッシュ化し、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 リファレンスの次のページを参照してください。
- データセットインポートセッションを作成する
- ファイルパートのアップロード URL を作成する
- データセットインポートセッションを取得する
- データセットインポートを完了して検証する
- データセットインポートをキャンセルする
次のステップ
再ラベル付け
元の行は変更せずに、アップロードしたデータセット内のアシスタントの応答を、より高性能なモデルで書き直します。
ファインチューニング
元の出力またはリラベルした出力セットを使用して、サポートされるベースモデルをアップロードしたデータセットでトレーニングします。