ERP/bale stt report/bale_stt_integration_report.md

گزارش فنی و امکان‌سنجی: ادغام قابلیت صوت به متن (STT) بله در سامانه تدارکات هوشمند

Note

مخاطب گزارش: تیم فنی، معماران سیستم و مدیران محصول
موضوع: بررسی، مقایسه دو رویکرد فنی و نقشه راه پیاده‌سازی اتصال به موتور تبدیل ویس به متن پیام‌رسان «بله»
هدف نهایی: افزودن بله به عنوان یکی از مدل‌های کاندید در خط لوله STT چندمدله (Multi-Provider STT) جهت افزایش دقت استخراج اقلام تدارکات

---

۱. خلاصه مدیریتی (Executive Summary)

سامانه هوشمند تدارکات در حال حاضر مجهز به موتور پردازش موازی صوت (Multi-Provider STT) است که قادر است فایل‌های صوتی دریافتی از کاربران را هم‌زمان به چندین ارائه‌دهنده (نظیر Whisper، Soniox یا سرویس‌های ابری) ارسال کرده و از طریق مدل تحلیلی DeepSeek یک خروجی یکپارچه و دقیق (Consensus Text) به همراه اقلام استعلام استخراج کند.

برای افزایش هرچه بیشتر دقت در زبان فارسی و لهجه‌های محلی، استفاده از موتور صوت‌به‌متن بومی پیام‌رسان بله به عنوان یکی از مدل‌های کاندید مطرح شده است. از آن‌جا که پلتفرم توسعه‌دهندگان بله (Bale Bot API) متد مستقیمی برای فراخوانی API ترنسکرایب ارائه نمی‌دهد، دو روش اجرایی اصلی برای دستیابی به این موتور وجود دارد:

1. روش اول (اتوماسیون رابط کاربری وب / Headless Browser): شبیه‌سازی رفتار کاربر در مرورگر و کلیک روی دکمه تبدیل وویس.
2. روش دوم (مهندسی معکوس پروتکل کلاینت / Direct Client API): شبیه‌سازی درخواست‌های شبکه (WebSocket/HTTP) کلاینت بله بدون نیاز به مرورگر.

---

۲. پس‌زمینه فنی زیرساخت بله (Technical Context)

بخش	وضعیت دسترسی	توضیحات
Bale Bot API (رسمی)	فاقد متد STT	فقط امکان دانلود فایل صوتی خام (voice / audio) با file_id را فراهم می‌کند.
کلاینت‌های کاربری بله (Web / Android)	دارای موتور فعال STT	روی هر ویس یک دکمه تبدیل صوت به متن وجود دارد که با فشرده شدن آن، صوت روی سرورهای بله به متن تبدیل می‌شود.
دستیار هوش مصنوعی بله	پشتیبانی از ورودی صوتی	کاربر با ارسال ویس به چت هوش مصنوعی بله، متن پیاده‌شده به همراه پاسخ تحلیلی را دریافت می‌کند.

نتیجه: برای بهره‌برداری از این قابلیت، بات تدارکات باید در لایه ارتباطی خود، یک نشست کاربری (User Session) در بله داشته باشد تا بتواند خدمات تبدیل صوت کلاینت را فراخوانی کند.

---

۳. روش اول: اتوماسیون رابط کاربری وب (Headless Browser Scraping)

در این رویکرد، یک مرورگر کنترل‌شده بدون واسط گرافیکی (مانند Chromium تحت فریم‌ورک Playwright) در یک کانتینر اختصاصی داکر مستقر شده و در نسخه وب بله (web.bale.ai) فعال نگه داشته می‌شود.

معماری جریان داده (Architecture Flow)

sequenceDiagram
    autonumber
    participant Bot as Procurement Bot
    participant Worker as Browser Worker (Playwright)
    participant BaleWeb as web.bale.ai (Chromium)
    participant BaleServer as سرورهای پردازش صوت بله

    Bot->>Worker: ارسال فایل صوتی (voice.mp3)
    Worker->>BaleWeb: بارگذاری فایل در چت کلاینت
    BaleWeb->>BaleServer: ارسال صوت و درخواست تبدیل
    BaleServer-->>BaleWeb: بازگرداندن متن پیاده‌شده به صفحه
    Worker->>BaleWeb: استخراج متن از DOM (.transcription-text)
    Worker-->>Bot: بازگرداندن متن خروجی به خط لوله STT

مؤلفه‌های پیاده‌سازی:

1. مدیریت نشست پایدار (Persistent Profile):
   • پوشه پروفایل مرورگر (userDataDir) بر روی یک داکر ولوم ماندگار (/data/bale_browser_session) قرار می‌گیرد.
   • ورود اولیه فقط یک‌بار توسط تیم فنی با شماره تلفن اختصاصی و کد OTP پیامکی انجام می‌شود و کوکی‌ها و توکن‌های LocalStorage/IndexedDB برای همیشه حفظ می‌گردند.
2. انتظار هوشمند بر اساس رخدادهای DOM:
   • استفاده از سلکتورهای مقاوم با waitForSelector یا MutationObserver روی باکس متن ترنسکرایب.
3. مزایا و معایب:
   • 🟢 تضمین تطابق با سرور: چون مرورگر رسمی در حال اجرا است، هیچ‌گونه ریسک ناسازگاری پکت‌های شبکه وجود ندارد.
   • 🟢 پایداری در برابر تغییرات داخلی API: حتی اگر بله فریم‌ورک پکت‌های وب‌سوکت خود را عوض کند، تا زمانی که دکمه در UI وجود دارد سیستم کار می‌کند.
   • 🔴 مصرف بالای منابع: هر نمونه Chromium حدود ۳۰۰ تا ۵۰۰ مگابایت رم اشغال می‌کند.
   • 🔴 تاخیر زمانی (Latency): فرآیند رندر صفحه، شبیه‌سازی آپلود و رویداد کلیک حدود ۳ تا ۶ ثانیه زمان می‌برد.

---

۴. روش دوم: مهندسی معکوس شبکه و پروتکل کلاینت (Direct Client API)

در این روش، بدون استفاده از مرورگر سنگین، کلاینت پایتونی سبک ما مستقیماً همان درخواست‌های سوکت یا HTTP کلاینت رسمی بله را بازسازی و فراخوانی می‌کند.

معماری جریان داده (Architecture Flow)

sequenceDiagram
    autonumber
    participant Bot as Procurement Bot
    participant Adapter as Bale Client Protocol Adapter (Python)
    participant BaleCore as هسته سرور بله (WebSocket / RPC)

    Bot->>Adapter: ارسال بایت‌های فایل صوتی
    Adapter->>BaleCore: فراخوانی مستقیم متد Transcribe (از طریق سوکت یا HTTP)
    BaleCore-->>Adapter: پاسخ مستقیم باینری/JSON متن
    Adapter-->>Bot: متن نهایی در کمتر از ۱ ثانیه

مؤلفه‌های پیاده‌سازی:

1. آنالیز ترافیک شبکه (Traffic Inspection):
   • تحلیل تب Network مرورگر در web.bale.ai:
     • استخراج مسیر اتصال (غالباً wss://api.bale.ai/v1/users/websocket یا اندپوینت‌های REST).
     • استخراج هدرهای نشست از localStorage کلاینت وب (مانند access_token, device_id, session_key).
     • کشف پکت یا درخواست RPC مسئول تبدیل صوت (شامل شناسه پیام message_id و شناسه فایل صوتی file_id).
2. کلاینت ناهمگام پایتون (httpx / websockets):
   • اتصال دائمی و سبک به زیرساخت پیام‌رسانی بله.
   • ارسال مستقیم درخواست بدون بارگذاری فایل‌های گرافیکی، جاوااسکریپت و CSS مرورگر.
3. مزایا و معایب:
   • 🟢 سرعت خیره‌کننده (Ultra-low Latency): پاسخگویی معمولاً در کمتر از ۱ ثانیه انجام می‌شود.
   • 🟢 مصرف ناچیز منابع (Lightweight): مصرف حافظه رم زیر ۱۰ مگابایت.
   • 🟢 ظرفیت پردازش همزمان بالا (High Concurrency): امکان ارسال همزمان ده‌ها درخواست بدون افت پرفورمنس.
   • 🔴 حساسیت به پروتکل: در صورت بازنویسی پروتکل یا فیلدهای باینری کلاینت بله، ممکن است نیاز به به‌روزرسانی پکت‌ها باشد.

---

۵. ماتریس مقایسه جامع فنی (Technical Decision Matrix)

معیار ارزیابی	روش اول: اتوماسیون وب (Playwright)	روش دوم: مهندسی معکوس پروتکل کلاینت	اهمیت برای سیستم
تاخیر پاسخ‌دهی (Latency)	۳ تا ۶ ثانیه	زیر ۱ ثانیه ⚡️	بسیار بالا (تاثیر مستقیم روی UX وویس)
مصرف حافظه RAM	۳۵۰ الی ۵۰۰ مگابایت	کمتر از ۱۵ مگابایت 🪶	متوسط به بالا
هزینه پردازشی CPU	متوسط تا بالا (رندرینگ)	بسیار پایین (درخواست شبکه)	متوسط
پیچیدگی پیاده‌سازی اولیه	کم (طی چند ساعت با سلکتور)	متوسط (نیازمند اسنیف و دیکود پکت)	موقت
پایداری نشست کاربری (Session)	ذخیره در پوشه کاربری مرورگر	ذخیره توکن در متغیر محیطی / دیتابیس	بالا
ریسک تغییرات توسط بله	کم (مقاوم در برابر تغییر پروتکل)	نیازمند پایش در تغییر نسخه‌های ماژور	متوسط
قابلیت مقیاس‌پذیری (Scalability)	محدود (محدودیت منابع مرورگر)	نامحدود (ایسنک و چندنخی)	بالا

---

۶. نحوه اتصال به پایپ‌لاین STT چندمدله فعلی

سامانه تدارکات در حال حاضر قابلیت دریافت چند کاندیدا را دارد. با اتصال بله، خروجی به شکل زیر در پردازش قرار می‌گیرد:

graph TD
    Voice[وویس دریافتی کاربر از بله] --> FFMPEG[تبدیل یک‌باره به MP3]
    FFMPEG --> S1[مدل ۱: Whisper-Large]
    FFMPEG --> S2[مدل ۲: Soniox / OpenRouter]
    FFMPEG --> S3[مدل ۳: موتور صوت هوش مصنوعی بله]
    
    S1 --> Aggregator[تجمیع نتایج کاندیداها]
    S2 --> Aggregator
    S3 --> Aggregator
    
    Aggregator --> DeepSeek[تحلیلگر هوشمند DeepSeek]
    DeepSeek --> Final[متن اصلاح‌شده Consensus Text + استخراج اقلام استعلام JSON]

---

۷. نقشه راه پیشنهادی دو مرحله‌ای برای تیم توسعه (Recommended Roadmap)

Tip

استراتژی برد-برد (Fast Win + High Performance): برای اینکه از سریع‌ترین حالت ممکن با کمترین ریسک بهره‌مند شویم، فرآیند اجرای فازبندی‌شده زیر پیشنهاد می‌شود:

فاز ۱: ممیزی و اکتشاف ترافیک شبکه (کمتر از ۱ روز کاری)

1. باز کردن web.bale.ai با تب Network و کلیک روی دکمه تبدیل ویس.
2. تعیین ماهیت درخواست:
   • اگر درخواست یک HTTP POST ساده یا یک فریم متنی وب‌سوکت با Authorization Header باشد: 👉 روش دوم بلافاصله پیاده‌سازی می‌شود و به بالاترین سرعت و بهره‌وری ممکن می‌رسیم.
   • اگر پروتکل شامل امضاها و فریم‌های رمزگذاری‌شده پیچیده باشد: 👉 به سراغ اجرای فاز ۲ (روش اول) می‌رویم.

فاز ۲: استقرار سرویس اتوماسیون (Fallback تضمین‌شده)

1. ساخت کانتینر داکر سبک playwright-worker در کنار کانتینر procurement-bot.
2. اتصال امن این کانتینر از طریق یک اندپوینت داخلی ساده: POST http://bale-stt-worker:8080/transcribe
3. قرار گرفتن این سرویس به عنوان مدل سوم در متغیر محیطی: PROCUREMENT_BOT_STT_PROVIDER_3_BASE_URL=http://bale-stt-worker:8080/v1

---

تهیه شده جهت ارائه به تیم فنی و مدیران سیستم تدارکات هوشمند.