Pydantic + OpenAI: أنظف طريقة للحصول على مخرجات منظمة من نماذج اللغات الكبيرة

Pydantic + OpenAI: أنظف طريقة للحصول على مخرجات منظمة من نماذج اللغة الكبيرة

نماذج اللغة الكبيرة (LLMs) بارعة بشكل ملحوظ في توليد نصوص شبيهة بالنصوص البشرية، لكنها غالبًا ما تنتج مخرجات غير منظمة أو شبه منظمة تتطلب معالجة لاحقة مكثفة. عند بناء تطبيقات إنتاجية - سواء لاستخراج البيانات، أو مراقبة المحتوى، أو إعداد التقارير الآلية - فأنت بحاجة إلى بيانات موثوقة، ومحددة النوع، ومُتحقق من صحتها. وهنا يأتي دور Pydantic و OpenAI: مزيج قوي يتيح لك تحديد بنية المخرجات التي تريدها بالضبط، ويجعل نموذج اللغة الكبير يقدمها بتنسيق نظيف وقابل للتنبؤ.

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

لماذا تُعد المخرجات المنظمة مهمة؟

عندما تطرح سؤالاً على نموذج لغة كبير، عادةً ما تحصل على فقرة من النص. بالنسبة لروبوتات المحادثة، هذا جيد. ولكن إذا كنت بحاجة إلى استخراج قائمة بأسماء العملاء والتواريخ والمبالغ من بريد إلكتروني، أو إنشاء كائن JSON لقاعدة بيانات، فإن النص الخام يصبح مشكلة. قد تحاول تحليل المخرجات باستخدام التعبيرات النمطية (regex) أو استدعاء ثانٍ لنموذج اللغة الكبير، لكن هذه الأساليب هشة وعرضة للأخطاء.

تحل المخرجات المنظمة هذه المشكلة عن طريق تقييد النموذج لإنتاج بيانات تطابق مخططًا (schema) محددًا مسبقًا. وهنا يتألق Pydantic. Pydantic هي مكتبة بايثون للتحقق من صحة البيانات باستخدام تعليقات الأنواع في بايثون. عند دمجها مع إمكانيات استدعاء الدوال (function calling) أو المخرجات المنظمة من OpenAI، تحصل على:

• **أمان النوع (Type safety)** – يتم التحقق تلقائيًا من صحة المخرجات مقابل المخطط الخاص بك.
• **لا حاجة للتحليل اليدوي** – يُرجع النموذج مثيلاً لنموذج Pydantic، وليس نصًا خامًا.
• **عقود واضحة** – يعرف كودك بالضبط الحقول التي يتوقعها.

المتطلبات

قبل البدء، تأكد من توفر ما يلي:

• **بايثون 3.9 أو أحدث** – يتطلب Pydantic الإصدار 2 بايثون 3.9 أو أحدث.
• **مفتاح API من OpenAI** – تحتاج إلى مفتاح صالح مع صلاحية الوصول إلى نماذج GPT-4 أو GPT-3.5-turbo التي تدعم استدعاء الدوال.
• **إلمام أساسي ببايثون** – يجب أن تفهم الكلاسات والأنواع والبرمجة غير المتزامنة (اختياري لكنه مفيد).

التثبيت خطوة بخطوة

سنقوم بإعداد بيئة نظيفة وتثبيت المكتبات اللازمة.

1. إنشاء وتفعيل بيئة افتراضية

عزل التبعيات يمنع التعارض مع المشاريع الأخرى.

python -m venv pydantic_openai_env
source pydantic_openai_env/bin/activate  # على ويندوز: pydantic_openai_env\Scripts\activate

2. تثبيت Pydantic ومكتبة OpenAI للبايثون

Pydantic الإصدار 2 هو الإصدار الرئيسي الحالي. تتضمن مكتبة OpenAI دعمًا لاستدعاء الدوال والمخرجات المنظمة.

pip install pydantic openai

3. التحقق من التثبيت

قم بتشغيل فحص سريع للتأكد من توفر كلتا المكتبتين.

import pydantic
import openai
print(f"Pydantic version: {pydantic.__version__}")
print(f"OpenAI library version: {openai.__version__}")

إذا رأيت أرقام الإصدارات (مثل `2.5.0` لـ Pydantic و `1.6.0` لـ OpenAI)، فأنت جاهز.

4. تعيين مفتاح API الخاص بـ OpenAI

قم بتخزين مفتاحك كمتغير بيئة للأمان.

export OPENAI_API_KEY="your-api-key-here"

يمكنك أيضًا تعيينه في سكريبت بايثون الخاص بك، لكن استخدام متغيرات البيئة موصى به للإنتاج.

المفهوم الأساسي: تعريف نموذج Pydantic

نموذج Pydantic هو كلاس يرث من `BaseModel`. كل حقل مُعَلَّق بنوع، ويمكن إضافة قيم افتراضية اختيارية أو أدوات تحقق.

إليك نموذج بسيط لاستخراج معلومات شخص من النص:

from pydantic import BaseModel, Field
from typing import Optional

class Person(BaseModel):
    name: str = Field(description="الاسم الكامل للشخص")
    age: Optional[int] = Field(None, description="العمر بالسنوات، إذا تم ذكره")
    email: Optional[str] = Field(None, description="عنوان البريد الإلكتروني، إذا كان موجودًا")

تتيح لك دالة `Field` إضافة أوصاف وقيم افتراضية وقيود. يتم تمرير هذه الأوصاف إلى نموذج اللغة الكبير لتوجيه مخرجاته.

السحر: الجمع بين Pydantic واستدعاء الدوال من OpenAI

يتيح لك استدعاء الدوال من OpenAI تحديد مخطط JSON يجب أن يلتزم به النموذج عند إنشاء استجابة. يمكن تحويل نماذج Pydantic تلقائيًا إلى هذا المخطط باستخدام طريقة `.model_json_schema()`.

إليك سير عمل كامل:

الخطوة 1: تحديد نموذج المخرجات الخاص بك

سنقوم بإنشاء نموذج لاستخراج قائمة بمراجعات المنتجات.

from pydantic import BaseModel, Field
from typing import List

class Review(BaseModel):
    product_name: str = Field(description="اسم المنتج الذي تمت مراجعته")
    rating: int = Field(ge=1, le=5, description="التقييم من 1 إلى 5")
    summary: str = Field(description="ملخص من جملة واحدة للمراجعة")

class ReviewList(BaseModel):
    reviews: List[Review] = Field(description="قائمة المراجعات الموجودة في النص")

الخطوة 2: تحضير عميل OpenAI وتعريف الدالة

سنستخدم عميل OpenAI (صيغة الإصدار 1.0+) ونحول نموذجنا إلى مخطط JSON.

from openai import OpenAI

client = OpenAI()

# تحويل ReviewList إلى مخطط JSON
review_schema = ReviewList.model_json_schema()

سيبدو المخطط ككائن JSON Schema قياسي، والذي تستخدمه OpenAI لتحديد معاملات الدالة.

الخطوة 3: إجراء استدعاء API مع استدعاء الدالة

نمرر المخطط كتعريف دالة، ونطلب من النموذج استدعاء تلك الدالة.

response = client.chat.completions.create(
    model="gpt-4-1106-preview",  # أو "gpt-3.5-turbo-1106"
    messages=[
        {"role": "system", "content": "أنت تستخرج بيانات منظمة من إدخال المستخدم."},
        {"role": "user", "content": "أحببت آيفون 15 الجديد. الكاميرا رائعة. أعطيه 5 نجوم. أيضًا، ماك بوك برو مبالغ في سعره لكنه قوي. سأقيمه بـ 3 نجوم."}
    ],
    tools=[{
        "type": "function",
        "function": {
            "name": "extract_reviews",
            "description": "استخراج مراجعات المنتجات من النص المدخل",
            "parameters": review_schema
        }
    }],
    tool_choice={"type": "function", "function": {"name": "extract_reviews"}}
)

الخطوة 4: تحليل الاستجابة إلى نموذج Pydantic

ستحتوي استجابة النموذج على وسيطة استدعاء دالة (سلسلة JSON). نقوم بتحليلها مباشرة إلى نموذج Pydantic الخاص بنا.

import json

# استخراج وسيطات استدعاء الدالة
tool_call = response.choices[0].message.tool_calls[0]
arguments = json.loads(tool_call.function.arguments)

# التحقق من الصحة وإنشاء نموذج Pydantic
reviews = ReviewList(**arguments)
print(reviews)

المخرجات (منسقة):

reviews=[
    Review(product_name='iPhone 15', rating=5, summary='أحببت الكاميرا الرائعة.'),
    Review(product_name='MacBook Pro', rating=3, summary='مبالغ في سعره لكنه قوي.')
]

لاحظ أن النموذج تحقق تلقائيًا من نطاق التقييم (1-5) وحلل القائمة. إذا كان نموذج اللغة الكبير قد أعاد تقييمًا غير صالح (مثل 6)، لكان Pydantic قد أثار خطأ `ValidationError`.

أمثلة على الاستخدام

دعنا نستكشف سيناريوهين عمليين: استخراج البيانات المنظمة من رسائل البريد الإلكتروني وإنشاء كائنات التكوين.

مثال 1: تحليل البريد الإلكتروني لدعم العملاء

تخيل أنك تتلقى رسائل دعم وتحتاج إلى استخراج نوع المشكلة والأولوية ومعرف العميل.

from pydantic import BaseModel, Field
from enum import Enum

class Priority(str, Enum):
    low = "منخفضة"
    medium = "متوسطة"
    high = "عالية"

class SupportTicket(BaseModel):
    customer_id: str = Field(description="معرف العميل من توقيع البريد الإلكتروني")
    issue_type: str = Field(description="فئة المشكلة: فوترة، تقنية، أو حساب")
    priority: Priority = Field(description="مستوى الاستعجال")
    description: str = Field(description="ملخص مختصر للمشكلة")

ثم استخدم نفس النمط أعلاه لاستخراج هذا من نص البريد الإلكتروني. سيعيد نموذج اللغة الكبير مثيل `SupportTicket` مُتحققًا منه.

مثال 2: إنشاء كائنات التكوين

يمكنك أيضًا إنشاء تكوينات متداخلة معقدة، مثل معاملات اتصال قاعدة البيانات.

from pydantic import BaseModel, Field
from typing import Dict

class DatabaseConfig(BaseModel):
    host: str = Field(description="اسم المضيف أو IP لقاعدة البيانات")
    port: int = Field(ge=1, le=65535, description="رقم المنفذ")
    credentials: Dict[str, str] = Field(description="اسم المستخدم وكلمة المرور كقاموس")

اطلب من نموذج اللغة الكبير: "قم بإنشاء تكوين قاعدة بيانات لمثيل PostgreSQL يعمل على localhost مع مستخدم 'admin' وكلمة مرور 'secret123'." سيعيد النموذج تكوينًا مُتحققًا منه.

أفضل الممارسات والنصائح

1. **استخدم أسماء وأوصاف حقول وصفية** – يستخدمها نموذج اللغة الكبير لفهم ما تريد. كن محددًا. 2. **استفد من قيود الأنواع** – يدعم Pydantic `ge`، `le`، `min_length`، `regex`، والمزيد. هذه القيود مشفرة في مخطط JSON وتساعد نموذج اللغة الكبير على إنشاء مخرجات صالحة. 3. **تعامل مع الأخطاء بلطف** – سيثير Pydantic خطأ `ValidationError` إذا كانت مخرجات النموذج لا تطابق المخطط الخاص بك. قم بتغليف التحليل في كتلة try-except وأعد المحاولة مع موجه أكثر وضوحًا. 4. **حافظ على حجم المخططات معقولاً** – المخططات الكبيرة جدًا (العديد من الحقول أو التداخل العميق) يمكن أن تربك النموذج. قسم عمليات الاستخراج المعقدة إلى استدعاءات متعددة إذا لزم الأمر. 5. **استخدم التعدادات (enums) للمجموعات الثابتة** – إذا كان الحقل يمكن أن يكون واحدًا فقط من بضع قيم، فحدد كلاس `Enum`. هذا يقيد مخرجات نموذج اللغة الكبير بالخيارات الصالحة.

القيود والاعتبارات

بينما هذا النهج قوي، إلا أنه ليس مثاليًا:

• **التكلفة** – يستخدم استدعاء الدوال المزيد من الرموز (tokens)، خاصة مع المخططات الكبيرة. راقب استخدامك لواجهة API.
• **دعم النموذج** – ليست كل نماذج OpenAI تدعم استدعاء الدوال. استخدم `gpt-4-1106-preview` أو `gpt-3.5-turbo-1106` للحصول على أفضل النتائج.
• **تعقيد المخطط** – المخططات المتداخلة للغاية أو العودية قد تتسبب في هلوسة النموذج أو حذف الحقول. حافظ على المخطط مسطحًا قدر الإمكان.
• **زمن الاستجابة** – المعالجة الإضافية لاستدعاء الدوال تضيف حملًا صغيرًا (عادةً أقل من 100 مللي ثانية).

الخلاصة

يوفر Pydantic + OpenAI أنظف وأكثر الطرق موثوقية للحصول على مخرجات منظمة من نماذج اللغة الكبيرة. من خلال تعريف نموذج Pydantic، وتحويله إلى مخطط JSON، واستخدام استدعاء الدوال من OpenAI، فإنك تلغي الحاجة إلى التحليل اليدوي وتكتسب أمان النوع والتحقق من الصحة والعقود الواضحة. هذا النمط مثالي لاستخراج البيانات، وملء النماذج، وتوليد الأكواد، وأي مهمة تحتاج فيها إلى بيانات منظمة وقابلة للتنبؤ من اللغة الطبيعية.

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

*ملاحظة: تستند هذه المقالة إلى المعرفة العامة لـ Pydantic و OpenAI حتى بداية عام 2025. للحصول على أحدث التحديثات، راجع وثائق Pydantic الرسمية وسجل تغييرات API الخاص بـ OpenAI.*