Używanie szybkiego interfejsu API do transkrypcji z Azure Speech w Foundry Tools

Interfejs API szybkiej transkrypcji służy do transkrypcji plików audio z zwracaniem wyników synchronicznie i szybciej niż w czasie rzeczywistym. Użyj szybkiej transkrypcji w scenariuszach, w których potrzebujesz transkrypcji nagrania audio tak szybko, jak to możliwe z przewidywalnym opóźnieniem, na przykład:

  • Szybka transkrypcja audio lub wideo, napisy i edycja.
  • Notatki ze spotkania
  • Poczta głosowa

W przeciwieństwie do interfejsu API transkrypcji wsadowej, interfejs API szybkiej transkrypcji generuje tylko transkrypcje w formacie wyświetlania (nie w formacie leksykalnym). Formularz wyświetlania jest bardziej czytelną dla człowieka formą transkrypcji, która obejmuje znaki interpunkcyjne i wielkie litery.

Wskazówka

Możesz również użyć najnowszej transkrypcji mowy opartej na LLM i tłumaczenia mowy za pomocą mowy LLM.

Dostępność funkcji

Tabela przedstawia funkcje transkrypcji obsługiwane przez interfejs API szybkiej transkrypcji, zarówno z obsługą Mowy LLM, jak i bez niej.

Funkcja Szybka transkrypcja (domyślna) Ulepszona technologia mowy LLM Transkrypcja MAI
Transkrypcja ✅ (modele transkrypcji mowy) ✅ (model wielomodalny) ✅ (model wielomodalny)
Tłumaczenie ❌ ✅ (model wielomodalny) ❌
Diarization ✅ ✅ ❌
Kanał (stereo) ✅ ✅ ✅
Filtrowanie wulgaryzmów ✅ ✅ ✅
Określanie ustawień regionalnych ✅ ❌ 1 ✅
Niestandardowe podpowiedzi ❌ ✅ ❌
Lista fraz ✅ ❌ 1 ❌

1W przypadku mowy LLM użyj monitowania, aby kierować stylem danych wyjściowych zamiast używać jawnych ustawień regionalnych lub list fraz.

Możesz wypróbować szybką transkrypcję w Microsoft Foundry bez konieczności pisania kodu.

Wymagania wstępne

Wypróbuj szybką transkrypcję

  1. Zaloguj się do Microsoft Foundry. Upewnij się, że przełącznik New Foundry jest włączony. Te kroki dotyczą rozwiązania Foundry (nowy).
  2. Wybierz pozycję Kompiluj z menu w prawym górnym rogu.
  3. Wybierz pozycję Modele w okienku po lewej stronie.
  4. Na karcie Usługi sztucznej inteligencji są wyświetlane modele Foundry, które są gotowe do użycia w portalu Foundry. Wybierz Azure Mowa — zamiana mowy na tekst, aby otworzyć moduł zamiany mowy na tekst.
  5. Na górnej liście rozwijanej wybierz pozycję Szybka transkrypcja.
  6. Opcjonalnie użyj sekcji Parametry , aby zmienić język, zasady wulgaryzmów i inne ustawienia.
  7. Użyj sekcji Przekazywanie plików , aby wybrać plik audio. Następnie wybierz pozycję Uruchom.
  8. Wyświetl dane wyjściowe transkrypcji na karcie Transkrypcja . Opcjonalnie wyświetl nieprzetworzone dane wyjściowe odpowiedzi interfejsu API na karcie JSON .
  9. Przejdź do karty Kod , aby uzyskać przykładowy kod umożliwiający używanie szybkiej transkrypcji w aplikacji.

Wymagania wstępne

  • Zasób usługi Azure Speech w jednym z regionów, w których jest dostępny szybki interfejs API do transkrypcji. Aby zapoznać się z bieżącą listą obsługiwanych regionów, zobacz tabelę Regiony usługi Mowa.

  • Plik audio (mniej niż 5 godzin długości i mniej niż 500 MB rozmiaru) w jednym z formatów i kodeków obsługiwanych przez wsadowe API transkrypcji: WAV, MP3, OPUS/OGG, FLAC, WMA, AAC, ALAW w kontenerze WAV, MULAW w kontenerze WAV, AMR, WebM i SPEEX. Aby uzyskać więcej informacji na temat obsługiwanych formatów audio, zobacz obsługiwane formaty audio.

Przekazywanie dźwięku

Dane audio można udostępniać na potrzeby szybkiej transkrypcji w następujący sposób:

  • Przekazywanie dźwięku wbudowanego
--form 'audio=@"YourAudioFile"'
  • Dźwięk z publicznego adresu URL
--form 'definition="{"audioUrl": "https://crbn.us/hello.wav"}"'

Wskazówka

W przypadku długich plików audio zaleca się przekazywanie z publicznego adresu URL.

W poniższych sekcjach przesyłanie audio inline jest używane jako przykład.

Użyj szybkiego interfejsu API transkrypcji

Wskazówka

Wypróbuj szybką transkrypcję w portalu Microsoft Foundry.

Uczymy się, jak używać szybkiego interfejsu API transkrypcji (za pośrednictwem Transkrypcje — Transkrybuj) w następujących scenariuszach:

  • Określone ustawienia regionalne: transkrybuj plik audio z określonymi ustawieniami regionalnymi. Jeśli znasz ustawienia regionalne pliku audio, możesz określić go, aby poprawić dokładność transkrypcji i zminimalizować opóźnienie.
  • Identyfikacja języka włączona: transkrybuj plik audio z włączoną identyfikacją języka. Jeśli nie masz pewności co do ustawień regionalnych pliku audio, możesz włączyć identyfikację języka, aby umożliwić usłudze rozpoznawania mowy identyfikowanie ustawień regionalnych (jedno ustawienia regionalne na dźwięk).
  • Transkrypcja wielojęzyczna: transkrypcja pliku audio z najnowszym modelem transkrypcji mowy wielojęzycznej. Jeśli dźwięk zawiera zawartość wielojęzyczną, którą chcesz stale i dokładnie transkrybować, możesz użyć najnowszego modelu transkrypcji mowy wielojęzycznej bez określania kodów ustawień regionalnych.
  • Diarization on: Transkrybuj plik audio z włączoną diarizacją. Diarization rozróżnia różne osoby mówiące w konwersacji. Usługa rozpoznawania mowy zawiera informacje o tym, który prelegent mówił określoną część transkrypcji mowy.
  • Multi-channel on: Transkrybuj plik audio, który ma jeden lub dwa kanały. Transkrypcje wielokanałowe są przydatne w przypadku plików audio z wieloma kanałami, takich jak pliki audio z wieloma głośnikami lub plikami audio z szumem tła. Domyślnie interfejs API szybkiej transkrypcji scala wszystkie kanały wejściowe w jeden kanał, a następnie wykonuje transkrypcję. Jeśli nie jest to pożądane, kanały można transkrybować niezależnie bez scalania.

Utwórz żądanie POST multipart/form-data do punktu końcowego transcriptions przy użyciu pliku audio i właściwości treści żądania.

W poniższym przykładzie pokazano, jak transkrybować plik audio z określonymi ustawieniami regionalnymi. Jeśli znasz ustawienia regionalne pliku audio, możesz określić go, aby poprawić dokładność transkrypcji i zminimalizować opóźnienie.

  • Zastąp YourSpeechResourceKey kluczem zasobu usługi Mowy.
  • Zastąp YourServiceRegion element regionem zasobu Speech.
  • Zastąp YourAudioFile ścieżką do pliku audio.

Ważne

W przypadku zalecanego uwierzytelniania bez klucza za pomocą Microsoft Entra ID, zastąp --header 'Ocp-Apim-Subscription-Key: YourSpeechResourceKey' znakiem --header "Authorization: Bearer YourAccessToken". Aby uzyskać więcej informacji na temat uwierzytelniania bez klucza, zobacz przewodnik z instrukcjami dotyczącymi kontroli dostępu opartej na rolach .

curl --location 'https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/transcriptions:transcribe?api-version=2025-10-15' \
--header 'Content-Type: multipart/form-data' \
--header 'Ocp-Apim-Subscription-Key: YourSpeechResourceKey' \
--form 'audio=@"YourAudioFile"' \
--form 'definition="{
    "locales":["en-US"]}"'

Skonstruuj definicję formularza zgodnie z następującymi instrukcjami:

  • Ustaw opcjonalną (ale zalecaną) locales właściwość, która powinna być zgodna z oczekiwaną lokalizacją danych audio, które mają być przepisane. W tym przykładzie ustawienia regionalne są ustawione na en-US. Aby uzyskać więcej informacji na temat obsługiwanych ustawień regionalnych, zobacz obsługiwane języki dla zamiany mowy na tekst.

Aby uzyskać więcej informacji na temat locales i innych właściwości interfejsu API szybkiej transkrypcji, zobacz sekcję opcje konfiguracji żądań w dalszej części tego przewodnika.

Odpowiedź zawiera durationMilliseconds, offsetMillisecondsi nie tylko. Właściwość combinedPhrases zawiera pełne transkrypcje dla wszystkich osób mówiących.

{
    "durationMilliseconds": 182439,
    "combinedPhrases": [
        {
            "text": "Good afternoon. This is Sam. Thank you for calling Contoso. How can I help? Hi there. My name is Mary. I'm currently living in Los Angeles, but I'm planning to move to Las Vegas. I would like to apply for a loan. Okay. I see you're currently living in California. Let me make sure I understand you correctly. Uh You'd like to apply for a loan even though you'll be moving soon. Is that right? Yes, exactly. So I'm planning to relocate soon, but I would like to apply for the loan first so that I can purchase a new home once I move there. And are you planning to sell your current home? Yes, I will be listing it on the market soon and hopefully it'll sell quickly. That's why I'm applying for a loan now, so that I can purchase a new house in Nevada and close on it quickly as well once my current home sells. I see. Would you mind holding for a moment while I take your information down? Yeah, no problem. Thank you for your help. Mm-hmm. Just one moment. All right. Thank you for your patience, ma'am. May I have your first and last name, please? Yes, my name is Mary Smith. Thank you, Ms. Smith. May I have your current address, please? Yes. So my address is 123 Main Street in Los Angeles, California, and the zip code is 90923. Sorry, that was a 90 what? 90923. 90923 on Main Street. Got it. Thank you. May I have your phone number as well, please? Uh Yes, my phone number is 504-529-2351 and then yeah. 2351. Got it. And do you have an e-mail address we I can associate with this application? uh Yes, so my e-mail address is mary.a.sm78@gmail.com. Mary.a, was that a S-N as in November or M as in Mike? M as in Mike. Mike78, got it. Thank you. Ms. Smith, do you currently have any other loans? Uh Yes, so I currently have two other loans through Contoso. So my first one is my car loan and then my other is my student loan. They total about 1400 per month combined and my interest rate is 8%. I see. And you're currently paying those loans off monthly, is that right? Yes, of course I do. OK, thank you. Here's what I suggest we do. Let me place you on a brief hold again so that I can talk with one of our loan officers and get this started for you immediately. In the meantime, it would be great if you could take a few minutes and complete the remainder of the secure application online at www.contosoloans.com. Yeah, that sounds good. I can go ahead and get started. Thank you for your help. Thank you."
        }
    ],
    "phrases": [
        {
            "offsetMilliseconds": 960,
            "durationMilliseconds": 640,
            "text": "Good afternoon.",
            "words": [
                {
                    "text": "Good",
                    "offsetMilliseconds": 960,
                    "durationMilliseconds": 240
                },
                {
                    "text": "afternoon.",
                    "offsetMilliseconds": 1200,
                    "durationMilliseconds": 400
                }
            ],
            "locale": "en-US",
            "confidence": 0.93554276
        },
        {
            "offsetMilliseconds": 1600,
            "durationMilliseconds": 640,
            "text": "This is Sam.",
            "words": [
                {
                    "text": "This",
                    "offsetMilliseconds": 1600,
                    "durationMilliseconds": 240
                },
                {
                    "text": "is",
                    "offsetMilliseconds": 1840,
                    "durationMilliseconds": 120
                },
                {
                    "text": "Sam.",
                    "offsetMilliseconds": 1960,
                    "durationMilliseconds": 280
                }
            ],
            "locale": "en-US",
            "confidence": 0.93554276
        },
        {
            "offsetMilliseconds": 2240,
            "durationMilliseconds": 1040,
            "text": "Thank you for calling Contoso.",
            "words": [
                {
                    "text": "Thank",
                    "offsetMilliseconds": 2240,
                    "durationMilliseconds": 200
                },
                {
                    "text": "you",
                    "offsetMilliseconds": 2440,
                    "durationMilliseconds": 80
                },
                {
                    "text": "for",
                    "offsetMilliseconds": 2520,
                    "durationMilliseconds": 120
                },
                {
                    "text": "calling",
                    "offsetMilliseconds": 2640,
                    "durationMilliseconds": 200
                },
                {
                    "text": "Contoso.",
                    "offsetMilliseconds": 2840,
                    "durationMilliseconds": 440
                }
            ],
            "locale": "en-US",
            "confidence": 0.93554276
        },
        {
            "offsetMilliseconds": 3280,
            "durationMilliseconds": 640,
            "text": "How can I help?",
            "words": [
                {
                    "text": "How",
                    "offsetMilliseconds": 3280,
                    "durationMilliseconds": 120
                },
                {
                    "text": "can",
                    "offsetMilliseconds": 3440,
                    "durationMilliseconds": 120
                },
                {
                    "text": "I",
                    "offsetMilliseconds": 3560,
                    "durationMilliseconds": 40
                },
                {
                    "text": "help?",
                    "offsetMilliseconds": 3600,
                    "durationMilliseconds": 320
                }
            ],
            "locale": "en-US",
            "confidence": 0.93554276
        },
        {
            "offsetMilliseconds": 5040,
            "durationMilliseconds": 400,
            "text": "Hi there.",
            "words": [
                {
                    "text": "Hi",
                    "offsetMilliseconds": 5040,
                    "durationMilliseconds": 240
                },
                {
                    "text": "there.",
                    "offsetMilliseconds": 5280,
                    "durationMilliseconds": 160
                }
            ],
            "locale": "en-US",
            "confidence": 0.93554276
        },
        {
            "offsetMilliseconds": 5440,
            "durationMilliseconds": 800,
            "text": "My name is Mary.",
            "words": [
                {
                    "text": "My",
                    "offsetMilliseconds": 5440,
                    "durationMilliseconds": 80
                },
                {
                    "text": "name",
                    "offsetMilliseconds": 5520,
                    "durationMilliseconds": 120
                },
                {
                    "text": "is",
                    "offsetMilliseconds": 5640,
                    "durationMilliseconds": 80
                },
                {
                    "text": "Mary.",
                    "offsetMilliseconds": 5720,
                    "durationMilliseconds": 520
                }
            ],
            "locale": "en-US",
            "confidence": 0.93554276
        },
        // More transcription results...
        // Redacted for brevity
        {
            "offsetMilliseconds": 180320,
            "durationMilliseconds": 680,
            "text": "Thank you for your help.",
            "words": [
                {
                    "text": "Thank",
                    "offsetMilliseconds": 180320,
                    "durationMilliseconds": 160
                },
                {
                    "text": "you",
                    "offsetMilliseconds": 180480,
                    "durationMilliseconds": 80
                },
                {
                    "text": "for",
                    "offsetMilliseconds": 180560,
                    "durationMilliseconds": 120
                },
                {
                    "text": "your",
                    "offsetMilliseconds": 180680,
                    "durationMilliseconds": 120
                },
                {
                    "text": "help.",
                    "offsetMilliseconds": 180800,
                    "durationMilliseconds": 200
                }
            ],
            "locale": "en-US",
            "confidence": 0.92022026
        },
        {
            "offsetMilliseconds": 181960,
            "durationMilliseconds": 280,
            "text": "Thank you.",
            "words": [
                {
                    "text": "Thank",
                    "offsetMilliseconds": 181960,
                    "durationMilliseconds": 200
                },
                {
                    "text": "you.",
                    "offsetMilliseconds": 182160,
                    "durationMilliseconds": 80
                }
            ],
            "locale": "en-US",
            "confidence": 0.92022026
        }
    ]
}

Uwaga

Usługa rozpoznawania mowy jest elastyczna. Jeśli zostanie wyświetlony kod błędu 429 (zbyt wiele żądań), postępuj zgodnie z najlepszymi rozwiązaniami, aby ograniczyć ograniczanie przepustowości podczas skalowania automatycznego.

Żądanie opcji konfiguracji

Oto kilka opcji właściwości do skonfigurowania transkrypcji podczas wywoływania operacji Transcriptions - Transcribe.

Właściwość Opis Wymagane lub opcjonalne
channels Lista indeksów bazujących na zerze dla kanałów, które mają być transkrybowane oddzielnie. Do dwóch kanałów są obsługiwane, chyba że włączono diaryzację. Domyślnie interfejs API szybkiej transkrypcji scala wszystkie kanały wejściowe w jeden kanał, a następnie wykonuje transkrypcję. Jeśli nie jest to pożądane, kanały można transkrybować niezależnie bez scalania.

Jeśli chcesz oddzielnie transkrybować kanały z pliku audio stereo, musisz określić [0,1], [0]lub [1]. W przeciwnym razie dźwięk stereo jest scalony do mono i tylko jeden kanał jest transkrybowany.

Jeśli dźwięk jest stereo i diaryzacja jest włączona, nie można ustawić channels właściwości na [0,1]. Usługa rozpoznawania mowy nie wspiera diarizacji wielu kanałów.

W przypadku dźwięku mono, właściwość channels jest ignorowana, a dźwięk zawsze jest transkrybowany jako pojedynczy kanał.		 Opcjonalne
diarization Konfiguracja diaryzacji. Diarization to proces rozpoznawania i oddzielania wielu głośników w jednym kanale audio. Na przykład określ wartość "diarization": {"maxSpeakers": 2, "enabled": true}. Następnie plik transkrypcji zawiera speaker wpisy (takie jak "speaker": 0 lub "speaker": 1) dla każdej transkrypcji frazy. Opcjonalne
locales Lista ustawień lokalizacji, które powinny odpowiadać oczekiwanej lokalizacji danych audio do transkrypcji.

Jeśli znasz ustawienia regionalne pliku audio, możesz określić go, aby poprawić dokładność transkrypcji i zminimalizować opóźnienie. Jeśli określono pojedyncze ustawienia regionalne, te ustawienia regionalne są używane do transkrypcji.

Jeśli jednak nie masz pewności co do ustawień regionalnych, możesz określić wiele ustawień regionalnych, aby używać identyfikacji języka. Identyfikacja języka może być dokładniejsza z bardziej szczegółową listą lokalizacji.

Jeśli nie określisz żadnych ustawień regionalnych, usługa mowy użyje najnowszego modelu wielojęzycznego do ich identyfikowania i ciągłej transkrypcji.

Najnowsze obsługiwane języki można uzyskać za pomocą interfejsu API REST Transcriptions - Lista Obsługiwanych Języków Lokalnych (wersja API 2024-11-15 lub późniejsza). Aby uzyskać więcej informacji na temat ustawień regionalnych, zobacz dokumentację obsługi języków w usłudze Mowa.		 Opcjonalne, ale zalecane, jeśli znasz oczekiwane ustawienia regionalne.
phraseList Lista fraz jest listą wyrazów lub fraz podanych przed czasem, aby ułatwić ich rozpoznawanie. Dodanie frazy do listy fraz zwiększa jego znaczenie, co zwiększa prawdopodobieństwo rozpoznania. Na przykład określ wartość phraseList":{"phrases":["Contoso","Jessie","Rehaan"]}. Lista fraz jest obsługiwana za pośrednictwem interfejsu API w wersji 2025-10-15. Aby uzyskać więcej informacji, zobacz Zwiększanie dokładności rozpoznawania za pomocą listy fraz. Opcjonalne
profanityFilterMode Określa sposób obsługi wulgaryzmów w wynikach rozpoznawania. Akceptowane wartości to None wyłączenie filtrowania wulgaryzmów, Masked zastępowanie wulgaryzmów gwiazdkami, Removed usuwanie wszystkich wulgaryzmów z wyniku lub Tags dodawanie tagów wulgaryzmów. Domyślna wartość to Masked. Opcjonalne

Referencyjna Dokumentacja | Pakiet (PyPi) | GitHub Przykłady

Wymagania wstępne

Microsoft Entra ID wymagania wstępne

W przypadku zalecanego uwierzytelniania bez klucza za pomocą Microsoft Entra ID należy wykonać następujące czynności:

  • Zainstaluj Azure CLI używany do uwierzytelniania bez klucza za pomocą Microsoft Entra ID.
  • Cognitive Services User Przypisz rolę do konta użytkownika. Role można przypisać w portalu Azure w obszarze Kontrolka dostępu (IAM)>Dodaj przypisanie roli.

Konfiguracja

  1. Utwórz nowy folder o nazwie transcription-quickstart i przejdź do folderu Szybki start za pomocą następującego polecenia:

    mkdir transcription-quickstart && cd transcription-quickstart

  2. Tworzenie i aktywowanie środowiska Python wirtualnego w celu zainstalowania pakietów potrzebnych na potrzeby tego samouczka. Zalecamy zawsze używanie środowiska wirtualnego lub conda podczas instalowania pakietów Python. W przeciwnym razie możesz przerwać globalną instalację Python. Jeśli masz już zainstalowany Python 3.9 lub nowszy, utwórz środowisko wirtualne przy użyciu następujących poleceń:

    py -3 -m venv .venv
.venv\Scripts\Activate.ps1

    Po aktywowaniu środowiska Python uruchomienie python lub pip z wiersza polecenia używa interpretera Python w folderze .venv aplikacji. Użyj polecenia deactivate, aby zamknąć środowisko wirtualne Python. Możesz ją ponownie uaktywnić później w razie potrzeby.

  3. Utwórz plik o nazwie requirements.txt. Dodaj następujące pakiety do pliku:

    azure-ai-transcription
azure-identity

  4. Zainstaluj pakiety:

    pip install -r requirements.txt

Pobieranie informacji o zasobie

Musisz pobrać punkt końcowy zasobu i klucz API na potrzeby uwierzytelniania.

  1. Zaloguj się do portalu Foundry.

  2. Wybierz pozycję Centrum zarządzania z menu po lewej stronie. W sekcji Połączone zasoby wybierz zasób usługi Rozpoznawania Mowy lub wielu usług.

  3. Wybierz Klucze i punkt końcowy.

  4. Skopiuj wartości Punkt końcowy i Klucz . Użyj tych wartości, aby ustawić zmienne środowiskowe.

  5. Ustaw następujące zmienne środowiskowe:

    $env:AZURE_SPEECH_ENDPOINT="<your-speech-endpoint>"
$env:AZURE_SPEECH_API_KEY="<your-api-key>"

Uwaga

W przypadku uwierzytelniania Microsoft Entra ID (zalecane w środowisku produkcyjnym) zainstaluj azure-identity i skonfiguruj uwierzytelnianie zgodnie z opisem w sekcji Microsoft Entra ID wymagania wstępne.

Code

  1. Utwórz plik o nazwie transcribe_audio_file.py z następującym kodem:

    import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.transcription import TranscriptionClient
from azure.ai.transcription.models import TranscriptionContent, TranscriptionOptions

# Get configuration from environment variables
endpoint = os.environ["AZURE_SPEECH_ENDPOINT"]
api_key = os.environ["AZURE_SPEECH_API_KEY"]

# Create the transcription client
client = TranscriptionClient(endpoint=endpoint, credential=AzureKeyCredential(api_key))

# Path to your audio file (replace with your own file path)
audio_file_path = "<path-to-your-audio-file.wav>"

# Open and read the audio file
with open(audio_file_path, "rb") as audio_file:
    # Create transcription options
    options = TranscriptionOptions(locales=["en-US"])  # Specify the language

    # Create the request content
    request_content = TranscriptionContent(definition=options, audio=audio_file)

    # Transcribe the audio
    result = client.transcribe(request_content)

    # Print the transcription result
    print(f"Transcription: {result.combined_phrases[0].text}")

    # Print detailed phrase information
    if result.phrases:
        print("\nDetailed phrases:")
        for phrase in result.phrases:
            print(
                f"  [{phrase.offset_milliseconds}ms - "
                f"{phrase.offset_milliseconds + phrase.duration_milliseconds}ms]: "
                f"{phrase.text}"
            )

    Dokumentacja: TranscriptionClient | TranscriptionContent | TranscriptionOptions | AzureKeyCredential

  2. Zastąp <path-to-your-audio-file.wav> ciąg ścieżką do pliku audio. Usługa obsługuje formatY WAV, MP3, FLAC, OGG i inne typowe formaty audio.

  3. Uruchom skrypt Python:

    python transcribe_audio_file.py

Wyjście

Skrypt wyświetla wynik transkrypcji w konsoli:

Transcription: Hi there! This is a sample voice recording created for speech synthesis testing. The quick brown fox jumps over the lazy dog. Just a fun way to include every letter of the alphabet. Numbers, like 1, 2, 3, are spoken clearly. Let's see how well this voice captures tone, timing, and natural rhythm. This audio is provided by samplefiles.com.

Detailed phrases:
  [40ms - 4880ms]: Hi there! This is a sample voice recording created for speech synthesis testing.
  [5440ms - 8400ms]: The quick brown fox jumps over the lazy dog.
  [9040ms - 12240ms]: Just a fun way to include every letter of the alphabet.
  [12720ms - 16720ms]: Numbers, like 1, 2, 3, are spoken clearly.
  [17200ms - 22000ms]: Let's see how well this voice captures tone, timing, and natural rhythm.
  [22480ms - 25920ms]: This audio is provided by samplefiles.com.

Żądanie opcji konfiguracji

Użyj TranscriptionOptions do dostosowywania zachowania transkrypcji. W poniższych sekcjach opisano każdą obsługiwaną konfigurację i pokazano, jak ją zastosować.

Wykrywanie wielu języków

Przekaż wielu kandydatów na ustawienia regionalne do locales, aby umożliwić identyfikację języka w różnych systemach językowych. Usługa wykrywa język mówiony i oznacza poszczególne frazy wykrytymi ustawieniami regionalnymi. Pomiń locales całkowicie, aby umożliwić usłudze automatyczne wykrywanie wszystkich języków bez listy kandydatów.

from azure.core.credentials import AzureKeyCredential
from azure.ai.transcription import TranscriptionClient
from azure.ai.transcription.models import TranscriptionContent, TranscriptionOptions

client = TranscriptionClient(
    endpoint=endpoint, credential=AzureKeyCredential(api_key)
)

with open(audio_file_path, "rb") as audio_file:
    # Provide candidate locales — the service selects the best match per phrase
    options = TranscriptionOptions(locales=["en-US", "es-ES", "fr-FR", "de-DE"])
    result = client.transcribe(TranscriptionContent(definition=options, audio=audio_file))

    for phrase in result.phrases:
        locale = phrase.locale if phrase.locale else "detected"
        print(f"[{locale}] {phrase.text}")

Odwołanie: TranscriptionOptions

Diaryzacja osoby mówiącej

Diarization wykrywa i oznacza różne głośniki w jednym kanale audio. TranscriptionDiarizationOptions Utwórz obiekt z maksymalną oczekiwaną liczbą prelegentów (2–35) i przekaż go do TranscriptionOptions. Każda fraza w wyniku tożsami się z identyfikatorem speaker.

from azure.core.credentials import AzureKeyCredential
from azure.ai.transcription import TranscriptionClient
from azure.ai.transcription.models import (
    TranscriptionContent,
    TranscriptionOptions,
    TranscriptionDiarizationOptions,
)

client = TranscriptionClient(
    endpoint=endpoint, credential=AzureKeyCredential(api_key)
)

with open(audio_file_path, "rb") as audio_file:
    diarization_options = TranscriptionDiarizationOptions(
        max_speakers=5  # Hint for maximum number of speakers (2-35)
    )
    options = TranscriptionOptions(
        locales=["en-US"], diarization_options=diarization_options
    )
    result = client.transcribe(TranscriptionContent(definition=options, audio=audio_file))

    for phrase in result.phrases:
        speaker = phrase.speaker if phrase.speaker is not None else "Unknown"
        print(f"Speaker {speaker} [{phrase.offset_milliseconds}ms]: {phrase.text}")

Uwaga

Diarization jest obsługiwana tylko w dźwięku jednokanałowym (mono). Jeśli dźwięk jest stereo, nie ustawiaj właściwości na channels wartość po włączeniu [0, 1] diaryzacji.

Referencja: TranscriptionDiarizationOptions, TranscriptionOptions

Lista fraz

Lista fraz zwiększa dokładność rozpoznawania terminów specyficznych dla domeny, właściwych rzeczowników i nietypowych słów. Ustaw biasing_weight między 1.0 i 20.0 , aby kontrolować, jak mocno są preferowane frazy (wyższe wartości zwiększają stronniczość).

from azure.core.credentials import AzureKeyCredential
from azure.ai.transcription import TranscriptionClient
from azure.ai.transcription.models import (
    TranscriptionContent,
    TranscriptionOptions,
    PhraseListProperties,
)

client = TranscriptionClient(
    endpoint=endpoint, credential=AzureKeyCredential(api_key)
)

with open(audio_file_path, "rb") as audio_file:
    phrase_list = PhraseListProperties(
        phrases=["Contoso", "Jessie", "Rehaan"],
        biasing_weight=5.0,  # Weight between 1.0 and 20.0
    )
    options = TranscriptionOptions(locales=["en-US"], phrase_list=phrase_list)
    result = client.transcribe(TranscriptionContent(definition=options, audio=audio_file))

    print(result.combined_phrases[0].text)

Aby uzyskać więcej informacji, zobacz Zwiększanie dokładności rozpoznawania za pomocą listy fraz.

Referencja: PhraseListProperties, TranscriptionOptions

Filtrowanie wulgaryzmów

Określ sposób wyświetlania wulgaryzmów w danych wyjściowych transkrypcji przy użyciu parametru profanity_filter_mode . Dostępne są następujące tryby:

Tryb Zachowanie
"None" Wulgaryzm przechodzi bez zmian.
"Masked" Wulgaryzm jest zastępowany gwiazdkami (ustawienie domyślne).
"Removed" Wulgaryzm jest całkowicie usuwany z danych wyjściowych.
"Tags" Wulgaryzmy są ujęte w <profanity> tagi XML. 
from azure.core.credentials import AzureKeyCredential
from azure.ai.transcription import TranscriptionClient
from azure.ai.transcription.models import TranscriptionContent, TranscriptionOptions

client = TranscriptionClient(
    endpoint=endpoint, credential=AzureKeyCredential(api_key)
)

with open(audio_file_path, "rb") as audio_file:
    options = TranscriptionOptions(
        locales=["en-US"],
        profanity_filter_mode="Masked"  # Options: "None", "Removed", "Masked", "Tags"
    )
    result = client.transcribe(TranscriptionContent(definition=options, audio=audio_file))

    print(result.combined_phrases[0].text)

Odwołanie: TranscriptionOptions

Dokumentacja referencyjna | Package (NuGet) | Przykłady GitHub

Wymagania wstępne

Microsoft Entra ID wymagania wstępne

W przypadku zalecanego uwierzytelniania bez klucza za pomocą Microsoft Entra ID należy wykonać następujące czynności:

  • Zainstaluj Azure CLI używany do uwierzytelniania bez klucza za pomocą Microsoft Entra ID.
  • Zaloguj się przy użyciu Azure CLI, uruchamiając az login.
  • Cognitive Services User Przypisz rolę do konta użytkownika. Role można przypisać w portalu Azure w obszarze Kontrolka dostępu (IAM)>Dodaj przypisanie roli.

Konfigurowanie projektu

  1. Utwórz nową aplikację konsolową przy użyciu interfejsu wiersza polecenia .NET:

    dotnet new console -n transcription-quickstart
cd transcription-quickstart

  2. Zainstaluj wymagane pakiety:

    dotnet add package Azure.AI.Speech.Transcription --prerelease
dotnet add package Azure.Identity

Pobieranie informacji o zasobie

Musisz pobrać punkt końcowy zasobu na potrzeby uwierzytelniania.

  1. Zaloguj się do portalu Foundry.

  2. Wybierz pozycję Centrum zarządzania z menu po lewej stronie. W obszarze Połączone zasoby wybierz zasób usługi Speech lub zasób wielousługowy.

  3. Wybierz Klucze i punkt końcowy.

  4. Skopiuj wartość Punkt końcowy i ustaw ją jako zmienną środowiskową:

    $env:AZURE_SPEECH_ENDPOINT="<your-speech-endpoint>"

Transkrypcja dźwięku

Zastąp zawartość Program.cs następującym kodem:

using System;
using System.ClientModel;
using System.Linq;
using System.Threading.Tasks;
using Azure.AI.Speech.Transcription;
using Azure.Identity;

Uri endpoint = new Uri(Environment.GetEnvironmentVariable("AZURE_SPEECH_ENDPOINT")
    ?? throw new InvalidOperationException("Set the AZURE_SPEECH_ENDPOINT environment variable."));

// Use DefaultAzureCredential for keyless authentication (recommended).
// To use an API key instead, replace with:
// ApiKeyCredential credential = new ApiKeyCredential("<your-api-key>");
var credential = new DefaultAzureCredential();
TranscriptionClient client = new TranscriptionClient(endpoint, credential);

string audioFilePath = "<path-to-your-audio-file.wav>";
using FileStream audioStream = File.OpenRead(audioFilePath);

TranscriptionOptions options = new TranscriptionOptions(audioStream);
ClientResult<TranscriptionResult> response = await client.TranscribeAsync(options);

var channelPhrases = response.Value.PhrasesByChannel.First();
Console.WriteLine(channelPhrases.Text);

Uruchom aplikację:

dotnet run

Transkrypcja tekstu z pliku audio jest wyświetlana na konsoli.

Uzyskiwanie dostępu do szczegółów na poziomie wyrazów

Aby uzyskać dostęp do sygnatur czasowych, współczynników ufności i pojedynczych wyrazów, iteruj frazy:

var channelPhrases = response.Value.PhrasesByChannel.First();

foreach (TranscribedPhrase phrase in channelPhrases.Phrases)
{
    Console.WriteLine($"\nPhrase: {phrase.Text}");
    Console.WriteLine($"  Offset: {phrase.Offset} | Duration: {phrase.Duration}");
    Console.WriteLine($"  Confidence: {phrase.Confidence:F2}");

    foreach (TranscribedWord word in phrase.Words)
    {
        Console.WriteLine(
            $"    Word: '{word.Text}' | " +
            $"Confidence: {word.Confidence:F2} | " +
            $"Offset: {word.Offset}");
    }
}

Referencja: TranscribedPhrase, TranscribedWord

Identyfikacja mówców za pomocą diaryzacji

Diaryzacja osoby mówiącej określa, kto mówił w dźwiękach z wieloma głośnikami:

TranscriptionOptions options = new TranscriptionOptions(audioStream)
{
    DiarizationOptions = new TranscriptionDiarizationOptions
    {
        MaxSpeakers = 4
    }
};

ClientResult<TranscriptionResult> response = await client.TranscribeAsync(options);

var channelPhrases = response.Value.PhrasesByChannel.First();
foreach (TranscribedPhrase phrase in channelPhrases.Phrases)
{
    Console.WriteLine($"Speaker {phrase.Speaker}: {phrase.Text}");
}

Odwołanie: TranscriptionDiarizationOptions

dokumentacja referencyjna | Pakiet (npm) | przykłady GitHub

Wymagania wstępne

Microsoft Entra ID wymagania wstępne

W przypadku zalecanego uwierzytelniania bez klucza za pomocą Microsoft Entra ID należy wykonać następujące czynności:

  • Zainstaluj Azure CLI używany do uwierzytelniania bez klucza za pomocą Microsoft Entra ID.
  • Zaloguj się przy użyciu Azure CLI, uruchamiając az login.
  • Cognitive Services User Przypisz rolę do konta użytkownika. Role można przypisać w portalu Azure w obszarze Kontrolka dostępu (IAM)>Dodaj przypisanie roli.

Konfigurowanie projektu

  1. Utwórz nowy folder i zainicjuj projekt Node.js:

    mkdir transcription-quickstart
cd transcription-quickstart
npm init -y

  2. Zainstaluj wymagane pakiety:

    npm install @azure/ai-speech-transcription @azure/identity

  3. Skonfiguruj projekt tak, aby używał modułów ES, dodając typ modułu do elementu package.json:

    npm pkg set type=module

    Możesz też ręcznie dodać "type": "module" do pliku package.json. Jest to wymagane, aby instrukcje import w przykładowym kodzie działały.

Pobieranie informacji o zasobie

Musisz pobrać punkt końcowy zasobu na potrzeby uwierzytelniania.

  1. Zaloguj się do portalu Foundry.

  2. Wybierz pozycję Centrum zarządzania z menu po lewej stronie. W obszarze Połączone zasoby wybierz zasób usługi Speech lub zasób wielousługowy.

  3. Wybierz Klucze i punkt końcowy.

  4. Skopiuj wartość Punkt końcowy i ustaw ją jako zmienną środowiskową:

    $env:AZURE_SPEECH_ENDPOINT="<your-speech-endpoint>"

Transkrypcja dźwięku

  1. Utwórz plik o nazwie transcribe-audio-file.js zawierający następujący kod:

    import { readFileSync } from "node:fs";
import { DefaultAzureCredential } from "@azure/identity";
import { TranscriptionClient } from "@azure/ai-speech-transcription";

const endpoint = process.env.AZURE_SPEECH_ENDPOINT;
if (!endpoint) {
  throw new Error("Set the AZURE_SPEECH_ENDPOINT environment variable.");
}

// Use DefaultAzureCredential for keyless authentication (recommended).
const client = new TranscriptionClient(endpoint, new DefaultAzureCredential());

const audioFile = readFileSync("<path-to-your-audio-file.wav>");

const result = await client.transcribe(audioFile, {
  locales: ["en-US"],
});

console.log("Transcription:", result.combinedPhrases[0]?.text ?? "No text");

    Dokumentacja: TranscriptionClient | DefaultAzureCredential

  2. Zastąp <path-to-your-audio-file.wav> ciąg ścieżką do pliku audio.

  3. Uruchom aplikację:

    node transcribe-audio-file.js

Wyjście

Aplikacja wyświetla tekst transkrypcji w konsoli:

Transcription: Hi there! This is a sample voice recording.

Typowe opcje żądania

Identyfikacja mówców za pomocą diaryzacji

const result = await client.transcribe(audioFile, {
  locales: ["en-US"],
  diarizationOptions: {
    maxSpeakers: 4,
  },
});

for (const phrase of result.phrases) {
  console.log(`Speaker ${phrase.speaker}: ${phrase.text}`);
}

Referencja: TranscriptionDiarizationOptions

Ustawianie filtrowania wulgaryzmów

import {
  KnownProfanityFilterModes,
} from "@azure/ai-speech-transcription";

const result = await client.transcribe(audioFile, {
  locales: ["en-US"],
  profanityFilterMode: KnownProfanityFilterModes.Masked,
});

Dokumentacja: KnownProfanityFilterModes

Dodawanie listy fraz

Użyj listy fraz, aby ulepszyć rozpoznawanie terminów specyficznych dla domeny, odpowiednich rzeczowników i akronimów:

const result = await client.transcribe(audioFile, {
  locales: ["en-US"],
  phraseList: {
    phrases: ["Contoso", "Jessie", "Rehaan"],
  },
});

console.log("Transcription:", result.combinedPhrases[0]?.text ?? "No text");

Dokumentacja: PhraseListProperties

Włączanie wykrywania wielu języków

Jeśli nie jesteś pewien, jaki język jest używany, podaj wielu kandydatów językowych. Usługa wykrywa język i zwraca ustawienia regionalne dla każdej frazy.

const result = await client.transcribe(audioFile, {
  locales: ["en-US", "es-ES"],
});

for (const phrase of result.phrases) {
  console.log(`[${phrase.locale}] ${phrase.text}`);
}

Dokumentacja: TranskrypcjaPhrase

Dokumentacja referencyjna | Package (Maven) | Przykłady z GitHub

Wymagania wstępne

Konfigurowanie środowiska

  1. Utwórz nowy folder o nazwie transcription-quickstart i przejdź do niego:

    mkdir transcription-quickstart && cd transcription-quickstart

  2. pom.xml Umieść plik w katalogu głównym projektu z następującą zawartością:

    <?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>transcription-quickstart</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>

    <name>Speech Transcription Quickstart</name>
    <description>Quickstart sample for Azure Speech Transcription client library.</description>
    <url>https://github.com/Azure/azure-sdk-for-java</url>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-ai-speech-transcription</artifactId>
            <version>1.0.0-beta.2</version>
        </dependency>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-identity</artifactId>
            <version>1.18.1</version>
        </dependency>
    </dependencies>

    <build>
        <sourceDirectory>.</sourceDirectory>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.11.0</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>3.1.0</version>
                <configuration>
                    <mainClass>TranscriptionQuickstart</mainClass>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

    Uwaga

    Konfiguracja <sourceDirectory>.</sourceDirectory> informuje narzędzie Maven o wyszukaniu plików źródłowych Java w bieżącym katalogu zamiast domyślnej struktury src/main/java. Ta zmiana konfiguracji umożliwia prostszą płaską strukturę projektu.

  3. Zainstaluj zależności:

    mvn clean install

Ustawianie zmiennych środowiskowych

Aby uzyskać dostęp do usługi Rozpoznawanie mowy, aplikacja musi być uwierzytelniona. Zestaw SDK obsługuje zarówno klucz interfejsu API, jak i uwierzytelnianie Microsoft Entra ID. Automatycznie wykrywa, która metoda ma być używana na podstawie ustawionych zmiennych środowiskowych.

Najpierw ustaw punkt końcowy zasobu usługi rozpoznawania mowy. Zastąp <your-speech-endpoint> rzeczywistą nazwą zasobu.

$env:AZURE_SPEECH_ENDPOINT="<your-speech-endpoint>"

Następnie wybierz jedną z następujących metod uwierzytelniania:

Ustaw zmienną środowiskową klucza interfejsu API:

$env:AZURE_SPEECH_API_KEY="<your-speech-key>"

Zamiast ustawiać AZURE_SPEECH_API_KEY, skonfiguruj jedno z następujących źródeł poświadczeń:

  • Azure CLI: Uruchom az login na komputerze deweloperskim.
  • Managed Identity: w przypadku aplikacji działających w Azure (App Service, Azure Functions, maszyn wirtualnych).
  • Zmienne środowiskowe: ustaw AZURE_TENANT_ID, AZURE_CLIENT_ID i AZURE_CLIENT_SECRET.
  • Visual Studio Code lub IntelliJ: zaloguj się za pośrednictwem środowiska IDE.

Musisz również przypisać rolę użytkownika usług Cognitive Services do swojej tożsamości:

az role assignment create --assignee <your-identity> \
    --role "Cognitive Services User" \
    --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<speech-resource-name>

Uwaga

Po ustawieniu zmiennych środowiskowych na Windows uruchom ponownie wszystkie uruchomione programy, które muszą je odczytać, w tym okno konsoli. W systemie Linux lub macOS uruchom source ~/.bashrc (lub równoważny plik konfiguracji powłoki), aby zmiany były aktywne.

Tworzenie aplikacji

Utwórz plik o nazwie TranscriptionQuickstart.java w katalogu projektu przy użyciu następującego kodu:

import com.azure.ai.speech.transcription.TranscriptionClient;
import com.azure.ai.speech.transcription.TranscriptionClientBuilder;
import com.azure.ai.speech.transcription.models.AudioFileDetails;
import com.azure.ai.speech.transcription.models.TranscriptionOptions;
import com.azure.ai.speech.transcription.models.TranscriptionResult;
import com.azure.core.credential.KeyCredential;
import com.azure.core.util.BinaryData;
import com.azure.identity.DefaultAzureCredentialBuilder;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;

public class TranscriptionQuickstart {
    public static void main(String[] args) {
        try {
            // Get credentials from environment variables
            String endpoint = System.getenv("AZURE_SPEECH_ENDPOINT");
            String apiKey = System.getenv("AZURE_SPEECH_API_KEY");

            // Create client with API key or Entra ID authentication
            TranscriptionClientBuilder builder = new TranscriptionClientBuilder()
                .endpoint(endpoint);

            TranscriptionClient client;
            if (apiKey != null && !apiKey.isEmpty()) {
                // Use API key authentication
                client = builder.credential(new KeyCredential(apiKey)).buildClient();
            } else {
                // Use Entra ID authentication
                client = builder.credential(new DefaultAzureCredentialBuilder().build()).buildClient();
            }

            // Load audio file
            String audioFilePath = "<path-to-your-audio-file.wav>";
            byte[] audioData = Files.readAllBytes(Paths.get(audioFilePath));

            // Create audio file details
            AudioFileDetails audioFileDetails = new AudioFileDetails(BinaryData.fromBytes(audioData));

            // Transcribe
            TranscriptionOptions options = new TranscriptionOptions(audioFileDetails);
            TranscriptionResult result = client.transcribe(options);

            // Print result
            System.out.println("Transcription:");
            result.getCombinedPhrases().forEach(phrase ->
                System.out.println(phrase.getText())
            );

        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Zastąp <path-to-your-audio-file.wav> ciąg ścieżką do pliku audio.

Uruchamianie aplikacji

Uruchom aplikację przy użyciu narzędzia Maven:

mvn compile exec:java

Żądanie opcji konfiguracji

Użyj TranscriptionOptions, aby dostosować zachowanie transkrypcji. W poniższych sekcjach opisano każdą obsługiwaną konfigurację i pokazano, jak ją zastosować.

Wykrywanie wielu języków

Jeśli nie określisz ustawień regionalnych, usługa automatycznie wykrywa i transkrybuje wszystkie języki obecne w dźwięku. Każda zwrócona fraza locale zawiera pole identyfikujące wykryty język.

// No locale specified — service auto-detects all languages in the audio
TranscriptionOptions options = new TranscriptionOptions(audioFileDetails);
TranscriptionResult result = client.transcribe(options);

// Each phrase reports the detected locale
result.getPhrases().forEach(phrase ->
    System.out.println(phrase.getLocale() + ": " + phrase.getText())
);

Uwaga

Jeśli nie określono ustawień regionalnych, locale pole dla poszczególnych fraz może nie zawsze dokładnie odzwierciedlać dokładny język tej konkretnej frazy. Aby uzyskać najwyższą dokładność, określ oczekiwane ustawienia regionalne, kiedy je znasz.

Referencja: TranscriptionOptions, TranscribedPhrase.getLocale()

Diaryzacja osoby mówiącej

Diarization wykrywa i oznacza różne głośniki w jednym kanale audio. Użyj TranscriptionDiarizationOptions polecenia , aby ją włączyć i ustawić maksymalną oczekiwaną liczbę głośników (2–36). Każda fraza w wyniku tożsami się z identyfikatorem speaker.

import com.azure.ai.speech.transcription.models.TranscriptionDiarizationOptions;

// Configure diarization with a maximum of 5 speakers
TranscriptionDiarizationOptions diarizationOptions =
    new TranscriptionDiarizationOptions()
        .setMaxSpeakers(5);

TranscriptionOptions options = new TranscriptionOptions(audioFileDetails)
    .setDiarizationOptions(diarizationOptions);

TranscriptionResult result = client.transcribe(options);

// Each phrase includes the detected speaker ID
result.getPhrases().forEach(phrase ->
    System.out.println(
        "[Speaker " + phrase.getSpeaker() + "] " + phrase.getText()
    )
);

Uwaga

Diarization jest obsługiwana tylko w dźwięku jednokanałowym (mono). Jeśli dźwięk jest stereo, nie ustawiaj właściwości na channels wartość po włączeniu [0,1] diaryzacji.

Dokumentacja: TranscriptionDiarizationOptions, TranscriptionOptions.setDiarizationOptions(), TranscribedPhrase.getSpeaker()

Lista fraz

Lista fraz zwiększa dokładność rozpoznawania terminów specyficznych dla domeny, właściwych rzeczowników i nietypowych słów. Dodane frazy są ważone w większym stopniu przez system rozpoznawania, co sprawia, że bardziej prawdopodobna jest poprawna transkrypcja.

import com.azure.ai.speech.transcription.models.PhraseListOptions;
import java.util.Arrays;

// Add terms that appear in your audio to improve recognition
PhraseListOptions phraseListOptions = new PhraseListOptions()
    .setPhrases(Arrays.asList("Contoso", "Jessie", "Rehaan"));

TranscriptionOptions options = new TranscriptionOptions(audioFileDetails)
    .setPhraseListOptions(phraseListOptions);

TranscriptionResult result = client.transcribe(options);

result.getCombinedPhrases().forEach(phrase ->
    System.out.println(phrase.getText())
);

Aby uzyskać więcej informacji, zobacz Zwiększanie dokładności rozpoznawania za pomocą listy fraz.

Odniesienie: PhraseListOptions, TranscriptionOptions.setPhraseListOptions()

Filtrowanie wulgaryzmów

Określ sposób wyświetlania wulgaryzmów w danych wyjściowych transkrypcji przy użyciu polecenia ProfanityFilterMode. Dostępne są następujące tryby:

Tryb Zachowanie
NONE Wulgaryzm przechodzi bez zmian.
MASKED Wulgaryzm jest zastępowany gwiazdkami (ustawienie domyślne).
REMOVED Wulgaryzm jest całkowicie usuwany z danych wyjściowych.
TAGS Wulgaryzm jest opakowany w tagi XML. 
import com.azure.ai.speech.transcription.models.ProfanityFilterMode;

TranscriptionOptions options = new TranscriptionOptions(audioFileDetails)
    .setProfanityFilterMode(ProfanityFilterMode.MASKED);

TranscriptionResult result = client.transcribe(options);

System.out.println(result.getCombinedPhrases().get(0).getText());

Referencja: ProfanityFilterMode, TranscriptionOptions.setProfanityFilterMode()

Czyszczenie zasobów

Po zakończeniu pracy z szybkim startem możesz usunąć folder projektu:

rm -rf transcription-quickstart

Obsługa błędów transkrypcji

Podczas wywoływania szybkiego interfejsu API transkrypcji zaimplementuj logikę ponawiania prób w celu obsługi błędów przejściowych i ograniczania szybkości. Interfejs API wymusza limity szybkości, co może spowodować błąd podczas operacji o wysokiej współbieżności.

  • Ponów próbę do pięciu razy w przypadku błędów przejściowych.

  • Użyj wycofywania wykładniczego: 2 sekundy, 4 s, 8 s, 16 s, 32 s.

  • Całkowity czas wycofywania: 62 s.

Ta konfiguracja zapewnia wystarczający czas na odzyskanie interfejsu API podczas okna ograniczania szybkości, zwłaszcza w przypadku uruchamiania operacji wsadowych z wieloma współbieżnymi pracownikami.

Kiedy należy używać logiki ponawiania prób

Zaimplementuj logikę ponawiania dla następujących kategorii błędów:

  • Błędy HTTP — ponów próbę:

    • HTTP 429 (limit szybkości)
    • HTTP 500, 502, 503, 504 (błędy serwera)
    • status_code=None (niekompletne pobieranie odpowiedzi)

  • Azure SDK błędy sieci — ponów próbę:

    • ServiceRequestError
    • ServiceResponseError

    Te błędy zawierają wyjątki sieciowe niskiego poziomu, takie jak urllib3.exceptions.ReadTimeoutError, resetowania połączeń i błędy protokołu TLS.

  • Wyjątki sieciowe w Pythonie — ponowne próby:

    • ConnectionError
    • TimeoutError
    • OSError

Nie ponawiaj próby po następujących błędach, ponieważ wskazują problemy po stronie klienta, które wymagają korekty:

  • HTTP 400 (nieprawidłowe żądanie)
  • HTTP 401 (nieautoryzowany)
  • HTTP 422 (nieprzetworzona jednostka)
  • Inne błędy klienta (kody stanu 4xx)

Uwagi dotyczące implementacji

  • Zresetuj strumień plików audio (seek(0)) przed każdym ponowieniu próby.

  • W przypadku korzystania z współbieżnych procesów roboczych domyślny limit czasu odczytu HTTP (300 sekund) może zostać przekroczony w przypadku ograniczania dużej szybkości.

  • Interfejs API może zaakceptować żądanie, ale upłynął limit czasu podczas generowania odpowiedzi. Ten warunek może być wyświetlany jako błąd sieci opakowany za pomocą zestawu SDK, a nie standardowy błąd HTTP.

Powiązana zawartość

  • Last updated on