BigQuery to Cloud Storage TFRecords テンプレート

BigQuery to Cloud Storage TFRecords テンプレートは、BigQuery クエリからデータを読み取り、Cloud Storage バケットに TFRecord 形式で書き込むパイプラインです。トレーニング、テスト、検証の分割パーセンテージを指定できます。デフォルトでは、トレーニング セットの分割パーセンテージは 1 または 100%、テストセットと検証セットは 0 または 0% です。データセットの分割を設定する場合は、トレーニング、テスト、検証の合計が 1 または 100% になるようにする必要があります(たとえば、0.6 + 0.2 + 0.2)。Dataflow では、各出力データセットに最適なシャード数が自動的に設定されます。

パイプラインの要件

  • BigQuery のデータセットとテーブルが存在すること。
  • パイプラインの実行前に出力先の Cloud Storage バケットが存在すること。トレーニング、テスト、検証のサブディレクトリは事前に作成する必要はありません。自動的に生成されます。

テンプレートのパラメータ

必須パラメータ

  • readQuery: ソースからデータを抽出する BigQuery SQL クエリ。たとえば、select * from dataset1.sample_table などです。
  • outputDirectory: トレーニング、テスト、検証用の TFRecord ファイルを書き込むときに使用する最上位の Cloud Storage パスの接頭辞。トレーニング、テスト、検証用の TFRecord ファイルのサブディレクトリは、outputDirectory から自動的に生成されます。たとえば、gs://mybucket/output/train のようにします(例: gs://mybucket/output)。

オプション パラメータ

  • readIdColumn: 行の固有識別子を格納している BigQuery の列の名前。
  • invalidOutputPath: ターゲット エンティティに変換できない BigQuery 行を書き込む Cloud Storage パス(例: gs://your-bucket/your-path)。
  • outputSuffix: トレーニング、テスト、検証で書き込まれる TFRecord ファイルの接頭辞。デフォルト値は .tfrecord です。
  • trainingPercentage: トレーニングの TFRecord ファイルに割り当てられるクエリデータの割合。デフォルト値は 1 または 100% です。
  • testingPercentage: テストの TFRecord ファイルに割り当てられるクエリデータの割合。デフォルト値は 0 または 0% です。
  • validationPercentage: 検証の TFRecord ファイルに割り当てられるクエリデータの割合。デフォルト値は 0 または 0% です。

テンプレートを実行する

コンソール

  1. Dataflow の [テンプレートからジョブを作成] ページに移動します。
  2. [テンプレートからジョブを作成] に移動
  3. [ジョブ名] フィールドに、固有のジョブ名を入力します。
  4. (省略可)[リージョン エンドポイント] で、プルダウン メニューから値を選択します。デフォルトのリージョンは us-central1 です。

    Dataflow ジョブを実行できるリージョンのリストについては、Dataflow のロケーションをご覧ください。

  5. [Dataflow テンプレート] プルダウン メニューから、[ the BigQuery to TFRecords template] を選択します。
  6. 表示されたパラメータ フィールドに、パラメータ値を入力します。
  7. [ジョブを実行] をクリックします。

gcloud

シェルまたはターミナルで、テンプレートを実行します。

gcloud dataflow jobs run JOB_NAME \
    --gcs-location gs://dataflow-templates-REGION_NAME/VERSION/Cloud_BigQuery_to_GCS_TensorFlow_Records \
    --region REGION_NAME \
    --parameters \
readQuery=READ_QUERY,\
outputDirectory=OUTPUT_DIRECTORY,\
trainingPercentage=TRAINING_PERCENTAGE,\
testingPercentage=TESTING_PERCENTAGE,\
validationPercentage=VALIDATION_PERCENTAGE,\
outputSuffix=OUTPUT_FILENAME_SUFFIX

次のように置き換えます。

  • JOB_NAME: 一意の任意のジョブ名
  • VERSION: 使用するテンプレートのバージョン

    使用できる値は次のとおりです。

    • latest: 最新バージョンのテンプレートを使用します。このテンプレートは、バケット内で日付のない親フォルダ(gs://dataflow-templates-REGION_NAME/latest/)にあります。
    • バージョン名(例: 2023-09-12-00_RC00)。特定のバージョンのテンプレートを使用します。このテンプレートは、バケット内で対応する日付の親フォルダ(gs://dataflow-templates-REGION_NAME/)にあります。
  • REGION_NAME: Dataflow ジョブをデプロイするリージョン(例: us-central1
  • READ_QUERY: 実行する BigQuery クエリ
  • OUTPUT_DIRECTORY: 出力データセットの Cloud Storage パス接頭辞
  • TRAINING_PERCENTAGE: トレーニング データセットの分割割合の小数値
  • TESTING_PERCENTAGE: テスト データセットの分割割合の小数値
  • VALIDATION_PERCENTAGE: 検証データセットの分割割合の小数値
  • OUTPUT_FILENAME_SUFFIX: 出力される TensorFlow レコードのファイル サフィックス

API

REST API を使用してテンプレートを実行するには、HTTP POST リクエストを送信します。API とその認証スコープの詳細については、projects.templates.launch をご覧ください。

POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/templates:launch?gcsPath=gs://dataflow-templates-LOCATION/VERSION/Cloud_BigQuery_to_GCS_TensorFlow_Records
{
   "jobName": "JOB_NAME",
   "parameters": {
       "readQuery":"READ_QUERY",
       "outputDirectory":"OUTPUT_DIRECTORY",
       "trainingPercentage":"TRAINING_PERCENTAGE",
       "testingPercentage":"TESTING_PERCENTAGE",
       "validationPercentage":"VALIDATION_PERCENTAGE",
       "outputSuffix":"OUTPUT_FILENAME_SUFFIX"
   },
   "environment": { "zone": "us-central1-f" }
}

次のように置き換えます。

  • PROJECT_ID: Dataflow ジョブを実行する Google Cloud プロジェクトの ID
  • JOB_NAME: 一意の任意のジョブ名
  • VERSION: 使用するテンプレートのバージョン

    使用できる値は次のとおりです。

    • latest: 最新バージョンのテンプレートを使用します。このテンプレートは、バケット内で日付のない親フォルダ(gs://dataflow-templates-REGION_NAME/latest/)にあります。
    • バージョン名(例: 2023-09-12-00_RC00)。特定のバージョンのテンプレートを使用します。このテンプレートは、バケット内で対応する日付の親フォルダ(gs://dataflow-templates-REGION_NAME/)にあります。
  • LOCATION: Dataflow ジョブをデプロイするリージョン(例: us-central1
  • READ_QUERY: 実行する BigQuery クエリ
  • OUTPUT_DIRECTORY: 出力データセットの Cloud Storage パス接頭辞
  • TRAINING_PERCENTAGE: トレーニング データセットの分割割合の小数値
  • TESTING_PERCENTAGE: テスト データセットの分割割合の小数値
  • VALIDATION_PERCENTAGE: 検証データセットの分割割合の小数値
  • OUTPUT_FILENAME_SUFFIX: 出力される TensorFlow レコードのファイル サフィックス

次のステップ