实体检测 | 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 实体及其精确时间戳。

集成实体检测

通过将 entity_detection 参数传入 convert 方法，即可将实体检测集成到语音转文本 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_v3", # 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`	个人姓名，不包括“女士”或“先生”等称谓	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`	包含医疗专业人员头衔的姓名，如“医生”	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_v3",
    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 多声道输出样式不支持实体检测和脱敏。

实体脱敏也适用于 Scribe v2 Realtime：以查询参数传入 entity_redaction 和 entity_redaction_mode，格式与上述相同。每条已提交的转录文本后都会跟随一个 redacted_transcript 事件，其中包含原始 text 和 redacted_text。请参阅实时事件参考。

后续步骤

API 参考文档

完整的文本转语音 API 参考文档和参数说明。

多声道转录

转录多声道音频，并按声道识别说话人。