Detección de entidades

Descripción general

La detección de entidades es una función que te permite detectar palabras y frases específicas en la transcripción, proporcionando sus marcas de tiempo exactas. Resulta útil para detectar números de tarjetas de crédito, nombres, afecciones médicas o números de la Seguridad Social, que después pueden ocultarse.

Cuando está activada, el modelo detecta tipos de entidades específicos en la transcripción y proporciona sus marcas de tiempo exactas.

Por ejemplo, el siguiente audio:

Genera la siguiente transcripción cuando especificamos "pii" (información de identificación personal) como tipo de entidad:

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

El resultado muestra las entidades de PII detectadas en la transcripción, con sus marcas de tiempo exactas.

Integrar la detección de entidades

La detección de entidades se integra en la API de Voz a Texto pasando el parámetro entity_detection al 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 entidades

Se admiten los siguientes tipos de entidades para su detección. Puedes detectar grupos completos con las palabras clave de categoría pii, phi, pci, other u offensive_language, o especificar tipos de entidades individuales mediante su etiqueta. Para detectar todos los tipos de entidades, usa la categoría all.

Ocultación de entidades

Además de detectar entidades, puedes ocultarlas del texto de la transcripción con el parámetro entity_redaction. Acepta el mismo formato que entity_detection: all, una palabra clave de categoría o una lista de tipos de entidades específicos. Los tipos ocultados deben ser un subconjunto de los tipos detectados.

Cuando la ocultación está activada, el texto de las entidades coincidentes se sustituye por un marcador tanto en el texto de la transcripción como en la salida por palabra, y el campo entities no se devuelve en la respuesta.

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

El parámetro entity_redaction_mode controla el formato del marcador:

La ocultación de entidades también funciona con Scribe v2 Realtime: pasa entity_redaction y entity_redaction_mode como parámetros de consulta, en el mismo formato que arriba. Cada transcripción confirmada va seguida de un evento redacted_transcript que contiene el text original y el redacted_text. Consulta la referencia de eventos en tiempo real.

Próximos pasos