Μετάβαση στο κύριο περιεχόμενο
Ελληνικά— Επιλέξτε γλώσσα
Μενού

Η πρώτη σας κλήση απομαγνητοφώνησης

Μάθημα 5 / 16 Ενημερώθηκε 3 Νοεμβρίου 2026 Για developers
Σε αυτήν τη σελίδα
  1. Η πρώτη σας απομαγνητοφώνηση με το Voxtral
  2. Προετοιμασία του περιβάλλοντος
  3. Απομαγνητοφώνηση τοπικού αρχείου
  4. Απομαγνητοφώνηση από URL
  5. Μετάβαση σε μια robust έκδοση
  6. Τι περιέχει η απόκριση
  7. Βασικά σημεία

Το μάθημα ενημερώθηκε στις 3 Νοεμβρίου 2026 για το Voxtral 3, βάσει του οδηγού Migrate from Voxtral 2 της Mistral: Τα μοντέλα Voxtral 2 (voxtral-mini-2602, voxtral-mini-transcribe-realtime-2602, voxtral-mini-tts-2603), που απεσύρθησαν στις 31 Οκτωβρίου 2026 και θα αφαιρεθούν στις 30 Απριλίου 2027, αντικαθίστανται στα παραδείγματα από τα voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 και voxtral-mini-tts-3-0. Βασικές αλλαγές: οι χρονοσημάνσεις αφορούν μόνο τμήματα (η τιμή word επιστρέφει σφάλμα 400), η διάκριση ομιλητών είναι δυνατή σε πραγματικό χρόνο, οι ρυθμίσεις συνεδρίας πραγματικού χρόνου κλειδώνουν μετά το πρώτο κομμάτι ήχου και οι είσοδοι context_bias είναι ελεύθερης μορφής (φράσεις με κενά). Πηγές: Migrate from Voxtral 2 · Speech to Text.

Η πρώτη σας απομαγνητοφώνηση με το Voxtral

Αρκετά με τη θεωρία. Σε αυτό το μάθημα, θα πραγματοποιήσετε την πρώτη σας πλήρη κλήση στο API απομαγνητοφώνησης εκτός σύνδεσης: ένα τοπικό αρχείο ήχου αποστέλλεται στο Voxtral Mini Transcribe 3 και εσείς επεξεργάζεστε το κείμενο που επιστρέφεται. Ο κώδικας χωράει σε λίγες γραμμές, αλλά στη συνέχεια θα εξελίξουμε τη λύση σε μια robust έκδοση κατάλληλη για αυτόματη λειτουργία.

Προετοιμασία του περιβάλλοντος

Το SDK της Mistral εγκαθίσταται με μία μόνο εντολή. Το βήμα επαλήθευσης που ακολουθεί σας γλιτώνει από το κυνήγι σφαλμάτων εισαγωγής αργότερα.

# Εγκατάσταση του Mistral SDK
pip install mistralai

# Επαλήθευση της εγκατάστασης
python -c "from mistralai.client import Mistral; print('SDK installed')"

Θα χρειαστείτε ένα κλειδί API της Mistral. Δημιουργήστε ένα στο console.mistral.ai και αποθηκεύστε το σε μια μεταβλητή περιβάλλοντος αντί να το κωδικοποιήσετε απευθείας:

export MISTRAL_API_KEY="your-api-key-here"

Απομαγνητοφώνηση τοπικού αρχείου

Ορίστε ο πλήρης κώδικας για την απομαγνητοφώνηση ενός τοπικού αρχείου ήχου:

import os
from mistralai.client import Mistral

# Αρχικοποίηση του client
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Άνοιγμα και απομαγνητοφώνηση του αρχείου ήχου
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"}
    )

# Εμφάνιση του αποτελέσματος
print("=== Απομαγνητοφώνηση ===")
print(response.text)

Αυτό είναι όλο. Σε τέσσερις γραμμές ενεργού κώδικα, λαμβάνετε την πλήρη απομαγνητοφώνηση του αρχείου ήχου σας.

Ας αναλύσουμε αυτές τις τέσσερις γραμμές. Το Mistral(api_key=...) δημιουργεί τον client με το κλειδί API σας· αυτό είναι το αντικείμενο που θα επαναχρησιμοποιείτε για όλες τις επόμενες κλήσεις. Το open("mon_audio.mp3", "rb") ανοίγει το αρχείο σε δυαδική λειτουργία, κάτι που είναι υποχρεωτικό για τον ήχο· η παράλειψη του b προκαλεί σφάλμα αποκωδικοποίησης δύσκολο στην ερμηνεία. Η παράμετρος file={"content": f, "file_name": "..."} αναμένει ένα λεξικό που περιέχει το αντικείμενο του αρχείου και το όνομά του· αυτό το όνομα δεν είναι διακοσμητικό, βοηθά τον διακομιστή να εντοπίσει τη μορφή. Τέλος, το response.text περιέχει την πλήρη απομαγνητοφώνηση ως συμβολοσειρά.

Απομαγνητοφώνηση από URL

Εάν το αρχείο ήχου σας φιλοξενείται ήδη online, χρησιμοποιήστε το file_url αντί για το file:

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 πρέπει να είναι δημόσια προσβάσιμο. Ο διακομιστής της Mistral θα κατεβάσει το αρχείο απευθείας, αποφεύγοντας τη δρομολόγηση του ήχου μέσω του μηχανήματός σας όταν βρίσκεται ήδη στο cloud—μια σημαντική εξοικονόμηση εύρους ζώνης για έναν κατάλογο με αρκετές εκατοντάδες αρχεία.

Μετάβαση σε μια robust έκδοση

Το ελάχιστο script λειτουργεί για δοκιμές. Στην παραγωγή, πρέπει να διαχειριστείτε αρχεία που λείπουν, απροσδόκητες μορφές, κλειδιά που λείπουν και σφάλματα δικτύου. Το παρακάτω script εκτελεί αυτούς τους ελέγχους πριν την κλήση και στη συνέχεια αποθηκεύει το αποτέλεσμα.

import os
import sys
from pathlib import Path
from mistralai.client import Mistral

def transcrire_audio(chemin_fichier: str) -> str:
    """Απομαγνητοφωνεί ένα αρχείο ήχου με το Voxtral Mini Transcribe 3."""

    # Έλεγχος ύπαρξης του αρχείου
    fichier = Path(chemin_fichier)
    if not fichier.exists():
        raise FileNotFoundError(f"Fichier introuvable : {chemin_fichier}")

    # Έλεγχος επέκτασης
    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)}"
        )

    # Έλεγχος μεγέθους (πρακτικό όριο: ~200 MB)
    taille_mo = fichier.stat().st_size / (1024 * 1024)
    if taille_mo > 200:
        print(f"Attention : fichier volumineux ({taille_mo:.1f} Mo)")

    # Αρχικοποίηση του client
    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)

    # Απομαγνητοφώνηση
    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)

    # Αποθήκευση σε αρχείο κειμένου
    sortie = Path(chemin).stem + "_transcription.txt"
    Path(sortie).write_text(texte, encoding="utf-8")
    print(f"\nTranscription sauvegardée dans : {sortie}")

Εκτελέστε το από το τερματικό περνώντας τη διαδρομή του αρχείου:

python transcribe.py meeting_march15.mp3

Το script ελέγχει το αρχείο, το απομαγνητοφωνεί, εμφανίζει το αποτέλεσμα και το αποθηκεύει αυτόματα σε ένα αρχείο .txt με το ίδιο βασικό όνομα. Τώρα διαθέτετε τον σκελετό για μαζική επεξεργασία: κάντε loop σε έναν κατάλογο και το αρχείο ήχου σας μετατρέπεται σε ένα αρχείο κειμένου ανα searchable.

Τι περιέχει η απόκριση

Το αντικείμενο response δεν περιορίζεται μόνο στο κείμενο. Παρέχει επίσης τη διάρκεια του επεξεργασμένου ήχου και τη γλώσσα που αναγνώρισε το μοντέλο—δύο χρήσιμες πληροφορίες για την καταγραφή των εργασιών σας και τον εντοπισμό αρχείων που δεν είναι στην αναμενόμενη γλώσσα.

# Πλήρες κείμενο
print(response.text)

# Διάρκεια ήχου (σε δευτερόλεπτα)
print(f"Durée : {response.duration:.1f}s")

# Ανιχνευθείσα γλώσσα
print(f"Langue : {response.language}")

Ο καλύτερος τρόπος να αξιολογήσετε την ποιότητα του μοντέλου είναι να το δοκιμάσετε με τη δική σας φωνή. Ηχογραφήστε ένα φωνητικό μήνυμα διάρκειας τριάντα δευτερολέπτων έως δύο λεπτών, εκτελέστε το παραπάνω script και συγκρίνετε το αποτέλεσμα λέξη προς λέξη με αυτά που είπατε: θα δείτε αμέσως πού εντοπίζονται τα σπάνια σφάλματα, σχεδόν πάντα σε κύρια ονόματα. Στη συνέχεια, επαναλάβετε την άσκηση με ένα αρχείο σε άλλη γλώσσα, χωρίς να αλλάξετε τον κώδικα, για να παρατηρήσετε την αυτόματη ανίχνευση γλώσσας σε δράση.

Βασικά σημεία

  • Η ελάχιστη κλήση απαιτεί 4 γραμμές: client, άνοιγμα αρχείου, κλήση API, ανάγνωση αποτελέσματος
  • Δύο τρόποι αποστολής: τοπικό αρχείο (file) ή URL (file_url)
  • Το όνομα του αρχείου στο λεξικό file βοηθά στην ανίχνευση της μορφής
  • Στην παραγωγή, προσθέστε διαχείριση σφαλμάτων (λείπον αρχείο, μη έγκυρη μορφή, σφάλμα δικτύου)
  • Το response.text περιέχει πάντα την πλήρη απομαγνητοφώνηση ως συμβολοσειρά