ما الذي يشرحه هذا الدليل؟

تصف المواد الموثّقة FastAPI بأنه إطار Python حديث لبناء APIs. وتسلّط المراجعات المشار إليها الضوء على قدراته غير المتزامنة، والتحقق من صحة البيانات عبر Pydantic، وإنشاء وثائق API تفاعلية تلقائياً. وهذه هي القدرات التي يستخدمها المثال: يستقبل أحد المسارات طلباً مكتوباً، ويتحقق من صحته عبر نموذج Pydantic، ثم يعيد استجابة مكتوبة يوثّقها الإطار.

يستخدم المثال عقداً يشبه تصنيف تذاكر الدعم، لكنه لا يستدعي نموذجاً لغوياً عمداً. وهذا التمييز مهم. فـAPI HTTP التي تتحقق من صحة البيانات ليست بحد ذاتها موجّهاً للذكاء الاصطناعي. ولتوجيه الطلبات إلى OpenAI أو Anthropic، يحتاج التنفيذ أيضاً إلى عملاء خاصين بكل مزوّد، وإعدادات موثّقة، وآلية لمعالجة الاستجابات والأخطاء، وقرارات واضحة بشأن السياسات. ولا يمكن تقديم هذه التفاصيل بمسؤولية استناداً إلى المصادر المتاحة هنا.

يوضح السياق الموثّق أيضاً تمييزاً معمارياً أوسع. إذ تعتمد FastAPI نهج المسارات أولاً: يكون تعريف مسار HTTP محورياً لتسجيل نقطة النهاية ومخططها. وإذا كان يجب إتاحة القدرة نفسها كأداة MCP، فقد يلزم تسجيل منفصل، مع تعريفات تُدار بصورة مستقلة. ويصف بحث HarnessAPI بديلاً يعتمد المهارات أولاً، حيث تُسقَط المهارة وعقود أنواعها على وسائل النقل. يلتزم هذا الدليل بمسارات FastAPI التقليدية، ولا يطبّق MCP أو HarnessAPI.

المتطلبات الأساسية

• معرفة بـPython وإلمام بالدوال، وتعليقات الأنواع، وJSON.
• طرفية يمكنك من خلالها تثبيت حزم Python وتشغيل خادم تطوير محلي.
• فهم أساسي لطلبات HTTP واستجاباته.

لا تحتاج إلى مفتاح API لنموذج، لأن العينة لا تنفّذ استدعاءات إلى المزوّدين. كما أن السياق الموثّق لا يحدد إصدارات الحزم أو معرّفات نماذج المزوّدين، لذلك يتجنب هذا الدليل الادعاء بوجود حد أدنى محدد لإصدارات متوافقة.

الخطوة ١: إنشاء مشروع وتثبيت الإطار

أنشئ مجلداً للمشروع وبيئة افتراضية. وثبّت FastAPI وخادم ASGI باستخدام أسلوبك المعتاد لإدارة حزم Python. في المشاريع المشتركة أو المنشورة، اختر الإصدارات التي اختبرها فريقك وثبّتها؛ فالمصادر المقدمة لا تتحقق من أرقام إصدارات حالية بعينها.

mkdir typed-fastapi-service
cd typed-fastapi-service
python -m venv .venv

# macOS or Linux
source .venv/bin/activate

# Windows PowerShell
# .venvScriptsActivate.ps1

python -m pip install fastapi uvicorn

أنشئ ملفاً باسم main.py داخل مجلد المشروع. تستخدم FastAPI تعريفات المسارات لربط أساليب HTTP والمسارات بدوال نقاط النهاية في Python. ويمكن لتعليقات الأنواع في الدالة ونماذج Pydantic وصف البيانات التي تتوقعها نقطة النهاية.

الخطوة ٢: تعريف نماذج الطلب والاستجابة المكتوبة

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

from pydantic import BaseModel, Field


class TicketRequest(BaseModel):
    subject: str = Field(min_length=3, max_length=200)
    body: str = Field(min_length=10, max_length=8000)


class TicketAccepted(BaseModel):
    status: str
    subject: str

تجعل تعريفات النماذج أشكال الإدخال والإخراج المقصودة واضحة داخل Python. وتحدد القيود الحدين الأدنى والأقصى لطول حقلي الطلب. ويشكّل التحقق من صحة البيانات عبر Pydantic الجزء الذي يدعمه السياق المقدم من هذا النمط تحديداً؛ إذ يناقش وصف HarnessAPI استخدام التحقق من نموذج الإدخال عبر Pydantic وإعادة استجابة HTTP 422 عند فشل التحقق.

هذه النماذج عقود للتطبيق، وليست تعليمات لنموذج لغوي. ولا تضمن أن تكون مخرجات نموذج خارجي آمنة أو صحيحة. وإذا استدعى تنفيذ لاحق نموذجاً،...