bh-ab commited on
Commit
ec0d2e2
·
verified ·
1 Parent(s): 0af4efd

Upload 7 files

Browse files
Files changed (7) hide show
  1. .env.example +25 -0
  2. Dockerfile +19 -0
  3. README.md +126 -10
  4. docker-compose.yml +8 -0
  5. pyproject.toml +15 -0
  6. requirements-dev.txt +5 -0
  7. 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
- title: Tools
3
- emoji: 🌖
4
- colorFrom: pink
5
- colorTo: pink
6
- sdk: docker
7
- pinned: false
8
- ---
9
-
10
- Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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