من دفتر إلى خدمة

طريقان إلى نفس الفكرة

قبل أن تبدأ

الفكرة الجوهرية

الخدمة نقطة يرسل لها أي برنامج طلبًا ويأخذ ردًّا. تبني هنا تحميل النموذج مرة واحدة، ثم معالج الطلبات، ثم رموز الحالة، ثم فحص الجاهزية مع FastAPI.

1حمّل النموذج مرة واحدة

تحميل النموذج يأخذ ثوانيَ إلى دقائق ويستهلك ذاكرة كثيرة. لو حدث مع كل طلب لصارت الخدمة غير صالحة للاستخدام.

انظر إلى الرسم: أربعة طلبات. التحميل داخل الطلب يعني أربع مرات، والتحميل عند البدء يعني مرة واحدة يتشاركها الجميع.

2معالج الطلب: تحقّق ثم توقّع

النقطة عنوان مثل POST /predict يأخذ JSON ويردّ JSON بشكل ثابت وموثّق. وقبل أن يصل أي شيء إلى النموذج نتحقّق من النوع والطول والحقول المطلوبة.

قبل FastAPI، لنرَ ما يفعله أي إطار: يستقبل نصًّا، ويتحقّق منه، ويستدعي النموذج المحمّل مسبقًا، ويعيد رمز حالة ورد JSON.

import json

class SentimentModel:
    loads = 0
    def __init__(self):
        SentimentModel.loads += 1          # in real life: seconds of reading weights from disk
        self.version = "sentiment-2026-05-01"
    def predict(self, text):
        return "positive" if any(w in text for w in ["ممتاز", "شكرا", "رائع"]) else "negative"

MODEL = SentimentModel()                   # loaded once, when the service starts

def handle(body):
    try:
        data = json.loads(body)
    except json.JSONDecodeError:
        return 400, {"error": "body must be JSON"}
    text = data.get("text")
    if not isinstance(text, str) or not text.strip():
        return 422, {"error": "field 'text' must be a non-empty string"}
    if len(text) > 2000:
        return 422, {"error": "text is longer than 2000 characters"}
    return 200, {"label": MODEL.predict(text), "model_version": MODEL.version}

def health():
    return 200, {"status": "ok", "model_version": MODEL.version}

for body in ['{"text": "خدمة ممتاز وشكرا"}', '{"text": ""}', 'not json', '{"text": "تأخر الطلب"}']:
    print(handle(body))
print(health())
print("model loads after 4 requests:", SentimentModel.loads)

أربعة طلبات والنموذج حُمّل مرة واحدة. والرموز تقول للعميل ما حدث: 200 نجاح، و400 الطلب نفسه معطوب، و422 الطلب سليم الشكل لكن محتواه غير مقبول. وكل رد ناجح يحمل نسخة النموذج، فحين يشتكي أحد من إجابة تعرف أي نموذج أعطاها.

3رموز الحالة

رمز الحالة يقول للعميل ما حدث قبل أن يقرأ الرد. انظر إلى الرسم: ثلاثة رموز تكفي لمعظم الحالات.

400 يعني أن الطلب نفسه معطوب، مثل JSON غير صالح. و422 يعني أن الطلب سليم الشكل لكن محتواه غير مقبول، مثل نص فارغ أو طويل جدًا.

4FastAPI وفحص الجاهزية

الخدمة حيّة بمجرد أن يعمل الخادم، لكنها ليست جاهزة حتى ينتهي تحميل النموذج. لذلك نفصل فحصين: /health/live و /health/ready.

انظر إلى الرسم: منصّة النشر لا ترسل الطلبات إلا بعد أن يردّ فحص الجاهزية بـ 200.

هذا ما ستكتبه فعليًّا. يحتاج pip install fastapi uvicorn، فهو للقراءة هنا.

from contextlib import asynccontextmanager
from fastapi import FastAPI
from pydantic import BaseModel, Field

state = {}

@asynccontextmanager
async def lifespan(app):
    state["model"] = load_model("/models/sentiment-v3")   # once, before the first request
    yield
    state.clear()

app = FastAPI(lifespan=lifespan)

class PredictIn(BaseModel):
    text: str = Field(min_length=1, max_length=2000)

class PredictOut(BaseModel):
    label: str
    model_version: str

@app.post("/predict", response_model=PredictOut)
def predict(body: PredictIn):
    model = state["model"]
    return PredictOut(label=model.predict(body.text), model_version=model.version)

@app.get("/health/ready")
def ready():
    return {"status": "ok", "model_version": state["model"].version}

lifespan يحمّل النموذج قبل أول طلب، وPydantic يتحقّق من المدخلات ويعيد 422 بتفاصيل الخطأ تلقائيًّا، وتوثيق تفاعلي يظهر على /docs دون سطر إضافي. شغّله بـuvicorn app:app وجرّبه من المتصفح.

كيف يعمل، خطوة بخطوة: كيف تخدم الخدمة طلبًا

أعمق قليلًا

للنماذج اللغوية الكبيرة لا تكتب الخدمة من الصفر. خوادم مخصّصة مثل vLLM تتولّى التحميل، والتجميع الذكي للطلبات، وإدارة ذاكرة السياق، وتعرض واجهة متوافقة مع OpenAI مباشرة. FastAPI مناسب لنماذجك الصغيرة والمتوسطة ولطبقة منطق العمل حول نموذج لغوي يعمل في خادم مخصّص.

مثال محلول

الخطأ الأول في كل خدمة نموذج تقريبًا: تحميل النموذج داخل دالة الطلب. تحميل نموذج يستغرق ثواني إلى دقائق، فإن حدث مع كل طلب صارت الخدمة غير قابلة للاستخدام. الصحيح أن يُحمَّل مرة عند بدء الخدمة ويبقى في الذاكرة.

جرّب بلا كود

خرافة مقابل حقيقة

جرّب بنفسك

بطاقات مراجعة سريعة

تحقق من فهمك