Spaces:
Paused
Paused
File size: 6,038 Bytes
a3e79be 89a511b a3e79be 89a511b a3e79be 89a511b | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 | ---
title: Muaalem Proxy
sdk: docker
app_port: 7860
pinned: false
---
# وسيط «بيان» — Muaalem Proxy
المصدر الرسميّ لِـHF Space `hatimqman-muaalem-proxy`. كان يعيش صندوقًا أسود على HF فقط؛
هذا مصدره الحقيقيّ داخل المستودع (`Quran_Rateel/hf-endpoint/proxy/`).
يجلس بين عميل **بيان** المنشور على Cloudflare Pages وبين ثلاث نقاط HF Inference، فيؤدّي:
- **يحمل توكن HF سرًّا** (من متغيّر البيئة `HF_TOKEN`) ويحقنه في نداء النقطة — لا يصل التوكن للعميل أبدًا.
- **يتجاوز حجب Cloudflare 1010**: العميل ينادي هذا الـSpace، والـSpace ينادي خادم HF.
- **فان-آوت** لثلاث نقاط علويّة عبر ثلاثة مسارات.
- **يقبل جسمًا مسطّحًا** ويغلّفه `{ "inputs": { … } }` قبل تمريره للنقطة، فيبقى `STT_URL` و`MUAALEM_URL`
في `bayan/web/app.js` بلا تغيير عنوان.
- **CORS** لنطاق Pages، **حدّ معدّل** لكلّ IP، **إعادة محاولة** على البدء البارد (scale-to-zero)،
و**تدهورٌ آمن**: أيّ فشلٍ للنقطة يُرجَع خطأ HTTP نظيفًا (لا استثناء) فيتجاهله العميل بصمتٍ.
## المسارات (واجهة العميل — مسطّحة)
| المسار | يقبل من العميل | يُمرَّر للنقطة | النقطة العلويّة |
|---|---|---|---|
| `POST /stt` | `{pcm}` أو `{pcm, ref}` | `{inputs:{pcm, ref?}}` | `STT_ENDPOINT_URL` (الطبقة الصوتية) |
| `POST /analyze` | `{pcm, surah, ayahs\|ayah, mode?, scope?, sifat?}` | `{inputs:{…}}` | `ANALYZE_ENDPOINT_URL` (المُعلِّم QPS) |
| `WS /stream?kind=tlog\|clean` | إطارات int16 PCM 16k + نصّ `"end"` | تمريرٌ شفّاف | `STREAM_ENDPOINT_URL` (بثّ احتياطيّ) |
| `GET /health` | — | — | فحص جهوزيّة (يكشف أيّ نقطةٍ مُهيَّأة) |
### عقد `POST /analyze`
```
req {"pcm":"<b64 PCM16 LE 16k أحاديّ>", "surah":1, "ayahs":[1,2,3,4,5,6,7],
"mode?":"whole|teacher", "scope?":{…}, "sifat?":true}
// أو "ayah":n لآيةٍ مفردة بدل ayahs
res ردّ النقطة كما هو: {uthmani, match, per, words:[{w,hard,soft, …}],
word_hard, word_soft, flagged, ops, ref_phonemes, pred_phonemes, mode, …}
```
`mode`/`scope`/`sifat` تُمرَّر شفّافةً؛ النقطة الحاليّة تتجاهلها بأمان، وطبقتا P1/P2 تستهلكانها.
### عقد `POST /stt`
```
req {"pcm":"<b64 PCM16 LE 16k>", "ref?":"<كلمات التشكيل للمحاذاة القسريّة>"}
res {"text":"…", "words?":[{w,start_ms,end_ms,prob,gop,status}], "provider":"quran-stt-acoustic"}
```
بلا `ref`: نصّ فقط. مع `ref`: محاذاة قسريّة + توقيت/GOP/رأس نطق.
## متغيّرات البيئة (Settings → Variables and secrets)
| المتغيّر | النوع | الافتراضيّ | الوصف |
|---|---|---|---|
| `HF_TOKEN` | **سرّ** | — | توكن HF (Bearer) لنقاط الاستدلال. **إلزاميّ** إن كانت النقاط محميّة. |
| `STT_ENDPOINT_URL` | متغيّر | — | URL كامل لنقطة الطبقة الصوتية. فارغٌ ⇒ `/stt` يُرجِع 503 نظيفًا. |
| `ANALYZE_ENDPOINT_URL` | متغيّر | — | URL كامل لنقطة المُعلِّم QPS. فارغٌ ⇒ `/analyze` يُرجِع 503 نظيفًا. |
| `STREAM_ENDPOINT_URL` | متغيّر | — | URL كامل لنقطة البثّ (`ws://`/`wss://`). فارغٌ ⇒ `/stream` يُغلَق بلطف. |
| `ALLOWED_ORIGINS` | متغيّر | — | أصولٌ صريحة مفصولة بفواصل (بجانب النمط أدناه). |
| `ALLOWED_ORIGIN_REGEX` | متغيّر | `*.pages.dev`/`*.workers.dev`/localhost | نمط CORS. عدِّله لتقييده على نطاق Pages بعينه. |
| `RATE_LIMIT_PER_MIN` | متغيّر | `40` | سقف الطلبات لكلّ IP في الدقيقة. `0` = مُعطَّل. |
| `UPSTREAM_TIMEOUT` | متغيّر | `150` | سقف ميزانية الطلب الكلّيّة (ث) عبر كلّ المحاولات. |
| `ATTEMPT_TIMEOUT` | متغيّر | `60` | مهلة قراءة المحاولة الواحدة (ث). |
| `MAX_RETRIES` | متغيّر | `6` | أقصى عدد محاولات على البدء البارد. |
| `RETRY_BACKOFF` | متغيّر | `4` | أساس التراجع الخطّيّ (ث). |
| `RETRY_BACKOFF_MAX` | متغيّر | `20` | سقف التراجع بين المحاولات (ث). |
| `MAX_BODY_BYTES` | متغيّر | `25165824` | سقف حجم جسم الطلب (~24MB). |
| `LOG_LEVEL` | متغيّر | `INFO` | مستوى السجلّ. |
> إعادة المحاولة تُطلَق على حالات `500/502/503/504` (النقطة تستيقظ من scale-to-zero) وعلى أخطاء
> الاتصال/المهلة. أمّا `4xx` الحتميّة فتُعاد فورًا بلا إعادة محاولة.
## التشغيل المحلّيّ
```bash
pip install -r requirements.txt
export HF_TOKEN=hf_xxx
export ANALYZE_ENDPOINT_URL=https://<endpoint>.endpoints.huggingface.cloud
export STT_ENDPOINT_URL=https://<endpoint>.endpoints.huggingface.cloud
python app.py # يستمع على :7860 (أو $PORT)
# فحص: curl localhost:7860/health
```
## النشر على HF Space
1. أنشئ Space من نوع **Docker**.
2. ارفع `app.py` و`requirements.txt` و`Dockerfile` و`README.md` (front matter أعلاه يضبط `app_port=7860`).
3. أضِف الأسرار/المتغيّرات من الجدول أعلاه (`HF_TOKEN` سرًّا؛ عناوين النقاط متغيّراتٍ).
4. أبقِ `MUAALEM_URL`/`STT_URL` في `bayan/web/app.js` على `https://<space>.hf.space/{analyze,stt}` بلا تغيير.
**لا شيء هنا يَنشُر تلقائيًّا — كودٌ فقط.**
|