TransformersZeroShotTextRouter

사용자가 직접 정의한 분류 라벨을 기준으로 텍스트 입력을 여러 출력 연결로 라우팅해 주는 컴포넌트예요. 미리 라벨을 정해 두고, 오는 텍스트를 그 라벨에 따라 알맞은 경로로 보내고 싶을 때 써요.

파이프라인에서 가장 흔한 위치: 유연함 (Flexible) 필수 init 변수: labels — 분류에 사용할 라벨 리스트 필수 run 변수: text — 분류된 라벨에 따라 지정된 출력 중 하나로 라우팅할 텍스트 출력 변수: <label> — 모델이 할당한 라벨 이름을 딴 출력 연결로 보내진 입력 텍스트. 정의한 라벨마다 출력이 하나씩 있어요. API 레퍼런스: Transformers GitHub 링크: https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/transformers 패키지 이름: transformers-haystack

출처: 문서

본문

개요 (Overview)

TransformersZeroShotTextRouter는 분류 라벨을 기준으로 텍스트 입력을 여러 출력 연결로 라우팅해요. 이 기능은 파이프라인 안에서 쿼리를 각 카테고리에 따라 적절한 컴포넌트로 보낼 때 특히 유용해요. 분류 과정에 쓸 라벨은 사용자가 직접 정의할 수 있어요.

TransformersZeroShotTextRouter는 기본적으로 MoritzLaurer/deberta-v3-base-zeroshot-v1.1-all-33 zero-shot 텍스트 분류 모델을 사용해요. model 파라미터로 원하는 다른 모델을 설정할 수도 있어요.

TransformersZeroShotTextRouter를 사용하려면 필수 labels 파라미터를 제공해야 해요. 각 시퀀스를 분류할 가능한 클래스 라벨의 문자열 리스트예요.

Hugging Face API 토큰 인증은 비공개 모델이나 gated 모델에 접근할 때만 필요해요. 토큰은 초기화할 때 token으로 넘기거나, HF_API_TOKEN 또는 HF_TOKEN 환경 변수로 설정할 수 있어요.

전체 파라미터 목록은 API 레퍼런스에서 확인할 수 있어요.

사용법 (Usage)

TransformersZeroShotTextRouter를 사용하려면 transformers-haystack 패키지를 설치해요:

pip install transformers-haystack

단독으로 사용하기 (On its own)

TransformersZeroShotTextRouter는 단독으로는 효과가 크지 않아요. 이 컴포넌트의 진짜 강점은 파이프라인 안에서 살아나요. 파이프라인에 통합되면 텍스트를 가장 적절한 컴포넌트로 효율적으로 라우팅할 수 있거든요. 아래 다음 섹션에서 완전한 사용 예시를 볼 수 있어요.

파이프라인 안에서 사용하기 (In a pipeline)

아래는 입력 텍스트를 파이프라인의 적절한 경로로 라우팅하는 간단한 파이프라인 예시예요.

먼저 InMemoryDocumentStore를 만들고 독일과 프랑스에 관한 문서를 채운 다음, SentenceTransformersDocumentEmbedder로 이 문서들을 임베딩해요.

그런 다음 TransformersZeroShotTextRouter가 포함된 검색 파이프라인을 만들어서, 들어오는 텍스트를 미리 정의된 라벨 기준으로 "passage" 또는 "query"로 분류해요. 분류 결과에 따라 텍스트는 각각 passage용과 query용 Embedder로 처리돼요. 이 Embedder들이 만든 임베딩은 InMemoryEmbeddingRetriever가 Document Store에서 관련 문서를 찾는 데 사용돼요.

마지막으로 파이프라인을 샘플 텍스트 "What is the capital of Germany?"로 실행해요. 이 입력 텍스트는 "query"로 분류되어 Query Embedder로 보내지고, 이어서 Query Retriever에서 관련 결과를 반환해요.

이 페이지의 예시들은 sentence-transformers-haystack 패키지의 Sentence Transformers embedder를 사용해요. 예시를 실행하려면 설치하세요:

pip install sentence-transformers-haystack

from haystack import Documentfrom haystack.document_stores.in_memory import InMemoryDocumentStorefrom haystack.core.pipeline import Pipelinefrom haystack_integrations.components.routers.transformers import (
    TransformersZeroShotTextRouter,
)
from haystack_integrations.components.embedders.sentence_transformers import (
    SentenceTransformersTextEmbedder,
    SentenceTransformersDocumentEmbedder,
)
from haystack.components.retrievers import InMemoryEmbeddingRetriever

document_store = InMemoryDocumentStore()
doc_embedder = SentenceTransformersDocumentEmbedder(model="intfloat/e5-base-v2")
docs = [
    Document(
        content="Germany, officially the Federal Republic of Germany, is a country in the western region of "
        "Central Europe. The nation's capital and most populous city is Berlin and its main financial centre "
        "is Frankfurt; the largest urban area is the Ruhr."
    ),
    Document(
        content="France, officially the French Republic, is a country located primarily in Western Europe. "
        "France is a unitary semi-presidential republic with its capital in Paris, the country's largest city "
        "and main cultural and commercial centre; other major urban areas include Marseille, Lyon, Toulouse, "
        "Lille, Bordeaux, Strasbourg, Nantes and Nice."
    ),
]
docs_with_embeddings = doc_embedder.run(docs)
document_store.write_documents(docs_with_embeddings["documents"])

p = Pipeline()
p.add_component(
    instance=TransformersZeroShotTextRouter(labels=["passage", "query"]),
    name="text_router",
)
p.add_component(
    instance=SentenceTransformersTextEmbedder(
        model="intfloat/e5-base-v2", prefix="passage: "
    ),
    name="passage_embedder",
)
p.add_component(
    instance=SentenceTransformersTextEmbedder(
        model="intfloat/e5-base-v2", prefix="query: "
    ),
    name="query_embedder",
)
p.add_component(
    instance=InMemoryEmbeddingRetriever(document_store=document_store),
    name="query_retriever",
)
p.add_component(
    instance=InMemoryEmbeddingRetriever(document_store=document_store),
    name="passage_retriever",
)

p.connect("text_router.passage", "passage_embedder.text")
p.connect("passage_embedder.embedding", "passage_retriever.query_embedding")
p.connect("text_router.query", "query_embedder.text")
p.connect("query_embedder.embedding", "query_retriever.query_embedding")

# Query Example
result = p.run({"text_router": {"text": "What is the capital of Germany?"}})
print(result)
# >> {'query_retriever': {'documents': [Document(id=32d393dd8ee60648ae7e630cfe34b1922e747812ddf9a2c8b3650e66e0ecdb5a,
# >> content: 'Germany, officially the Federal Republic of Germany, is a country in the western region of Central E...',
# >> score: 0.8625669285150891), Document(id=c17102d8d818ce5cdfee0288488c518f5c9df238a9739a080142090e8c4cb3ba,
# >> content: 'France, officially the French Republic, is a country located primarily in Western Europe. France is ...',
# >> score: 0.7637571978602222)]}}

추가 레퍼런스 (Additional References)

📓 튜토리얼: Query Classification with TransformersTextRouter and TransformersZeroShotTextRouter

TransformersZeroShotTextRouter