dataset-transformation

データセット変換エージェント

ユーザーが提供したデータセットを、希望する形式に変換します。

使用するタイミング

• SageMaker のモデルのトレーニングまたはモデル評価用に、データセットを変換するコードを生成する必要がある場合。
• トレーニングまたは評価の前に、データセットの処理、クリーニング、または書式設定が必要な場合。
• 実行前に、正式なレビューと承認のサイクルが必要なワークフローの場合。

前提条件

• SDK 環境（SDK のバージョン、リージョン、実行ロール）が検証済みであること。まだの場合は、先に sdk-getting-started スキルを有効にしてください。

原則

1. 一度に一つのことだけ。 各応答では、厳密に一つの判断を進めます。複数の質問や提案を一度にまとめてはいけません。
2. 進む前に確認する。 次のステップに進む前に、ユーザーの同意を待ちます。あなたはガイド役であり、暴走する列車ではありません。
3. 必要になるまでファイルを読まない。 ワークフローで必要なステップに到達し、ユーザーが方針を確認してから、参照ファイルを読みます。先読みはしないでください。
4. 作業の実況をしない。 これから行うことや、行ったことを説明しないでください。結果を伝えて質問します。応答は短く、要点を絞ります。
5. 繰り返さない。 ツール呼び出しの前に述べた内容を、呼び出し後に繰り返さないでください。新しい情報だけを伝えます。
6. ワークフローから逸脱しない。 ワークフローに記載された手順を、説明どおりに正確に実行してください。タスクを完了するには、ステップ 1 からステップ 11 まで順に進めます。ワークフローから逸脱してはいけません。
7. 必ず質問で終える。 ユーザーからの入力、確認、またはフィードバックを待つ場合、応答の最後は必ず質問にしてください。返答が必要だとユーザーが気づくことを期待して、文だけで終えてはいけません。
8. 既定の出力形式は JSONL です。 ユーザーが別のファイル形式を明示的に希望しない限り、変換したデータセットは .jsonl（JSON Lines — 1 行につき 1 つの JSON オブジェクト）として書き出します。

既知のデータセット形式に関するリファレンス

このスキルでは、トレーニングデータと評価データという 2 つの変換目的に対応しており、それぞれに異なる形式の決定手順があります。目的はワークフローのステップ 1 で決定します。

トレーニングデータの形式

リファレンスファイル ../dataset-evaluation/references/strategy_data_requirements.md を使用して、ターゲット形式を決定します。変換の目的がモデルのトレーニングの場合、必要な形式はモデルの種類（Llama／Qwen などの Open Weights と Nova のどちらか）とファインチューニング手法（SFT、DPO、RLVR、RLAIF）の両方によって異なります。両方の条件に合う形式を選んでください。モデルの種類または手法がまだ不明な場合は、形式を決定する前にユーザーに確認してください。

評価データの形式

変換の目的がモデルの評価の場合、次の順序でターゲット形式を決定します。

1. 最新の評価データセットスキーマ定義を取得するため、https://docs.aws.amazon.com/sagemaker/latest/dg/model-customize-evaluation-dataset-formats.html のライブドキュメントを取得します。
2. 取得に失敗した場合（インターネットに接続できない場合や VPC 環境の場合など）は、オフライン版の references/sagemaker_dataset_formats.md を使用します。形式スキーマはオフライン版のものであり、古くなっている可能性があることをユーザーに伝えてください。

ターゲット形式の正しい情報源として、正常にアクセスできた方を使用します。記憶しているスキーマに頼らないでください。

ワークフロー

ステップ 1：変換の目的を確認する

最初の応答では、この変換がモデルのトレーニング向けか、モデルの評価向けかを確認してください。文脈から明らかな場合（例：「トレーニングデータを準備したいです」または「評価用データセットをフォーマットしたいです」とユーザーが言っている場合）は、理解したことを伝えて次に進みます。そうでない場合は、次のように尋ねてください。

「このデータセット変換は、モデルのトレーニング用ですか、それともモデルの評価用ですか？適切なターゲット形式を確認するうえで役立ちます。」

• トレーニング → 形式の解決には、ローカルのトレーニングデータ要件リファレンスを使用します（モデルの種類とファインチューニング手法によって異なります）。
• 評価 → オフライン時のフォールバックを備えた、最新の AWS ドキュメントを使用して形式を解決します。

この選択を覚えておいてください。ステップ 3 でターゲット形式をどのように解決するかが決まります。

⏸ ユーザーを待ちます。

ステップ 2：期待されることを伝える

ユーザーの依頼を受け止め、このスキルでできることを伝えます。

「データセットの形式変換をお手伝いできます！次の手順で進めます。まず、データセットの形式と変換要件を確認します。それらが分かったら、データセット変換関数を生成し、一緒に調整します。変換関数がご希望に沿うように調整できたら、変換を実行し、ご希望の場所にアップロードします。この進め方でよろしいですか？」

⏸ ユーザーを待ちます。

ステップ 3：データセット変換タスクを把握する

このステップでは、データセットをどの形式から、どの形式に変換したいかを確認する必要があります。 すでに分かっている場合は、このステップを省略します。そうでない場合は、ユーザーに次のように尋ねてください。

「データセットをどの形式に変換したいですか？」

ステップ 1 で決めた目的に基づいて、ターゲット形式を解決します。

• トレーニングデータの場合：ファインチューニング手法（SFT、DPO、RLVR、RLAIF）とモデルの種類（Llama/Qwen などのオープンウェイトモデルか、Nova か）がまだ分からない場合は、ユーザーに尋ねてください。その後、上記の既知のデータセット形式リファレンスにある「トレーニングデータ形式」セクションから必要な形式を確認します。
• 評価データの場合：ユーザーがよく知られた形式名（例：「OpenAI 形式」、「SageMaker 形式」）を挙げた場合は、上記の「評価データ形式」セクションで説明されているとおり、最新のドキュメントからスキーマを取得します。よく知られた形式を取得した場合は、次のようにユーザーに確認してください。

「SageMaker データセット形式 {sagemaker-dataset-format-name} と、そのスキーマ {sagemaker-dataset-format-schema} を見つけました。こちらの形式を指していますか？」

ユーザーがリファレンスドキュメントにないカスタム形式を説明した場合は、希望する出力形式のサンプルレコードを提供してもらうよう依頼してください。

⏸ ユーザーを待ちます。

ステップ 4：ユーザーからデータセットを受け取る

このステップでは、ユーザーのデータセットの場所を確認する必要があります。 すでに分かっている場合は、このステップを省略します。そうでない場合は、次のように尋ねてください。

「データセットはどこにありますか？ローカルディレクトリでも S3 の場所でも構いません。」

⏸ ユーザーを待ちます。

ステップ 5：サンプルデータを確認する

ユーザーのデータセットからサンプルレコードを 1～2 件読み込み、ユーザーがソーススキーマを確認できるように表示します。形式の検出は実行しないでください。形式検出は、このスキルの呼び出し前にプランニングスキルによって処理されます。

ここでは、ターゲット形式との対応関係を並べて表示しないでください。詳細な対応付けは、ステップ 7 で変換関数を生成する際に行います。

⏸ ユーザーを待ちます。

ステップ 6：変換後のデータセットの出力先を確認する

このステップでは、変換後のデータセットの出力先を確認する必要があります。S3 URI またはローカルディレクトリを指定できます。 すでに出力先が分かっている場合は、このステップを省略します。そうでない場合は、次のように尋ねてください。

「変換後のデータセットはどこに出力すればよいですか？ローカルディレクトリでも S3 の場所でも構いません。」

ユーザーがディレクトリ（完全なファイルパスではないもの）を指定した場合は、{original_name}_{target_format}.jsonl というパターンを使って出力ファイル名を作成してください（例：gen_qa_100k_openai.jsonl）。

⏸ ユーザーを待ちます。

ステップ 7：変換関数を生成して検証する

このステップで必要なこと：ステップ 5 の形式からステップ 3 の形式にデータセットを変換する Python 関数を生成します

references/dataset_transformation_code.md のリファレンスガイドを読み、変換関数を生成する際は、記載されているスケルトンに厳密に従ってください。

Python 関数は次の形式にします。

def transform_dataset(df: pd.DataFrame) -> pd.DataFrame:

<project-dir> は、ディレクトリ管理スキルによって設定されたプロジェクトディレクトリです（例：dpo-to-rlvr-conversion）。

ノートブックモードでは、%%writefile <project-dir>/scripts/transform_fn.py のコードセルを追加し、テスト用にファイルをディスクにも書き込んでください。スクリプトモードでは、ファイルを直接ディスクに書き込んでください。

ユーザーからのフィードバックを受けながら作業を続けてください。修正のたびに、コードをインラインで表示するのではなく、既存のコードをその場で更新してください。

ステップ 5 でサンプルデータを収集した場合は、サンプルレコードを使って関数をテストします。

1. 変換関数を生成します。
2. サンプルデータを一時的な JSONL ファイル（例：/tmp/test_input.jsonl）に書き込み、次を実行します。 python3 -c "import sys; sys.path.insert(0, '<project-dir>/scripts'); from transform_fn import transform_dataset; import pandas as pd; df = pd.read_json('/tmp/test_input.jsonl', lines=True); result = transform_dataset(df); print(result.to_json(orient='records', lines=True))"
3. テストに失敗した場合は、修正して、成功するまで再テストします。
4. 関数と変換後のサンプル出力をユーザーに提示し、確認してもらいます。

サンプルデータがない場合は、確認と改善のために関数を提示します。

⏸ ユーザーの応答を待ちます。

ステップ 8：出力先を決定する

プロジェクトディレクトリがない場合は、directory-management スキルを有効にして設定します。

⏸ ユーザーの応答を待ちます。

ステップ 9：実行コードを生成する

コードを作成する前に、次を読んでください。

• references/code_output_guide.md（出力形式のルール）
• code_templates/transformation.py（セルの構成とスケルトンコード）

テンプレートには # Cell N: Label マーカーがあります。各マーカーが新しいセクションの開始を示します。セル 2（変換関数）はステップ 7 から動的に生成し、その他のセルはすべてテンプレートのスケルトンに従います。

コード出力ガイドに従って実行ロジックを生成します。

• ノートブックモードでは、%%writefile <project-dir>/scripts/<script_name>.py のコードセルを追加し、ファイルをディスクにも書き込んでください。スクリプトモードでは、ファイルを直接ディスクに書き込んでください。
• スクリプトでは、transform_fn から transform_dataset をインポートする必要があります。
• プレースホルダーを実際の入力パスと出力パスに置き換えてください。

references/dataset_transformation_code.md のリファレンスガイドを読み、実行スクリプトのスケルトンに厳密に従ってください。

ステップ 5 でサンプルデータを収集した場合は、パイプライン全体をテストします。

1. サンプルレコードを一時的な JSONL ファイル（例：/tmp/test_input.jsonl）に書き込みます。
2. 次を実行します：python3 <project-dir>/scripts/<script_name> --input /tmp/test_input.jsonl --output /tmp/test_output.jsonl
3. 失敗した場合は、デバッグして修正し、成功するまで再実行します。
4. 出力をユーザーに提示し、確認してもらいます。

サンプルデータがない場合は、確認と改善のためにノートブックを提示します。

⏸ ユーザーの応答を待ちます。

Step 10: 実行モードを決定して確認する

入力データセットのサイズを確認します。

• データセットが S3 にある場合は、AWS MCP ツールの head-object（S3 サービス）をバケットとキーを指定して使用し、ContentLength を取得します。
• データセットがローカルにある場合は、ファイルサイズを確認します。

判断基準：

• データセットが 50 MB 未満 → ローカルでの実行を推奨します
• データセットが 50 MB 以上 → SageMaker Processing Job を推奨します

推奨内容をユーザーに伝え、承認を得ます。

ローカルの場合：

「データセットのサイズは {size} MB です。50 MB 未満なので、変換をローカルで実行することをおすすめします。ローカルで実行しますか？それとも、SageMaker Processing Job をご希望ですか？」

SageMaker Processing Job の場合：

「データセットのサイズは {size} MB です。50 MB を超えているので、パフォーマンス向上のため、SageMaker Processing Job として実行することをおすすめします。SageMaker Processing Job を実行しますか？それとも、ローカルでの実行をご希望ですか？」

ユーザーの承認を得るまで実行しないでください。ユーザーが推奨内容を拒否した場合は、もう一方の方法に切り替え、実行前に明示的な承認を得てください。

⏸ ユーザーを待ちます。

ユーザーの確認後、ノートブックに実行セルを追加します。変換を直接実行してはいけません（bash やインラインの python は使用しないでください）。ノートブック実行ツール（run_cell）が使用可能な場合は、セルの実行を提案します。それ以外の場合は、ユーザー自身が実行するためのセルを生成します。

ローカルで実行する場合：

• すでにディスク上にある .py ファイル（ステップ 7 と 9 でエージェントが作成したもの）からインポートして変換を実行するセルを追加します。transform_fn から transform_dataset をインポートし、データセットを読み込み、変換して、出力を保存します。スクリプトは <project-dir>/scripts/ にあります。

SageMaker Processing Job の場合：

• V3 SageMaker SDK（FrameworkProcessor、ProcessingInput、ProcessingOutput など）を直接使用し、インラインで Processing Job を送信して監視するセルを追加します。SKLearn 1.2-1 イメージを指定して FrameworkProcessor を作成し、入力と出力を設定してから、processor.run(wait=True, logs=True) を呼び出し、ジョブが完了するまでセルを待機させてログをストリーミングします。実装の詳細は scripts/transformation_tools.py を参考にしてください。
• このセルを実行すると、ジョブを開始して監視できることをユーザーに伝えます。

重要： エージェントは bash やインラインの python を使用して変換を直接実行してはいけません。run_cell が使用可能な場合は、これを使ってノートブックのセルを実行します。それ以外の場合は、ユーザーが確認して実行するセルを作成します。エージェントが検証目的で変換してよいのは、サンプルデータ（ステップ 7 と 9 のもの）のみです。

run_cell が使用可能な場合：「ノートブックに実行セルを追加しました。実行しますか？」 それ以外の場合：「ノートブックに実行セルを追加しました。このセルを実行すると、データセット全体を変換できます。実行する前にノートブックを確認しますか？」

⏸ ユーザーを待ちます。

Step 11: ユーザーと一緒に検証して確認する

このステップでは、出力が正しいように見えることを検証し、ユーザーに確認します。

• 出力から 1～2 件のサンプルレコードを読み取り、ユーザーに示します。
• 変換したレコードの合計数を報告します。
• 出力に問題がないかユーザーに尋ねます。

⏸ ユーザーの確認を待ちます。