Przejdź do głównej treści
Polski— Wybierz język
Menu

Strumieniowanie w czasie rzeczywistym

Lekcja 10 z 14 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Dlaczego strumieniowanie zmienia wszystko
  2. Protokół zdarzeń
  3. Odtwarzanie dźwięku w miarę jego napływania
  4. Przekazywanie strumienia do przeglądarki
  5. Ustawienie, które robi różnicę: bufor
  6. Kluczowe wnioski

Kurs zaktualizowano 3 listopada 2026 r. dla Voxtral TTS 3, na podstawie przewodnika Migrate from Voxtral 2 oraz dokumentacji Mistral Text to Speech: model voxtral-mini-tts-2603, wycofany 31 października 2026 r. i całkowicie usunięty 30 kwietnia 2027 r., został zastąpiony w przykładach modelem voxtral-mini-tts-3-0. Predefiniowane głosy z Voxtral 2 (gb_jane_neutral…) są nadal obsługiwane; Voxtral 3 wprowadza tagi [emotion=…] i [pace=…] w tekście, ustawienie expressiveness, niestandardową wymowę (phoneme_hints) oraz obsługę 35 języków. Mistral zaleca ponowne zmierzenie opóźnień po migracji. Źródła: Migrate from Voxtral 2 · Speech generation.

Dlaczego strumieniowanie zmienia wszystko

Do tej pory pracowałeś w trybie synchronicznym: wysyłałeś tekst, czekałeś na całkowite zakończenie syntezy, a dopiero potem otrzymywałeś pełny plik audio. W przypadku powitania wygenerowanego dzień wcześniej to oczekiwanie nie ma znaczenia. Dla asystenta głosowego odpowiadającego klientowi przez telefon jest to jednak problem krytyczny – dwie sekundy ciszy po zadaniu pytania sprawiają, że użytkownik myśli, iż połączenie zostało zerwane.

Strumieniowanie eliminuje to oczekiwanie. Audio jest wysyłane w miarę generowania, fragment po fragmencie, dzięki czemu użytkownik słyszy pierwsze słowa, gdy model wciąż produkuje koniec zdania. Całkowity czas generowania się nie zmienia; to, co ulega skróceniu, to opóźnienie przed pojawieniem się pierwszego dźwięku.

Protokół zdarzeń

Strumień opiera się na zdarzeniach Server-Sent Events (SSE). Każda otrzymana wiadomość jest zdarzeniem określonego typu, a dwa z nich są dla Ciebie kluczowe:

  • speech.audio.delta: zawiera fragment audio zakodowany w base64. To główne zdarzenie, którym będziesz się zajmować.
  • speech.audio.done: sygnał końca – generowanie zostało zakończone.

Po stronie kodu przejście na tryb strumieniowy oznacza dodanie parametru stream=True i przetwarzanie odpowiedzi w bloku with. Poniższy przykład gromadzi fragmenty w pamięci, aby zapisać plik na końcu: nie jest to jeszcze rozwiązanie czasu rzeczywistego, ale stanowi strukturę pętli, na której będziemy budować w dalszej części lekcji.

import base64
from pathlib import Path
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")

audio_chunks = []

with client.audio.speech.complete(
    model="voxtral-mini-tts-3-0",
    input="Streaming makes voice agents responsive and natural.",
    voice_id="your-voice-id",
    response_format="opus",
    stream=True,
) as stream:
    for event in stream:
        if event.event == "speech.audio.delta":
            chunk = base64.b64decode(event.data.audio_data)
            audio_chunks.append(chunk)
            print(f"Chunk received: {len(chunk)} bytes")

# Assemble all chunks
audio_complet = b"".join(audio_chunks)
Path("streaming-output.opus").write_bytes(audio_complet)
print(f"Final audio: {len(audio_complet)} bytes")

Odtwarzanie dźwięku w miarę jego napływania

Aby osiągnąć obiecaną responsywność, przestań gromadzić dane i zapisuj każdy fragment bezpośrednio do karty dźwiękowej. Przy użyciu biblioteki pyaudio zmiana sprowadza się do jednej linii: zamiast dodawać zdekodowany fragment do listy, wysyłasz go do strumienia wyjściowego otwartego wcześniej, skonfigurowanego dla mono Float32 przy częstotliwości 24 000 Hz.

import base64
import pyaudio
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")

# PCM audio configuration (fastest format)
p = pyaudio.PyAudio()
stream_audio = p.open(
    format=pyaudio.paFloat32,
    channels=1,
    rate=24000,
    output=True,
)

with client.audio.speech.complete(
    model="voxtral-mini-tts-3-0",
    input="You're hearing this sentence while I generate it.",
    voice_id="your-voice-id",
    response_format="pcm",
    stream=True,
) as stream:
    for event in stream:
        if event.event == "speech.audio.delta":
            audio_data = base64.b64decode(event.data.audio_data)
            stream_audio.write(audio_data)

stream_audio.stop_stream()
stream_audio.close()
p.terminate()

Żądany format zmienił się z opus na pcm i ma to istotne znaczenie. PCM nie wymaga dekodowania: otrzymane bajty są gotowe do natychmiastowego odtworzenia, co czyni ten format rekomendowanym do zastosowań w czasie rzeczywistym.

Przekazywanie strumienia do przeglądarki

W aplikacji internetowej serwer nie odtwarza dźwięku – przekazuje go dalej. Klasyczny wzorzec wykorzystuje WebSocket, który odbiera tekst z przeglądarki, otwiera strumień Voxtral i pushuje każdy zdekodowany fragment z powrotem do klienta. Po stronie przeglądarki interfejs Web Audio API przejmuje kontrolę, aby odtwarzać otrzymane fragmenty PCM.

# Server side (FastAPI example)
from fastapi import FastAPI, WebSocket
import base64
from mistralai.client import Mistral

app = FastAPI()
client = Mistral(api_key="your-api-key")

@app.websocket("/ws/tts")
async def tts_websocket(websocket: WebSocket):
    await websocket.accept()
    texte = await websocket.receive_text()

    with client.audio.speech.complete(
        model="voxtral-mini-tts-3-0",
        input=texte,
        voice_id="your-voice-id",
        response_format="pcm",
        stream=True,
    ) as stream:
        for event in stream:
            if event.event == "speech.audio.delta":
                await websocket.send_bytes(
                    base64.b64decode(event.data.audio_data)
                )

    await websocket.close()

Ustawienie, które robi różnicę: bufor

Rozmiary fragmentów są zmienne i zazwyczaj reprezentują kilka milisekund audio każdy. Jeśli zaczniesz odtwarzać pierwszy fragment w momencie jego nadejścia, każda nieregularność sieciowa spowoduje słyszalne mikro-przerwanie – „czkawkę“ w głosie, która natychmiast zdradzi maszynę. Rozwiązaniem jest buforowanie dwóch lub trzech fragmentów przed rozpoczęciem odtwarzania. Kosztuje to kilkadziesiąt milisekund, ale wygładza resztę strumienia.

Istotny jest również wybór formatu, który stanowi kompromis między opóźnieniem a przepustowością. PCM dostarcza pierwszy dźwięk najszybciej – około 0,7 sekundy według pomiarów wykonanych dla Voxtral 2 (należy je powtórzyć dla Voxtral TTS 3) – kosztem wysokiego zużycia przepustowości. Opus nieco przegrywa pod względem opóźnienia, ale mocno kompresuje dane, co czyni go właściwym kompromisem, gdy Twoi użytkownicy korzystają z urządzeń mobilnych.

Kluczowe wnioski

  • Strumieniowanie wysyła audio fragment po fragmencie w trakcie generowania.
  • Włączasz je, dodając stream=True w wywołaniu audio.speech.complete().
  • Zdarzenia speech.audio.delta zawierają fragmenty audio zakodowane w base64.
  • Format PCM oferuje najniższe opóźnienie dla strumieniowania (~0,7 s w porównaniu do ~2 s dla MP3).
  • Do odtwarzania w czasie rzeczywistym użyj pyaudio lub połączenia WebSocket z Web Audio API.