Ensimmäinen litterointipuhelusi
Tällä sivulla
Kurssi päivitetty 3. marraskuuta 2026 Voxtral 3:lle Mistralin Migrate from Voxtral 2 -oppaan pohjalta: Voxtral 2 -mallit (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603) poistettiin käytöstä 31. lokakuuta 2026 ja ne poistetaan kokonaan 30. huhtikuuta 2027. Esimerkeissä ne on korvattu malleillavoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3javoxtral-mini-tts-3-0. Keskeiset muutokset: aikaleimat ovat vain segmenttitasolla (wordpalauttaa 400-virheen), puhujantunnistus on mahdollista reaaliajassa, reaaliaikaisten istuntojen asetukset lukittuvat ensimmäisen äänipaketin jälkeen, jacontext_bias-syötteet ovat vapaamuotoisia (välilyönnillisiä fraaseja). Lähteet: Migrate from Voxtral 2 · Speech to Text.
Ensimmäinen litterointisi Voxtralilla
Teoriaa tarpeeksi. Tässä oppitunnissa teet ensimmäisen täydellisen pyyntösi offline-litterointi-APIin: paikallinen äänitiedosto lähetetään Voxtral Mini Transcribe 3 -mallille, ja käsittelet palautetun tekstin. Koodi mahtuu muutamaan riviin, mutta rakennamme sen jälkeen version, joka on tarpeeksi robusti automaattiseen käyttöön.
Ympäristön valmistelu
Mistral SDK:n asennus onnistuu yhdellä komennolla. Seuraava varmistusvaihe säästää sinut myöhemmiltä tuontivirheiden metsästyksiltä.
# Asenna Mistral SDK
pip install mistralai
# Varmista asennus
python -c "from mistralai.client import Mistral; print('SDK installed')"
Tarvitset Mistral API -avaimen. Luo sellainen osoitteessa console.mistral.ai ja tallenna se ympäristömuuttujaan kovakoodauksen sijaan:
export MISTRAL_API_KEY="your-api-key-here"
Paikallisen tiedoston litterointi
Tässä on koko koodi paikallisen äänitiedoston litteroimiseksi:
import os
from mistralai.client import Mistral
# Alusta asiakasohjelma
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Avaa ja litteroi äänitiedosto
with open("mon_audio.mp3", "rb") as f:
response = client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "mon_audio.mp3"}
)
# Näytä tulos
print("=== Litterointi ===")
print(response.text)
Siinä kaikki. Neljällä aktiivisella koodirivillä saat koko äänitiedostosi litteroinnin.
Käydään nämä neljä riviä läpi. Mistral(api_key=...) luo asiakasohjelman API-avaimellasi; tämä on objekti, jota käytät uudelleen kaikissa myöhemmissä pyynnöissä. open("mon_audio.mp3", "rb") avaa tiedoston binääritilassa, mikä on pakollista äänelle – b:n pois jättäminen aiheuttaa vaikeasti tulkittavan dekoodausvirheen. Parametri file={"content": f, "file_name": "..."} odottaa sanakirjaa, joka sisältää tiedosto-objektin ja sen nimen; tämä nimi ei ole vain koriste, vaan se auttaa palvelinta tunnistamaan tiedostomuodon. Lopuksi response.text sisältää koko litteroinnin merkkijonona.
Litterointi URL-osoitteesta
Jos äänitiedostosi on jo verkossa, käytä file_url:ää file:n sijaan:
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
response = client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file_url="https://example.com/mon_audio.mp3"
)
print(response.text)
URL-osoitteen on oltava julkisesti saatavilla. Mistral-palvelin lataa tiedoston suoraan, mikä välttää äänen reitittämisen koneesi kautta, kun se on jo pilvessä – tämä säästää merkittävästi kaistanleveyttä, jos sinulla on satojen tiedostojen katalogi.
Siirtyminen robustiin versioon
Minimaalinen skripti toimii testaukseen. Tuotannossa sinun on käsiteltävä puuttuvat tiedostot, odottamattomat muodot, puuttuvat avaimet ja verkkovirheet. Seuraava skripti suorittaa nämä tarkistukset ennen pyyntöä ja tallentaa sitten tuloksen.
import os
import sys
from pathlib import Path
from mistralai.client import Mistral
def transcrire_audio(chemin_fichier: str) -> str:
"""Litteroi äänitiedoston Voxtral Mini Transcribe 3:lla."""
# Tarkista, että tiedosto on olemassa
fichier = Path(chemin_fichier)
if not fichier.exists():
raise FileNotFoundError(f"Fichier introuvable : {chemin_fichier}")
# Tarkista tiedostopääte
extensions_valides = {".mp3", ".wav", ".flac", ".ogg", ".m4a", ".webm"}
if fichier.suffix.lower() not in extensions_valides:
raise ValueError(
f"Format non supporté : {fichier.suffix}. "
f"Formats valides : {', '.join(extensions_valides)}"
)
# Tarkista koko (käytännön raja: ~200 Mt)
taille_mo = fichier.stat().st_size / (1024 * 1024)
if taille_mo > 200:
print(f"Attention : fichier volumineux ({taille_mo:.1f} Mo)")
# Alusta asiakasohjelma
api_key = os.environ.get("MISTRAL_API_KEY")
if not api_key:
raise EnvironmentError("Variable MISTRAL_API_KEY non définie")
client = Mistral(api_key=api_key)
# Litteroi
try:
with open(chemin_fichier, "rb") as f:
response = client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": fichier.name}
)
return response.text
except Exception as e:
raise RuntimeError(f"Erreur de transcription : {e}")
if __name__ == "__main__":
if len(sys.argv) < 2:
print("Usage : python transcrire.py <fichier_audio>")
sys.exit(1)
chemin = sys.argv[1]
print(f"Transcription de : {chemin}")
print("-" * 50)
texte = transcrire_audio(chemin)
print(texte)
# Tallenna tekstitiedostoon
sortie = Path(chemin).stem + "_transcription.txt"
Path(sortie).write_text(texte, encoding="utf-8")
print(f"\nTranscription sauvegardée dans : {sortie}")
Suorita se päätteen kautta antamalla tiedostopolku:
python transcribe.py meeting_march15.mp3
Skripti tarkistaa tiedoston, litteroi sen, näyttää tuloksen ja tallentaa sen automaattisesti .txt-tiedostoon samalla perusnimellä. Sinulla on nyt runko eräajoon: silmukoi hakemisto, ja ääniarkistostasi tulee haettava tekstiarkisto.
Mitä vastaus sisältää
response-objekti ei rajoitu pelkkään tekstiin. Se tarjoaa myös käsitellyn äänen keston ja mallin tunnistaman kielen – kaksi hyödyllistä tietoa tehtäviesi lokittamiseen ja sellaisten tiedostojen havaitsemiseen, jotka eivät ole odotetulla kielellä.
# Koko teksti
print(response.text)
# Äänen kesto (sekunteina)
print(f"Durée : {response.duration:.1f}s")
# Havaittu kieli
print(f"Langue : {response.language}")
Paras tapa arvioida mallin laatua on testata sitä omalla äänelläsi. Nauhoita 30 sekunnin – 2 minuutin pituinen ääniviesti, suorita yllä oleva skripti ja vertaa tulosta sana sanalta siihen, mitä sanoit: näet heti, missä harvinaiset virheet ovat, lähes aina erisnimissä. Toista sitten harjoitus toisenkielisellä tiedostolla muuttamatta koodia havainnollistaaksesi automaattista kielen tunnistusta toiminnassa.
Keskeiset asiat
- Minimaalinen pyyntö vaatii 4 riviä: asiakas, tiedoston avaus, API-kutsu, tuloksen luku
- Kaksi lähetystapaa: paikallinen tiedosto (
file) tai URL (file_url) - Tiedostonimi
file-sanakirjassa auttaa muodon tunnistamisessa - Tuotannossa lisää virheenkäsittely (puuttuva tiedosto, virheellinen muoto, verkkovirhe)
response.textsisältää aina koko litteroinnin merkkijonona