فئات البيانات الصارمة

توفر حزمة huggingface_hub أداة لإنشاء فئات بيانات صارمة. وهي نسخ محسّنة من فئة dataclass القياسية في بايثون، مع ميزات تحقق إضافية. تضمن فئات البيانات الصارمة التحقق من الحقول أثناء التهيئة والتعيين على حد سواء، مما يجعلها مثالية للسيناريوهات التي تكون فيها سلامة البيانات حاسمة.

نظرة عامة

تُنشأ كائنات البيانات الصارمة (Strict dataclasses) باستخدام الزخرفة @strict. وهي توسّع وظائف كائنات البيانات العادية من خلال:

• التحقق من أنواع الحقول بناءً على تلميحات الأنواع
• دعم المُتحقّقات المخصّصة لإجراء فحوصات إضافية
• السماح اختيارياً بحجج كلمات مفتاحية اعتباطية في منشئ الكائن
• التحقق من الحقول عند التهيئة وأثناء الإسناد

المزايا

• سلامة البيانات: يضمن أن تحتوي الحقول دائمًا على بيانات صالحة
• سهولة الاستخدام: يتكامل بسلاسة مع وحدة dataclass في بايثون
• المرونة: يدعم أدوات تحقق مخصصة لمنطق التحقق المعقد
• خفيف الوزن: لا يتطلب أي تبعيات إضافية مثل Pydantic أو attrs أو مكتبات مشابهة

الاستخدام

مثال أساسي

from dataclasses import dataclass
from huggingface_hub.dataclasses import strict, as_validated_field

# Custom validator to ensure a value is positive
@as_validated_field
def positive_int(value: int):
    if not value > 0:
        raise ValueError(f"Value must be positive, got {value}")

@strict
@dataclass
class Config:
    model_type: str
    hidden_size: int = positive_int(default=16)
    vocab_size: int = 32  # Default value

    # Methods named `validate_xxx` are treated as class-wise validators
    def validate_big_enough_vocab(self):
        if self.vocab_size < self.hidden_size:
            raise ValueError(f"vocab_size ({self.vocab_size}) must be greater than hidden_size ({self.hidden_size})")

تُتحقَّق من الحقول أثناء التهيئة:

config = Config(model_type="bert", hidden_size=24)   # Valid
config = Config(model_type="bert", hidden_size=-1)   # Raises StrictDataclassFieldValidationError

يتم أيضًا التحقق من الاتساق بين الحقول أثناء التهيئة (التحقق على مستوى الفئة):

# `vocab_size` too small compared to `hidden_size`
config = Config(model_type="bert", hidden_size=32, vocab_size=16)   # Raises StrictDataclassClassValidationError

يتم التحقق من صحة الحقول أيضًا أثناء الإسناد:

config.hidden_size = 512  # Valid
config.hidden_size = -1   # Raises StrictDataclassFieldValidationError

لإعادة تشغيل التحقق على مستوى الفئة بعد الإسناد، يجب عليك استدعاء .validate بشكل صريح:

config.validate()  # Runs all class validators

المُتحقِّقات المخصَّصة

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

from dataclasses import dataclass
from huggingface_hub.dataclasses import strict, validated_field

def multiple_of_64(value: int):
    if value % 64 != 0:
        raise ValueError(f"Value must be a multiple of 64, got {value}")

@strict
@dataclass
class Config:
    hidden_size: int = validated_field(validator=[positive_int, multiple_of_64])

في هذا المثال، تُطبَّق كلا المُتحقِّقين على حقل hidden_size.

حجج الكلمات المفتاحية الإضافية

بشكل افتراضي، تقبل فئات البيانات الصارمة (strict dataclasses) الحقول المعرّفة في الفئة فقط. يمكنك السماح بحجج كلمات مفتاحية إضافية عن طريق تعيين accept_kwargs=True في الزخرفة (decorator) @strict.

from dataclasses import dataclass
from huggingface_hub.dataclasses import strict

@strict(accept_kwargs=True)
@dataclass
class ConfigWithKwargs:
    model_type: str
    vocab_size: int = 16

config = ConfigWithKwargs(model_type="bert", vocab_size=30000, extra_field="extra_value")
print(config)  # ConfigWithKwargs(model_type='bert', vocab_size=30000, *extra_field='extra_value')

تظهر حُجج الكلمات المفتاحية الإضافية في التمثيل النصي لفئة البيانات (dataclass) لكنها تُسبق بـ* لإبراز أنها غير مُتحقَّق منها.

التكامل مع تلميحات الأنواع

تلتزم كائنات البيانات الصارمة (Strict dataclasses) بتلميحات الأنواع وتحقق منها تلقائيًا. على سبيل المثال:

from typing import List
from dataclasses import dataclass
from huggingface_hub.dataclasses import strict

@strict
@dataclass
class Config:
    layers: List[int]

config = Config(layers=[64, 128])  # Valid
config = Config(layers="not_a_list")  # Raises StrictDataclassFieldValidationError

تشمل الأنواع المدعومة:

• أي
• اتحاد
• اختياري
• حرفي
• قائمة
• Dict
• Tuple
• مجموعة

وأي تركيبة من هذه الأنواع. إذا كنت بحاجة إلى تحقق أكثر تعقيدًا من الأنواع، يمكنك القيام بذلك من خلال مُتحقّق مخصص.

مُتحقِّقات الفئة

تُعامل الدوال التي تحمل أسماء على شكل validate_xxx كمُتحقّقات على مستوى الفئة. يجب أن تستقبل هذه الدوال self فقط كحجة. تُنفَّذ مُتحقّقات الفئة مرة واحدة أثناء التهيئة، مباشرة بعد __post_init__. يمكنك تعريف عدد غير محدود منها—ستُنفَّذ تباعًا بالترتيب الذي تظهر فيه.

لاحظ أن مُتحقّقات الفئة (class validators) لا تُعاد تلقائيًا عند تحديث حقل بعد التهيئة. لإعادة التحقق من الكائن يدويًا، يجب عليك استدعاء obj.validate().

from dataclasses import dataclass
from huggingface_hub.dataclasses import strict

@strict
@dataclass
class Config:
    foo: str
    foo_length: int
    upper_case: bool = False

    def validate_foo_length(self):
        if len(self.foo) != self.foo_length:
            raise ValueError(f"foo must be {self.foo_length} characters long, got {len(self.foo)}")

    def validate_foo_casing(self):
        if self.upper_case and self.foo.upper() != self.foo:
            raise ValueError(f"foo must be uppercase, got {self.foo}")

config = Config(foo="bar", foo_length=3) # ok

config.upper_case = True
config.validate() # Raises StrictDataclassClassValidationError

Config(foo="abcd", foo_length=3) # Raises StrictDataclassFieldValidationError
Config(foo="Bar", foo_length=3, upper_case=True) # Raises StrictDataclassFieldValidationError

الطريقة .validate() هي اسم محجوز في فئات البيانات الصارمة. لمنع السلوكيات غير المتوقعة، سيُستدعى خطأ StrictDataclassDefinitionError إذا كانت فئتك تعرّف طريقة بهذا الاسم مسبقًا.

مرجع الواجهة البرمجية

@strict

يعزز مُزيِّن @strict فئة البيانات (dataclass) بالتحقق الصارم.

>>> from dataclasses import dataclass
>>> from huggingface_hub.dataclasses import as_validated_field, strict, validated_field

>>> @as_validated_field
>>> def positive_int(value: int):
...     if not value >= 0:
...         raise ValueError(f"Value must be positive, got {value}")

>>> @strict(accept_kwargs=True)
... @dataclass
... class User:
...     name: str
...     age: int = positive_int(default=10)

# Initialize
>>> User(name="John")
User(name='John', age=10)

# Extra kwargs are accepted
>>> User(name="John", age=30, lastname="Doe")
User(name='John', age=30, *lastname='Doe')

# Invalid type => raises
>>> User(name="John", age="30")
huggingface_hub.errors.StrictDataclassFieldValidationError: Validation error for field 'age':
    TypeError: Field 'age' expected int, got str (value: '30')

# Invalid value => raises
>>> User(name="John", age=-1)
huggingface_hub.errors.StrictDataclassFieldValidationError: Validation error for field 'age':
    ValueError: Value must be positive, got -1

validate_typed_dict

طريقة للتحقق من أن قاموسًا يتوافق مع الأنواع المعرّفة في فئة TypedDict.

This is the equivalent to dataclass validation but for TypedDicts. Since typed dicts are never instantiated (only used by static type checkers), validation step must be manually called.

>>> from typing import Annotated, TypedDict
>>> from huggingface_hub.dataclasses import validate_typed_dict

>>> def positive_int(value: int):
...     if not value >= 0:
...         raise ValueError(f"Value must be positive, got {value}")

>>> class User(TypedDict):
...     name: str
...     age: Annotated[int, positive_int]

>>> # Valid data
>>> validate_typed_dict(User, {"name": "John", "age": 30})

>>> # Invalid type for age
>>> validate_typed_dict(User, {"name": "John", "age": "30"})
huggingface_hub.errors.StrictDataclassFieldValidationError: Validation error for field 'age':
    TypeError: Field 'age' expected int, got str (value: '30')

>>> # Invalid value for age
>>> validate_typed_dict(User, {"name": "John", "age": -1})
huggingface_hub.errors.StrictDataclassFieldValidationError: Validation error for field 'age':
    ValueError: Value must be positive, got -1

as_validated_field

مُزيِّن لإنشاء validated_field. يُنصح به للحقول التي تحتوي على مُتحقق واحد لتجنب كتابة أكواد متكررة.

validated_field

ينشئ حقلًا لـ dataclass مع تحقق مخصص.

الأخطاء

لماذا لا نستخدم pydantic؟ (أو attrs؟ أو marshmallow_dataclass؟)

• انظر إلى المناقشة في https://github.com/huggingface/transformers/issues/36329 حول إضافة Pydantic كاعتماد. ستكون إضافة ثقيلة وتتطلب منطقًا دقيقًا لدعم كل من الإصدار v1 والإصدار v2.
• لا نحتاج إلى معظم ميزات Pydantic، لا سيما تلك المتعلقة بالتحويل التلقائي، وjsonschema، والتسلسل، والكنيات، وما إلى ذلك.
• لا نحتاج إلى القدرة على إنشاء كائن من فئة انطلاقًا من قاموس.
• لا نرغب في تعديل البيانات. في @strict ، تعني كلمة “التحقق” “فحص ما إذا كانت القيمة صالحة”. أما في Pydantic ، فتعني كلمة “التحقق” “تحويل القيمة، مع احتمال تعديلها، ثم فحص ما إذا كانت صالحة”.
• لا نحتاج إلى تحقق سريع للغاية. لم يُصمَّم @strict للتعامل مع الأحمال الثقيلة حيث تكون الأداء عاملاً حاسماً. تتضمن حالات الاستخدام الشائعة التحقق من تكوين النموذج (يُنفَّذ مرة واحدة فقط وهو ضئيل مقارنةً بتشغيل النموذج). وهذا يتيح لنا إبقاء الكود في أبسط صوره.