Оптимизация за продукционна среда
На тази страница
Курсът е актуализиран на 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
- Систематично запазвайте транскрипциите и отчетите за пакетна обработка