Dokumen ini adalah panduan dasar-dasar penggunaan Cloud Speech-to-Text. Panduan konseptual ini membahas jenis permintaan yang dapat Anda buat ke Cloud STT, cara membuat permintaan tersebut, dan cara menangani responsnya. Sebaiknya semua pengguna Cloud STT membaca panduan ini dan salah satu tutorial terkait sebelum mendalami API itu sendiri.
Coba sendiri
Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa Cloud STT dalam skenario dunia nyata. Pelanggan baru juga akan mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.
Coba Cloud STT gratisPermintaan ucapan
Cloud STT memiliki tiga metode utama untuk melakukan pengenalan ucapan:
Pengenalan sinkron (REST dan gRPC) mengirimkan data audio ke Cloud Speech-to-Text API, melakukan pengenalan pada data tersebut, dan menampilkan hasil setelah semua audio diproses. Permintaan pengenalan sinkron dibatasi untuk data audio dengan durasi 1 menit atau kurang.
Pengenalan Asinkron (REST dan gRPC) mengirimkan data audio ke Cloud Speech-to-Text API dan memulai Operasi yang Berjalan Lama. Dengan operasi ini, Anda dapat melakukan polling hasil pengenalan secara berkala. Gunakan permintaan asinkron untuk data audio dengan durasi hingga 480 menit.
Pengenalan Aliran Data (khusus gRPC) menjalankan pengenalan atas data audio yang disediakan dalam aliran data dua arah gRPC. Permintaan streaming didesain untuk tujuan pengenalan real-time, seperti saat merekam audio live dari mikrofon. Pengenalan streaming memberikan hasil sementara saat audio direkam, sehingga hasil dapat muncul, misalnya, saat pengguna masih berbicara.
Permintaan berisi parameter konfigurasi serta data audio. Bagian berikut menjelaskan jenis permintaan pengenalan ini, respons yang dihasilkannya, dan cara menangani respons tersebut secara lebih mendetail.
Pengenalan Cloud Speech-to-Text API
Permintaan pengenalan sinkron Cloud Speech-to-Text API adalah metode paling sederhana untuk menjalankan pengenalan atas data audio ucapan. Cloud STT dapat memproses data audio ucapan berdurasi hingga 1 menit yang dikirim dalam permintaan sinkron. Setelah memproses dan mengenali semua audio, Cloud STT akan menampilkan respons.
Permintaan sinkron bersifat memblokir, yang berarti Cloud STT harus menampilkan respons sebelum memproses permintaan berikutnya. Cloud STT biasanya memproses audio lebih cepat daripada waktu sebenarnya, rata-rata memproses audio berdurasi 30 detik dalam 15 detik. Jika kualitas audio buruk, permintaan pengenalan Anda dapat memerlukan waktu jauh lebih lama.
Permintaan Pengenalan Ucapan Sinkron
Permintaan Cloud Speech-to-Text API sinkron terdiri atas konfigurasi pengenalan ucapan dan data audio. Contoh:
{ "config": { "encoding": "LINEAR16", "sampleRateHertz": 16000, "languageCode": "en-US", }, "audio": { "uri": "gs://bucket-name/path_to_audio_file" } }
Semua permintaan pengenalan sinkron Cloud Speech-to-Text API harus menyertakan kolom config pengenalan ucapan (dari jenis RecognitionConfig). RecognitionConfig berisi sub-kolom berikut:
encoding: Wajib diisi. Menentukan skema encoding untuk audio yang disediakan (dari jenisAudioEncoding). Jika memiliki pilihan codec, sebaiknya Anda menggunakan encoding lossless seperti FLAC atauLINEAR16untuk performa terbaik. (Untuk mengetahui informasi selengkapnya, lihat Encoding Audio.) Kolomencodingbersifat opsional untuk file FLAC dan WAV yang encoding-nya disertakan dalam header file.sampleRateHertz: Wajib diisi. Menentukan frekuensi sampel (dalam Hertz) untuk audio yang disediakan. (Untuk informasi lebih lanjut tentang frekuensi sampel, lihat Frekuensi Sampel di bawah.) KolomsampleRateHertzbersifat opsional untuk file FLAC dan WAV yang frekuensi sampelnya disertakan dalam header file.languageCode: Wajib diisi. Berisi bahasa serta wilayah atau lokalitas yang akan digunakan untuk pengenalan ucapan audio yang disediakan. Kode bahasa harus berupa ID BCP-47. Perlu diperhatikan bahwa kode bahasa biasanya terdiri atas tag bahasa primer dan subtag wilayah sekunder untuk menunjukkan dialek (misalnya, dalam contoh sebelumnya, 'en' untuk bahasa Inggris dan 'US' untuk Amerika Serikat.) (Untuk mengetahui daftar bahasa yang didukung, lihat Bahasa yang Didukung.)maxAlternatives: Opsional, defaultnya adalah1. Menunjukkan jumlah transkripsi alternatif yang harus disediakan dalam respons. Secara default, Cloud Speech-to-Text API menyediakan satu transkripsi primer. Jika Anda ingin mengevaluasi alternatif lainnya, tetapkanmaxAlternativeske nilai yang lebih tinggi. Perhatikan bahwa Cloud STT hanya akan menampilkan alternatif jika pengenal menentukan alternatif memiliki kualitas yang memadai; secara umum, alternatif lebih sesuai untuk permintaan real-time yang memerlukan masukan pengguna (misalnya, perintah suara) dan oleh karena itu lebih cocok untuk permintaan pengenalan streaming.profanityFilter: Opsional. Menunjukkan apakah kata atau frasa yang tidak sopan harus difilter. Kata yang difilter akan berisi huruf pertama dan tanda bintang untuk karakter selebihnya (misalnya f***). Filter kata-kata tidak sopan beroperasi per kata. Filter ini tidak mendeteksi ucapan kasar atau menyinggung yang berupa frasa atau kombinasi kata.speechContext: Opsional. Berisi informasi kontekstual tambahan untuk memproses audio ini. Konteks berisi sub-kolom berikut:boost: Berisi nilai yang menetapkan bobot untuk mengenali kata atau frasa tertentu.phrases: Berisi daftar kata dan frasa yang memberikan petunjuk untuk tugas pengenalan ucapan. Untuk mengetahui informasi selengkapnya, lihat informasi tentang adaptasi ucapan.
Audio dimasukkan ke Cloud STT melalui parameter audio dari jenis RecognitionAudio. Kolom audio berisi salah satu sub-kolom berikut:
contentberisi audio yang akan dievaluasi, yang disematkan ke dalam permintaan. Lihat Menyematkan Konten Audio untuk mengetahui informasi selengkapnya. Durasi audio yang diteruskan langsung dalam kolom ini dibatasi maksimal 1 menit.uriberisi URI yang mengarah ke konten audio. File tidak boleh dikompresi (misalnya gzip). Kolom ini harus berisi URI Cloud Storage (dengan formatgs://bucket-name/path_to_audio_file). Lihat Meneruskan referensi Audio dengan URI.
Frekuensi sampel
Anda harus menentukan frekuensi sampel audio di kolom sampleRateHertz konfigurasi permintaan, yang harus cocok dengan frekuensi sampel konten atau aliran data audio yang terkait. Frekuensi sampel antara 8.000 Hz dan 48.000 Hz didukung dalam Cloud STT. Anda dapat menentukan frekuensi sampel untuk file FLAC atau
WAV di header file, bukan menggunakan kolom sampleRateHertz.
File FLAC harus mencantumkan frekuensi sampelnya di header FLAC agar dapat dikirim ke Speech-to-Text API.
Jika Anda memiliki pilihan saat mengenkode materi sumber, rekam audio menggunakan frekuensi sampel 16.000 Hz. Nilai yang lebih rendah dari ini dapat menghalangi akurasi pengenalan suara, sementara tingkat yang lebih tinggi tidak memiliki pengaruh yang signifikan terhadap kualitas pengenalan ucapan.
Namun, jika data audio telah direkam dengan frekuensi sampel yang ada selain 16.000 Hz, jangan lakukan resampling pada audio menjadi 16.000 Hz. Sebagian besar audio telepon lama, misalnya, menggunakan frekuensi sampel 8.000 Hz, yang mungkin memberikan hasil yang kurang akurat. Jika harus menggunakan audio semacam ini, sediakan audio ke Speech API sesuai frekuensi sampel aslinya.
Bahasa
Mesin pengenalan Cloud STT mendukung berbagai bahasa dan
dialek. Tentukan bahasa (dan dialek nasional atau regional) audio Anda dalam kolom languageCode pada konfigurasi permintaan, menggunakan ID BCP-47.
Daftar lengkap bahasa yang didukung untuk setiap fitur tersedia di halaman Dukungan Bahasa.
Selisih waktu (stempel waktu)
Cloud STT dapat menyertakan nilai selisih waktu (stempel waktu) untuk awal dan akhir setiap kata yang diucapkan dan dikenali dalam audio yang disediakan. Nilai selisih waktu menunjukkan jumlah waktu yang telah berlalu dari awal audio, dalam kelipatan 100 milidetik.
Selisih waktu sangat berguna untuk menganalisis file audio yang lebih panjang, di mana Anda mungkin perlu menelusuri kata tertentu dalam teks yang dikenali dan menemukan lokasinya (mencari) dalam audio asli. Selisih waktu didukung untuk semua metode pengenalan: recognize, streamingrecognize, dan longrunningrecognize.
Nilai selisih waktu hanya dicantumkan untuk alternatif pertama yang disediakan dalam respons pengenalan.
Untuk mencantumkan selisih waktu dalam hasil permintaan, tetapkan parameter enableWordTimeOffsets ke benar dalam konfigurasi permintaan Anda. Untuk contoh penggunaan REST API atau Library Klien, lihat Menggunakan Selisih Waktu (Stempel Waktu).
Misalnya, Anda dapat mencantumkan parameter enableWordTimeOffsets dalam konfigurasi permintaan seperti yang ditunjukkan di sini:
{ "config": { "languageCode": "en-US", "enableWordTimeOffsets": true }, "audio":{ "uri":"gs://gcs-test-data/gettysburg.flac" } }
Hasil yang ditampilkan oleh Cloud Speech-to-Text API akan berisi nilai selisih waktu untuk setiap kata yang dikenali seperti yang ditunjukkan berikut ini:
{ "name": "6212202767953098955", "metadata": { "@type": "type.googleapis.com/google.cloud.speech.v1.LongRunningRecognizeMetadata", "progressPercent": 100, "startTime": "2017-07-24T10:21:22.013650Z", "lastUpdateTime": "2017-07-24T10:21:45.278630Z" }, "done": true, "response": { "@type": "type.googleapis.com/google.cloud.speech.v1.LongRunningRecognizeResponse", "results": [ { "alternatives": [ { "transcript": "Four score and twenty...(etc)...", "confidence": 0.97186122, "words": [ { "startTime": "1.300s", "endTime": "1.400s", "word": "Four" }, { "startTime": "1.400s", "endTime": "1.600s", "word": "score" }, { "startTime": "1.600s", "endTime": "1.600s", "word": "and" }, { "startTime": "1.600s", "endTime": "1.900s", "word": "twenty" }, ... ] } ] }, { "alternatives": [ { "transcript": "for score and plenty...(etc)...", "confidence": 0.9041967, } ] } ] } }
Pemilihan model
Cloud STT dapat menggunakan salah satu dari beberapa model machine learning untuk mentranskripsikan file audio Anda. Google telah melatih model pengenalan ucapan ini untuk jenis dan sumber audio tertentu.
Saat mengirim permintaan transkripsi audio ke Cloud STT, Anda dapat meningkatkan hasil yang diterima dengan menentukan sumber audio asli. Hal ini memungkinkan Cloud Speech-to-Text API memproses file audio Anda menggunakan model machine learning yang dilatih untuk mengenali audio ucapan dari jenis sumber tertentu.
Untuk menentukan model pengenalan ucapan, sertakan kolom model dalam objek RecognitionConfig untuk permintaan Anda, dengan menentukan model yang ingin digunakan.
Lihat daftar model transkripsi Cloud STT untuk mengetahui model machine learning yang tersedia.
Konten audio yang disematkan
Audio tersemat disertakan dalam permintaan pengenalan ucapan saat meneruskan
parameter content dalam kolom audio permintaan. Untuk audio tersemat yang disediakan sebagai konten dalam permintaan gRPC, audio tersebut harus kompatibel untuk serialisasi Proto3, dan disediakan sebagai data biner. Untuk audio tersemat yang disediakan sebagai konten dalam permintaan REST, audio tersebut harus kompatibel dengan serialisasi JSON dan dienkode Base64 terlebih dahulu. Lihat Mengenkode Audio dengan Base64 untuk informasi selengkapnya.
Saat membuat permintaan menggunakan library klien Google Cloud, Anda umumnya akan menulis data biner ini (atau data berenkode base-64) langsung dalam kolom content.
Meneruskan audio yang direferensikan oleh URI
Biasanya, Anda akan meneruskan parameter uri dalam kolom audio permintaan Speech, yang mengarah ke file audio (dalam format biner, bukan base64) yang terletak di Cloud Storage, dengan format berikut:
gs://bucket-name/path_to_audio_file
Misalnya, bagian permintaan Speech berikut mereferensikan sampel file audio yang digunakan dalam Panduan Memulai:
... "audio": { "uri":"gs://cloud-samples-tests/speech/brooklyn.flac" } ...
Anda harus memiliki izin akses yang sesuai untuk membaca file Cloud Storage, seperti salah satu dari berikut ini:
- Dapat dibaca secara publik (seperti sampel file audio kami).
- Dapat dibaca oleh akun layanan Anda, jika menggunakan otorisasi akun layanan.
- Dapat dibaca oleh akun pengguna, jika menggunakan 3-legged OAuth untuk otorisasi akun pengguna.
Informasi selengkapnya tentang cara mengelola akses ke Cloud Storage tersedia di bagian Membuat dan Mengelola Daftar Kontrol Akses dalam dokumentasi Cloud Storage.
Respons Cloud Speech-to-Text API
Seperti yang ditunjukkan sebelumnya, respons Cloud Speech-to-Text API sinkron mungkin memerlukan waktu beberapa lama untuk menampilkan hasil, sesuai dengan durasi audio yang disediakan. Setelah diproses, API akan menampilkan respons seperti yang ditunjukkan dalam blok kode berikut:
{ "results": [ { "alternatives": [ { "confidence": 0.98267895, "transcript": "how old is the Brooklyn Bridge" } ] } ] }
resultsberisi daftar hasil (dengan jenisSpeechRecognitionResult) di mana setiap hasil bersesuaian dengan satu segmen audio (segmen audio dipisahkan oleh jeda). Setiap hasil akan terdiri atas satu atau beberapa kolom berikut:alternativesberisi daftar transkripsi yang mungkin, dengan jenisSpeechRecognitionAlternatives. Apakah alternatif yang ditampilkan lebih dari satu atau tidak bergantung pada apakah Anda meminta lebih dari satu alternatif (dengan menetapkanmaxAlternativeske nilai yang lebih besar daripada1) dan apakah Cloud STT menghasilkan alternatif dengan kualitas cukup tinggi. Setiap alternatif akan terdiri atas kolom berikut:transcriptberisi teks yang ditranskripsikan. Lihat Menangani Transkripsi.confidenceberisi nilai antara0dan1yang menunjukkan tingkat keyakinan Cloud STT pada transkripsi yang ditentukan. Lihat Menafsirkan Tingkat Keyakinan.
Komponen respons ini dijelaskan di bagian berikut.
Memilih alternatif
Setiap hasil dalam respons pengenalan sinkron yang berhasil dapat berisi satu atau beberapa alternatives (jika nilai maxAlternatives untuk permintaan lebih besar daripada 1). Jika Cloud STT menentukan bahwa sebuah alternatif memiliki Nilai Keyakinan yang memadai, alternatif tersebut akan disertakan dalam respons. Alternatif pertama dalam respons selalu merupakan alternatif terbaik (kemungkinan besar).
Menetapkan maxAlternatives ke nilai yang lebih tinggi dari 1 tidak berarti atau menjamin bahwa beberapa alternatif akan ditampilkan. Secara umum, alternatif lebih dari satu lebih sesuai untuk memberikan opsi real-time kepada pengguna yang mendapatkan hasil menggunakan Permintaan Pengenalan Streaming.
Menangani transkripsi
Setiap alternatif yang diberikan dalam respons akan memuat transcript yang berisi teks yang dikenali. Jika alternatif berurutan disediakan, Anda harus menyambung transkripsi tersebut.
Kode Python berikut mengiterasi daftar hasil dan menyambung beberapa transkripsi bersama-sama. Perhatikan bahwa, dalam semua kasus, alternatif pertama (ke-0) selalu diambil.
response = service_request.execute() recognized_text = 'Transcribed Text: \n' for i in range(len(response['results'])): recognized_text += response['results'][i]['alternatives'][0]['transcript']
Tingkat keyakinan
Nilai confidence merupakan perkiraan antara 0.0 dan 1.0. Nilai ini dihitung
dengan menggabungkan nilai "kemungkinan" yang ditetapkan untuk setiap kata dalam
audio. Angka yang lebih tinggi menunjukkan estimasi kemungkinan yang lebih besar bahwa kata tersebut dikenali dengan benar. Kolom ini biasanya
disediakan hanya untuk hipotesis teratas, dan hanya untuk hasil di
mana is_final=true. Misalnya, Anda dapat menggunakan nilai confidence untuk memutuskan apakah akan menampilkan hasil alternatif atau tidak kepada pengguna atau meminta konfirmasi dari pengguna.
Namun, perhatikan bahwa model tersebut menentukan hasil peringkat teratas "terbaik" berdasarkan lebih banyak sinyal daripada skor confidence saja (seperti konteks kalimat).
Karena itu, terkadang ada kasus di mana hasil teratas tidak memiliki skor keyakinan tertinggi. Jika Anda belum meminta beberapa hasil alternatif, satu hasil "terbaik" yang ditampilkan mungkin memiliki tingkat keyakinan lebih rendah daripada yang diharapkan. Hal ini dapat terjadi, misalnya, dalam kasus kata-kata yang jarang digunakan. Kata yang jarang digunakan dapat diberi nilai "kemungkinan" yang rendah meskipun kata tersebut dikenali dengan benar. Jika model menentukan bahwa kata yang jarang digunakan tersebut merupakan opsi yang paling mungkin berdasarkan konteks, hasil itu akan ditampilkan paling atas meskipun tingkat confidence-nya lebih rendah daripada opsi alternatif.
Permintaan Asinkron dan Responsnya
Permintaan Cloud Speech-to-Text API asinkron ke metode LongRunningRecognize memiliki format yang sama persis dengan permintaan Cloud Speech-to-Text API sinkron. Namun, alih-alih menampilkan respons, permintaan asinkron akan memulai Operasi yang Berjalan Lama (dengan jenis Operation) dan segera mengembalikan operasi ini ke tujuan panggilan. Anda dapat menggunakan pengenalan ucapan asinkron dengan audio yang berdurasi maksimal 480 menit.
Contoh:
{ "name": "operation_name", "metadata": { "@type": "type.googleapis.com/google.cloud.speech.v1.LongRunningRecognizeMetadata" "progressPercent": 34, "startTime": "2016-08-30T23:26:29.579144Z", "lastUpdateTime": "2016-08-30T23:26:29.826903Z" } }
Perhatikan bahwa belum ada hasil apa pun yang ditampilkan. Cloud STT akan terus memproses audio dan menggunakan operasi ini untuk menyimpan hasilnya. Hasil akan muncul di kolom response dari operasi yang ditampilkan setelah permintaan LongRunningRecognize selesai.
Contoh berikut adalah respons lengkap setelah permintaan selesai:
{ "name": "1268386125834704889", "metadata": { "lastUpdateTime": "2016-08-31T00:16:32.169Z", "@type": "type.googleapis.com/google.cloud.speech.v1.LongrunningRecognizeMetadata", "startTime": "2016-08-31T00:16:29.539820Z", "progressPercent": 100 } "response": { "@type": "type.googleapis.com/google.cloud.speech.v1.LongRunningRecognizeResponse", "results": [{ "alternatives": [{ "confidence": 0.98267895, "transcript": "how old is the Brooklyn Bridge" }]}] }, "done": True, }
Perhatikan bahwa done telah ditetapkan ke True dan bahwa response operasi ini berisi sekumpulan hasil dengan jenis SpeechRecognitionResult—sama dengan jenis yang ditampilkan oleh permintaan pengenalan Cloud Speech-to-Text API sinkron.
Permintaan Pengenalan Aliran Data Cloud Speech-to-Text API
Panggilan pengenalan Cloud Speech-to-Text API streaming dirancang untuk perekaman dan pengenalan audio secara real-time, dalam aliran data dua arah. Aplikasi Anda dapat mengirim audio pada aliran data permintaan, lalu menerima hasil pengenalan sementara atau final pada aliran data respons secara real time. Hasil sementara mewakili hasil pengenalan saat ini untuk suatu bagian audio, sedangkan hasil pengenalan final mewakili tebakan terakhir dan terbaik untuk bagian audio tersebut.
Permintaan aliran data
Tidak seperti panggilan sinkron dan asinkron, di mana Anda mengirim konfigurasi dan audio dalam satu permintaan, panggilan Speech API aliran data mengharuskan pengiriman beberapa permintaan. StreamingRecognizeRequest pertama harus berisi konfigurasi dengan jenis StreamingRecognitionConfig tanpa audio apa pun yang menyertainya. StreamingRecognizeRequest berikutnya yang dikirim melalui aliran data yang sama harus berisi frame berurutan untuk byte audio mentah.
StreamingRecognitionConfig terdiri atas kolom berikut:
config: Wajib. Berisi informasi konfigurasi untuk audio, dengan jenis RecognitionConfig dan sama dengan yang ditampilkan dalam permintaan sinkron dan asinkron.single_utterance: (opsional, default-nya ditetapkan kefalse) menunjukkan apakah permintaan ini harus otomatis berakhir setelah ucapan tidak lagi terdeteksi. Jika disetel, Cloud STT akan mendeteksi jeda, senyap, atau audio non-ucapan untuk menentukan kapan harus mengakhiri pengenalan. Jika tidak disetel, aliran data akan terus mendengarkan dan memproses audio hingga aliran data tersebut ditutup secara langsung, atau batas durasinya terlampaui. Menyetelsingle_utteranceketrueberguna untuk memproses perintah suara.interim_results: (opsional, default-nya ditetapkan kefalse) menunjukkan bahwa permintaan streaming ini harus menampilkan hasil sementara yang kualitasnya dapat ditingkatkan pada lain waktu (setelah memproses lebih banyak audio). Hasil sementara akan dicatat dalam respons dengan menetapkanis_finalkefalse.
Respons aliran data
Hasil pengenalan ucapan aliran data ditampilkan dalam serangkaian respons dengan jenis StreamingRecognitionResponse. Respons tersebut terdiri atas kolom berikut:
speechEventTypeberisi peristiwa dengan jenis SpeechEventType. Nilai peristiwa ini akan menunjukkan kapan sebuah ucapan tunggal ditentukan sebagai telah selesai. Peristiwa ucapan berfungsi sebagai penanda dalam respons aliran data Anda.resultsberisi daftar hasil, yang dapat berupa hasil sementara atau final, dengan jenis StreamingRecognitionResult. Daftarresultsberisi sub-kolom berikut:alternativesberisi daftar transkripsi alternatif.isFinalmenunjukkan apakah hasil yang diperoleh dalam entri daftar ini bersifat sementara atau final. Google dapat menampilkan beberapa hasilisFinal=truedi sepanjang aliran data tunggal, tetapi hasilisFinal=truehanya dijamin setelah aliran data tulis ditutup (setengah tertutup).stabilitymenunjukkan ketidakstabilan hasil yang diperoleh sejauh ini, dengan0.0menunjukkan ketidakstabilan penuh, sementara1.0menunjukkan stabilitas penuh. Perlu diperhatikan bahwa tidak seperti tingkat keyakinan, yang memperkirakan benar tidaknya transkripsi,stabilitymemperkirakan apakah hasil parsial yang ditentukan dapat berubah atau tidak. JikaisFinalditetapkan ketrue,stabilitytidak akan ditetapkan.