TransformersNamedEntityExtractor
TransformersNamedEntityExtractor
텍스트 속에서 정해진 개체(엔티티)를 찾아내 문서의 meta 필드에 기록해 주는 컴포넌트예요. 사람 이름, 조직, 위치 같은 것들을 모델이 자동으로 인식해서 분류해 줘요.
파이프라인에서 가장 흔한 위치: 인덱싱 파이프라인의 PreProcessor 다음, 또는 쿼리 파이프라인의 Retriever 다음
필수 init 변수: model — 사용할 모델의 이름 또는 경로
필수 run 변수: documents — 문서 리스트
출력 변수: documents — 문서 리스트
API 레퍼런스: Transformers
GitHub 링크: https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/transformers
패키지 이름: transformers-haystack
출처: 문서
본문
개요 (Overview)
TransformersNamedEntityExtractor는 텍스트에서 개체, 그러니까 텍스트 안의 특정 구간(span)을 찾아내요. 추출기는 이 구간들을 클래스에 따라 자동으로 인식하고 묶어 주는데, 예를 들어 사람 이름, 조직, 위치 같은 유형이 있어요. 정확한 클래스는 컴포넌트를 초기화할 때 지정한 모델이 결정해요. 그러니까 "어떤 개체를 인식할지"는 결국 모델이 정한다고 보면 돼요.
TransformersNamedEntityExtractor는 문서 리스트를 받아서, 각 문서의 meta 데이터에 NamedEntityAnnotations를 추가한 동일한 문서 리스트를 반환해요. 하나의 NamedEntityAnnotation은 개체의 유형, 구간의 시작과 끝 지점, 그리고 모델이 계산한 점수로 구성돼요. 예를 들면 이런 형태예요:
NamedEntityAnnotation(entity='PER', start=11, end=16, score=0.9)
TransformersNamedEntityExtractor를 초기화할 때는 model을 반드시 설정해야 해요. 선택적으로 pipeline_kwargs를 설정할 수 있는데, 이 값은 Hugging Face 파이프라인에 그대로 전달돼요. 또 컴포넌트를 실행할 때 사용할 device도 추가로 설정할 수 있어요.
Hugging Face API 토큰 인증은 비공개 모델이나 gated 모델에 접근할 때만 필요해요. 토큰은 초기화할 때 token으로 넘기거나, HF_API_TOKEN 또는 HF_TOKEN 환경 변수로 설정할 수 있어요.
사용법 (Usage)
TransformersNamedEntityExtractor를 사용하려면 transformers-haystack 패키지를 설치해요:
pip install transformers-haystack
이 컴포넌트는 토큰 분류(token classification)나 NER을 지원하는 어떤 Hugging Face 모델과도 잘 동작해요.
TransformersNamedEntityExtractor는 Documents 리스트를 입력으로 받아요. 추출기는 문서의 원문 텍스트를 주석 처리하고, 그 주석을 문서의 meta 딕셔너리 안 named_entities 키 아래에 저장해요.
from haystack.dataclasses import Documentfrom haystack_integrations.components.extractors.transformers import (
TransformersNamedEntityExtractor,
)
extractor = TransformersNamedEntityExtractor(model="dslim/bert-base-NER")
documents = [
Document(content="My name is Clara and I live in Berkeley, California."),
Document(content="I'm Merlin, the happy pig!"),
Document(content="New York State is home to the Empire State Building."),
]
result = extractor.run(documents)
print(result["documents"])
결과는 이렇게 나와요:
[Document(id=aec840d1b6c85609f4f16c3e222a5a25fd8c4c53bd981a40c1268ab9c72cee10, content: 'My name is Clara and I live in Berkeley, California.', meta: {'named_entities': [NamedEntityAnnotation(entity='PER', start=11, end=16, score=np.float32(0.99641764)), NamedEntityAnnotation(entity='LOC', start=31, end=39, score=np.float32(0.996198)), NamedEntityAnnotation(entity='LOC', start=41, end=51, score=np.float32(0.9990196))]}),
Document(id=98f1dc5d0ccd9d9950cd191d1076db0f7af40c401dd7608f11c90cb3fc38c0c2, content: 'I'm Merlin, the happy pig!', meta: {'named_entities': [NamedEntityAnnotation(entity='PER', start=4, end=10, score=np.float32(0.99054915))]}),
Document(id=44948ea0eec018b33aceaaedde4616eb9e93ce075e0090ec1613fc145f84b4a9, content: 'New York State is home to the Empire State Building.', meta: {'named_entities': [NamedEntityAnnotation(entity='LOC', start=0, end=14, score=np.float32(0.9989541)), NamedEntityAnnotation(entity='LOC', start=30, end=51, score=np.float32(0.9574631))]})]
저장된 주석 가져오기 (Get stored annotations)
이 컴포넌트에는 get_stored_annotations 헬퍼 클래스 메서드가 포함되어 있어요. 이 메서드로 Document에 저장된 주석을 투명하게(transparently) 가져올 수 있어요.
from haystack.dataclasses import Documentfrom haystack_integrations.components.extractors.transformers import (
TransformersNamedEntityExtractor,
)
extractor = TransformersNamedEntityExtractor(model="dslim/bert-base-NER")
documents = [
Document(content="My name is Clara and I live in Berkeley, California."),
Document(content="I'm Merlin, the happy pig!"),
Document(content="New York State is home to the Empire State Building."),
]
result = extractor.run(documents)
annotations = [
TransformersNamedEntityExtractor.get_stored_annotations(doc)
for doc in result["documents"]
]
print(annotations)
# If a Document doesn't contain any annotations, this returns None.
new_doc = Document(content="In one of many possible worlds...")
assert TransformersNamedEntityExtractor.get_stored_annotations(new_doc) is None