엔터티 감지 | ElevenLabs Documentation

사용 방법 가이드 · 음성 텍스트 변환 빠른 시작을 완료했다고 가정합니다.

개요

엔터티 감지는 트랜스크립트에서 특정 단어와 구문을 감지하고 정확한 타임스탬프를 제공하는 기능입니다. 신용카드 번호, 이름, 의학적 질환 또는 주민등록번호를 감지하여 이후 삭제 처리하는 데 유용합니다.

활성화하면 모델은 트랜스크립트에서 특정 엔터티 유형을 감지하고 정확한 타임스탬프를 제공합니다.

예를 들어 다음 오디오에서:

엔터티 유형으로 "pii"(개인 식별 정보)를 지정하면 다음 트랜스크립트가 출력됩니다.

{
  "language_code": "eng",
  "language_probability": 0.9869821071624756,
  "text": "My name is Jill. My date of birth is the 12th of July 1987, and my credit card number is 4242-4242-4242-4242.",
  "words": [
    { "text": "My", "start": 0.099, "end": 0.259, "type": "word", "logprob": 0.0 },
    { "text": " ", "start": 0.259, "end": 0.299, "type": "spacing", "logprob": 0.0 },
    { "text": "name", "start": 0.299, "end": 0.42, "type": "word", "logprob": 0.0 },
    ...
  ],
  "transcription_id": "Y2ZX8AxHUzTPCIualYiE",
  "entities": [
    {
      "text": "Jill",
      "entity_type": "name",
      "start_char": 11,
      "end_char": 15
    },
    {
      "text": "12th of July 1987",
      "entity_type": "dob",
      "start_char": 41,
      "end_char": 58
    },
    {
      "text": "4242-4242-4242-4242",
      "entity_type": "credit_card",
      "start_char": 89,
      "end_char": 108
    }
  ]
}

결과에는 트랜스크립트에서 감지된 PII 엔터티와 정확한 타임스탬프가 표시됩니다.

엔터티 감지 통합

convert 메서드에 entity_detection 매개변수를 전달하여 음성 텍스트 변환 API에 엔터티 감지를 통합할 수 있습니다.

import os
from dotenv import load_dotenv
from io import BytesIO
import requests
from elevenlabs.client import ElevenLabs
load_dotenv()
elevenlabs = ElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)
audio_url = (
    "https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/stt-entity-detection-pii.mp3"
)
response = requests.get(audio_url)
audio_data = BytesIO(response.content)
transcription = elevenlabs.speech_to_text.convert(
    file=audio_data,
    model_id="scribe_v2", # Model to use
    # Entity types to detect, accepts a list of specific entity types or categories.
    # To detect all entity types, use the "all" category.
    entity_detection=["pii"],
)
print("Entities detected:", transcription.entities)

엔터티 유형

다음 엔터티 유형을 감지할 수 있습니다. 카테고리 키워드 pii, phi, pci, other, offensive_language를 사용해 전체 그룹을 감지하거나, 라벨로 개별 엔터티 유형을 지정할 수 있습니다. 모든 엔터티 유형을 감지하려면 all 카테고리를 사용하세요.

PII(개인 식별 정보)

라벨	설명	규제 준수
`account_number`	고객 계정 또는 멤버십 식별 번호	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI
`age`	개인의 나이와 관련된 숫자	GDPR, HIPAA, Quebec Privacy Act, APPI
`bank_account`	IBAN 등 은행 계좌 번호 및 국제적 동등 식별자	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI
`cardinal`	기수 형태의 수치 표현
`credit_card`	신용카드 번호	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI
`credit_card_expiration`	신용카드 만료일	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI
`cvv`	3자리 또는 4자리 카드 인증 코드 및 동등 식별자	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI
`date`	요일, 날짜, 월 또는 연도를 포함할 수 있는 특정 달력 날짜	HIPAA, Quebec Privacy Act
`date_interval`	날짜 범위, 월, 계절, 연도, 십 년 단위를 포함한 더 넓은 기간	HIPAA
`dob`	생년월일	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI
`driver_license`	운전면허 번호	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI
`email_address`	이메일 주소	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI
`event`	행사 또는 공휴일 이름
`filename`	확장자 또는 파일 경로를 포함한 컴퓨터 파일 이름
`gender`	속어를 포함한 성 정체성을 나타내는 용어	CPRA, GDPR, GDPR Sensitive, APPI Sensitive
`gender_sexuality`	`gender` 및 `sexual_orientation`을 모두 포함하는 레거시 별칭	CPRA, GDPR, GDPR Sensitive, APPI Sensitive
`sexual_orientation`	속어를 포함한 성적 지향을 나타내는 용어	CPRA, GDPR, GDPR Sensitive, APPI Sensitive
`healthcare_number`	의료 번호 및 건강 보험 수혜자 번호	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI
`ip_address`	IPv4 및 IPv6 형식을 포함한 인터넷 IP 주소	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI
`location`	이름이 지정된 모든 위치 참조를 위한 메타클래스	GDPR, HIPAA, APPI
`location_address`	전체 또는 일부 실제 우편 주소	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI
`location_city`	마을, 소도시, 도시를 포함한 지방자치단체 이름	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI
`location_coordinate`	위도, 경도 및/또는 고도 좌표로 참조되는 지리적 위치	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI
`location_country`	국가 이름	GDPR, APPI
`location_state`	주, 도, 준주 또는 현 이름	GDPR, APPI
`location_zip`	ZIP+4를 포함한 ZIP 코드, 우편번호 또는 postal code	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI
`money`	통화 이름 및/또는 금액
`name`	’Mrs.’ 또는 ‘Mr.’ 같은 개인 호칭을 제외한 개인 이름	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI
`name_given`	보통 출생 시 개인에게 부여되는 이름으로, 서구 문화권에서는 흔히 이름/중간 이름	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI
`name_family`	개인의 가족 또는 공동체를 나타내는 이름으로, 서구 문화권에서는 흔히 성	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI
`name_medical_professional`	”Doctor”와 같은 의료 전문가 직함을 포함한 이름	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI
`numerical_pii`	다른 카테고리에 속하지 않는 숫자형 PII	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI
`occupation`	직책 또는 직업	Quebec Privacy Act, APPI
`ordinal`	서수 형태의 수치 표현
`origin`	국적, 민족 또는 출신을 나타내는 용어	CPRA, GDPR, GDPR Sensitive, Quebec Privacy Act, APPI Sensitive
`passport_number`	모든 국가에서 발급한 여권 번호	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI
`password`	계정 비밀번호, PIN, 액세스 키 또는 인증 답변	CPRA, APPI
`percent`	백분율 형태의 수치 표현
`phone_number`	전화번호 또는 팩스 번호	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI
`physical_attribute`	인종을 나타내는 용어를 포함한 고유한 신체적 특성	CPRA, GDPR, GDPR Sensitive, APPI Sensitive
`ssn`	사회 보장 번호 또는 국제적으로 동등한 정부 식별 번호	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI
`time`	시각을 나타내는 표현
`url`	인터넷 주소	CPRA, GDPR, HIPAA, Quebec Privacy Act
`username`	사용자 이름, 로그인 이름 또는 핸들	CPRA, GDPR, APPI
`vehicle_id`	차량 식별 번호(VIN), 차량 일련 번호 및 번호판 번호	CPRA, GDPR, HIPAA, APPI

PHI(보호 대상 건강 정보)

라벨	설명	규제 준수
`condition`	질환, 질병, 증후군, 결손, 장애의 이름	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI Sensitive
`drug`	의약품, 비타민 및 보충제	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI Sensitive
`injury`	돌연변이, 유산 및 탈구를 포함한 신체 부상	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI Sensitive
`blood_type`	혈액형	CPRA, GDPR, HIPAA, Quebec Privacy Act
`medical_process`	치료, 시술 및 검사를 포함한 의료 과정	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI Sensitive
`clinical_measurement`	임상 측정값, 활력 징후 및 검사실 결과	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI Sensitive
`statistics`	`clinical_measurement`의 레거시 별칭	HIPAA, Quebec Privacy Act

PCI(결제 카드 산업)

라벨	설명	규제 준수
`credit_card`	신용카드 번호	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI
`credit_card_expiration`	신용카드 만료일	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI
`cvv`	3자리 또는 4자리 카드 인증 코드 및 동등 식별자	CPRA, GDPR, HIPAA, Quebec Privacy Act, APPI

기타 엔터티

라벨	설명	규제 준수
`language`	자연어 이름	GDPR, GDPR Sensitive, APPI Sensitive
`marital_status`	혼인 상태를 나타내는 용어	APPI Sensitive
`organization`	조직 또는 조직 내 부서의 이름	Quebec Privacy Act, APPI
`political_affiliation`	정당, 정치 운동 또는 이념을 가리키는 용어	CPRA, GDPR, GDPR Sensitive, Quebec Privacy Act, APPI Sensitive
`religion`	종교적 소속을 나타내는 용어	CPRA, GDPR, GDPR Sensitive, Quebec Privacy Act, APPI Sensitive
`routing_number`	은행 또는 금융기관과 연결된 라우팅 번호
`zodiac_sign`	황도 12궁 별자리 이름
`product_or_service`	상업용 제품 또는 서비스 이름
`food_or_beverage`	음식, 음료 및 요리 이름
`document_reference`	문서, 사건 번호 또는 파일 식별자에 대한 참조
`generic_id`	다른 ID 카테고리에 속하지 않는 일반 식별자
`measurement`	단위가 있는 물리적 측정값 및 수량
`time_duration`	시간의 길이 또는 기간을 나타내는 표현

공격적인 언어

라벨	설명	규제 준수
`very_offensive_language`	비속어를 포함한 매우 공격적인 언어
`less_offensive_language`	약간 공격적이거나 부적절한 언어

엔터티 마스킹

엔터티 감지 외에도 entity_redaction 매개변수를 사용하여 트랜스크립트 텍스트에서 엔터티를 마스킹할 수 있습니다. entity_detection과 같은 형식, 즉 all, 카테고리 키워드 또는 특정 엔터티 유형 목록을 허용합니다. 마스킹되는 유형은 감지된 유형의 하위 집합이어야 합니다.

마스킹을 활성화하면 일치하는 엔터티 텍스트가 트랜스크립트 텍스트와 단어 수준 출력 모두에서 마커로 대체되며, 응답에는 entities 필드가 반환되지 않습니다.

transcription = elevenlabs.speech_to_text.convert(
    file=audio_file,
    model_id="scribe_v2",
    entity_detection=["pii"],
    entity_redaction=["pii"],
    entity_redaction_mode="enumerated_entity_type",
)
print(transcription.text)
# "Hi {NAME_0}, your card ending in {CREDIT_CARD_0} was declined."

entity_redaction_mode 매개변수는 마커 형식을 제어합니다.

모드	마커	예시
`redacted`	모든 엔터티에 `{REDACTED}`	`Hi {REDACTED}`
`entity_type`	중괄호 안의 엔터티 유형	`Hi {NAME}`
`enumerated_entity_type`	엔터티 유형과 발생 횟수 카운터	`Hi {NAME_0}`(기본값)

엔터티 감지 및 마스킹은 combined 멀티채널 출력 스타일에서 지원되지 않습니다.

다음 단계

API 레퍼런스

전체 텍스트 음성 변환 API 레퍼런스 및 매개변수입니다.

멀티채널 트랜스크립션

채널별 화자 속성으로 멀티채널 오디오를 트랜스크립션합니다.