README.md

---
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}` بلا تغيير.

**لا شيء هنا يَنشُر تلقائيًّا — كودٌ فقط.**