Upload 7 files
Browse files- .env.example +25 -0
- Dockerfile +19 -0
- README.md +126 -10
- docker-compose.yml +8 -0
- pyproject.toml +15 -0
- requirements-dev.txt +5 -0
- requirements.txt +7 -0
.env.example
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# إعدادات عامة
|
| 2 |
+
APP_NAME=HF Chat Backend
|
| 3 |
+
APP_ENV=development
|
| 4 |
+
DEBUG=false
|
| 5 |
+
|
| 6 |
+
# إعدادات Hugging Face
|
| 7 |
+
# احصل على التوكن من: https://huggingface.co/settings/tokens
|
| 8 |
+
HF_API_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
| 9 |
+
# معرّف النموذج على Hugging Face (أو رابط Inference Endpoint المخصص)
|
| 10 |
+
HF_MODEL_ID=meta-llama/Llama-3.1-8B-Instruct
|
| 11 |
+
# اتركه فارغاً لاستخدام Hugging Face Inference API الافتراضي
|
| 12 |
+
# أو حدد مزود متوافق مثل: together, fireworks-ai, replicate, sambanova
|
| 13 |
+
HF_PROVIDER=
|
| 14 |
+
HF_TIMEOUT_SECONDS=60
|
| 15 |
+
|
| 16 |
+
# إعدادات التوليد الافتراضية
|
| 17 |
+
DEFAULT_MAX_NEW_TOKENS=512
|
| 18 |
+
DEFAULT_TEMPERATURE=0.7
|
| 19 |
+
DEFAULT_TOP_P=0.95
|
| 20 |
+
|
| 21 |
+
# مفتاح لحماية الباكند نفسه (اتركه فارغاً لتعطيل الحماية)
|
| 22 |
+
BACKEND_API_KEY=
|
| 23 |
+
|
| 24 |
+
# CORS - افصل بفواصل أو استخدم * للسماح للجميع
|
| 25 |
+
CORS_ALLOW_ORIGINS=*
|
Dockerfile
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
FROM python:3.12-slim
|
| 2 |
+
|
| 3 |
+
WORKDIR /app
|
| 4 |
+
|
| 5 |
+
ENV PYTHONDONTWRITEBYTECODE=1 \
|
| 6 |
+
PYTHONUNBUFFERED=1
|
| 7 |
+
|
| 8 |
+
COPY requirements.txt .
|
| 9 |
+
RUN pip install --no-cache-dir -r requirements.txt
|
| 10 |
+
|
| 11 |
+
COPY app ./app
|
| 12 |
+
|
| 13 |
+
EXPOSE 8000
|
| 14 |
+
|
| 15 |
+
# Healthcheck بسيط
|
| 16 |
+
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
|
| 17 |
+
CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" || exit 1
|
| 18 |
+
|
| 19 |
+
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
|
README.md
CHANGED
|
@@ -1,10 +1,126 @@
|
|
| 1 |
-
|
| 2 |
-
|
| 3 |
-
|
| 4 |
-
|
| 5 |
-
|
| 6 |
-
|
| 7 |
-
|
| 8 |
-
--
|
| 9 |
-
|
| 10 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# HF Chat Backend
|
| 2 |
+
|
| 3 |
+
باكند بسيط ومنظّم مبني بـ **FastAPI** يستدعي نموذج **LLM/Chatbot** مستضاف على **Hugging Face** (عبر Inference API أو Inference Endpoint أو أي مزود متوافق) ويعرضه كـ REST API جاهز للاستخدام من أي تطبيق أو Agent.
|
| 4 |
+
|
| 5 |
+
## البنية
|
| 6 |
+
|
| 7 |
+
```
|
| 8 |
+
hf-chat-backend/
|
| 9 |
+
├── app/
|
| 10 |
+
│ ├── main.py # نقطة الدخول + إعداد FastAPI
|
| 11 |
+
│ ├── config.py # الإعدادات (تُقرأ من .env)
|
| 12 |
+
│ ├── schemas.py # Pydantic Schemas
|
| 13 |
+
│ ├── dependencies.py # Dependency Injection + حماية بمفتاح API
|
| 14 |
+
│ ├── logging_config.py # Logging مهيكل بصيغة JSON
|
| 15 |
+
│ ├── services/
|
| 16 |
+
│ │ └── hf_client.py # طبقة الاتصال بـ Hugging Face
|
| 17 |
+
│ └── routers/
|
| 18 |
+
│ ├── health.py # GET /health
|
| 19 |
+
│ └── chat.py # POST /chat (رد كامل أو بث SSE)
|
| 20 |
+
├── tests/ # اختبارات pytest
|
| 21 |
+
├── requirements.txt
|
| 22 |
+
├── requirements-dev.txt
|
| 23 |
+
├── Dockerfile
|
| 24 |
+
├── docker-compose.yml
|
| 25 |
+
├── .env.example
|
| 26 |
+
└── pyproject.toml
|
| 27 |
+
```
|
| 28 |
+
|
| 29 |
+
## 1) الإعداد المحلي
|
| 30 |
+
|
| 31 |
+
```bash
|
| 32 |
+
cd hf-chat-backend
|
| 33 |
+
python -m venv .venv && source .venv/bin/activate
|
| 34 |
+
pip install -r requirements-dev.txt
|
| 35 |
+
cp .env.example .env
|
| 36 |
+
# عدّل .env وضع HF_API_TOKEN و HF_MODEL_ID الخاصين بك
|
| 37 |
+
```
|
| 38 |
+
|
| 39 |
+
### متغيرات البيئة الأساسية (.env)
|
| 40 |
+
|
| 41 |
+
| المتغير | الوصف |
|
| 42 |
+
|---|---|
|
| 43 |
+
| `HF_API_TOKEN` | التوكن من https://huggingface.co/settings/tokens |
|
| 44 |
+
| `HF_MODEL_ID` | معرّف النموذج، مثال: `meta-llama/Llama-3.1-8B-Instruct` |
|
| 45 |
+
| `HF_PROVIDER` | اتركه فارغاً لاستخدام hf-inference الافتراضي، أو حدد مزود مثل `together`، `fireworks-ai` |
|
| 46 |
+
| `BACKEND_API_KEY` | اختياري: لحماية الباكند نفسه بمفتاح `X-API-Key` |
|
| 47 |
+
|
| 48 |
+
### التشغيل
|
| 49 |
+
|
| 50 |
+
```bash
|
| 51 |
+
uvicorn app.main:app --reload
|
| 52 |
+
```
|
| 53 |
+
|
| 54 |
+
ثم افتح: `http://localhost:8000/docs` لتوثيق Swagger التفاعلي.
|
| 55 |
+
|
| 56 |
+
## 2) الاختبارات والجودة
|
| 57 |
+
|
| 58 |
+
```bash
|
| 59 |
+
pytest -v
|
| 60 |
+
ruff check app tests
|
| 61 |
+
mypy app
|
| 62 |
+
```
|
| 63 |
+
|
| 64 |
+
## 3) الاستخدام عبر Docker
|
| 65 |
+
|
| 66 |
+
```bash
|
| 67 |
+
docker compose up --build
|
| 68 |
+
```
|
| 69 |
+
|
| 70 |
+
## 4) استدعاء الـ API
|
| 71 |
+
|
| 72 |
+
### رد كامل (بدون بث)
|
| 73 |
+
|
| 74 |
+
```bash
|
| 75 |
+
curl -X POST http://localhost:8000/chat \
|
| 76 |
+
-H "Content-Type: application/json" \
|
| 77 |
+
-d '{
|
| 78 |
+
"messages": [
|
| 79 |
+
{"role": "system", "content": "أنت مساعد ذكي ومفيد."},
|
| 80 |
+
{"role": "user", "content": "اشرح لي ما هو FastAPI باختصار"}
|
| 81 |
+
]
|
| 82 |
+
}'
|
| 83 |
+
```
|
| 84 |
+
|
| 85 |
+
### رد ببث لحظي (Server-Sent Events)
|
| 86 |
+
|
| 87 |
+
```bash
|
| 88 |
+
curl -N -X POST http://localhost:8000/chat \
|
| 89 |
+
-H "Content-Type: application/json" \
|
| 90 |
+
-d '{
|
| 91 |
+
"messages": [{"role": "user", "content": "اكتب قصة قصيرة"}],
|
| 92 |
+
"stream": true
|
| 93 |
+
}'
|
| 94 |
+
```
|
| 95 |
+
|
| 96 |
+
### مع حماية بمفتاح API
|
| 97 |
+
|
| 98 |
+
إذا فعّلت `BACKEND_API_KEY` في `.env`، أضف الهيدر:
|
| 99 |
+
|
| 100 |
+
```bash
|
| 101 |
+
-H "X-API-Key: your-secret-key"
|
| 102 |
+
```
|
| 103 |
+
|
| 104 |
+
## 5) النشر على Hugging Face
|
| 105 |
+
|
| 106 |
+
عندك خياران رئيسيان حسب مكان استضافة **النموذج نفسه**:
|
| 107 |
+
|
| 108 |
+
### الخيار أ: النموذج مستضاف بالفعل على HF (Inference API / Endpoint)
|
| 109 |
+
هذا الباكند لا يحتاج لاستضافة النموذج — فقط يستدعيه عبر الشبكة. يمكنك نشر هذا الباكند في أي مكان (Render, Railway, VPS, Docker, Fly.io...) طالما ضبطت `HF_API_TOKEN` و `HF_MODEL_ID`.
|
| 110 |
+
|
| 111 |
+
### الخيار ب: نشر الباكند نفسه كـ Hugging Face Space
|
| 112 |
+
1. أنشئ Space جديد من نوع **Docker** على https://huggingface.co/new-space
|
| 113 |
+
2. ارفع محتويات هذا المجلد كاملة (بما فيها `Dockerfile`)
|
| 114 |
+
3. من إعدادات الـ Space أضف Secret باسم `HF_API_TOKEN` وقيمته توكنك
|
| 115 |
+
4. عدّل `HF_MODEL_ID` حسب النموذج المطلوب (Variable وليس Secret)
|
| 116 |
+
5. Hugging Face Spaces يستخدم المنفذ `7860` افتراضياً — عدّل `Dockerfile` وضع:
|
| 117 |
+
```dockerfile
|
| 118 |
+
EXPOSE 7860
|
| 119 |
+
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]
|
| 120 |
+
```
|
| 121 |
+
|
| 122 |
+
## 6) ملاحظات إنتاجية
|
| 123 |
+
|
| 124 |
+
- **الأمان**: فعّل `BACKEND_API_KEY` دائماً في الإنتاج، ولا تضع `HF_API_TOKEN` في الكود مطلقاً — استخدم Secrets فقط.
|
| 125 |
+
- **Rate Limiting**: هذا المشروع بسيط ومخصص للانطلاق السريع؛ إذا احتجت Rate Limiting متقدم أو RBAC كامل أو Plugins متعددة (PDF, Media, Network...) أخبرني وأبني لك نسخة موسّعة على مراحل.
|
| 126 |
+
- **CORS**: بشكل افتراضي مفتوح للجميع (`*`) — قيّده بدومينات تطبيقك الفعلية في الإنتاج عبر `CORS_ALLOW_ORIGINS`.
|
docker-compose.yml
ADDED
|
@@ -0,0 +1,8 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
services:
|
| 2 |
+
api:
|
| 3 |
+
build: .
|
| 4 |
+
ports:
|
| 5 |
+
- "8000:8000"
|
| 6 |
+
env_file:
|
| 7 |
+
- .env
|
| 8 |
+
restart: unless-stopped
|
pyproject.toml
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
[tool.ruff]
|
| 2 |
+
line-length = 100
|
| 3 |
+
target-version = "py312"
|
| 4 |
+
|
| 5 |
+
[tool.ruff.lint]
|
| 6 |
+
select = ["E", "F", "I", "UP", "B"]
|
| 7 |
+
|
| 8 |
+
[tool.mypy]
|
| 9 |
+
python_version = "3.12"
|
| 10 |
+
ignore_missing_imports = true
|
| 11 |
+
disallow_untyped_defs = false
|
| 12 |
+
|
| 13 |
+
[tool.pytest.ini_options]
|
| 14 |
+
asyncio_mode = "auto"
|
| 15 |
+
testpaths = ["tests"]
|
requirements-dev.txt
ADDED
|
@@ -0,0 +1,5 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
-r requirements.txt
|
| 2 |
+
pytest==8.3.4
|
| 3 |
+
pytest-asyncio==0.25.2
|
| 4 |
+
ruff==0.9.1
|
| 5 |
+
mypy==1.14.1
|
requirements.txt
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
fastapi==0.115.6
|
| 2 |
+
uvicorn[standard]==0.34.0
|
| 3 |
+
pydantic==2.10.4
|
| 4 |
+
pydantic-settings==2.7.1
|
| 5 |
+
huggingface_hub==1.21.0
|
| 6 |
+
python-multipart==0.0.20
|
| 7 |
+
httpx==0.28.1
|