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

Оптимизация за продукционна среда

Урок 15 от 16 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. От прототип до надеждна услуга
  2. Обработка на грешки: Разграничаване на възстановимите от фаталните
  3. Обработка на пакет файлове без надзор
  4. Предварителна подготовка на аудиото
  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.

От прототип до надеждна услуга

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

Обработка на грешки: Разграничаване на възстановимите от фаталните

Първото правило е да не третирате всички грешки по един и същи начин. Прекъсване на мрежата, изтичане на времето за изчакване или временна неизправност заслужават повторен опит; нечетим файл или невалиден API ключ никога няма да се поправят сами и повторният им опит само губи време и замърсява дневниците Ви. Обвивката по-долу реализира това разграничение чрез кортеж от временни изключения: всичко в ERREURS_TEMPORAIRES задейства повторен опит, докато всичко останало води до незабавен провал. И в двата случая функцията връща речник вместо да хвърля изключение, позволявайки на пакетната обработка да продължи с останалите файлове.

import os
import time
import logging
from pathlib import Path
from mistralai.client import Mistral

logger = logging.getLogger("voxtral")

# Изключения за повторен опит
ERREURS_TEMPORAIRES = (
    ConnectionError,
    TimeoutError,
    OSError,
)

def transcrire_avec_retry(
    chemin_audio: str,
    max_tentatives: int = 3,
    delai_base: float = 2.0,
    **kwargs
) -> dict:
    """Транскрибира файл с експоненциален повторен опит."""
    client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
    fichier = Path(chemin_audio)

    for tentative in range(1, max_tentatives + 1):
        try:
            with open(chemin_audio, "rb") as f:
                response = client.audio.transcriptions.complete(
                    model=kwargs.get("model", "voxtral-mini-transcribe-3"),
                    file={"content": f, "file_name": fichier.name},
                    **{k: v for k, v in kwargs.items() if k != "model"}
                )

            return {
                "succes": True,
                "texte": response.text,
                "fichier": chemin_audio,
                "tentative": tentative,
            }

        except ERREURS_TEMPORAIRES as e:
            if tentative < max_tentatives:
                delai = delai_base * (2 ** (tentative - 1))
                logger.warning(
                    f"Tentative {tentative}/{max_tentatives} échouée "
                    f"pour {fichier.name} : {e}. "
                    f"Retry dans {delai:.0f}s"
                )
                time.sleep(delai)
            else:
                logger.error(
                    f"Échec définitif pour {fichier.name} "
                    f"après {max_tentatives} tentatives : {e}"
                )
                return {
                    "succes": False,
                    "erreur": str(e),
                    "fichier": chemin_audio,
                    "tentative": tentative,
                }

        except Exception as e:
            # Невъзстановима грешка (невалиден файл, удостоверяване и т.н.)
            logger.error(f"Erreur fatale pour {fichier.name} : {e}")
            return {
                "succes": False,
                "erreur": str(e),
                "fichier": chemin_audio,
                "tentative": tentative,
            }

Закъснението между опитите се удвоява при всеки неуспех – две секунди, после четири, после осем – за да не се „бомбардира“ API, който вече изпитва затруднения. Въпреки това, това експоненциално отстъпване има недостатък, когато имате много клиенти: ако всички се провалят в един и същи момент, те всички ще направят повторен опит едновременно и вълната ще удари услугата наведнъж. Решаваме това с jitter (трептене) – случайно вариране, добавено към закъснението, което е достатъчно, за да десинхронизира опитите.

import random

delai = delai_base * (2 ** (tentative - 1))
jitter = random.uniform(0, delai * 0.25)
time.sleep(delai + jitter)

Обработка на пакет файлове без надзор

Транскрибирането на двеста записа един след друг е неефективно: повечето време се губи в чакане на мрежата. Пул от работници (worker pool) обработва множество транскрипции едновременно, без да се губи следенето на прогреса. Функцията по-долу сканира папка, запазва известните аудио разширения, подава всеки файл към обвивката за повторен опит, дефинирана по-горе, и записва транскрипцията веднага щом пристигне, а не в края: ако процесът се срине по средата, обработеното вече е на диска. JSON отчет обобщава успехите и неуспехите, позволявайки Ви да рестартирате само това, което е се провалило.

import os
import json
import logging
from pathlib import Path
from concurrent.futures import ThreadPoolExecutor, as_completed

logger = logging.getLogger("voxtral-batch")

def traiter_batch(
    dossier_audio: str,
    dossier_sortie: str,
    max_workers: int = 4,
    **kwargs_transcription
):
    """Транскрибира всички аудио файлове в папка паралелно."""
    dossier = Path(dossier_audio)
    sortie = Path(dossier_sortie)
    sortie.mkdir(parents=True, exist_ok=True)

    # намиране на всички аудио файлове
    extensions = {".mp3", ".wav", ".flac", ".ogg", ".m4a", ".webm"}
    fichiers = [
        f for f in dossier.iterdir()
        if f.suffix.lower() in extensions
    ]

    if not fichiers:
        logger.warning(f"Aucun fichier audio dans {dossier_audio}")
        return []

    logger.info(f"Traitement de {len(fichiers)} fichiers avec {max_workers} workers")

    resultats = []

    with ThreadPoolExecutor(max_workers=max_workers) as pool:
        futures = {
            pool.submit(
                transcrire_avec_retry,
                str(f),
                **kwargs_transcription
            ): f
            for f in fichiers
        }

        for i, future in enumerate(as_completed(futures), 1):
            fichier = futures[future]
            resultat = future.result()
            resultats.append(resultat)

            status = "OK" if resultat["succes"] else "ERREUR"
            logger.info(
                f"[{i}/{len(fichiers)}] {status} — {fichier.name}"
            )

            # Запазване на транскрипцията
            if resultat["succes"]:
                nom_sortie = fichier.stem + ".txt"
                (sortie / nom_sortie).write_text(
                    resultat["texte"], encoding="utf-8"
                )

    # Краен отчет
    succes = sum(1 for r in resultats if r["succes"])
    echecs = len(resultats) - succes
    logger.info(f"Terminé : {succes} succès, {echecs} échecs")

    # Запазване на отчета
    rapport_path = sortie / "rapport_batch.json"
    with open(rapport_path, "w", encoding="utf-8") as f:
        json.dump(resultats, f, ensure_ascii=False, indent=2)

    return resultats

# Употреба
resultats = traiter_batch(
    dossier_audio="enregistrements/",
    dossier_sortie="transcriptions/",
    max_workers=4,
    diarize=True,
    timestamp_granularities=["segment"]
)

Не се поддавайте на изкушението да увеличите max_workers, за да работи по-бързо. Mistral API налага лимити на заявките в минута и четири работници обикновено Ви държат под този праг. Ако в дневниците Ви се появят грешки 429 (Too Many Requests), отговорът не е да правите по-упорити повторни опити, а да намалите броя на работниците или да въведете забавяне между заявките.

Предварителна подготовка на аудиото

Форматът на файловете, които изпращате, влияе както върху времето за качване, така и върху качеството на получения текст. Ако точността е от първостепенно значение, придържайте се към WAV или FLAC – формати без загуби: моделът получава пълната аудио информация. За обща употреба, MP3 при 128 kbps или по-високо предлага най-добрия компромис, с качество, повече от достатъчно за транскрипция, и разумен размер на файла. А когато пропускателната способност е основното ограничение, OGG Vorbis или MP3 при 64 kbps остават напълно приемливи за реч, което е много различно от музиката в това отношение.

Вместо да приемате каквито и да е формати, нормализирайте ги преди изпращане. Функцията по-долу прилага четири трансформации: конвертиране в моно, тъй като стереото не добавя нищо към транскрипцията; ресемплиране до 16 kHz, родната честота на Voxtral; задаване на битрейт от 64 kbps, достатъчен за глас; и loudnorm, който изравнява силата на звука.

import subprocess

def preparer_audio(chemin_entree: str, chemin_sortie: str = None) -> str:
    """Подготвя аудио файл за оптимална транскрипция."""
    if chemin_sortie is None:
        chemin_sortie = chemin_entree.rsplit(".", 1)[0] + "_prep.mp3"

    subprocess.run([
        "ffmpeg", "-y",
        "-i", chemin_entree,
        "-ac", "1",          # Моно (стереото не помага за транскрипцията)
        "-ar", "16000",       # 16 kHz (родна честота на Voxtral)
        "-b:a", "64k",        # 64 kbps (достатъчно за реч)
        "-af", "loudnorm",    # Нормализиране на силата на звука
        chemin_sortie
    ], check=True, capture_output=True)

    return chemin_sortie

Ползата е двойна: конвертирането към моно 16 kHz 64 kbps значително намалява размерите на файловете без влошаване на транскрипцията, а loudnorm значително подобрява резултатите при записи с неравномерна сила на звука, типично срещано при срещи, където един участник е далеч от микрофона.

Знание за случващото се

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

import time
import logging
import json
from datetime import datetime

logger = logging.getLogger("voxtral-prod")

def transcrire_avec_metriques(chemin_audio: str, **kwargs) -> dict:
    """Транскрибира със събиране на метрики."""
    debut = time.time()
    taille_fichier = Path(chemin_audio).stat().st_size

    resultat = transcrire_avec_retry(chemin_audio, **kwargs)

    duree_traitement = time.time() - debut

    metriques = {
        "timestamp": datetime.now().isoformat(),
        "fichier": chemin_audio,
        "taille_octets": taille_fichier,
        "duree_traitement_s": round(duree_traitement, 2),
        "succes": resultat["succes"],
        "tentatives": resultat["tentative"],
    }

    if resultat["succes"]:
        metriques["nb_caracteres"] = len(resultat["texte"])
        metriques["nb_mots"] = len(resultat["texte"].split())
        ratio = taille_fichier / duree_traitement / 1024
        metriques["debit_ko_par_s"] = round(ratio, 1)

    # Структуриран дневник (JSON)
    logger.info(json.dumps(metriques, ensure_ascii=False))

    return resultat

Контролен списък за продукционна среда

Преди да отворите услугата си за първия реален потребител, прегледайте тези седем точки:

ОбластПроверка
Обработка на грешкиПовторен опит с експоненциално отстъпване за временни грешки
Ограничаване на честотатаСпазване на лимитите на API, внедряване на throttling при необходимост
МониторингСтруктурирани дневници, метрики за производителност, известия при грешки
СигурностAPI ключ в променлива на средата, никога твърдо кодиран в кода
СъхранениеЗапазване на транскрипциите трайно, а не само в паметта
Аудио форматНормализиране на файловете предварително (моно, 16 kHz)
ТестванеРазнообразни файлове: езици, продължителности, аудио качество, брой говорещи

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

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

  • Внедрете повторен опит с експоненциално отстъпване и jitter за временни грешки
  • Използвайте пул от работници за пакетна обработка (4 работници е добра отправна точка)
  • Нормализирайте файловете си към моно 16 kHz с FFmpeg за оптимални резултати
  • Събирайте структурирани метрики за мониторинг в продукционна среда
  • Спазвайте лимитите за честота на Mistral API
  • Систематично запазвайте транскрипциите и отчетите за пакетна обработка