注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。

Python トランスフォームでメディアセットを使用する

Python トランスフォームでは、メディアセットを使用して、PDF のテキスト抽出、光学文字認識 (OCR)、画像のタイル分割、メタデータのパースなどを行えます。以降のセクションでは、Python リポジトリでメディアセットを設定する方法と、Python トランスフォームでメディアセットの読み取りと書き込みを行う方法を説明します。

Code Repositories でメディアセットのバッチパイプラインを作成する手順を示す例もあります。

メディアセットを使用するインクリメンタル(差分処理)トランスフォームを記述する方法も確認できます。

現在、Code Repositories のプレビュー機能は、メディアの変換に対応していません。メディアセットを使用するトランスフォームはビルドできますが、プレビューはできません。

transforms-media ライブラリをリポジトリにインポートする

メディアセット固有のデコレーターを使用するには、まず transforms-media ライブラリをリポジトリにインポートする必要があります。Code Repositories インターフェースの左側にあるライブラリファイルドロワーに移動します。transforms-media を検索し、ライブラリをインストールします。

コードリポジトリに transforms-media への依存関係を追加する

メディアセットを扱う場合は、@transform デコレーターを使用する必要があります。メディアセットの入力と出力は、transforms.mediasets.MediaSetInput と transforms.mediasets.MediaSetOutput の指定を使用して渡せます。ビルド時には、入力の指定が transforms.mediasets.MediaSetInputParam オブジェクトに、出力の指定が transforms.mediasets.MediaSetOutputParam オブジェクトに解決されます。これらの MediaSetInputParam オブジェクトと MediaSetOutputParam オブジェクトを通じて、計算関数内からメディアセットにアクセスできます。任意の数のメディアセットの入力や出力を、ほかの有効なトランスフォームの入力や出力(表形式データセットなど)と組み合わせて使用できます。例:

Copied!
1 2 3 4 5 6 7 8 9 10 from transforms.api import transform from transforms.mediasets import MediaSetInput, MediaSetOutput @transform.spark.using( images=MediaSetInput('/examples/images'), output_images=MediaSetOutput('/examples/output_images') ) def translate_images(images, output_images): ...

メディアセットから読み取る

個々のメディアアイテムには、ファイルパスまたは RID でアクセスできます。

Copied!
1 2 3 4 5 6 7 8 9 10 11 12 from transforms.api import transform from transforms.mediasets import MediaSetInput, MediaSetOutput @transform.spark.using( images=MediaSetInput('/examples/images'), output_images=MediaSetOutput('/examples/output_images') ) def translate_images(images, output_images): image1 = images.get_media_item_by_path("image1") image2 = images.get_media_item("ri.mio.main.media-item.123") ...

ただし、多くの場合はメディアセット内のすべてのメディアアイテムを加工することになります。そのためには、まず listing メソッドを使用して、メディアアイテムをデータフレームに取り込む必要があります。次の例では、入力メディアセット内のすべてのメディアアイテムを一覧化し、その結果のデータフレームを表形式の出力に書き込みます。

Copied!
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 from transforms.api import transform, Output from transforms.mediasets import MediaSetInput @transform.spark.using( images=MediaSetInput('/examples/images'), listing_output=Output('/examples/listed_images') ) def translate_images(ctx, images, listing_output): media_items_listing = images.list_media_items_by_path_with_media_reference(ctx) # media_items_listing に対して通常の PySpark の変換を実行できます column_typeclasses = {'mediaReference': [{'kind': 'reference', 'name': 'media_reference'}]} listing_output.write_dataframe(media_items_listing, column_typeclasses=column_typeclasses)

メディアセット内の特定のパスに複数のメディアアイテムがある場合、一覧には最新のメディアアイテムのみが含まれます。一覧のスキーマは次のとおりです。

+--------------------------+-----------+-------------------+
|        mediaItemRid      |    path   |  mediaReference   |
+--------------------------+-----------+-------------------+
| ri.mio.main.media-item.1 | item1.jpg |  {{reference1}}   |
| ri.mio.main.media-item.2 | item2.jpg |  {{reference2}}   |
| ri.mio.main.media-item.3 | item3.jpg |  {{reference3}}   |
+--------------------------+-----------+-------------------+

上の例では、一覧の先頭3行のみを表示しています。

mediaReference 列のタイプクラスを設定すると、その列を Media Reference として読み取れるようになります。

get_media_item() や get_media_item_by_path() などを呼び出すと、Python のファイルライクなストリームオブジェクトが返されます。io.open() ↗ が受け付けるすべてのオプションにも対応しています。メディアアイテムはストリームとして読み取られるため、ランダムアクセスには対応していません。

メディアアイテム全体をダウンロードせずに、個々のメディアアイテムのメタデータを取得することもできます。メタデータには、画像の寸法や音声の長さなどの情報が含まれます。次の例では、メディアアイテムの一覧に列を追加し、各画像のメタデータを格納します。

Copied!
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 import json from transforms.api import transform, Output from transforms.mediasets import MediaSetInput from pyspark.sql import functions as F from pyspark.sql.types import StringType from conjure_python_client import ConjureEncoder @transform.spark.using( images=MediaSetInput('/examples/images'), listing_output_with_metadata=Output('/examples/listed_images_with_metadata') ) def translate_images(ctx, images, listing_output_with_metadata): def get_metadata(media_item_rid): metadata = images.get_media_item_metadata(media_item_rid) return ConjureEncoder().default(metadata) metadata_udf = F.udf(get_metadata, StringType()) media_items_listing = images.list_media_items_by_path_with_media_reference(ctx) listing_with_metadata = media_items_listing.withColumn('metadata', metadata_udf(F.col('mediaItemRid'))) column_typeclasses = {'mediaReference': [{'kind': 'reference', 'name': 'media_reference'}]} listing_output_with_metadata.write_dataframe(listing_with_metadata, column_typeclasses=column_typeclasses)

メディアセットには、あらかじめ組み込みの変換がいくつか用意されています。完全な一覧については、メディアセットのトランスフォーム API を参照してください。これらの変換を呼び出した場合も、Python のファイルライクなストリームオブジェクトが返されます。これらの組み込みの変換を使用するには、メディアセットの入力で適切なメソッドを呼び出します。例:

Copied!
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 @transform.spark.using( images=MediaSetInput('/examples/images'), image_text_output=Output('/examples/listed_images_with_text') ) def translate_images(ctx, images, image_text_output): def get_ocr_on_image(media_item_rid): return images.transform_image_to_text_ocr_output_text(media_item_rid).read().decode('utf-8') ocr_on_image_udf = F.udf(get_ocr_on_image, StringType()) media_items_listing = images.list_media_items_by_path_with_media_reference(ctx) listing_with_ocr = media_items_listing.withColumn('text', ocr_on_image_udf(F.col('mediaItemRid'))) column_typeclasses = {'mediaReference': [{'kind': 'reference', 'name': 'media_reference'}]} image_text_output.write_dataframe(listing_with_ocr, column_typeclasses=column_typeclasses)

メディアセットを作成する

メディアセット作成ダイアログを使用してプロジェクトやフォルダー内にメディアセットを作成するだけでなく、Code Repositories 内で直接メディアセットを作成し、Python トランスフォームの出力として使用することもできます。

まず、MediaSetOutput の指定で、新しいメディアセットの出力先と名前を選択します。

定義したパスを選択します。この時点では、パスに赤い下線が付いているはずです。ホバー時には、メディアセットが存在しないことを示すエラーメッセージが表示されます。

行の左側にある電球アイコンから、メディアセットを作成を選択します。

メディアセットの出力を作成するプロンプト

ダイアログのステップに沿って目的のメディアセットのスキーマを選択し、新しいメディアセットに必要なその他の設定を完了します。

メディアセット作成ダイアログ

作成を選択すると、指定した詳細情報が MediaSetOutput の指定に入力されます。これらの注釈フィールドによって、メディアセットの作成方法が定義されます。

メディアセット作成の注釈

新しいメディアセットは、Python トランスフォームが初めてビルドされた後に作成されます。それ以降は、注釈フィールドを編集しないでください。

メディアセットに書き込む

MediaSetOutput の指定を使用すると、メディアセットをトランスフォームの出力として使用できます。

メディアアイテムをアップロードするには、出力メディアセットで put_media_item() エンドポイントを呼び出します。このエンドポイントは、任意のファイルライクオブジェクトと、出力メディアセット内でメディアアイテムを識別するために使用するパスを受け付けます。基本的な例を次に示します。

Copied!
1 2 3 4 5 6 7 8 9 10 11 from transforms.api import transform from transforms.mediasets import MediaSetInput, MediaSetOutput @transform.spark.using( images=MediaSetInput('/examples/images'), output_images=MediaSetOutput('/examples/output_images') ) def upload_images(images, output_images): with images.get_media_item_by_path("image1.jpg") as input_image: output_images.put_media_item(input_image, "copied_image1.jpg")

あるメディアセットから別のメディアセットにメディアアイテムをコピーする場合は、出力で fast_copy_media_item() メソッドを使用できます。この方法は、メディアアイテムをダウンロードして再アップロードするよりも高速で効率的です。

Copied!
1 2 3 4 5 6 7 @transform.spark.using( images=MediaSetInput('/examples/images'), output_images=MediaSetOutput('/examples/output_images') ) def upload_images(images, output_images): origin_media_item_rid = images.get_media_item_rid_by_path("image1.jpg").item output_images.fast_copy_media_item(images, origin_media_item_rid, "fast_copied_image1.jpg")

ユーザー定義関数 (UDF) 内でメディアセットにメディアアイテムをアップロードすると、並列度を高められます。次の例では、組み込みの PDF から JPEG への変換を使用して、入力メディアセット内の PDF を JPEG に変換し、それらの JPEG を新しい出力メディアセットにアップロードします。次に、アップロードした JPEG の Media Reference を含む表形式データセットを書き出します。

Copied!
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 from transforms.api import transform, Output from transforms.mediasets import MediaSetInput, MediaSetOutput from pyspark.sql import functions as F from pyspark.sql.types import StringType @transform.spark.using( pdfs=MediaSetInput('/examples/PDFs'), output_images=MediaSetOutput('/examples/JPEGs'), output_references=Output('/examples/JPEG listing') ) def upload_images(ctx, pdfs, output_images, output_references): def upload_jpg(media_item_rid, path): with pdfs.transform_document_to_jpg(media_item_rid, 0) as jpeg: response = output_images.put_media_item(jpeg, path) return response.media_item_rid upload_udf = F.udf(upload_jpg, StringType()) listed_pdfs = pdfs.list_media_items_by_path(ctx) media_reference_template = output_images.media_reference_template() uploaded_jpegs = listed_pdfs\ .withColumn('uploaded_media_item_rid', upload_udf(F.col('mediaItemRid'), F.col('path')))\ .select('path', 'uploaded_media_item_rid')\ .withColumn("mediaReference", F.format_string(media_reference_template, 'uploaded_media_item_rid')) column_typeclasses = {'mediaReference': [{'kind': 'reference', 'name': 'media_reference'}]} output_references.write_dataframe(uploaded_jpegs, column_typeclasses=column_typeclasses)

メディアセットの書き込みモード

メディアセットには、次の2つの書き込みモードのいずれかを使用して書き込めます。

  • modify:アップロードしたメディアアイテムは、メディアセットのブランチ内にある既存のメディアアイテムに追加されます。
  • replace:アップロードしたメディアアイテムで、メディアセットのブランチ全体が置き換えられます。

デフォルトの書き込みモードは、メディアセットのトランザクションポリシーによって異なります。トランザクション型メディアセットのデフォルトは replace です。非トランザクション型メディアセットは modify 書き込みモードを使用し、これは変更できません。非トランザクション型メディアセットのブランチは、空の状態にリセットできないためです。

メディアセットの出力の書き込みモードは、実行時に動的に変更できます。これは、出力全体を置き換えるかどうかをパイプライン内のカスタム基準に基づいて判断するシナリオで役立ちます。

メディアセットの書き込みモードを変更するには、メディアセットの出力で .set_write_mode() メソッドを使用できます。書き込みモードは、出力にメディアアイテムがアップロードされるまで、いつでも変更できます。例:

Copied!
1 2 3 4 5 6 7 8 9 10 11 12 13 14 from transforms.api import transform, Input from transforms.mediasets import MediaSetOutput @transform.spark.using( input_PNGs=Input('/examples/input_PNGs'), output_PNGs=MediaSetOutput('/examples/output_PNGs'), ) def upload_pngs(input_PNGs, output_PNGs): if should_replace(input_PNGs): output_PNGs.set_write_mode("replace") else: output_PNGs.set_write_mode("modify") output_PNGs.put_dataset_files(input_PNGs)

ファイルシステム(Catalog)データセットからアップロードする

put_dataset_files を使用する

Python メディアセット SDK には、Palantir のファイルシステム(Catalog と呼ばれます)内の従来のデータセットからメディアセットにファイルをアップロードするツールが組み込まれています。例:

Copied!
1 2 3 4 5 6 7 8 9 10 from transforms.api import transform, Input from transforms.mediasets import MediaSetOutput @transform.spark.using( pdfs_dataset=Input('/examples/PDFs'), pdfs_media_set=MediaSetOutput('/examples/PDFs media set') ) def upload_to_media_set(pdfs_dataset, pdfs_media_set): pdfs_media_set.put_dataset_files(pdfs_dataset, ignore_items_not_matching_schema=False)

このトランスフォームは、データセット内のすべての項目をメディアセットにアップロードします。メディアセットのスキーマに一致しない項目がある場合(たとえば、データセット内に JPEG がある場合)、ビルドは失敗します。ignore_items_not_matching_schema=True を設定すると、このような不一致は無視されます。

put_media_item を使用する

ファイルを1つずつアップロードすることもできます。例:

Copied!
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 from transforms.api import transform, Input from transforms.mediasets import MediaSetOutput import os @transform.spark.using( output_media_set=MediaSetOutput("/path/media_set_output", should_snapshot=False), input_dataset=Input("/path/dataset_of_raw_files"), ) def compute(input_dataset, output_media_set): all_files = list(input_dataset.filesystem().ls()) for current_file in all_files: with input_dataset.filesystem().open(current_file.path, 'rb') as f: filename = os.path.basename(current_file.path) output_media_set.put_media_item(f, filename)

軽量トランスフォームのサポート

メディアセットは、軽量トランスフォームを使用して加工できます。API は標準の Python トランスフォームと同じですが、メディアアイテムを一覧表示する際のデータフレーム操作には、pandas などの単一ノードライブラリを使用します。次の例は、入力メディアセット内のすべてのメディアアイテムを一覧表示し、結果のデータフレームを表形式の出力に書き込む軽量トランスフォームを示しています。

Copied!
1 2 3 4 5 6 7 8 9 10 11 12 13 from transforms.api import transform, Output, LightweightOutput from transforms.mediasets import MediaSetInput, LightweightMediaSetInputParam @transform.using( images=MediaSetInput('/examples/images'), listing_output=Output('/examples/listed_images') ) def translate_images(images: LightweightMediaSetInputParam, listing_output: LightweightOutput): media_items_listing = images.list_media_items_by_path_with_media_reference().pandas() # media_items_listing に対して通常の pandas の変換を実行できます listing_output.write_table(media_items_listing)

軽量トランスフォームでは、一部の操作に対応していません。特に、put_dataset_files は、ファイルを並列でアップロードするために Spark の分散処理に依存しているため、利用できません。

ドキュメントからレイアウトを考慮した内容を抽出する

extractLayoutAwareTextV2 操作を使用して、出力形式(TEXT、MARKDOWN、HTML)、処理モード(ELECTRONIC、SCAN、AUTO)、ページ範囲を設定します。ドキュメントからテキストへのメディア変換の詳しくはこちら。

メディアセットを扱う際は、トランスフォームを使用して、ドキュメントから段落、見出し、テーブルなどの内容を、そのレイアウトに関する追加のメタデータとともに抽出できます。この抽出トランスフォームは、PDF と画像の両方のメディアセットで実行できます。

特に複雑なドキュメントでは、抽出した境界ボックスをビジョンモデルに渡すことで、より良い結果になる場合があります。

PDF ドキュメントの場合、V2 レスポンスは、リクエストしたページごとにブロックの配列を格納する pages 配列を持つオブジェクトです。各ブロックには、種類、信頼度、ID、境界ボックス、抽出されたテキスト、0始まりのページ番号が含まれます。format を TEXT に設定すると、ブロックのテキストは {"type": "text", "text": "Extracted content"} のようなタグ付きの値になります。

次の Python トランスフォームは、OCR を使用して1ページずつ抽出し、結合した V2 レスポンスを JSON として text 列に保存します。ドキュメントごとに1行が作成されます。

Copied!
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 import json from transforms.api import transform, Output from transforms.mediasets import MediaSetInput, MediaSetInputParam from pyspark.sql.functions import udf @transform.spark.using( output=Output('ri.foundry.main.dataset.0-1-2-3-4'), media_input=MediaSetInput('/examples/input_pdfs'), ) def compute(media_input: MediaSetInputParam, output): def extract_all_text(media_item_rid): metadata = media_input.get_media_item_metadata(media_item_rid) pages = metadata.document.pages if pages is None: return "" extracted_pages = [] for page in range(pages): response = media_input.transform_media_item(media_item_rid, str(page), { "type": "documentToText", "documentToText": { "operation": { "type": "extractLayoutAwareTextV2", "extractLayoutAwareTextV2": { "pageRange": { "startPageInclusive": page, "endPageExclusive": page + 1 }, "config": { "mode": "SCAN", "format": "TEXT", "languages": [{"type": "language", "language": "ENG"}] } } } } }) extracted_pages.extend(response.json()["pages"]) return json.dumps({"pages": extracted_pages}) extract_text_udf = udf(extract_all_text) result = media_input.dataframe().withColumn("text", extract_text_udf("mediaItemRid")) column_typeclasses = { "mediaReference": [{"kind": "reference", "name": "media_reference"}] } output.write_dataframe(result, column_typeclasses=column_typeclasses)

多数のドキュメントやページ数の多いドキュメントに対してこの抽出トランスフォームを実行する場合は、パフォーマンスを最適化するために並列処理を使用することを推奨します。

サイズの大きいドキュメントでは、pageRange を使用して、1回のリクエストで複数のページをまとめて処理できます。ページ範囲の設定の詳しくはこちら。

リファレンス:組み込みの変換

利用可能なすべての変換メソッド、パラメーター、および例の完全なリファレンスについては、メディアセットのトランスフォーム API ドキュメントを参照してください。

PDF ドキュメントを JPEG 画像に変換する

ドキュメントのページを、指定した寸法の画像に変換します。

パラメーター:

  • media_item_rid (Optional[str]):指定した場合、メディアセット全体ではなく、指定したメディアアイテムに対して変換を実行します。デフォルトは None です。
  • start_page (Optional[int]):変換を開始するページ(0始まり)です。デフォルトは0(最初のページ)です。
  • end_page (Optional[int]):変換を終了するページ(0始まり、指定したページは含みません)です。デフォルトは None(最後のページ)です。
  • width (Optional[int]):出力画像の幅です。デフォルトは1024です。
  • height (Optional[int]):出力画像の高さです。デフォルトは1024です。
  • output_format (str):出力画像の形式です(PNG、JPEG など)。デフォルトは PNG です。

戻り値:

  • ドキュメントから画像への変換を含む MediaSetInputTransform のインスタンスです。さらに変換を適用できます。

例:

Copied!
1 2 transform = pdf_input.transform().convert_document_to_images("ri.mio.main.media-item.1", 0, 5, 600, 900, output_format="jpg") image_output.write(transform)

PDF ドキュメントセットを OCR でテキストに変換する

このトランスフォームでは、視覚言語モデルを使用して抽出を行う AI ベースの OCR ではなく、従来の光学文字認識(OCR)を使用して PDF ドキュメントからテキストを抽出します。視覚言語モデルを使用した PDF ドキュメントの内容の抽出について、詳しくはこちら。

パラメーター:

  • languages (list[str]):OCR に使用する言語のリストです。デフォルトは英語です。有効なすべてのコードは、Tesseract ドキュメント ↗ の languages に記載されています。
  • scripts (Optional[list[str]]):OCR に使用する文字体系のリストです。デフォルトは None です。有効なすべてのコードは、Tesseract ドキュメント ↗ の scripts に記載されています。
  • media_item_rid (Optional[str]):指定した場合、メディアセット全体ではなく、指定したメディアアイテムに対して変換を実行します。デフォルトは None です。
  • start_page (Optional[int]):OCR を開始するページ(0始まり)です。PDF メディアセットにのみ適用されます。デフォルトは 0(最初のページ)です。
  • end_page (Optional[int]):OCR を終了するページ(0始まり、指定したページは含みません)です。PDF メディアセットにのみ適用されます。デフォルトは None(最後のページ)です。
  • return_structure (str):item_per_row または page_per_row です。PDF メディアセット全体に対する変換にのみ適用されます。デフォルトは item_per_row です。
  • suppress_errors (bool):エラー処理の動作を指定します。True の場合、エラーが捕捉され、エラーメッセージが出力に返されます。False の場合、エラーは捕捉されず、ビルドが失敗します。デフォルトは True です。メディアセット全体に対する変換にのみ適用されます。

戻り値:

  • DataFrame、文字列のリスト、または単一の文字列です。
    • str:単一の画像に対する変換です。
    • list[str]:単一の PDF に対する変換です。
    • DataFrame:メディアセット全体に対する変換です。
      • PDF(item_per_row)の場合:列は media_item_rid、path、media_reference、extracted_text (list[str]) です。
      • PDF(page_per_row)または画像セットの場合:列は media_item_rid、path、media_reference、page_number、extracted_text (str) です。

例:

Copied!
1 2 df = media_set.transform().ocr() dataset_output.write_dataframe(df)

音声をテキストに文字起こしする

発話を含む音声ファイルをテキストに文字起こしします。

パラメーター:

  • media_item_rid (Optional[str]):指定した場合、メディアセット全体ではなく、指定したメディアアイテムに対して変換を実行します。デフォルトは None です。
  • language (Optional[str]):文字起こしに使用する言語です。デフォルトは None で、この場合は自動検出されます。有効な言語は、Whisper GitHub リポジトリ ↗ の LANGUAGES に記載されています。
  • performance_mode (Literal["more_economical", "more_performant"]):文字起こしに使用するパフォーマンスモードです。デフォルトは more_economical です。
  • output_format (Literal["text", "segments"]):出力の形式です。デフォルトは text です。
  • add_timestamps (Optional[bool]):文字起こしにタイムスタンプを追加するかどうかを制御します。デフォルトは False です。output_format が text の場合にのみ適用されます。
  • suppress_errors (bool):エラー処理の動作を指定します。True の場合、エラーが捕捉され、エラーメッセージが出力に返されます。False の場合、エラーは捕捉されず、ビルドが失敗します。デフォルトは True です。メディアセット全体に対する変換にのみ適用されます。

戻り値:

  • DataFrame または単一の文字列です。
    • str:単一のメディアアイテムに対する変換に適用されます。
      • text:文字起こしされたテキストです。
      • segments:文字起こしされたセグメントを含む JSON オブジェクトです。タイムスタンプ、セグメントの信頼度、およびその他の詳細情報が含まれます。
    • DataFrame:列は media_item_rid、path、media_reference、transcription (str) です。メディアセット全体に対する変換に適用されます。

例:

Copied!
1 2 df = media_set.transform().transcribe("ri.mio.main.media-item.1", language="english") dataset_output.write_dataframe(df)