Python في منظومة AI Software Engineering
في المسار ده Python مش بديل عن C# ولا مطلوب منك تبني كل الـ backend بيه. اعتبره لغة البيانات والنماذج والتجارب، بينما يظل ASP.NET Core مسؤولًا عن business APIs، الهوية، المعاملات، التكامل مع الأنظمة، والمنتج النهائي. Python يلمع في NumPy و Pandas و scikit-learn و PyTorch ومكتبات parsing والـ AI.
اختيار اللغة حسب مسؤولية المكوّن يقلل coupling: خدمة Python صغيرة قد تنفذ inference أو ingestion، و .NET يستهلكها عبر HTTP/gRPC أو queue. لا تبدأ بخدمتين لمجرد اختلاف اللغة؛ لو الوظيفة مجرد استدعاء LLM، قد يكون .NET وحده أبسط.
هل لازم تنقل الـ backend كله إلى Python عشان تدخل AI؟
Python جنب .NET في نظام AI
Syntax والأنواع وهياكل البيانات
Python ديناميكية الأنواع، لكن ده لا يعني إن الأنواع غير مهمة. المتغير اسم يشير إلى object، والـ list قابلة للتعديل، والـ tuple مناسبة لتجميع ثابت، والـ dict للربط key/value، والـ set للعضوية الفريدة. افهم mutability لأن مشاركة list بين أجزاء الكود قد تنتج side effects.
الـ indentation جزء من syntax. استخدم f-strings للتنسيق، و comprehensions للتحويلات البسيطة، لكن لا تضغط منطقًا معقدًا في سطر واحد. في البيانات، راقب الفرق بين None و 0 و string فارغ و NaN؛ كل واحدة لها semantics مختلفة.
users = ["Mona", "Ali", "Mona"]
unique = set(users)
counts = {name: users.count(name) for name in unique}
print(sorted(counts.items()))
# [('Ali', 1), ('Mona', 2)]Functions و Scope و Type Hints
الدالة الجيدة لها مسؤولية واحدة ومدخلات ومخرجات واضحتان. افهم positional/keyword arguments و default values و *args/**kwargs، وتجنب mutable default arguments مثل items=[] لأنها تُنشأ مرة واحدة عند تعريف الدالة. الـ type hints لا تفرض الأنواع وقت التشغيل تلقائيًا؛ هي عقد يساعد IDE و static checkers ويجعل interfaces أوضح.
استخدم dataclasses أو Pydantic عندما تحتاج models، وخلّي parsing والتحقق من البيانات عند حدود النظام. لا تخلط قراءة ملف، تنظيفه، وحفظه داخل دالة ضخمة؛ افصلها لتختبر كل خطوة.
from typing import Iterable
def normalize_names(values: Iterable[str]) -> list[str]:
return [value.strip().title() for value in values if value.strip()]
print(normalize_names([" baraa ", "", "ali eid "]))
# ['Baraa', 'Ali Eid']Modules و Virtual Environments و Packaging
كل مشروع لازم يكون له virtual environment مستقل حتى لا تتداخل إصدارات المكتبات. ثبّت dependencies بإصدارات مقيدة ومراجعة، واحتفظ بملف dependency lock أو آلية reproducible install. pip مدير تثبيت، و pyproject.toml نقطة إعداد حديثة للأدوات والحزم. لا تضع secrets في ملفات المشروع ولا ترفع .venv أو ملفات البيانات الضخمة إلى Git.
هيكل بسيط: src/app/ للكود، tests/ للاختبارات، pyproject.toml للإعداد، و .env.example لأسماء الإعدادات دون قيم سرية. فرّق بين package للتوزيع وبين script داخلي. استخدم logging بدل print في الخدمات.
python -m venv .venv
# Windows PowerShell:
.venv\Scripts\Activate.ps1
# macOS/Linux:
# source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install fastapi uvicorn pydantic pytest
python -m pip freeze > requirements-lock.txtExceptions و Files و JSON
تعامل مع الملفات باستخدام with حتى تُغلق الموارد تلقائيًا. حدد encoding صراحةً، وتعامل مع FileNotFoundError و PermissionError و JSON decode errors. لا تستخدم except Exception: pass؛ سجّل السياق وأعد رمي exception أو حوّلها إلى domain error واضح. JSON مناسب للتبادل بين .NET و Python، لكن راقب decimal precision والتواريخ و nullability.
لا تثق في اسم الملف أو حجمه أو محتواه القادم من المستخدم. ضع limits، افحص MIME/format، امنع path traversal، وخزّن uploads في object storage أو مسار معزول.
import json
from pathlib import Path
path = Path("data/input.json")
try:
payload = json.loads(path.read_text(encoding="utf-8"))
except FileNotFoundError as exc:
raise RuntimeError(f"Required input is missing: {path}") from exc
except json.JSONDecodeError as exc:
raise ValueError(f"Invalid JSON at line {exc.lineno}") from exc
print(payload.get("records", []))Iterators و Generators و Comprehensions
الـ list materializes كل العناصر في الذاكرة. الـ iterator ينتج العناصر عند الطلب، والـ generator باستخدام yield يسمح بمعالجة stream أو ملف كبير دون تحميله كاملًا. ده مهم في ingestion: اقرأ batches، طبّق transform، ثم اكتب output، مع backpressure وحدود للذاكرة.
لا تستخدم generator لمجرد أنه يبدو متقدمًا؛ لو البيانات صغيرة والـ reuse مطلوب فالـ list أوضح. قِس الذاكرة والزمن بدل التخمين.
def read_nonempty_lines(path: str):
with open(path, encoding="utf-8") as stream:
for line in stream:
value = line.strip()
if value:
yield value
for row in read_nonempty_lines("data.txt"):
process(row) # process is your validated transformHTTP Clients و asyncio
استخدم HTTP client يدعم connection pooling و timeouts، ولا تنشئ client جديدًا لكل request. في async Python، await يسمح بتداخل I/O-bound work لكنه لا يجعل CPU-bound work أسرع تلقائيًا. لا تخلط sync blocking calls داخل event loop. حدد connect/read/overall timeout، تعامل مع status codes، وطبّق retry فقط على الأخطاء المؤقتة والعمليات الآمنة أو idempotent.
في التكامل مع .NET، اجعل endpoint contract versioned، واستخدم correlation ID، و health/readiness، و structured errors. لا تُرجع stack trace للعميل.
import httpx
import asyncio
async def fetch_profile(client: httpx.AsyncClient, user_id: int):
response = await client.get(f"https://api.example.test/users/{user_id}")
response.raise_for_status()
return response.json()
async def main():
timeout = httpx.Timeout(5.0, connect=2.0)
async with httpx.AsyncClient(timeout=timeout) as client:
profile = await fetch_profile(client, 42)
print(profile)
asyncio.run(main())Pydantic و FastAPI و pytest
FastAPI مناسب لعمل thin inference service، و Pydantic للتحقق من request/response schemas. validation لا يعني business authorization؛ افحص هوية المستهلك وصلاحياته وحدود الاستخدام. اختبر happy path و invalid payload و timeout و model unavailable و large input. اجعل model loading عند startup أو lifespan بدل تحميله في كل request.
في الإنتاج أضف authentication بين الخدمات، request size limit، rate limit، metrics، structured logs، graceful shutdown، container non-root، وإدارة secrets. الـ Notebook للاستكشاف وليس شكلًا مناسبًا للنشر كما هو.
from fastapi import FastAPI
from pydantic import BaseModel, Field
app = FastAPI(title="Scoring Service")
class ScoreRequest(BaseModel):
age: int = Field(ge=18, le=120)
annual_income: float = Field(gt=0)
class ScoreResponse(BaseModel):
score: float
model_version: str
@app.post("/score", response_model=ScoreResponse)
def score(request: ScoreRequest):
value = min(request.annual_income / 100_000, 1.0)
return ScoreResponse(score=value, model_version="baseline-1")
# Run: uvicorn app:app --host 0.0.0.0 --port 8000هل type hints تمنع وصول string مكان int وقت التشغيل؟
مشروع Python صغير منظم
حوّل script التجريبي إلى package صغيرة: app/ للكود، tests/ للاختبارات، pyproject.toml للأدوات، و README يشرح setup/run/test. افصل pure functions عن I/O؛ pure function أسهل في الاختبار لأنها لا تقرأ environment أو network. عرّف configuration object وتحقق منه مرة عند startup. استخدم dependency injection البسيط بتمرير client أو repository بدل global state.
أضف static checks مثل Ruff و mypy أو pyright حسب احتياج المشروع، و pytest مع fixtures. اختبر invalid input و empty file و unexpected API status و timeout. لا تضع network calls في import-time؛ استيراد module يجب ألا ينفذ عملية مكلفة أو يغير state.
# src/cleaner/core.py
from collections.abc import Iterable
def clean_rows(rows: Iterable[dict]) -> list[dict]:
cleaned = []
for row in rows:
customer_id = str(row.get("customer_id", "")).strip()
if not customer_id:
continue
cleaned.append({"customer_id": customer_id,
"amount": float(row.get("amount", 0) or 0)})
return cleaned
# tests/test_core.py
def test_clean_rows_skips_missing_customer():
assert clean_rows([{"amount": 5}, {"customer_id": " C1 ", "amount": 7}]) == [
{"customer_id": "C1", "amount": 7.0}]لماذا نتجنب network call أثناء import؟
Python و .NET: حدود الخدمة
عندما تنقل وظيفة إلى Python service، لا تشارك implementation details بين اللغتين؛ شارك contract. عرّف request/response JSON schema، قواعد versioning، error codes، idempotency، timeout، authentication، correlation ID، و compatibility policy. في .NET استخدم typed HttpClient و DTOs، وفي Python استخدم Pydantic models. اجعل timestamps بصيغة ISO-8601 UTC، والأرقام المالية decimal strings أو minor units بدل float binary.
لا ترسل ملفات ضخمة داخل JSON؛ استخدم object storage مع short-lived signed URL أو stream endpoint مصممًا لذلك. لا تجعل Python service يعتمد على قاعدة بيانات .NET مباشرة دون ownership agreement. الأفضل أن يتواصل عبر API أو events مع فصل واضح لمسؤولية البيانات.
// .NET typed client boundary
public sealed record ScoreRequest(int Age, decimal AnnualIncome);
public sealed record ScoreResponse(decimal Score, string ModelVersion);
public sealed class ScoringClient(HttpClient http)
{
public async Task<ScoreResponse> ScoreAsync(
ScoreRequest request, CancellationToken ct) =>
await http.PostAsJsonAsync("/score", request, ct)
.ContinueWith(async task =>
{
using var response = await task;
response.EnsureSuccessStatusCode();
return (await response.Content.ReadFromJsonAsync<ScoreResponse>(cancellationToken: ct))!;
}).Unwrap();
}ما الذي يجب أن يكون مشتركًا بين .NET و Python؟
Testing Async و HTTP Boundaries
اختبر الـ HTTP client دون الاعتماد على internet: استخدم mock transport أو dependency injection لحقن client fake. غطِّ status 200 مع JSON صالح، 204 بلا body، 400 validation error، 429 مع Retry-After، 500، timeout، DNS/connect failure، cancellation، و response غير صالح. لا تجعل retry يعيد كل الأخطاء؛ 400 غالبًا terminal، و429/503 قد تكون transient وفق policy. استخدم bounded retries مع jitter، وحدد idempotency semantics قبل إعادة POST.
في asyncio، cancellation جزء من lifecycle. لا تبتلع CancelledError وتكمل عملًا بعد إلغاء الطلب. أغلق clients والـ streams، وحدد concurrency semaphore حتى لا تطلق آلاف الاتصالات مرة واحدة. إذا كان العمل CPU-bound ففكر في process pool أو worker منفصل بدل حبس event loop.
Python Security و Dependency Hygiene
مكتبات Python تأتي من package ecosystem؛ ثبّت dependencies من مصادر موثوقة، راجع الإصدارات والثغرات، واستخدم lock file. لا تنفذ eval أو exec على user input، ولا تستخدم pickle من مصدر غير موثوق. افحص الملفات قبل parsing، ضع maximum size/page count/time، واعزل parser للملفات المعقدة. لا تبنِ file path مباشرة من filename يرسله المستخدم.
في containers شغّل non-root، read-only filesystem قدر الإمكان، secrets عبر environment/secret manager، و network egress محدود. أضف SBOM/scan في CI حسب مستوى المنتج. Python service تظل خدمة إنتاجية وتحتاج نفس threat model لأي API.
Python Object Model: Names, Objects, Identity & Mutability
أهم نقلة ذهنية في Python إن المتغير مش صندوق بيحتفظ بالقيمة بالطريقة اللي ممكن تتخيلها من لغات أخرى؛ الاسم name بيرتبط بكائن object. الكائن له identity و type و value. الـ assignment غالبًا بيربط اسمًا إضافيًا بنفس الكائن، مش بيعمل نسخة منه. ده يفسر ليه تعديل list من خلال alias ممكن يظهر في مكان تاني غير متوقع.
فرّق بين == و is: الأول يقارن equality حسب تعريف النوع، والثاني يقارن identity: هل الاسمان يشيران إلى نفس الكائن؟ استخدم is None لفحص None، لكن لا تستخدم is لمقارنة strings أو integers اعتمادًا على interning implementation details. الـ immutability معناها إن حالة الكائن لا تتغير بعد إنشائه؛ مش معناها إن الاسم لا يمكن إعادة ربطه بكائن آخر.
الـ shallow copy ينسخ الحاوية الخارجية فقط، أما العناصر المتداخلة فتبقى مراجع مشتركة. الـ deep copy يحاول نسخ الرسم البياني للكائنات، لكنه قد يكون مكلفًا أو غير مناسب لكائنات مرتبطة بموارد خارجية. في data pipelines اسأل دائمًا: هل الدالة تملك البيانات؟ هل تعدلها in-place؟ وهل المستهلك التالي يتوقع نسخة مستقلة؟ وثّق ذلك في contract الدالة.
original = {"features": [1, 2]}
alias = original
shallow = original.copy()
alias["features"].append(3)
shallow["new_key"] = True
print(original is alias) # True
print(original["features"]) # [1, 2, 3]
print("new_key" in original) # False
print(shallow["features"] is original["features"]) # Trueهل shallow copy يضمن استقلال كل العناصر المتداخلة؟
Python Collections & Complexity
اختيار الـ data structure قرار أداء وصحة، مش مجرد ذوق. الـ list تدعم indexing في زمن ثابت تقريبًا، لكن البحث عن عنصر بالقيمة خطي. الإضافة في نهاية list amortized O(1)، بينما الإدراج في المنتصف يتطلب تحريك عناصر. الـ dict والـ set يعتمدان على hash table؛ البحث والإضافة متوسطهما O(1)، لكن worst case قد يصل إلى O(n)، ويتطلب المفتاح hashable وثابتًا من منظور hash/equality أثناء وجوده في الجدول.
الـ tuple immutable كحاوية، لكنها قد تحتوي كائنات mutable. الـ deque مناسبة للطوابير والإضافة/الحذف من الطرفين. الـ heapq يدعم priority queues بعمليات push/pop O(log n). الـ Counter و defaultdict يقللان boilerplate في counting/grouping. لا تحول كل شيء إلى set لمجرد السرعة؛ افهم فقدان الترتيب الدلالي أو التكرارات، وتأكد إن equality/hash semantics مناسبة.
في RAG ingestion مثلًا، استخدم set لتتبع document IDs التي تمت معالجتها، و dict للفهرسة من ID إلى metadata، و deque لطابور محدود، و heap لأعلى نتائج مرشحة. لكن حجم البيانات لو تجاوز الذاكرة، انقل الفهرسة إلى قاعدة بيانات أو external store بدل بناء Python dict ضخم داخل web worker.
import heapq
scores = [("doc-A", 0.81), ("doc-B", 0.94), ("doc-C", 0.77), ("doc-D", 0.91)]
top_two = heapq.nlargest(2, scores, key=lambda item: item[1])
print(top_two)
# [('doc-B', 0.94), ('doc-D', 0.91)]Functions, Closures, Decorators & Context Managers
الدوال في Python objects من الدرجة الأولى: يمكن تمريرها كقيم، إرجاعها من دوال، وتخزينها في structures. الـ closure يحتفظ ببيئة lexical variables من النطاق الخارجي. ده أساس decorators وبعض أنماط dependency injection. الـ decorator يلف function لتضيف behavior مثل timing أو logging أو authorization، لكن حافظ على metadata باستخدام functools.wraps، ولا تجعل decorator يخفي network calls أو retries مؤثرة في semantics.
الـ context manager يحدد setup/teardown حول resource: file، database transaction، lock، أو temporary directory. بروتوكوله الأساسي __enter__/__exit__، ويمكن بناؤه باستخدام contextlib.contextmanager. استخدامه يقلل تسرب الموارد ويجعل lifecycle واضحًا. في async services ستقابل async with للموارد التي تحتاج asynchronous cleanup.
افصل pure functions عن impure functions. الـ pure function لا تعتمد على global mutable state ولا تحدث side effects، ونفس المدخلات تعطي نفس المخرجات. ده يجعلها سهلة الاختبار والـ memoization. أما قراءة الوقت أو البيئة أو الشبكة أو الملفات فاجعلها عند boundaries ومرر النتائج إلى منطق التحويل.
from functools import wraps
from time import perf_counter
def timed(fn):
@wraps(fn)
def wrapper(*args, **kwargs):
started = perf_counter()
try:
return fn(*args, **kwargs)
finally:
elapsed = perf_counter() - started
print(f"{fn.__name__}: {elapsed:.6f}s")
return wrapper
@timed
def normalize(values):
return [value.strip().lower() for value in values]
print(normalize([" AI ", " Python "]))لماذا نستخدم functools.wraps داخل decorator؟
Exceptions, Error Taxonomy & Resource Safety
الاستثناءات ليست بديلًا عن كل branching، لكنها مناسبة للإبلاغ عن فشل يمنع العملية من الاكتمال. صنّف الأخطاء إلى: input/domain errors، dependency/transient errors، configuration errors، programming bugs، cancellation. لا تحول كل الأخطاء إلى ValueError واحد ولا تلتقط Exception ثم ترجع قيمة افتراضية؛ هذا يخفي فساد البيانات ويجعل النظام يبدو ناجحًا وهو غير صحيح.
استخدم exception chaining بـ raise DomainError(...) from exc للحفاظ على السبب. عند حدود HTTP حوّل الأخطاء إلى stable error codes ورسائل آمنة، وسجّل stack trace داخليًا مع correlation ID. لا تسجل access tokens أو prompts التي تحتوي بيانات شخصية أو ملفات المستخدم كاملة. اجعل retry policy في طبقة orchestration لا داخل كل helper، لتجنب تضاعف retries عبر الطبقات.
Resource safety تشمل files، sockets، database connections، GPU memory، temporary files. استخدم context managers، وضمن cleanup في success و failure و cancellation. لو عندك batch pipeline، حدد سياسة للـ partial failure: هل تفشل الدفعة كلها؟ هل تعزل record الفاسد في quarantine؟ هل تسمح بإعادة التشغيل دون تكرار الآثار؟
import json
from pathlib import Path
class InvalidDatasetError(Exception):
pass
def load_dataset(path: Path) -> dict:
try:
return json.loads(path.read_text(encoding="utf-8"))
except FileNotFoundError as exc:
raise InvalidDatasetError("dataset file is missing") from exc
except json.JSONDecodeError as exc:
raise InvalidDatasetError(
f"dataset JSON is malformed at line {exc.lineno}"
) from excTyping at Scale: Protocols, Generics & Static Analysis
Type hints لا تحول Python إلى statically typed language، ولا تمنع runtime values غير صحيحة وحدها. قيمتها الحقيقية إنها توضح contracts وتساعد IDE و static analyzers على اكتشاف أخطاء قبل التشغيل. استخدم Protocol للتعبير عن behavior المطلوب دون فرض inheritance، و TypeVar/Generic لبناء abstractions قابلة لإعادة الاستخدام. استخدم TypedDict عندما تتعامل مع dict له schema معروف، و dataclass للبيانات الداخلية، و Pydantic عند حدود بيانات غير موثوقة تحتاج parsing/validation.
لا تضع Any في كل مكان؛ هو يوقف كثيرًا من فحوصات النوع ويخلق مناطق عمياء. ابدأ بـ strictness تدريجيًا، وحدد module boundaries، وشغّل type checker في CI. افصل بين validation (هل payload مطابق للشكل؟) و domain invariants (هل العملية مسموحة في حالة النظام؟) و authorization (هل هذا المستخدم مخول؟).
from typing import Protocol
class Embedder(Protocol):
def embed(self, texts: list[str]) -> list[list[float]]: ...
class IndexWriter(Protocol):
def upsert(self, ids: list[str], vectors: list[list[float]]) -> None: ...
def index_batch(texts: list[str], ids: list[str],
embedder: Embedder, writer: IndexWriter) -> None:
if len(texts) != len(ids):
raise ValueError("texts and ids must have equal length")
vectors = embedder.embed(texts)
if len(vectors) != len(ids):
raise RuntimeError("embedding provider returned an unexpected count")
writer.upsert(ids, vectors)Concurrency Model: GIL, Threads, Processes & Async
لازم تفرق بين concurrency (تداخل تقدم عدة مهام) و parallelism (تنفيذ فعلي في نفس الوقت). الـ threading غالبًا مفيد لـ I/O-bound tasks مثل انتظار HTTP أو disk، لكنه لا يعني بالضرورة تنفيذ Python bytecode بالتوازي على عدة CPU cores في builds التقليدية التي تستخدم GIL. الـ multiprocessing يشغل processes مستقلة ويمكنه استغلال cores، لكنه يضيف serialization و IPC و memory overhead. أما asyncio فيستخدم event loop لتنسيق عدد كبير من عمليات I/O عبر cooperative scheduling؛ المهمة تتنازل عند await.
الـ GIL ليس قفلًا عامًا يحمي business data من race conditions، ولا ينبغي الاعتماد عليه كضمان لصحة shared state. استخدم locks/queues أو ownership isolation حسب التصميم. في عمليات NumPy/PyTorch، بعض الحسابات تنفذ داخل native kernels وقد تختلف خصائص التوازي عن Python bytecode؛ قِس سلوك المكتبة والإصدار الفعلي بدل التعميم.
اختر الآلية من طبيعة workload: API fan-out إلى عدة خدمات = async I/O غالبًا؛ ضغط صور/تحويل ملفات CPU-heavy = process workers أو queue workers؛ GPU inference = model server يضبط batching والذاكرة؛ ingestion طويل = durable background job بدل إبقاء HTTP request مفتوحًا. ضع concurrency limit و queue capacity و timeout و cancellation، وإلا يتحول النظام إلى overload amplifier.
import asyncio
import httpx
async def fetch_one(client: httpx.AsyncClient, semaphore: asyncio.Semaphore, url: str):
async with semaphore:
response = await client.get(url)
response.raise_for_status()
return response.json()
async def fetch_many(urls: list[str]):
limit = asyncio.Semaphore(10)
timeout = httpx.Timeout(8.0, connect=2.0)
async with httpx.AsyncClient(timeout=timeout) as client:
tasks = [fetch_one(client, limit, url) for url in urls]
return await asyncio.gather(*tasks)Performance Engineering & Profiling
لا تستنتج الأداء من شكل الكود. ابدأ بتعريف workload واقعي: حجم dataset، توزيع أحجام records، concurrency، warm/cold cache، وهدف latency مثل p50/p95/p99. قِس wall-clock time والـ CPU time والذاكرة وعدد allocations أو حجم البيانات المنقولة. المتوسط وحده قد يخفي tail latency؛ وقياس notebook مرة واحدة لا يمثل production.
استخدم timeit لقياس microbenchmarks صغيرة، و cProfile/pstats لمعرفة أين يستهلك البرنامج CPU، و tracemalloc لتتبع allocations Python. فرّق بين Python heap و native memory التي قد تستهلكها NumPy/PyTorch. في الخدمات راقب throughput و queue wait و dependency latency و error rate، وليس endpoint duration فقط.
التحسينات الشائعة: تجنب repeated parsing، قلل copies غير الضرورية، استخدم vectorized operations للبيانات العددية، batch network/database operations، cache فقط ما له invalidation policy واضحة، واستخدم streaming بدل materializing giant lists. لا تحسن readability إلى حد يجعل correctness غامضًا، ولا تعمل caching لنتيجة تعتمد على tenant/user من دون تضمين scope في cache key.
import cProfile
import pstats
def count_pairs(n: int) -> int:
total = 0
for left in range(n):
for right in range(n):
total += (left * right) % 7
return total
profiler = cProfile.Profile()
profiler.enable()
result = count_pairs(700)
profiler.disable()
print("result:", result)
pstats.Stats(profiler).sort_stats("cumulative").print_stats(8)NumPy Bridge: From Python Loops to Vectorized Computing
NumPy مش مجرد list أسرع؛ هو نموذج بيانات مختلف. الـ ndarray عادةً يخزن عناصر متجانسة في memory buffer، ومعه metadata مثل shape و dtype و strides. ده يسمح بتنفيذ عمليات كثيرة داخل compiled native loops بدل Python loop لكل عنصر. الـ dtype يؤثر على الدقة والذاكرة والأداء؛ مثلًا float32 يستهلك نصف ذاكرة float64 تقريبًا، لكن اختيار precision لازم يتوافق مع حساسية الحساب.
افهم الفرق بين shape و axis و dimension، والـ broadcasting rules: الأبعاد تُقارن من اليمين، ويكون البعدان متوافقين إذا تساويا أو كان أحدهما 1. Broadcasting لا يعني دائمًا نسخ المصفوفة فعليًا، لكنه قد ينتج intermediate arrays كبيرة عند بعض التعبيرات. راقب memory layout: C-contiguous و Fortran-contiguous و views الناتجة عن slicing. الـ view قد يشارك الذاكرة مع الأصل، بينما بعض العمليات تنتج copy.
في ML، shape errors من أكثر الأخطاء شيوعًا. اكتب shapes بجوار كل tensor operation، واستخدم assertions في حدود pipeline. لا تعتمد على implicit broadcasting لو كان يخفي خطأ semantic مثل جمع batch dimension مع feature dimension. افحص missing values و NaN و Inf صراحةً؛ NaN لا يساوي نفسه، وقد ينتشر عبر العمليات الحسابية.
import numpy as np
# 3 samples, 2 features
X = np.array([[1.0, 10.0], [2.0, 20.0], [3.0, 30.0]])
# one mean per feature: shape (2,)
means = X.mean(axis=0)
centered = X - means
print("X:", X.shape) # (3, 2)
print("means:", means.shape) # (2,)
print("centered:", centered.shape) # (3, 2)
print(centered.mean(axis=0)) # approximately [0. 0.]Numerical Computing: Floating Point, Stability & Reproducibility
الحاسوب لا يمثل معظم الأعداد الحقيقية بدقة لا نهائية. floating-point numbers تقريب محدود، والعمليات الحسابية تتضمن rounding. لذلك 0.1 + 0.2 قد لا يساوي تمثيلًا ثنائيًا دقيقًا لـ 0.3. لا تستخدم equality المباشرة لمقارنة نتائج floating-point العامة؛ استخدم tolerance مناسبًا مثل isclose مع فهم absolute و relative tolerance.
ترتيب العمليات قد يغير النتيجة بسبب rounding، وعمليات مثل subtracting two nearly equal large numbers قد تسبب catastrophic cancellation. الـ overflow والـ underflow و NaN/Inf قد تنتج قيمًا غير صالحة دون exception. في ML ده يؤثر على loss و gradient؛ لذلك نحتاج initialization مناسب، normalization، stable log-sum-exp، وفحص gradients/loss على NaN/Inf.
Reproducibility ليست مجرد تثبيت random seed. وثّق Python/package versions، dataset snapshot، preprocessing code، model config، hardware/backend، seeds، و determinism settings. بعض GPU kernels أو parallel reductions قد لا تكون deterministic تمامًا. اعتبر seed أداة لتسهيل المقارنة وليس ضمانًا مطلقًا لتطابق كل bit.
import numpy as np
print(0.1 + 0.2 == 0.3) # False on typical binary floating-point
print(np.isclose(0.1 + 0.2, 0.3, rtol=1e-9, atol=1e-12))
values = np.array([1.0, np.nan, np.inf])
print(np.isfinite(values)) # [ True False False ]Testing Strategy for Data & AI Code
اختبارات AI code تحتاج أكثر من assert على output واحد. اختبر invariants: عدد الصفوف لا يتغير دون سبب، IDs لا تتكرر، القيم تقع داخل domain، ترتيب train/validation لا يتسرب، preprocessing لا يتعلم statistics من test، embedding count يساوي input count، ونتيجة التحويل مستقرة عند إعادة التشغيل. استخدم unit tests للمنطق الخالص، contract tests للتكامل، integration tests للخدمات، و small golden datasets لتثبيت السلوك.
اختبر الحدود: empty input، single record، duplicate IDs، malformed Unicode، huge input، NaN/Inf، missing columns، timezone edge cases، network timeout، rate limit، model unavailable. في property-based testing يمكن توليد inputs كثيرة لاكتشاف edge cases؛ وفي parametrized tests يمكنك تغطية قواعد validation بوضوح. لا تجعل الاختبارات تعتمد على model provider خارجي أو ترتيب نتائج غير مضمون.
للـ ML، افصل correctness tests عن quality evaluation. unit test يثبت أن preprocessing يحافظ على shape، لكنه لا يثبت أن model دقيق. evaluation dataset و metrics و thresholds لها مسار منفصل، ويجب أن تكون versioned. سجّل model/data/prompt versions مع نتائج التقييم حتى يمكن تفسير regression.
import math
import pytest
def normalize_scores(scores: list[float]) -> list[float]:
if any(not math.isfinite(score) for score in scores):
raise ValueError("scores must be finite")
return [min(1.0, max(0.0, score)) for score in scores]
@pytest.mark.parametrize("value, expected", [
(-0.2, 0.0), (0.4, 0.4), (1.7, 1.0)
])
def test_scores_are_clamped(value, expected):
assert normalize_scores([value]) == [expected]
def test_nan_is_rejected():
with pytest.raises(ValueError):
normalize_scores([float("nan")])Python Project Engineering & Reproducible Environments
المشروع الاحترافي له lifecycle واضح: إنشاء environment، تثبيت dependencies، تشغيل lint/type checks/tests، بناء artifact، وتشغيله في بيئة نظيفة. افصل dependencies الأساسية عن dev dependencies، وثبّت versions بطريقة reproducible، واحتفظ ببيانات المصدر أو dataset fingerprints. لا تعتبر pip freeze وحده استراتيجية dependency management كاملة لكل المشاريع؛ اختَر lock workflow يناسب package manager المستخدم وتأكد من platform constraints.
اجعل package قابلة للتثبيت، واستخدم pyproject.toml لإعداد build backend والأدوات. لا تجعل working directory شرطًا خفيًا لنجاح التطبيق؛ استخدم pathlib ومسارات config صريحة. لا تقرأ secrets من source code أو notebook. اجعل config typed ومتحققًا عند startup، وافشل مبكرًا برسالة واضحة إذا كان إعداد ضروري ناقصًا.
الـ Notebook ممتاز للاستكشاف، لكنه ليس deployment artifact. انقل المنطق المستقر إلى modules قابلة للاختبار، واجعل notebook يستورد هذه الوحدات. أضف README يشرح setup/run/test، و Makefile أو task runner عند الحاجة، و CI يختبر نفس commands محليًا. سجّل versioning للبيانات والنموذج والـ code؛ reproducibility تعني القدرة على إعادة بناء النتيجة ومعرفة ما الذي تغير.
[build-system]
requires = ["setuptools>=68", "wheel"]
build-backend = "setuptools.build_meta"
[project]
name = "ai-data-service"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
"numpy>=2.0,<3",
"pydantic>=2,<3",
]
[project.optional-dependencies]
dev = ["pytest>=8,<9", "ruff>=0.6,<1"]Python AI Engineering Capstone Lab
المعمل ده يجمع المهارات السابقة في pipeline صغير قبل RAG. استقبل records تمثل مستندات، تحقق من schema، نظّف النص، احسب metadata، ارفض السجلات غير الصالحة أو اعزلها، ثم أخرج JSONL قابلًا لإعادة التشغيل. لا تستدعِ LLM أو Vector DB في أول نسخة؛ الهدف هنا تثبيت data contracts و reliability قبل إضافة تكلفة وتعقيد.
المتطلبات: كل document له document_id و tenant_id و text و source. IDs غير الفارغة يجب أن تكون فريدة داخل tenant. النص الفارغ يُرفض. احسب character_count و word_count و sha256 للمحتوى بعد normalization. لا تخلط مستندات tenants، ولا تسجل النص الخام في logs. اجعل التشغيل idempotent بحيث إعادة معالجة نفس الملف لا تنشئ records مكررة.
اختبارات القبول: duplicate ID، empty text، invalid Unicode input، missing tenant، large document limit، deterministic hash، stable output ordering، malformed JSON line، و partial failure policy. أضف metrics: accepted/rejected count، rejection reason، processing duration، input bytes. بعد نجاح المعمل، أضف API thin layer ثم اربطه لاحقًا بـ ASP.NET Core عبر versioned JSON contract.
from dataclasses import dataclass
from hashlib import sha256
import re
@dataclass(frozen=True)
class NormalizedDocument:
document_id: str
tenant_id: str
text: str
character_count: int
word_count: int
content_sha256: str
def normalize_document(raw: dict, max_chars: int = 200_000) -> NormalizedDocument:
document_id = str(raw.get("document_id", "")).strip()
tenant_id = str(raw.get("tenant_id", "")).strip()
text = str(raw.get("text", ""))
text = text.replace("\r\n", "\n").strip()
text = re.sub(r"[ \t]+", " ", text)
if not document_id or not tenant_id:
raise ValueError("document_id and tenant_id are required")
if not text:
raise ValueError("document text cannot be empty")
if len(text) > max_chars:
raise ValueError("document exceeds configured size limit")
digest = sha256(text.encode("utf-8")).hexdigest()
return NormalizedDocument(
document_id=document_id,
tenant_id=tenant_id,
text=text,
character_count=len(text),
word_count=len(text.split()),
content_sha256=digest,
)أدوات Python اللي بتفرّق في خدمات الـ AI
الفرق بين notebook وخدمة production مش في المكتبات — في أربع أدوات من اللغة نفسها: الـ generators (ذاكرة ثابتة مهما كبر الملف)، الـ decorators (retry و caching و timing من غير تكرار)، الـ context managers (موارد بتتقفل حتى لو حصل exception)، والـ asyncio (مئات النداءات المتزامنة على thread واحد). الكود بيقيس أثر كل واحدة.
import asyncio, functools, time, tracemalloc
from contextlib import contextmanager
# ---------- 1) generators: constant memory for arbitrarily large inputs ----------
def read_records(n):
for i in range(n):
yield {"id": i, "text": "x" * 200} # produced one at a time, on demand
def batched(iterable, size):
batch = []
for item in iterable:
batch.append(item)
if len(batch) == size:
yield batch; batch = []
if batch:
yield batch
def peak_mb(fn):
tracemalloc.start(); fn(); peak = tracemalloc.get_traced_memory()[1]; tracemalloc.stop()
return peak / 1e6
N = 100_000
as_list = peak_mb(lambda: sum(len(r["text"]) for r in list(read_records(N))))
as_stream = peak_mb(lambda: sum(len(r["text"]) for b in batched(read_records(N), 500) for r in b))
print(f"1) peak memory, {N:,} records: list={as_list:.1f} MB generator in batches of 500={as_stream:.2f} MB")
# ---------- 2) decorators: cross-cutting behaviour written once ----------
def retry(times, exceptions=(Exception,), base_delay=0.0):
def wrap(fn):
@functools.wraps(fn) # keeps __name__/__doc__ for logs and debuggers
def inner(*args, **kwargs):
for attempt in range(1, times + 1):
try:
return fn(*args, **kwargs)
except exceptions:
if attempt == times:
raise
time.sleep(base_delay * 2 ** (attempt - 1))
return inner
return wrap
calls = {"n": 0}
@retry(times=4, exceptions=(TimeoutError,))
def flaky_embedding_call(text):
calls["n"] += 1
if calls["n"] < 3:
raise TimeoutError("upstream timeout")
return [0.1, 0.2, 0.3]
print(f"2) retry decorator: result={flaky_embedding_call('hello')} after {calls['n']} calls; function name preserved: {flaky_embedding_call.__name__}")
@functools.lru_cache(maxsize=1024)
def expensive_tokenize(text):
time.sleep(0.002); return tuple(text.split())
t0 = time.perf_counter(); [expensive_tokenize("the same prompt prefix") for _ in range(200)]
print(f" lru_cache: 200 identical calls took {(time.perf_counter() - t0) * 1000:.0f} ms (1 real computation), {expensive_tokenize.cache_info().hits} cache hits")
# ---------- 3) context managers: cleanup that cannot be forgotten ----------
events = []
@contextmanager
def model_session(name):
events.append(f"load {name}")
try:
yield name
finally: # runs on success, on exception, on early return
events.append(f"release {name}")
try:
with model_session("reranker") as m:
events.append("infer"); raise ValueError("bad input")
except ValueError:
events.append("error handled by caller")
print("3) context manager event order:", " -> ".join(events))
# ---------- 4) asyncio: concurrency for I/O-bound work, with a concurrency limit ----------
async def call_llm(i, sem):
async with sem: # at most N requests in flight: respect provider rate limits
await asyncio.sleep(0.05) # stands in for network latency
return i
async def run_all(n, limit):
sem = asyncio.Semaphore(limit)
t0 = time.perf_counter()
results = await asyncio.gather(*(call_llm(i, sem) for i in range(n)))
return len(results), time.perf_counter() - t0
print("4) 40 simulated 50 ms API calls:")
for limit in (1, 8, 40):
n, seconds = asyncio.run(run_all(40, limit))
print(f" concurrency limit {limit:>2}: {seconds:.2f} s")
def cpu_bound(n): # pure computation: asyncio cannot help here
return sum(i * i for i in range(n))
async def cpu_tasks():
t0 = time.perf_counter()
await asyncio.gather(*(asyncio.to_thread(cpu_bound, 300_000) for _ in range(4)))
return time.perf_counter() - t0
t0 = time.perf_counter(); [cpu_bound(300_000) for _ in range(4)]; serial = time.perf_counter() - t0
threaded = asyncio.run(cpu_tasks())
print(f" CPU-bound work x4: sequential and threaded take about the same time (ratio {threaded / serial:.1f}x) — threads do not parallelise Python bytecode")1) peak memory, 100,000 records: list=22.4 MB generator in batches of 500=0.23 MB
2) retry decorator: result=[0.1, 0.2, 0.3] after 3 calls; function name preserved: flaky_embedding_call
lru_cache: 200 identical calls took 2 ms (1 real computation), 199 cache hits
3) context manager event order: load reranker -> infer -> release reranker -> error handled by caller
4) 40 simulated 50 ms API calls:
concurrency limit 1: 2.05 s
concurrency limit 8: 0.25 s
concurrency limit 40: 0.05 s
CPU-bound work x4: sequential and threaded take about the same time (ratio 2.0x) — threads do not parallelise Python bytecode1) Generators: نفس المعالجة، والفرق في الذاكرة عشرات المرات. الـ list بتحمّل كل الـ records قبل ما تبدأ؛ الـ generator بيولّد واحد واحد. ده اللي بيخلّي ingestion ملف 20GB ممكن على جهاز بـ 2GB. ونمط الـ batched هو اللي بتبعت بيه للـ embedding API: دفعات بحجم ثابت من stream.
2) Decorators: الـ retry اتكتب مرة ويتطبق على أي دالة بسطر. functools.wraps مش تجميل: من غيره كل الدوال هتظهر في الـ logs والـ traces باسم inner. والـ lru_cache: 200 نداء = حساب واحد — لكن خد بالك إنه cache لكل process وبيفضل للأبد؛ مش بديل عن Redis ومش مناسب لبيانات بتتغير.
3) Context managers: الـ release حصل قبل ما الـ caller يمسك الـ exception. نفس الضمان لملف، connection، lock، أو GPU memory. الكود اللي فيه open() من غير with بيسرّب موارد في أول exception.
4) asyncio: 40 نداء × 50ms = ثانيتين بالتسلسل، وحوالي 50ms لما كلهم متزامنين. الـ Semaphore هو اللي بيخليك تختار نقطة في النص: سريع من غير ما تعدّي الـ rate limit بتاع المزوّد. والسطر الأخير بيورّي الحد: الـ asyncio والـ threads بيفيدوا في الانتظار (network، disk) مش في الحساب — الشغل الـ CPU-bound محتاج multiprocessing أو مكتبة بتشتغل برا الـ interpreter lock زي NumPy.
نداء blocking جوه async def (زي requests.get أو time.sleep أو inference تقيل) بيوقّف الـ event loop كله: كل الـ requests التانية بتستنى. استخدم client async (httpx.AsyncClient)، أو انقل الشغل الـ blocking بـ asyncio.to_thread. في FastAPI: endpoint بـ def عادي بيتشغّل في threadpool تلقائيًا، وده الاختيار الصح للـ inference المتزامن.
def العادي بس. جوه async def أي شغل blocking بيحبس الـ loop. الحل: خليه def، أو await asyncio.to_thread(model.predict, x).بتعالج ملف JSONL حجمه 30GB سطر بسطر وتبعته للـ embedding API. أنهي تصميم؟
اختبر فهمك
لماذا نستخدم Pydantic عند API boundary؟
اختبار الإتقان المهني
ما الفرق بين shallow copy و deep copy؟
لماذا لا يعني async أن CPU-heavy code أصبح أسرع؟
لماذا يجب أن يتضمن cache key هوية tenant؟
المراجع والقراءة الإضافية
الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)
التوثيق الرسمي — Official documentation
مصادر تعليمية ومتقدمة — Third-party & advanced reading
خريطة التغطية: 20 عنصر من الـ Roadmap ومكان شرحه في الدرس
خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.