实体检测 | 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`	Internet IP 地址，包括 IPv4 和 IPv6 格式	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 代码（包括 ZIP+4）、邮政编码或邮编	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`	Internet 地址	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`	黄道十二宫星座名称
`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 参考文档和参数。

多声道转录

转录多声道音频，并按声道标注说话人。