Detecção de entidades

Visão geral

A detecção de entidades é um recurso que permite detectar palavras e frases específicas na transcrição e fornecer seus timestamps exatos. Isso é útil para detectar números de cartão de crédito, nomes, condições médicas ou números de seguridade social, que podem ser ocultados.

Quando ativado, o modelo detecta tipos específicos de entidades na transcrição e fornece seus timestamps exatos.

Por exemplo, o áudio a seguir:

Gera a seguinte transcrição quando especificamos "pii" (Informações de Identificação Pessoal) como o tipo de entidade:

{
  "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
    }
  ]
}

O resultado mostra as entidades de PII detectadas na transcrição, com seus timestamps exatos.

Integração da detecção de entidades

A detecção de entidades é integrada à API Speech to Text ao passar o parâmetro entity_detection para o método convert.

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)

Tipos de entidade

Os seguintes tipos de entidade são compatíveis com a detecção. Você pode detectar grupos inteiros usando as palavras-chave de categoria pii, phi, pci, other ou offensive_language, ou especificar tipos individuais de entidade pelo rótulo. Para detectar todos os tipos de entidade, use a categoria all.

Ocultação de entidades

Além de detectar entidades, você pode ocultá-las do texto da transcrição com o parâmetro entity_redaction. Ele aceita o mesmo formato que entity_detection: all, uma palavra-chave de categoria ou uma lista de tipos específicos de entidade. Os tipos ocultados devem ser um subconjunto dos tipos detectados.

Quando a ocultação está ativada, o texto das entidades correspondentes é substituído por um marcador tanto no texto da transcrição quanto na saída em nível de palavra, e o campo entities não é retornado na resposta.

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."

O parâmetro entity_redaction_mode controla o formato do marcador:

A ocultação de entidades também funciona com o Scribe v2 Realtime: passe entity_redaction e entity_redaction_mode como parâmetros de consulta, no mesmo formato acima. Cada transcrição confirmada é seguida por um evento redacted_transcript que contém o text original e o redacted_text. Consulte a referência de eventos em tempo real.

Próximas etapas