Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Ensimmäinen litterointipuhelusi

Oppitunti 5 / 16 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Ensimmäinen litterointisi Voxtralilla
  2. Ympäristön valmistelu
  3. Paikallisen tiedoston litterointi
  4. Litterointi URL-osoitteesta
  5. Siirtyminen robustiin versioon
  6. Mitä vastaus sisältää
  7. Keskeiset asiat

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 malleilla voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 ja voxtral-mini-tts-3-0. Keskeiset muutokset: aikaleimat ovat vain segmenttitasolla (word palauttaa 400-virheen), puhujantunnistus on mahdollista reaaliajassa, reaaliaikaisten istuntojen asetukset lukittuvat ensimmäisen äänipaketin jälkeen, ja context_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.text sisältää aina koko litteroinnin merkkijonona