Премини към основното съдържание
Български— Изберете език
Меню

Първото Ви обаждане за транскрипция

Урок 5 от 16 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Първата Ви транскрипция с Voxtral
  2. Подготовка на средата
  3. Транскрибиране на локален файл
  4. Транскрибиране от URL адрес
  5. Преминаване към надеждна версия
  6. Какво съдържа отговорът
  7. Ключови изводи

Курсът е актуализиран на 3 ноември 2026 г. за Voxtral 3, въз основа на ръководството на Mistral Migrate from Voxtral 2: Моделите 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 и Вие обработвате върнатия текст. Кодът се събира в няколко реда, но след това ще го развием до надеждна версия, подходяща за автономна работа.

Подготовка на средата

SDK на Mistral се инсталира с една команда. Стъпката за проверка, която следва, Ви спестява търсенето на грешка при импортиране по-късно.

# Install the Mistral SDK
pip install mistralai

# Verify the installation
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

# Initialize the client
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Open and transcribe the audio file
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"}
    )

# Display the result
print("=== Transcription ===")
print(response.text)

Това е. С четири реда активен код получавате пълната транскрипция на Вашия аудиофайл.

Нека разгледаме тези четири реда. Mistral(api_key=...) създава клиента с Вашия API ключ; това е обектът, който ще използвате повторно за всички последващи обаждания. open("mon_audio.mp3", "rb") отваря файла в двоичен режим, което е задължително за аудио – пропускането на b причинява грешка при декодиране, която е трудна за тълкуване. Параметърът file={"content": f, "file_name": "..."} очаква речник, съдържащ файловия обект и неговото име; това име не е просто декорация, то помага на сървъра да открие формата. Накрая, response.text съдържа пълната транскрипция като низ.

Транскрибиране от URL адрес

Ако Вашият аудиофайл вече е хостван онлайн, използвайте 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 ще изтегли файла директно, което избягва маршрутизирането на аудиото през Вашата машина, когато то вече е в облака – значителна икономия на честотна лента за каталог от няколкостотин файла.

Преминаване към надеждна версия

Минималният скрипт работи за тест. В производствена среда трябва да обработвате липсващи файлове, неочаквани формати, липсващи ключове и мрежови грешки. Следващият скрипт извършва тези проверки преди обаждането и след това запазва резултата.

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

def transcrire_audio(chemin_fichier: str) -> str:
    """Transcribes an audio file with Voxtral Mini Transcribe 3."""

    # Check that the file exists
    fichier = Path(chemin_fichier)
    if not fichier.exists():
        raise FileNotFoundError(f"Fichier introuvable : {chemin_fichier}")

    # Check the extension
    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)}"
        )

    # Check size (practical limit: ~200 MB)
    taille_mo = fichier.stat().st_size / (1024 * 1024)
    if taille_mo > 200:
        print(f"Attention : fichier volumineux ({taille_mo:.1f} Mo)")

    # Initialize the 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)

    # Transcribe
    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)

    # Save to text file
    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

Скриптът проверява файла, транскрибира го, показва резултата и автоматично го запазва в .txt файл със същото основно име. Сега разполагате със скелет за пакетна обработка: обхождайте директория и Вашият аудиоархив се превръща в архив от текст, подлежащ на търсене.

Какво съдържа отговорът

Обектът response не се ограничава само до текст. Той предоставя и продължителността на обработеното аудио, както и езика, разпознат от модела – две полезни информации за регистриране на Вашите задачи и откриване на файлове, които не са на очаквания език.

# Full text
print(response.text)

# Audio duration (in seconds)
print(f"Durée : {response.duration:.1f}s")

# Detected language
print(f"Langue : {response.language}")

Най-добрият начин да оцените качеството на модела е да го тествате със собствения си глас. Запишете гласово съобщение с продължителност от тридесет секунди до две минути, стартирайте горния скрипт и сравнете резултата дума по дума с казаното от Вас: веднага ще видите къде са рядките грешки, почти винаги свързани със собствени имена. След това повторете упражнението с файл на друг език, без да променяте кода, за да наблюдавате автоматичното откриване на езика в действие.

Ключови изводи

  • Минималното обаждане изисква 4 реда: клиент, отваряне на файл, API обаждане, четене на резултата
  • Два режима на изпращане: локален файл (file) или URL адрес (file_url)
  • Името на файла в речника file помага за откриване на формата
  • В производствена среда добавете обработка на грешки (липсващ файл, невалиден формат, мрежова грешка)
  • response.text винаги съдържа пълната транскрипция като низ