بنّي وشغّل نموذج لغوي تشريعي برازيلي بـ PyTorch

شنو هو LLM Legislativo Brasileiro؟

LLM Legislativo Brasileiro هو مشروع بحث وهندسة شامل لبناء نموذج لغوي سببي متخصص فوثائق التشريع البرازيلي. كينظّم المواد الرسمية ديال مجلس النواب ومجلس الشيوخ الفيدرالي فمجموعات بيانات مفتوحة وقابلة للتدقيق، ومن بعد كيدرّب Transformer decoder من الصفر كامل باستعمال PyTorch.

المشروع ما كيستعملش أوزان مدرّبة من قبل، ولا واجهات API مغلقة، ولا تجريدات تدريب عالية المستوى بحال Hugging Face Trainer. التصميم ديالو كيركّز على العلوم المفتوحة، وقابلية إعادة الإنتاج، والتحقق من السلامة باستعمال SHA-256، والعزل السببي الصارم بين بيانات التدريب والتحقق والاختبار.

هاد النموذج أثر بحثي وتعليمي. ما خاصوش يتعتبر مستشار قانوني واقعي ولا أداة لاتخاذ قرارات معيارية، حيث النماذج اللغوية السببية تقدر تهلوس القوانين، والتعديلات، والملخصات، والمقتضيات القانونية.

أهم المميزات

• كتر من 360 GiB من البيانات الخام الرسمية، بما فيها مجموعات مجلس النواب ومجلس الشيوخ.
• كتر من 930,000 وثيقة ونسخة جوهرية، بحال مشاريع القوانين، والتعديلات الدستورية، والتقارير، والآراء، والبدائل، والنصوص النهائية، ومحاضر الجلسات.
• خمسة إصدارات عامة لمجموعات البيانات فـ Hugging Face Hub، كتشمل الأرشيفات الخام، والنصوص المستخرجة، وبيانات Apache Parquet المنقحة.
• Tokenizer من نوع byte-level BPE فيه 8,192 رمز، تدرّب حصريا على جزء التدريب.
• مفكّك Transformer سببي صريح مطبّق بـ PyTorch، فيه ست طبقات، وستة رؤوس انتباه، وتمثيل مخفي بأبعاد 384، ونافذة سياق من 512 رمز.
• ربط الأوزان بين طبقات تضمين الرموز وإسقاط الخرج.
• تجميع دقيق للتدرجات مبني على العدد الإجمالي للأهداف الصالحة، وهاد الشي كيتفادى أخطاء الترجيح المرتبطة بالحشو بين السلاسل المختلفة.
• تقسيمات حتمية للبيانات بنسبة 80/10/10 مبنية على معرّفات العائلات التشريعية، وكتمنع الوثائق المرتبطة من الانتقال بين حدود التدريب والاختبار.
• أوزان النموذج متاحة للعموم بصيغة safetensors، مع tokenizer، والإعدادات، والمقاييس، وكود مستقل للاستدلال.

فهم البيانات ومسار التدريب

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

فـ macOS، كيستعمل محوّل استخراج أصلي مكتوب بـ Swift مكتبة PDFKit للوثائق اللي فيها نص مضمّن. الصفحات الممسوحة ضوئيا أو الصفحات اللي فيها كثافة نصية غير كافية كتمشي لـ Apple Vision OCR. من بعد كيتنقح النص فـ R باستعمال إزالة التكرار الدقيقة بـ SHA-256، واكتشاف احتواء المقاطع، ورسم بياني عالمي للعائلات التشريعية مبني بـ igraph.

كل اقتراح، وتعديل، وتقرير، ورأي، وبديل مرتبط بنفس المسار التشريعي كياخذ نفس family_id. هاش حتمي ديال هاد المعرّف كيسند العائلة كاملة للتدريب أو التحقق أو الاختبار. هاد الشي كيمنع تسريب النسخ المرتبطة بين تقسيمات التقييم.

من بعد التقسيم، مرحلة تحويل الرموز فـ Python كتدرّب مفردات byte-level BPE فيها 8,192 رمز باستعمال بيانات التدريب بوحدها. كتدعم اللكنات البرتغالية، والرموز التشريعية بحال § وº وª وArt.، وزيد عليها الأرقام والحروف الخاصة الأخرى. البيانات المحوّلة لرموز كتتكتب فشظايا ثنائية مع فهارس للنوافذ اللي فيها 512 رمز.

إعداد المستودع

1. نسخ المشروع

المستودع كيتطلب Python 3.9 أو أحدث. نسخو ودخل لمجلد المشروع:

git clone https://github.com/BaruqueRodrigues/llm-legislativo.git
cd llm-legislativo

2. إنشاء بيئة افتراضية

استعمال بيئة افتراضية كيخلي تبعيات المشروع معزولة على باقي النظام ديالك:

python3 -m venv .venv
source .venv/bin/activate

3. تثبيت الحزمة

ثبّت المستودع فالوضع القابل للتعديل باش التغييرات المحلية فالمصدر تولّي متاحة مباشرة:

pip install -e .

المستودع فيه حزمة Python تحت src/legislm/، وملفات قفل لبيئات الأساس وCPU، وبيانات وصفية لإعادة إنتاج R، وإعدادات تصريحية، ودفاتر، ونصوص سطر الأوامر، ومجموعة اختبارات.

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

قبل ما تحاول تدير الاستدلال بالنموذج أو التدريب على نطاق كبير، شغّل الاختبارات الآلية محليا على CPU:

pytest tests/ -q

الـ README كيشير لأكثر من 135 اختبار وحدة واختبار عقد كيغطي سلوك النموذج، والحفظ والاسترجاع، وتحويل الرموز، والتقييم. التشغيل الناجح كيتأكد باللي الواجهات الأساسية خدامة بلا ما تحتاج كامل المتن اللي حجمو مئات الجيغابايت أو وحدة معالجة A100.

تحميل النموذج المنشور

النموذج المدرّب متاح فمستودع BaruqRodrigues/llm-legislativo. المثال التالي كيحمّل الأوزان وtokenizer، وكيعاود يبني البنية، وكيحمّل قاموس الحالة safetensors.

import torch
from huggingface_hub import hf_hub_download
from safetensors.torch import load_file
from legislm.model.gpt import GPTModel
from legislm.model.config import ModelConfig
from tokenizers import Tokenizer

# Download the model artifacts
weights_path = hf_hub_download(
    repo_id="BaruqRodrigues/llm-legislativo",
    filename="model.safetensors"
)
tokenizer_path = hf_hub_download(
    repo_id="BaruqRodrigues/llm-legislativo",
    filename="tokenizer.json"
)

# Recreate the tokenizer and model configuration
tokenizer = Tokenizer.from_file(tokenizer_path)
config = ModelConfig(
    vocab_size=8192,
    context_length=512,
    d_model=384,
    n_layers=6,
    n_heads=6,
    tie_embeddings=True
)
model = GPTModel(config)

# Load the trained parameters
state_dict = load_file(weights_path)
model.load_state_dict(state_dict)
model.eval()

ولّد نص تشريعي

منين كيتحمّل الموديل، حوّل البرومبت التشريعي بالبرتغالية لصيغة مشفّرة وعيّط على ميثود التوليد ديال الموديل. المثال كيستعمل بداية قصيرة ديال مشروع قانون وكيطلب حتى لـ64 توكن جديد.

prompt = "PROJETO DE LEI Nº , DE 2026\n\nDispõe sobre"
input_ids = torch.tensor(
    [tokenizer.encode(prompt).ids],
    dtype=torch.long
)

with torch.no_grad():
    output_ids = model.generate(
        input_ids,
        max_new_tokens=64,
        temperature=0.7,
        top_k=40,
        eos_token_id=2
    )

print(tokenizer.decode(output_ids[0].tolist()))

الموديل كيستعمل طول أقصى للسياق ديال 512 توكن. فهاد المثال، temperature=0.7 كيتحكّم فالتنوّع ديال أخذ العينات، وtop_k=40 كيحصر أخذ العينات فـ40 مرشّح اللي عندهم أعلى احتمال. بدّل هاد القيم ملي كتجرّب، ولكن ردّ بالك باللي النص المولّد ناتج إحصائي وماشي محتوى قانوني متحقّق منّو.

استكشف مجموعات البيانات العمومية

المشروع كينشر مراحل مختلفة من المتن فـHugging Face Hub:

• corpus-legislativo-pretraining: إصدار موحّد ومنقّح بصيغة Parquet، فيه تقسيمات التدريب والتحقّق والاختبار منظّمة حسب العائلة.
• camara-corpus-raw: أرشيفات TAR الخام ديال مجلس النواب وبيانات SHA-256.
• camara-corpus-text: استخراجات منظّمة لنصوص مجلس النواب مع التحقّق من الجودة.
• senado-corpus-raw: جرد المعطيات والبيانات الأصلية ديال مجلس الشيوخ الفدرالي.
• senado-corpus-text: وثائق وصفحات منقّحة ديال مجلس الشيوخ بصيغة Parquet العمودية.

هاد الإصدارات كتمكّن من تفحّص المشروع فمراحل مختلفة من خط المعالجة، من الأرشيفات المصدرية والنصوص المستخرجة حتى لمصفوفات التدريب النهائية.

عاود التدريب ولا وسّعو

تنفيذ التدريب كاين فـsrc/legislm/training/، بينما التقطيع وتوليد الأجزاء كاينين فـsrc/legislm/tokenization/. الإعدادات مخزّنة فـconfigs/، وسيرورات Google Colab متوفّرة فـnotebooks/ وsrc/legislm/colab/.

جولة التدريب المنشورة تستعملات بيئة NVIDIA A100-SXM4-40GB وكملات 173,209 تحديث ديال التحسين فحوالي 20 ساعة. عالجات تقريباً 1.25 مليار توكن باستعمال AdamW، ومجدول جيبي مع تسخين خطّي ديال 2,000 خطوة، ودقّة مختلطة FP16، وحفظ نقاط التحقّق عبر Google Drive.

باش تدير تجارب قابلة لإعادة الإنتاج، خلّي التقطيع محصور فجزء التدريب، وحافظ على مسطرة التقسيم الحتمية حسب العائلة، وخلي بيانات SHA-256 الوصفية ديال المستودع وبيانات نقاط التحقّق. هاد التفاصيل ضرورية باش تتفادى تسرّب البيانات وتقارن النتائج بنزاهة.

قيّم النتائج بالطريقة الصحيحة

المشروع كيحدّد بروتوكول تقييم موحّد سميتو byte_nll_v1 على جزء اختبار مستقل فيه 71,069 وثيقة وحوالي 482 مليون بايت. النتائج المعلنة كتشمل متوسط خسارة قدرها 2.1065 لكل هدف صالح، وتعقيداً رمزياً قدره 8.2197، وتعقيداً على مستوى الكلمات قدره 65.6509.

النتيجة المعيّرة على مستوى البايتات هي 0.7297 نات لكل بايت، أو 1.0528 بت لكل بايت. والقيم المعلنة هي 0.7049 نات لكل بايت بالنسبة لمجموعة مجلس النواب و0.8817 بالنسبة لمجموعة مجلس الشيوخ. ملي كتقارن تجارب مستقبلية، استعمل نفس منطق التقسيم وتعريف التقييم، وما تعتمدش غير على التعقيد الرمزي.

بنية المستودع

المجلدات الرئيسية ك توضّح فين خاصك تقلّب ملي كتبدّل النظام ولا كتدرسو:

• R/: جرد رسمي للبيانات، والتنزيلات، ودمج الاستخراج، والتنقيح.
• src/legislm/: كود التقطيع، والموديل، والتدريب، وحفظ Colab، والتقييم.
• schemas/: عقود البيانات ديال Arrow وJSON Schema.
• configs/: إعدادات البيانات، والتنقيح، والتدريب، وColab.
• notebooks/: سيرورات Google Colab التجريبية والكاملة.
• scripts/: نقاط الدخول التنفيذية لسطر الأوامر.
• tests/: اختبارات الوحدات واختبارات العقود.
• docs/: التوثيق المعياري، والعقود، والتقارير.

نصائح عملية متقدّمة

• بدا بالاختبارات: التحقّق من المعالج (CPU) طريقة قليلة التكلفة باش تتأكّد من التثبيت قبل ما تحمّل مجموعات بيانات كبار ولا تطلب موارد GPU.
• حافظ على حدود العائلات: ما تديرش تقسيمات عشوائية على مستوى الوثائق إلا بغيتي نتائج قابلة للمقارنة مع المشروع، حيث الإصدارات ديال نفس المسار التشريعي تقدر تكون مرتبطة ببعضياتها بزاف.
• درّب محلّل الرموز من بعد التقسيم: حساب إحصائيات المفردات باستعمال بيانات التحقّق ولا الاختبار يقدر يفسد ضوابط تسرّب البيانات ديال المشروع.
• تبّع الأهداف الصالحة: ملي كتستعمل سلاسل معمّرة بالحشو، جمّع قيمة خسارة الانتروبيا المتقاطعة حسب العدد الإجمالي ديال الأهداف الصالحة عبر الدفعات الصغرى.
• خلّي الملفات الناتجة برا Git: المستودع كيسجّل عمداً البيانات الوصفية والمخططات، وماشي الملفات الثنائية الخام، وأوزان النماذج، وذاكرات التخزين المؤقت.
• استعمل الإصدارات العمومية للفحص: مجموعات البيانات الخام، والمستخرجة، والمنقّحة فـ Hub كتخليك تفحص المراحل الفردية ديال خط المعالجة بلا ما تعاود تبني عملية الجمع كاملة.
• فسّر النصوص المولّدة بحذر: اللغة التشريعية المولّدة تقدر تبان معقولة، ولكن يكون فيها مراجع ولا مقتضيات مخترعة.

الخلاصة

كيبيّن LLM Legislativo Brasileiro مساراً كاملاً وقابلاً للتدقيق، كينطلق من الأرشيفات التشريعية الرسمية وكيقود لنموذج لغوي سببي متخصّص. من بعد تثبيت الحزمة وتشغيل الاختبارات ديالها، تقدر تحمّل محلّل الرموز ونموذج PyTorch المنشورين، وتولّد النصوص، وتفحص مجموعات البيانات العمومية، وتدرس طرق التنقيح والتدريب ديال المستودع المقاومة لتسرّب البيانات. الكود المرخّص برخصة MIT والملفات المنشورة بشكل مفتوح كيوفّرو أساساً مفيداً للبحث فـ نمذجة اللغة التشريعية البرتغالية.