PresidioTextCleaner

PresidioTextCleaner는 일반 문자열에서 개인 식별 정보(PII)를 교체해요. list[str]를 입력으로 받아 list[str]를 반환하므로, 사용자 쿼리를 LLM에 보내기 전에 정제하기 쉽게 해 주죠.

출처: 문서

본문

항목	내용
파이프라인에서 가장 흔한 위치	쿼리 파이프라인에서 Generator 또는 Chat Generator 앞
필수 run 변수	`texts`: 문자열 목록
출력 변수	`texts`: PII가 교체된 문자열 목록
API reference	Presidio
GitHub 링크	presidio 통합
패키지 이름	`presidio-haystack`

개요

Microsoft Presidio는 PII 감지와 익명화를 위한 오픈소스 프레임워크예요. PresidioTextCleaner는 Presidio의 Analyzer와 Anonymizer 엔진을 사용해 일반 텍스트 문자열을 스캔하고, 감지된 엔티티를 <PERSON>이나 <US_SSN> 같은 타입 플레이스홀더로 교체해요.

이 기능은 사용자 쿼리를 LLM에 보내기 전에 정제해, 개인 식별 정보가 모델로 전달되지 않도록 하고 싶을 때 유용해요.

일반 문자열이 아니라 Haystack Document 객체를 정제하려면 PresidioDocumentCleaner를 보세요.

구성

파라미터	기본값	설명
`language`	`"en"`	PII 감지를 위한 ISO 639-1 언어 코드. 지원 언어에 대해 적절한 spaCy 모델이 자동 선택돼요. Presidio 지원 언어 참고
`entities`	`None`	감지·익명화할 PII 엔티티 타입 목록 (예: `["PERSON", "EMAIL_ADDRESS"]`). `None`이면 지원되는 모든 타입을 감지해요. 지원 엔티티 참고
`score_threshold`	`0.35`	감지된 엔티티가 익명화되기 위한 최소 신뢰 점수(0–1)
`models`	`None`	고급 오버라이드: spaCy 모델 구성의 명시적 목록 (예: `[{"lang_code": "fr", "model_name": "fr_core_news_md"}]`). 특정 모델 변형이나 내장 매핑에 없는 언어가 필요할 때만 사용하세요. `None`이면 `language`에 따라 모델이 자동 선택돼요

사용법

PresidioTextCleaner를 사용하려면 presidio-haystack 패키지를 설치하세요.

pip install presidio-haystack

단독으로 사용하기

from haystack_integrations.components.preprocessors.presidio import PresidioTextCleaner

cleaner = PresidioTextCleaner()
result = cleaner.run(texts=["My name is John Doe, my SSN is 123-45-6789"])
print(result["texts"][0])
# My name is <PERSON>, my SSN is <US_SSN>

파이프라인에서 사용하기

from haystack import Pipeline
from haystack.components.builders import ChatPromptBuilder
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.dataclasses import ChatMessage
from haystack_integrations.components.preprocessors.presidio import PresidioTextCleaner

template = [ChatMessage.from_user("Answer this question: {{query}}")]

query_pipeline = Pipeline()
query_pipeline.add_component("cleaner", PresidioTextCleaner())
query_pipeline.add_component("prompt_builder", ChatPromptBuilder(template=template))
query_pipeline.add_component("llm", OpenAIChatGenerator(model="gpt-4o-mini"))
query_pipeline.connect("cleaner.texts[0]", "prompt_builder.query")
query_pipeline.connect("prompt_builder", "llm")

query_pipeline.run(
    {"cleaner": {"texts": ["My name is John Smith. What is the capital of France?"]}},
)

커스텀 파라미터 사용하기

entities를 사용해 실제로 관심 있는 PII 타입에만 익명화를 제한할 수 있어요. 필요 없는 recognizer를 건너뛰므로 오탐을 줄이고 성능도 높여 주죠.

score_threshold로 정밀도-재현율 트레이드오프를 조정할 수 있어요. 기본값 0.35는 넓게 잡기 때문에 일부 오탐을 익명화할 수 있어요. 텍스트를 교체하기 전에 높은 신뢰도가 필요하면 높이고요(예: 0.7), PII를 놓치는 것이 더 큰 위험이라면 낮추면 돼요.

from haystack_integrations.components.preprocessors.presidio import PresidioTextCleaner

cleaner = PresidioTextCleaner(
    language="de",
    entities=["PERSON", "EMAIL_ADDRESS"],  # only anonymize names and emails
    score_threshold=0.7,  # higher precision, fewer false positives
)

비영어 언어

내장 매핑에 있는 언어라면 language만 설정하면 돼요. 적절한 spaCy 모델이 워밍업 시점에 자동으로 선택되고 로드되죠.

from haystack_integrations.components.preprocessors.presidio import PresidioTextCleaner

# No `models` parameter needed — de_core_news_lg is selected automatically
cleaner = PresidioTextCleaner(language="de")
result = cleaner.run(
    texts=["Hallo, ich bin Thomas Schmidt und meine E-Mail ist [email protected]"],
)
print(result["texts"][0])
# Hallo, ich bin <PERSON> und meine E-Mail ist <EMAIL_ADDRESS>

지원 언어와 기본 모델은 PresidioTextCleaner.SPACY_DEFAULT_MODELS에 나열돼 있어요. 그 매핑에 없는 언어를 models 없이 사용하면 워밍업 시점에 지원 언어 코드 목록과 함께 ValueError가 발생해요.

기본이 아닌 모델 변형이나 내장 매핑 밖의 언어를 사용하려면 models를 명시적으로 전달하세요:

cleaner = PresidioTextCleaner(
    language="fr",
    models=[{"lang_code": "fr", "model_name": "fr_core_news_md"}],
)

PresidioTextCleaner