본 번역은 검증되지 않았습니다. AIP를 통해 영문원문으로부터 번역되었습니다.

파이썬 변환기와 함께 미디어 세트 사용

파이썬 변환기에서 미디어 세트를 사용하여 PDF 텍스트 추출, 광학 문자 인식(OCR), 이미지 타일링, 메타데이터 파싱 등을 수행할 수 있습니다. 다음 섹션에서는 파이썬 리포지토리에 미디어 세트를 설정하는 방법과 파이썬 변환기로 미디어 세트를 읽고 쓰는 방법에 대해 설명합니다.

Code Repositories에 `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
11
12
13
14
15
# transforms.api에서 transform 임포트
from transforms.api import transform
# transforms.mediasets에서 MediaSetInput, MediaSetOutput 임포트
from transforms.mediasets import MediaSetInput, MediaSetOutput

# 이미지를 변환하는 함수 정의
@transform(
    # 입력 이미지 경로 설정
    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
13
14
15
16
from transforms.api import transform
from transforms.mediasets import MediaSetInput, MediaSetOutput

# transform 데코레이터를 사용하여 이미지를 변환하는 함수를 정의합니다.
# images는 입력 미디어 세트로 '/examples/images' 경로의 이미지들을 받아옵니다.
# output_images는 출력 미디어 세트로 변환된 이미지들을 '/examples/output_images' 경로에 저장합니다.
@transform(
    images=MediaSetInput('/examples/images'),
    output_images=MediaSetOutput('/examples/output_images')
)
def translate_images(images, output_images):
    # 이미지1은 'image1'이라는 이름의 미디어 아이템을 가져옵니다.
    image1 = images.get_media_item_by_path("image1")
    # 이미지2는 'ri.mio.main.media-item.123'이라는 ID를 가진 미디어 아이템을 가져옵니다.
    image2 = images.get_media_item("ri.mio.main.media-item.123")
    ...

그러나 아마도 미디어 세트의 모든 항목을 변환하고 싶을 것입니다. 이를 위해서는 먼저 리스팅 방법을 사용하여 항목을 데이터프레임으로 가져와야 합니다. 아래 예시에서는 입력 미디어 세트의 모든 항목을 나열하고 결과 데이터프레임을 탭형식 결과물로 작성합니다:

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
from transforms.api import transform, Output
from transforms.mediasets import MediaSetInput

# 이미지를 번역하는 함수를 정의합니다.
@transform(
    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}}   |  // 미디어 항목 1
| ri.mio.main.media-item.2 | item2.jpg |  {{reference2}}   |  // 미디어 항목 2
| ri.mio.main.media-item.3 | item3.jpg |  {{reference3}}   |  // 미디어 항목 3
+--------------------------+-----------+-------------------+

위 예시는 목록의 상위 세 줄만 보여줍니다.

mediaReference 열의 타입클래스를 설정함으로써, 이 열을 미디어 출처로 읽을 수 있게 합니다.

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
26
27
28
29
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(
    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(
    images=MediaSetInput('/examples/images'),  # 이미지 집합을 입력으로 받습니다.
    image_text_output=Output('/examples/listed_images_with_text')  # 이미지 텍스트를 출력으로 내보냅니다.
)
def translate_images(ctx, images, listing_output_with_metadata):  # translate_images 함수를 정의합니다.

    def get_ocr_on_image(media_item_rid):  # 이미지에서 텍스트를 추출하는 함수를 정의합니다.
        return images.transform_image_to_text_ocr_output_text(media_item_rid)  # OCR를 사용하여 이미지에서 텍스트를 추출합니다.

    ocr_on_image_udf = F.udf(get_ocr_on_image, StringType())  # 위에서 정의한 OCR 함수를 사용자 정의 함수(UDF)로 등록합니다.

    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')))  # OCR을 통해 추출한 텍스트를 새로운 컬럼으로 추가합니다.
    column_typeclasses = {'mediaReference': [{'kind': 'reference', 'name': 'media_reference'}]}  # 컬럼의 타입을 정의합니다.
    listing_output_with_metadata.write_dataframe(listing_with_metadata, column_typeclasses=column_typeclasses)  # 데이터프레임을 작성하고, 컬럼의 타입을 반영하여 출력합니다.

미디어 세트에 쓰기

MediaSetOutput 사양을 사용하여 미디어 세트를 변환 결과물로 사용할 수 있습니다. 일반 데이터셋과 달리 미디어 세트는 결과물로 사용되기 전에 반드시 먼저 존재해야 합니다. 이 작업은 Foundry 파일시스템 인터페이스를 통해 미디어 세트가 존재해야 하는 폴더로 이동하여 수행할 수 있습니다.

항목을 업로드하려면 결과물 미디어 세트에서 put_media_item() 엔드포인트를 호출합니다. 이 엔드포인트는 파일과 유사한 객체와 결과물 미디어 세트에서 항목을 식별하는 데 사용되는 경로를 수락합니다. 다음은 기본 예입니다:

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
from transforms.api import transform
from transforms.mediasets import MediaSetInput, MediaSetOutput

# 트랜스폼을 이용하여 이미지를 업로드하는 함수
@transform(
    images=MediaSetInput('/examples/images'),  # 입력 이미지 경로
    output_images=MediaSetOutput('/examples/output_images')  # 출력 이미지 경로
)
def upload_images(images, output_images):
    # 이미지1을 가져와서 input_image에 저장
    with images.get_media_item_by_path("image1.jpg") as input_image:
        # input_image를 복사하여 출력 이미지 폴더에 저장
        output_images.put_media_item(input_image, "copied_image1.jpg")

한 미디어 세트에서 다른 미디어 세트로 아이템을 복사할 때, 결과물에서 fast_copy_media_item() 메서드를 사용할 수 있습니다. 이는 미디어 아이템을 다운로드하고 다시 업로드하는 것보다 더 빠르고 효율적인 옵션입니다:

Copied!1
2
3
4
5
6
7
8
9
@transform(
    images=MediaSetInput('/examples/images'),
    output_images=MediaSetOutput('/examples/output_images')
)
def upload_images(images, output_images):
    # "image1.jpg"의 미디어 항목 RID를 가져옵니다.
    origin_media_item_rid = images.get_media_item_rid_by_path("image1.jpg")
    # 이미지를 빠르게 복사하여 "fast_copied_image1.jpg"로 저장합니다.
    output_images.fast_copy_media_item(images, origin_media_item_rid, "fast_copied_image1.jpg")

사용자 정의 함수(UDFs)에서 미디어 세트에 항목을 업로드하여 병렬성을 높일 수 있습니다. 아래 예시에서는 입력 미디어 세트의 PDF를 내장된 PDF to JPEG 변환을 사용하여 JPEG로 변환하고, 그 JPEG를 새로운 결과물 미디어 세트에 업로드합니다. 그런 다음 업로드된 JPEG의 미디어 출처를 포함하는 표 형식 데이터셋을 작성합니다:

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
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

# 트랜스폼 함수 정의. 입력으로는 PDF 경로, 출력으로는 JPEG 경로 및 JPEG 목록을 받음
@transform(
    pdfs=MediaSetInput('/examples/PDFs'),
    output_images=MediaSetOutput('/examples/JPEGs'),
    output_references=Output('/examples/JPEG listing')
)
def upload_images(ctx, pdfs, output_images, output_references):

    # JPEG 업로드 함수 정의. 각 미디어 항목의 rid와 경로를 입력으로 받음
    def upload_jpg(media_item_rid, path):
        # 주어진 rid의 문서를 JPEG로 변환
        with pdfs.transform_document_to_jpg(media_item_rid, 0) as jpeg:
            # 변환된 JPEG를 지정된 경로에 업로드하고 응답을 받음
            response = output_images.put_media_item(jpeg, path)
        return response.media_item_rid

    # 위에서 정의한 업로드 함수를 UDF(사용자 정의 함수)로 사용
    upload_udf = F.udf(upload_jpg, StringType())

    # PDF 목록을 가져옴
    listed_pdfs = pdfs.list_media_items_by_path(ctx)
    # 미디어 참조 템플릿을 가져옴
    media_reference_template = output_images.media_reference_template()
    # PDF 목록에 대해 업로드 함수를 적용하고, 업로드한 JPEG의 rid와 경로, 미디어 참조를 선택
    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'}]}
    # JPEG 목록을 쓰기
    output_references.write_dataframe(uploaded_jpegs, column_typeclasses=column_typeclasses)

파일 시스템(Catalog) 데이터셋에서 업로드

Python 미디어 세트 SDK는 Palantir 파일 시스템(카탈로그로 알려져 있음)에서 일반 데이터셋의 파일을 미디어 세트로 업로드하는 데 사용할 수 있는 내장 도구를 갖추고 있습니다. 예를 들면:

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 라이브러리를 import합니다.
from transforms.api import transform, Input
from transforms.mediasets import MediaSetOutput

# 'transform' 데코레이터를 사용하여 함수를 정의합니다.
# 이 함수는 입력으로 PDF 데이터셋을 받고, 이를 MediaSetOutput으로 변환합니다.
@transform(
    pdfs_dataset=Input('/examples/PDFs'),  # PDF 파일이 있는 데이터셋의 경로를 지정합니다.
    pdfs_media_set=MediaSetOutput('/examples/PDFs mediaset')  # 변환된 데이터셋을 저장할 mediaset의 경로를 지정합니다.
)
def upload_to_media_set(pdfs_dataset, pdfs_media_set):  # 함수를 정의합니다.
    # put_dataset_files 메소드를 사용하여 pdfs_dataset의 데이터를 pdfs_media_set에 업로드합니다.
    # ignore_items_not_matching_schema를 False로 설정하면, 스키마와 일치하지 않는 항목을 무시하지 않습니다.
    pdfs_media_set.put_dataset_files(pdfs_dataset, ignore_items_not_matching_schema=False)

이 변환은 데이터셋의 모든 항목을 미디어 세트에 업로드합니다. 어떤 항목이 미디어 세트의 스키마와 일치하지 않는 경우(예를 들어, 데이터셋에 JPEG가 있는 경우), 빌드는 실패합니다. ignore_items_not_matching_schema=True를 설정함으로써 이런 불일치는 무시됩니다.

출처: 내장 변환

PDF 문서를 JPEG로 변환

PDF 문서의 개별 페이지를 JPEG로 변환하고 반환합니다.

작동 대상: PDF 문서
반환: JPEG 이미지
파라미터:
- media_item_rid: 변환될 미디어 항목의 RID입니다.
- page_number: 0부터 시작하는 페이지 번호입니다.
- 높이 (선택적): 결과물 이미지의 원하는 높이, 픽셀 단위입니다.
- 너비 (선택적): 결과물 이미지의 원하는 너비, 픽셀 단위입니다.
예시:

Copied!1
2
# PDF 파일을 JPG 이미지로 변환합니다.
input_pdfs.transform_document_to_jpg("ri.mio.main.media-item.1", 0)

PDF 문서를 PNG로 변환

PDF 문서의 개별 페이지를 PNG로 변환하고 반환합니다.

작동 대상: PDF 문서
반환: PNG 이미지
파라미터:
- media_item_rid: 변환할 미디어 아이템의 RID.
- page_number: 0으로 시작하는 페이지 번호.
- 높이 (선택적): 결과물 이미지의 원하는 높이(픽셀 단위).
- 너비 (선택적): 결과물 이미지의 원하는 너비(픽셀 단위).
예시:

Copied!1
2
# "ri.mio.main.media-item.1"이라는 이름의 PDF 문서를 PNG 형식으로 변환합니다. 이때, 페이지 번호는 0으로 설정됩니다.
input_pdfs.transform_document_to_png("ri.mio.main.media-item.1", 0)

광학 문자 인식(OCR)을 사용하여 페이지별로 PDF 문서를 텍스트로 변환하기

페이지별로 OCR을 적용하여 PDF를 텍스트 결과물로 변환합니다.

적용 대상: PDF 문서
반환 값: utf-8 인코딩의 비구조화된 텍스트
파라미터:
- media_item_rid: 변환할 미디어 아이템의 RID입니다.
- page_number: 0부터 시작하는 페이지 번호입니다.
- 언어(선택 사항): 언어 코드로 기본값은 ENG입니다.
예시:

Copied!1
2
# 입력된 PDF 파일을 OCR을 통해 텍스트로 변환합니다.
input_pdfs.transform_document_to_text_ocr_output_text("ri.mio.main.media-item.1", 0)

PDF 문서를 페이지별로 OCR하여 hOCR XML로 변환

페이지별로 PDF를 OCR하여 hOCR XML로 변환합니다. hOCR(외부 링크)에 대해 더 알아보기.

작동 대상: PDF 문서
결과: UTF-8 인코딩된 hOCR XML
파라미터:
- media_item_rid: 변환할 미디어 항목의 RID.
- page_number: 0부터 시작하는 페이지 번호.
- 언어 (선택 사항): 기본값으로 설정된 언어 코드 ENG.
예시:

Copied!1
2
3
4
# 한국어 주석
# input_pdfs의 transform_document_to_text_ocr_output_hocr 함수를 이용하여
# "ri.mio.main.media-item.1" PDF 파일의 0번째 페이지를 텍스트로 변환합니다 (OCR 및 HOCR 출력 포함).
input_pdfs.transform_document_to_text_ocr_output_hocr("ri.mio.main.media-item.1", 0)

PDF 문서를 변환하여 원시 텍스트 추출

PDF에서 필드를 추출하고 반환합니다. 이는 OCR과 달리 이미지 처리가 필요하지 않은 파싱 방법입니다.

작동 대상: PDF 문서
반환값: UTF-8 인코딩의 비구조화된 텍스트
파라미터:
- media_item_rid: 변환될 미디어 항목의 RID.
- page_number: 0으로 시작하는 페이지 번호.
예시:

Copied!1
2
# "ri.mio.main.media-item.1" 문서를 원시 텍스트로 변환합니다.
input_pdfs.transform_document_to_text_raw("ri.mio.main.media-item.1", 0)

PDF 문서에서 양식 필드 추출

PDF 전체에서 모든 양식 필드를 추출하여 반환합니다.

작동 대상: PDF 문서
결과물: JSON
파라미터:
- media_item_rid: 변환할 미디어 아이템의 RID입니다.
예시:

Copied!1
2
# "transform_document_to_text_extract_field" 함수를 사용하여 "ri.mio.main.media-item.1" 필드를 텍스트로 변환합니다.
input_pdfs.transform_document_to_text_extract_field("ri.mio.main.media-item.1")

PDF 문서 변환하여 목차 추출하기

PDF에서 필드를 추출하고 반환합니다.

작동 대상: PDF 문서
결과물: JSON
파라미터:
- media_item_rid: 변환될 미디어 아이템의 RID.
예시:

Copied!1
2
# "ri.mio.main.media-item.1"라는 이름의 문서를 텍스트로 변환하고 목차를 추출하는 함수를 실행합니다.
input_pdfs.transform_document_to_text_extract_table_of_contents("ri.mio.main.media-item.1")

이미지를 hOCR XML로 변환

이미지를 hOCR XML로 OCR합니다. hOCR(외부)에 대해 더 알아보기.

작동 대상: 이미지
반환: JSON
파라미터:
- media_item_rid: 변환할 미디어 항목의 RID.
예시:

Copied!1
2
# 'transform_image_to_text_ocr_output_hocr' 함수를 사용하여 "ri.mio.main.media-item.1" 이미지를 텍스트로 변환합니다.
input_pdfs.transform_image_to_text_ocr_output_hocr("ri.mio.main.media-item.1")

이미지를 텍스트로 변환

이미지를 텍스트로 OCR 변환합니다.

작동 대상: 이미지
반환: UTF-8 인코딩의 비구조화된 텍스트
파라미터:
- media_item_rid: 변환될 미디어 항목의 RID입니다.
예시:

Copied!1
2
# "ri.mio.main.media-item.1"이라는 이름의 이미지를 텍스트로 변환하는 함수를 실행합니다.
input_images.transform_image_to_text_ocr_output_text("ri.mio.main.media-item.1")

오디오를 텍스트로 변환

음성이 포함된 오디오 파일을 텍스트로 변환합니다.

작동 대상: 오디오
결과물: 음성을 텍스트로 변환한 비구조화된 평문 파일
파라미터:
- media_item_rid: 변환할 미디어 항목의 RID.
- 언어 (선택 사항): 오디오를 변환할 언어 코드입니다. 비워 두면 오디오 파일 시작 부분에서 언어가 추론됩니다. 세트 1 또는 ISO 언어 이름 중 하나를 사용하세요: https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes
예시:

Copied!1
2
3
4
5
6
7
# 오디오 파일을 음성 인식을 통해 텍스트로 변환합니다.
input_audio_files.transcribe("ri.mio.main.media-item.1")

# 위의 코드는 기본적으로 영어를 기반으로 텍스트를 변환하지만, 
# 아래의 코드처럼 TranscriptionLanguage.ARABIC을 추가하면 
# 아랍어 오디오 파일을 텍스트로 변환하는 것이 가능합니다.
input_audio_files.transcribe("ri.mio.main.media-item.1", TranscriptionLanguage.ARABIC)