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

모델 어댑터 API

모델 어댑터의 api() 메서드는 이 모델 어댑터의 추론 로직을 실행하기 위해 예상되는 입력과 출력을 명시합니다. 입력과 출력은 별도로 명시됩니다.

`api()` 예시

다음 예시는 하나의 입력인 input_dataframe과 하나의 출력인 output_dataframe를 명시하는 API를 보여줍니다. 입력과 출력 오브젝트는 모두 Pandas 데이터프레임으로 명시되며, 입력 데이터프레임은 input_feature라는 이름의 float 유형의 한 열을 가지고, 출력 데이터프레임은 두 열을 가집니다: (1) float 유형의 input_feature라는 이름의 열과 (2) int 유형의 output_feature라는 이름의 열.

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import palantir_models as pm

# 예제 모델 어댑터 클래스
class ExampleModelAdapter(pm.ModelAdapter):
    ...

    # API 메서드
    @classmethod
    def api(cls):
        # 입력: Pandas 데이터 프레임(input_feature 열을 갖는 float 타입)
        inputs = {
            "input_dataframe": pm.Pandas(columns=[("input_feature", float)])
        }
        # 출력: Pandas 데이터 프레임(input_feature 열을 갖는 float 타입, output_feature 열을 갖는 int 타입)
        outputs = {
            "output_dataframe": pm.Pandas(columns=[("input_feature", float), ("output_feature", int)])
        }
        # 입력과 출력 반환
        return inputs, outputs

    ...

API 정의는 임의의 유형의 다중 입력 또는 결과물을 지원하도록 확장할 수도 있습니다:

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import palantir_models as pm

# 예제 모델 어댑터 클래스
class ExampleModelAdapter(pm.ModelAdapter):
    ...

    # API 메서드
    @classmethod
    def api(cls):
        # 입력 데이터 구성
        inputs = {
            "input_dataframe": pm.Pandas(columns=[("input_feature", float)]),  # 입력 데이터프레임 (input_feature 열)
            "input_parameter": pm.Parameter(float, default=0.0)  # 입력 파라미터 (기본값: 0.0)
        }
        # 출력 데이터 구성
        outputs = {
            "output_dataframe": pm.Pandas(columns=[("input_feature", float), ("output_feature", int)])  # 출력 데이터프레임 (input_feature, output_feature 열)
        }
        return inputs, outputs

    ...

API 유형

모델 어댑터 API의 입력 및 결과물 유형은 아래에 자세히 정의된 다음 클래스로 지정할 수 있습니다:

pm.Pandas, Pandas 데이터프레임을 위해
pm.Spark, Spark 데이터프레임을 위해
pm.Parameter, 상수, 단일 값을 가진 파라미터를 위해
pm.FileSystem, Foundry 데이터셋 파일시스템 접근을 위해
pm.MediaReference, 미디어 출처를 사용할 때

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
# 다음 클래스들은 `palantir_models` 또는 `pm`을 통해 접근 가능합니다.

class Pandas:
    def __init__(self, columns: List[Union[str, Tuple[str, type]]]):
        """
        Pandas 데이터프레임 입력 또는 출력을 정의합니다. 컬럼 이름과 타입 정의는 이 타입의 파라미터로 지정할 수 있습니다.
        """

class Spark:
    def __init__(self, columns: List[Union[str, Tuple[str, type]]] = []):
        """
        Spark 데이터프레임(pyspark.sql.Dataframe) 입력 또는 출력을 정의합니다. 컬럼 이름과 타입 정의는 이 타입의 파라미터로 지정할 수 있습니다.
        """

class Parameter:
    def __init__(self, type: type = Any, default = None):
        """
        상수 단일 값 파라미터 입력 또는 출력을 정의합니다. 이 파라미터의 타입(기본값은 어떤 타입이든 가능)과 기본값은 이 타입의 파라미터로 지정할 수 있습니다.
        """

class FileSystem:
    def __init__(self):
        """
        파일 시스템 접근 입력 또는 출력 객체를 정의합니다. 이 타입은 모델 어댑터의 `transform()` 또는 `transform_write()` 메소드가 Foundry Dataset 객체와 함께 호출될 때만 사용 가능합니다.
        
        입력으로 사용될 경우, 데이터셋의 파일 시스템 표현이 반환됩니다.

        출력으로 사용될 경우, 출력 데이터셋에 파일을 쓰기 위해 `open()` 메소드를 포함하는 객체가 사용됩니다.

        파일 시스템 출력은 `.transform_write()`를 호출하여만 사용 가능하다는 점에 주의하십시오.
        """

class MediaReference:
    def __init__(self):
        """
        입력 객체를 MediaReference 타입으로 정의합니다. 이 입력은 미디어 참조 객체의 문자열화된 JSON 표현 또는 사전 표현 중 하나를 예상합니다.

        이 타입은 API 출력으로 지원되지 않습니다. 
        """

테이블 형식의 열 지정

Pandas 또는 Spark 입력 및 결과물에 대해 열은 열 이름을 지정하는 스트링 목록 또는 (<이름>, <유형>) 형식의 두 개체 튜플 목록으로 지정할 수 있습니다. 여기서 <이름>은 열 이름을 나타내는 스트링이고 <유형>은 열의 데이터 유형을 나타내는 Python 유형입니다. 열 정의에 대한 스트링이 제공되면 유형은 기본적으로 Any로 설정됩니다.

열 유형

다음 유형은 테이블 열에 대해 지원됩니다:

str
int
float
bool
list
dict
set
tuple
typing.Any
MediaReference

열 유형은 강제되지 않으며 이 모델 어댑터의 사용자에게 예상되는 열 유형을 알리는 방법으로 작용합니다. 유일한 예외는 MediaReference 유형으로, 열의 각 요소가 미디어 참조 스트링이어야 하며, 각 요소를 MediaReference 오브젝트로 변환한 다음 이 모델 어댑터의 추론 로직에 전달됩니다.

파라미터 유형

Parameter 입력 및 결과물에 대해 다음 유형이 지원됩니다:

str
int
float
bool
list
dict
set
tuple
typing.Any

파라미터 유형은 강제되며, 지정된 유형에 해당하지 않는 model.transform()의 파라미터 입력은 런타임 오류를 발생시킵니다.