از WebSocket تا متن نهایی: ساخت یک مسیر گفتار زنده با Vosk

با یک سرور محلی و فایل صوتی تکه‌تکه، مسیر صدا تا متن موقت و نهایی را مشاهده کنید. این نمونه نشان می‌دهد چرا پایان یک قطعهٔ گفتار با پایان کل جریان یکی نیست.

برای دیدن مسیر گفتار زنده، لازم نیست از ابتدا میکروفون و رابط کاربری بسازید: یک WAV را هر ۱۰۰ میلی‌ثانیه روی WebSocket بفرستید و در سمت سرور سه رویداد partial، segment و done تولید کنید. نتیجه، آزمایشی محلی و قابل مشاهده است که نشان می‌دهد کدام متن هنوز قابل تغییر است و چه زمانی می‌توان متن کل نشست را قطعی دانست.

مخاطب این راهنما سارا، توسعه‌دهندهٔ بک‌اند یک ابزار پیاده‌سازی مصاحبه است که می‌خواهد پیش از اتصال میکروفون مرورگر، قرارداد انتقال صدا و تحویل متن را آزمایش کند. مسئلهٔ محدود ما اتصال یک فرستنده به یک بازشناس محلی Vosk است؛ نه ساخت سرویس آمادهٔ تولید. استفاده از فایل، ورودی آزمایش را تکرارپذیر می‌کند، اما تجربهٔ کامل ضبط زنده را بازسازی نمی‌کند.

۱. قرارداد جریان: بایت صوت با پایان گفتار فرق دارد

قرارداد این نمونه ساده است: هر پیام باینری شامل PCM خام، تک‌کاناله، شانزده‌بیتی و با نرخ ۱۶۰۰۰ هرتز است. سرآیند WAV ارسال نمی‌شود؛ ماژول wave آن را می‌خواند و فقط فریم‌های صوتی را تحویل می‌دهد. هر قطعهٔ ۱۰۰ میلی‌ثانیه‌ای شامل ۱۶۰۰ نمونه و ۳۲۰۰ بایت است: ۱۶۰۰۰ × ۰٫۱ × ۲. اندازهٔ پیام WebSocket در اینجا مرز انتقال است، نه مرز کلمه یا جمله.

پیام متنی {"eof": true} یعنی فرستنده دیگر صوتی ندارد. تا پیش از آن، PartialResult فرضیهٔ فعلی را می‌دهد؛ این متن را باید در رابط کاربری جایگزین کرد، نه به متن قبلی چسباند. وقتی AcceptWaveform مقدار درست برگرداند، Result نتیجهٔ قطعهٔ تشخیص‌داده‌شده را می‌دهد. در این قرارداد نام آن segment است. در پایان ورودی، FinalResult باقی‌مانده را تخلیه می‌کند و سرور done را با متن تجمیع‌شده می‌فرستد.

۲. نمونهٔ اجراشدنی: سرور و فرستنده در یک فایل

با پایتون ۳٫۱۰ یا جدیدتر شروع کنید. از صفحهٔ مدل‌های Vosk، مدل متناسب با زبان ضبط را دریافت و استخراج کنید؛ مسیر پوشهٔ استخراج‌شده را به سرور بدهید. مدل داخل کد دانلود نمی‌شود. ورودی مثال input.wav است: یک ضبط کوتاه با چند کلمه و کمی سکوت در انتها. برای گفتار فارسی مدل فارسی لازم است؛ نرخ اعلام‌شده در کد نیز باید با صوت و نیاز مدل سازگار باشد.

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install vosk 'websockets>=14'
# در صورت نیاز، تبدیل فایل ضبط‌شده با ابزار جداگانهٔ ffmpeg:
ffmpeg -i recording.wav -ac 1 -ar 16000 -c:a pcm_s16le input.wav
# کد بعدی را با نام stream_demo.py ذخیره کنید.
# ترمینال اول؛ مسیر واقعی پوشهٔ مدل را جایگزین کنید:
python stream_demo.py server ./model
# ترمینال دوم، با محیط مجازی فعال:
python stream_demo.py client input.wav
```

```python
import asyncio
import json
import sys
import wave

from vosk import Model, KaldiRecognizer
from websockets.asyncio.client import connect
from websockets.asyncio.server import serve

RATE = 16000
CHUNK_FRAMES = 1600


def encode(event, text):
return json.dumps({'event': event, 'text': text}, ensure_ascii=False)


async def run_server(model_path):
model = Model(model_path)

async def handler(ws):
recognizer = KaldiRecognizer(model, RATE)
segments = []
last_partial = None

async for message in ws:
if isinstance(message, bytes):
if len(message) % 2:
await ws.close(code=1008, reason='PCM sample is incomplete')
return
if recognizer.AcceptWaveform(message):
text = json.loads(recognizer.Result()).get('text', '')
if text:
segments.append(text)
await ws.send(encode('segment', text))
last_partial = None
else:
partial = json.loads(recognizer.PartialResult()).get('partial', '')
if partial != last_partial:
await ws.send(encode('partial', partial))
last_partial = partial
else:
try:
command = json.loads(message)
except json.JSONDecodeError:
command = None
if command != {'eof': True}:
await ws.close(code=1008, reason='Expected EOF command')
return
tail = json.loads(recognizer.FinalResult()).get('text', '')
if tail:
segments.append(tail)
await ws.send(encode('segment', tail))
await ws.send(encode('done', ' '.join(segments)))
return

async with serve(handler, '127.0.0.1', 8765):
print('Listening on ws://127.0.0.1:8765', flush=True)
await asyncio.Future()


async def run_client(wav_path):
with wave.open(wav_path, 'rb') as audio:
actual = (audio.getnchannels(), audio.getsampwidth(),
audio.getframerate(), audio.getcomptype())
if actual != (1, 2, RATE, 'NONE'):
raise ValueError('Expected mono 16-bit PCM WAV at 16000 Hz')

async with connect('ws://127.0.0.1:8765') as ws:
async def receive():
async for message in ws:
event = json.loads(message)
print(json.dumps(event, ensure_ascii=False), flush=True)
if event['event'] == 'done':
return
raise RuntimeError('Connection closed before done')

receiver = asyncio.create_task(receive())
try:
while True:
chunk = audio.readframes(CHUNK_FRAMES)
if not chunk:
break
await ws.send(chunk)
await asyncio.sleep(len(chunk) / (RATE * 2))
await ws.send(json.dumps({'eof': True}))
await asyncio.wait_for(receiver, timeout=60)
finally:
if not receiver.done():
receiver.cancel()
await asyncio.gather(receiver, return_exceptions=True)


if __name__ == '__main__':
if len(sys.argv) != 3 or sys.argv[1] not in ('server', 'client'):
raise SystemExit('Usage: python stream_demo.py server MODEL_DIR | client INPUT.wav')
if sys.argv[1] == 'server':
asyncio.run(run_server(sys.argv[2]))
else:
asyncio.run(run_client(sys.argv[2]))
```

خروجی مورد انتظار، چند شیء JSON با event و text و در انتها دقیقاً یک done است. برای ضبط «سلام»، خروجی نمونه می‌تواند مانند زیر باشد؛ واژهٔ تشخیص‌داده‌شده و تعداد partialها تضمین‌شده نیستند. حتی ورودی سکوت هم باید به done با متن خالی برسد. معیار موفقیت آزمایش، دریافت پایان صریح و یکسان‌بودن متن done با اتصال segmentهای غیرخالی به ترتیب دریافت است.

```other
{"event": "partial", "text": ""}
{"event": "partial", "text": "سلام"}
{"event": "segment", "text": "سلام"}
{"event": "done", "text": "سلام"}
```

۳. شکست رایج: متن موقت را نهایی فرض نکنید

اگر هر partial را به خروجی اضافه کنید، واژه‌های تکراری و فرضیه‌های کنارگذاشته‌شده وارد متن می‌شوند. در کلاینت واقعی دو وضعیت نگه دارید: فهرست segmentهای قطعی و یک رشتهٔ موقت قابل جایگزینی. با دریافت segment، متن آن را به فهرست اضافه و رشتهٔ موقت را پاک کنید؛ با done، متن کل نشست را جایگزین نمایش نهایی کنید، نه اینکه دوباره به آن بچسبانید. بسته‌شدن اتصال پیش از done نیز باید «نشست ناقص» تلقی شود، نه پایان موفق.

شکست دیگر، ارسال خروجی MediaRecorder به همین سرور است. بایت‌های یک ظرف فشرده مثل WebM، PCM خام نیستند؛ یکسان‌بودن مسیر WebSocket این تفاوت را رفع نمی‌کند. برای میکروفون مرورگر باید یا مسیر تولید و بازنمونه‌برداری PCM بسازید، یا در سمت سرور رمزگشایی پیوسته با حفظ وضعیت ظرف و کدک داشته باشید. تغییر نام فایل یا تنظیم عدد RATE به‌تنهایی تبدیل صوت نیست.

۴. مصالحه‌ها و مرز استفاده

قطعهٔ ۱۰۰ میلی‌ثانیه‌ای مصالحه‌ای آموزشی است: قطعه‌های کوچک‌تر فرصت ارسال زودتر می‌دهند اما تعداد پیام و سربار پردازش را بیشتر می‌کنند؛ قطعه‌های بزرگ‌تر انتظار اولیه را افزایش می‌دهند. این اندازه تضمین نمی‌کند متن هر ۱۰۰ میلی‌ثانیه تغییر کند، چون بازشناس برای تصمیم خود به زمینه نیاز دارد. sleep نیز فقط سرعت تقریبی فایل را شبیه‌سازی می‌کند و ساعت دقیق بلادرنگ نیست.

اگر فقط متن نهایی فایل را می‌خواهید، ارسال فایل با HTTP ساده‌تر است؛ WebSocket وقتی ارزش دارد که دریافت متن حین ارسال مهم باشد. Vosk محلی برای بررسی قرارداد بدون ارسال صوت به سرویس بیرونی مناسب است، اما انتخاب نهایی موتور باید با ضبط‌های واقعی همان زبان آزمایش شود. برای چند کاربر هم‌زمان، اجرای همگام بازشناسی در حلقهٔ رویداد انتخاب نادرستی است: آن را به کارگر جدا و صف محدود منتقل کنید و برای عقب‌افتادن پردازش سیاست روشن بگذارید. این نمونه نه آن معماری را دارد و نه باید مستقیماً روی اینترنت منتشر شود.

منابع

نمونهٔ رسمی پردازش WAV با Vosk: https://github.com/alphacep/vosk-api/blob/master/python/example/test_simple.py
مدل‌های رسمی Vosk و شرایط استفادهٔ آن‌ها: https://alphacephei.com/vosk/models
راهنمای شروع سریع websockets: https://websockets.readthedocs.io/en/stable/intro/quickstart.html
مستندات ماژول wave در پایتون: https://docs.python.org/3/library/wave.html

No comments yet