注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。
Python トランスフォームでは、メディアセットを使用して、PDF のテキスト抽出、光学文字認識 (OCR)、画像のタイル分割、メタデータのパースなどを行えます。以降のセクションでは、Python リポジトリでメディアセットを設定する方法と、Python トランスフォームでメディアセットの読み取りと書き込みを行う方法を説明します。
Code Repositories でメディアセットのバッチパイプラインを作成する手順を示す例もあります。
メディアセットを使用するインクリメンタル(差分処理)トランスフォームを記述する方法も確認できます。
現在、Code Repositories のプレビュー機能は、メディアの変換に対応していません。メディアセットを使用するトランスフォームはビルドできますが、プレビューはできません。
メディアセット固有のデコレーターを使用するには、まず 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 10from 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 12from 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 15from 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 25import 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 11from 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 30from 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 14from 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)
put_dataset_files を使用するPython メディアセット SDK には、Palantir のファイルシステム(Catalog と呼ばれます)内の従来のデータセットからメディアセットにファイルをアップロードするツールが組み込まれています。例:
Copied!1 2 3 4 5 6 7 8 9 10from 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 15from 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 13from 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 52import 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 ドキュメントを参照してください。
ドキュメントのページを、指定した寸法の画像に変換します。
パラメーター:
None です。None(最後のページ)です。戻り値:
MediaSetInputTransform のインスタンスです。さらに変換を適用できます。例:
Copied!1 2transform = pdf_input.transform().convert_document_to_images("ri.mio.main.media-item.1", 0, 5, 600, 900, output_format="jpg") image_output.write(transform)
このトランスフォームでは、視覚言語モデルを使用して抽出を行う AI ベースの OCR ではなく、従来の光学文字認識(OCR)を使用して PDF ドキュメントからテキストを抽出します。視覚言語モデルを使用した PDF ドキュメントの内容の抽出について、詳しくはこちら。
パラメーター:
None です。有効なすべてのコードは、Tesseract ドキュメント ↗ の scripts に記載されています。None です。0(最初のページ)です。None(最後のページ)です。item_per_row または page_per_row です。PDF メディアセット全体に対する変換にのみ適用されます。デフォルトは item_per_row です。True の場合、エラーが捕捉され、エラーメッセージが出力に返されます。False の場合、エラーは捕捉されず、ビルドが失敗します。デフォルトは True です。メディアセット全体に対する変換にのみ適用されます。戻り値:
str:単一の画像に対する変換です。list[str]:単一の PDF に対する変換です。DataFrame:メディアセット全体に対する変換です。
item_per_row)の場合:列は media_item_rid、path、media_reference、extracted_text (list[str]) です。page_per_row)または画像セットの場合:列は media_item_rid、path、media_reference、page_number、extracted_text (str) です。例:
Copied!1 2df = media_set.transform().ocr() dataset_output.write_dataframe(df)
発話を含む音声ファイルをテキストに文字起こしします。
パラメーター:
None です。None で、この場合は自動検出されます。有効な言語は、Whisper GitHub リポジトリ ↗ の LANGUAGES に記載されています。more_economical です。text です。False です。output_format が text の場合にのみ適用されます。True の場合、エラーが捕捉され、エラーメッセージが出力に返されます。False の場合、エラーは捕捉されず、ビルドが失敗します。デフォルトは True です。メディアセット全体に対する変換にのみ適用されます。戻り値:
str:単一のメディアアイテムに対する変換に適用されます。
text:文字起こしされたテキストです。segments:文字起こしされたセグメントを含む JSON オブジェクトです。タイムスタンプ、セグメントの信頼度、およびその他の詳細情報が含まれます。DataFrame:列は media_item_rid、path、media_reference、transcription (str) です。メディアセット全体に対する変換に適用されます。例:
Copied!1 2df = media_set.transform().transcribe("ri.mio.main.media-item.1", language="english") dataset_output.write_dataframe(df)