Transformers documentation

새로운 파이프라인 추가

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

새로운 파이프라인 추가

Pipeline를 서브클래스로 상속하고 몇 가지 메서드를 구현하여 직접 커스터마이즈할 수 있습니다. 코드를 Hub에서 커뮤니티와 공유하고 Transformers에 파이프라인을 등록하면 누구나 빠르고 쉽게 사용할 수 있습니다.

이 가이드에서는 Transformers에 새로운 파이프라인을 추가하는 과정을 안내합니다.

디자인 선택 사항

최소한 Pipeline에 작업을 위한 적절한 입력만 제공하면 됩니다. 파이프라인을 설계할 때도 이 부분부터 시작해야 합니다.

Pipeline가 받을 수 있는 입력 유형을 결정합니다. 문자열, 원시 바이트, 사전 등이 될 수 있습니다. 호환성이 더 좋으므로 가능하면 순수 Python으로 입력을 유지하는 것이 좋습니다. 다음으로, Pipeline이 반환해야 할 출력을 결정합니다. 마찬가지로, 작업하기가 더 쉬우므로 출력을 Python으로 유지하는 것이 가장 간단하고 좋은 선택입니다.

입력과 출력을 단순하게 유지하고, 이상적으로는 JSON 직렬화가 가능하도록 하면 사용자가 새로운 객체 타입을 학습하지 않고도 Pipeline을 실행할 수 있어 편리합니다. 사용 편의성을 극대화하기 위해 다양한 입력 타입을 지원하는 것도 일반적입니다. 예를 들어, 오디오 파일을 파일명, URL 또는 원시 바이트로 허용하면 사용자가 오디오 데이터를 제공하는 방식에 대해 더 많은 유연성을 갖게 됩니다.

파이프라인 만들기

입력과 출력을 결정했으면 Pipeline 구현을 시작할 수 있습니다. 파이프라인은 기본 Pipeline 클래스를 상속받고 4개의 메서드를 포함해야 합니다.

from transformers import Pipeline

class MyPipeline(Pipeline):
    def _sanitize_parameters(self, **kwargs):

    def preprocess(self, inputs, args=2):

    def _forward(self, model_inputs):

    def postprocess(self, model_outputs):
  1. preprocess는 입력을 받아 모델에 적합한 입력 형식으로 변환합니다.
def preprocess(self, inputs, maybe_arg=2):
    model_input = Tensor(inputs["input_ids"])
    return {"model_input": model_input}
  1. _forward는 직접 호출해서는 안 됩니다. forward가 권장되는 메서드이며, 이는 예상된 디바이스에서 모든 것이 올바르게 작동하도록 보장하는 안전 장치를 포함하고 있기 때문입니다. 모델과 관련된 모든 것은 _forward에, 나머지는 preprocess 또는 postprocess에 포함되어야 합니다.
def _forward(self, model_inputs):
    outputs = self.model(**model_inputs)
    return outputs
  1. postprocess는 _forward의 모델 출력을 기반으로 최종 출력을 생성합니다.
def postprocess(self, model_outputs, top_k=5):
    best_class = model_outputs["logits"].softmax(-1)
    return best_class
  1. _sanitize_parameters은 사용자가 Pipeline에 추가 매개변수를 전달할 수 있게 합니다. 이는 초기화 시나 Pipeline이 호출될 때 발생할 수 있습니다. _sanitize_parameters는 preprocess, _forward, postprocess에 직접 전달되는 추가 키워드 인수를 담은 3개의 딕셔너리를 반환합니다. 사용자가 추가 매개변수 없이 파이프라인을 호출한 경우 아무것도 추가하지 마세요. 이는 함수 정의의 기본 인수를 유지하게 하여 항상 더 자연스러운 결과를 제공합니다.

예를 들어, postprocess에 top_k 매개변수를 추가하여 가장 가능성이 높은 상위 5개 클래스를 반환하도록 할 수 있습니다. 그런 다음 _sanitize_parameters에서 사용자가 top_k를 전달했는지 확인하고 postprocess_kwargs에 추가합니다.

def _sanitize_parameters(self, **kwargs):
    preprocess_kwargs = {}
    if "maybe_arg" in kwargs:
        preprocess_kwargs["maybe_arg"] = kwargs["maybe_arg"]

    postprocess_kwargs = {}
    if "top_k" in kwargs:
        postprocess_kwargs["top_k"] = kwargs["top_k"]
    return preprocess_kwargs, {}, postprocess_kwargs

이제 사용자가 원할 경우 파이프라인은 가장 가능성이 높은 상위 라벨을 반환할 수 있습니다.

from transformers import pipeline

pipeline = pipeline("my-task")
# returns 3 most likely labels
pipeline("This is the best meal I've ever had", top_k=3)
# returns 5 most likely labels by default
pipeline("This is the best meal I've ever had")

파이프라인 등록

파이프라인이 지원하는 새 작업을 PIPELINE_REGISTRY에 등록합니다. 레지스트리는 다음을 정의합니다:

  • pt_model을 사용하는 지원되는 Pytorch 모델 클래스
  • default로 모델이 의도대로 작동하는 특정 리비전(브랜치 또는 커밋 해시)에서 가져와야 하는 기본 모델
  • type인 예상 입력
from transformers.pipelines import PIPELINE_REGISTRY
from transformers import AutoModelForSequenceClassification

PIPELINE_REGISTRY.register_pipeline(
    "new-task",
    pipeline_class=MyPipeline,
    pt_model=AutoModelForSequenceClassification,
    default={"pt": ("user/awesome-model", "branch-name")},
    type="text",
)

파이프라인 공유하기

Hub에서 커뮤니티와 파이프라인을 공유하거나 Transformers에 직접 추가할 수 있습니다.

Transformers 팀의 검토가 필요하지 않으므로 파이프라인 코드를 Hub에 업로드하는 것이 더 빠릅니다. 파이프라인을 Transformers에 추가하는 것은 검토가 필요하고 Pipeline이 정상적으로 작동하는지 확인하기 위해 테스트를 추가해야 하므로 더 느릴 수 있습니다.

Hub에 업로드

파이프라인 코드를 Python 파일로 Hub에 추가하세요.

예를 들어, 문장 쌍 분류를 위한 사용자 정의 파이프라인은 다음과 같은 코드를 가질 수 있습니다.

import numpy as np
from transformers import Pipeline

def softmax(outputs):
    maxes = np.max(outputs, axis=-1, keepdims=True)
    shifted_exp = np.exp(outputs - maxes)
    return shifted_exp / shifted_exp.sum(axis=-1, keepdims=True)

class PairClassificationPipeline(Pipeline):
    def _sanitize_parameters(self, **kwargs):
        preprocess_kwargs = {}
        if "second_text" in kwargs:
            preprocess_kwargs["second_text"] = kwargs["second_text"]
        return preprocess_kwargs, {}, {}

    def preprocess(self, text, second_text=None):
        return self.tokenizer(text, text_pair=second_text, return_tensors=self.framework)

    def _forward(self, model_inputs):
        return self.model(**model_inputs)

    def postprocess(self, model_outputs):
        logits = model_outputs.logits[0].numpy()
        probabilities = softmax(logits)

        best_class = np.argmax(probabilities)
        label = self.model.config.id2label[best_class]
        score = probabilities[best_class].item()
        logits = logits.tolist()
        return {"label": label, "score": score, "logits": logits}

pair_classification.py라는 이름의 파일에 코드를 저장하고, 아래에 표시된 대로 가져와서 등록하세요.

from pair_classification import PairClassificationPipeline
from transformers.pipelines import PIPELINE_REGISTRY
from transformers import AutoModelForSequenceClassification

PIPELINE_REGISTRY.register_pipeline(
    "pair-classification",
    pipeline_class=PairClassificationPipeline,
    pt_model=AutoModelForSequenceClassification,
)

register_pipeline 함수는 파이프라인 세부 정보(작업 유형, 파이프라인 클래스, 지원되는 백엔드)를 모델의 config.json 파일에 등록합니다.

  "custom_pipelines": {
    "pair-classification": {
      "impl": "pair_classification.PairClassificationPipeline",
      "pt": [
        "AutoModelForSequenceClassification"
      ],
    }
  },

push_to_hub()을 호출하여 파이프라인을 Hub에 업로드합니다. 코드가 포함된 Python 파일이 Hub로 복사되고, 파이프라인의 모델과 토크나이저도 저장되어 Hub에 업로드됩니다. 이제 파이프라인은 Hub에서 사용자 네임스페이스 아래에서 사용할 수 있습니다.

from transformers import pipeline

pipeline = pipeline(task="pair-classification", model="sgugger/finetuned-bert-mrpc")
pipeline.push_to_hub("pair-classification-pipeline")

trust_remote_code=True를 추가하여 파이프라인을 로드하면 파이프라인을 사용할 수 있습니다.

from transformers import pipeline

pipeline = pipeline(task="pair-classification", trust_remote_code=True)

Transformers에 추가

Transformers에 사용자 정의 파이프라인을 추가하려면 모든 것이 의도대로 작동하는지 확인하기 위해 테스트를 추가하고, Transformers 팀의 리뷰를 요청해야 합니다.

pipelines 서브모듈에 파이프라인 코드를 새 모듈로 추가하고, pipelines/init.py에 정의된 작업 목록에 추가하세요.

다음으로, transformers/tests/pipelines에 파이프라인을 위한 새로운 테스트를 추가합니다. 파이프라인을 테스트하는 방법에 대한 예시를 확인하려면 다른 테스트를 참고할 수 있습니다.

run_pipeline_test 함수는 매우 범용적이어야 하며, model_mapping에 정의된 모델에서 실행되어야 합니다. 이는 새로운 모델과의 향후 호환성을 테스트하는 데 중요합니다.

ANY가 run_pipeline_test 함수 전반에 걸쳐 사용된다는 점도 주목할 만합니다. 모델이 랜덤이므로 실제 값을 확인할 수 없습니다. ANY를 사용하면 테스트가 파이프라인 유형의 출력과 일치하도록 할 수 있습니다.

마지막으로, 다음 4개의 테스트도 구현해야 합니다.

  1. test_small_model_pt에서는 이러한 파이프라인이 올바른 출력을 반환하는지 확인하기 위해 작은 모델을 사용합니다. 결과가 의미 있는 것이 아니어도 됩니다. 각 파이프라인은 동일한 결과를 반환해야 합니다.
  2. test_large_model_pt는 이러한 파이프라인이 의미 있는 결과를 반환하는지 확인하기 위해 현실적인 모델을 사용합니다. 이러한 테스트는 느리므로 slow로 표시해야 합니다.
Update on GitHub