Lähe põhisisu juurde
Eesti— Vali keel
Menüü

API de transkriptsiooni offline-režiimis

Õppetund 4 / 16 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Transkriptsiooni lõpp-punkt
  2. Väljakutse parameetrid
  3. Toetatud helivormingud
  4. Vastuse struktuur
  5. Parameetrite kombinatsioonid
  6. Autentimine
  7. Peamised punktid

Kursust uuendati 3. novembril 2026 Voxtral 3 jaoks, tuginedes Mistrali juhendile Migrate from Voxtral 2: Voxtral 2 mudelid (voxtral-mini-2602, voxtral-mini-transcribe-realtime-2602, voxtral-mini-tts-2603), mis tunnistati aegunuks 31. oktoobril 2026 ja lõpetati 30. aprillil 2027, on näidetes asendatud mudelitega voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 ja voxtral-mini-tts-3-0. Peamised muudatused: ajatemplid on ainult lõigupõhised (word tagastab vea 400), reaalajas kõneleja eristamine on toetatud, reaalajaseansi seaded lukustuvad pärast esimest helilõiku ja context_bias kirjed on vabas vormingus (fraasid tühikutega). Allikad: Migrate from Voxtral 2 · Speech to Text.

Transkriptsiooni lõpp-punkt

Mistrali offline-transkriptsiooni API kasutab lõpp-punkti /audio/transcriptions. See on sünkroonne API: saadad helifaili, päring jääb töötlemise ajaks avatuks ja saad vastuses kogu transkriptsiooni. Pole ülesande ID-d, mida pollida, ega veebikonksu, mida seadistada. See lihtsustab sinu koodi oluliselt, kuid pikkade failide jaoks pead lubama piisavalt pikad ajalõpid.

Enne kodeerimise alustamist veendu, et sul on kolm eeldust: Mistrali platvormi konto (console.mistral.ai), aktiivne API-võti ja paigaldatud Pythoni SDK.

SDK paigaldamine

pip install mistralai

Väljakutse parameetrid

Kõik toimub funktsiooni client.audio.transcriptions.complete() kaudu. Nõutud on kaks parameetrit ja valikulisi on neli. Just need valikulised parameetrid muudavad toore transkriptsiooni kasutatavaks tulemuseks.

Nõutud parameetrid

  • model — Mudeli identifikaator. Offline-transkriptsiooni jaoks kasuta "voxtral-mini-transcribe-3" (soovitatav) või fikseeritud versiooni, nagu "voxtral-mini-transcribe-3".
  • file või file_url — Transkribeeritav helifail. Sul on kaks võimalust:
    • file: Sõnastik {"content": file_object, "file_name": "name.mp3"} otseseks üleslaadimiseks.
    • file_url: Avalik URL, mis viitab helifailile.

Valik file ja file_url vahel on arhitektuuriline otsus. Kui su heli on juba avalikus kohas salvestatud, väldib file_url faili marsruutimist läbi sinu serveri. Kui fail pärineb kasutaja seadmest või privaatsest salvestusruumist, on otsene üleslaadimine vajalik.

Valikulised parameetrid

Neli valikulist seadet muudavad väljundi olemust.

language eeldab ISO keelekoodi, näiteks "fr" või "en", ja möödub automaatsest tuvastamisest. Sunni seda ühtlaste partiide puhul, nagu näiteks kataloog intervjuudest, mis on tehtud täielikult prantsuse keeles, et vältida olukorda, kus lühike ingliskeelne lõik sunnib mudelit faili keskel keelt vahetama. Pane tähele, et see on kokkusobimatu parameetriga timestamp_granularities.

timestamp_granularities võtab vastu loendi ["segment"] ja käivitab ajatemplite tagastamise lõikude kaupa. Voxtral 3 puhul granulaarsust word enam ei eksisteeri ja see tagastab vea 400. See parameeter võimaldab luua videoga sünkroniseeritud subtiitrifaile või indekseerida lõike kahetunnisel konverentsil.

diarize on boolean-tüüpi. Kui see on määratud väärtusele True, tuvastab mudel kõnelejad ja omistab igale lõigule ühe neist. Kuueliikmelise juhatuse koosoleku puhul teeb see erinevuse anonüümse tekstiseina ja aruande vahel, kus iga kohustus on omistatav.

Lõpuks aktsepteerib context_bias terminite loendit – üks sõna või fraas tühikutega, nagu toote nimi –, et parandada spetsiifilise sõnavara tuvastamist. Kirjete arv ei ole enam fikseeritud, kuid need jagavad kontekstiakent heliga, seega hoia loend lühike. Insenerikoosolek, kus esinevad terminid nagu “Kubernetes” ja “GDPR”, muutub selle seadega oluliselt loetavamaks.

Toetatud helivormingud

Voxtral aktsepteerib levinud helivorminguid ja sul on harva vaja midagi eelnevalt konverteerida. Kahtluse korral vaata dokumentatsiooni lehte Audio formats.

VormingOmadus
MP3Kõige levinum, hea tihendus
WAVTihendamata, maksimaalne kvaliteet
FLACKadudeta tihendus
OGGAvatud vorming, hea tihendus
M4A / AACApple’i vorming, levinud mobiilseadmetes
WEBMVeebivorming, levinud brauserisalvestiste puhul

Kriitiline piirang on mudeli kontekstiaken, mida jagavad heli ja context_bias sõnavara. Sellest piirangust suurem päring lükatakse tagasi veaga 400; API ei lühenda faili. Väga pikkade failide, nagu päevane seminar, puhul jaga need enne saatmist, eelistatavalt vaikusekohtades, et vältida lausete poolitamist.

Vastuse struktuur

Vastus sisaldab vähemalt transkribeeritud teksti:

response.text          # Kogu transkribeeritud tekst (str)

Kui küsisid ajatempleid (timestamp_granularities), sisaldab vastus ka:

response.segments      # Lõikude loend algusaja, lõpuaja ja tekstiga

Kui lubasid kõneleja eristamise (diarize=True), sisaldab iga lõik kõneleja identiteeti:

segment.speaker_id        # Kõneleja identifikaator (str)
segment.start          # Algusaeg sekundites (float)
segment.end            # Lõpuaeg sekundites (float)
segment.text           # Lõigu tekst (str)

Lühidalt öeldes sõltub tagastatud objekti kuju sinu päringust. Kood, mis iteratsioonib üle response.segments ilma timestamp_granularities parameetrit kasutamata, ebaõnnestub. Kontrolli alati sisendparameetrite ja väljundi töötlemise kooskõla.

Parameetrite kombinatsioonid

Siin on viis kehtivat kombinatsiooni, mida kohtad kõige sagedamini, lihtsaimast kõige spetsiifilisemani.

# Lihtne transkriptsioon (ainult tekst)
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file={"content": f, "file_name": "audio.mp3"}
)

# Sunnitud keelega (ajatemplid puuduvad)
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file={"content": f, "file_name": "audio.mp3"},
    language="fr"
)

# Lõigu ajatemplitega
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file={"content": f, "file_name": "audio.mp3"},
    timestamp_granularities=["segment"]
)

# Kõneleja eristamine + ajatemplid
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file={"content": f, "file_name": "audio.mp3"},
    diarize=True,
    timestamp_granularities=["segment"]
)

# Konteksti kallutamisega
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file_url="https://example.com/audio.mp3",
    context_bias=["Mistral", "Voxtral", "Corsen", "GDPR"]
)

Üllatav piirang Voxtral 2-s oli see, et language ja timestamp_granularities ei saanud samas väljakutses koos kasutada. Voxtral 3 dokumentatsioon seda piirangut enam ei maini; enne sellele tuginemist kontrolli seda testiga.

Autentimine

Kõik päringud nõuavad kehtivat API-võtit, mis antakse kliendi konstruktorile. Arenduskeskkonnas piisab otsesest argumendist. Tootmiskeskkonnas kasuta keskkonnamuutujat, et vältida võtme sattumist sinu Git-i hoidlasse.

from mistralai.client import Mistral

# Otsese argumendina
client = Mistral(api_key="your-api-key")

# Või keskkonnamuutuja kaudu (soovitatav tootmiskeskkonnale)
import os
os.environ["MISTRAL_API_KEY"] = "your-api-key"
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

Peamised punktid

  • Lõpp-punkt /audio/transcriptions on sünkroonne: saada fail, saada tekst.
  • Kaks üleslaadimisrežiimi: otsene üleslaadimine (file) või avalik URL (file_url).
  • Valikulised parameetrid: language, timestamp_granularities, diarize, context_bias.
  • Voxtral 2-s olid language ja timestamp_granularities vastastikku välistavad; Voxtral 3 dokumentatsioon seda enam ei väida.
  • Toetatud on levinud helivormingud; piiranguks on kontekstiaken, mida jagavad heli ja context_bias (ületamisel tekib viga 400).
  • Kõneleja eristamist ja ajatempleid saab kombineerida.