मॉडल प्रशिक्षण कॉन्फ़िगरेशन और रूट

v2.14.0 में नया

यह पेज Potato config के model_training ब्लॉक का और रन शुरू करने के बाद उसके साथ जो होता है उसका संदर्भ है। पेज उस व्यक्ति के लिए है जो अध्ययन चलाता है और रन सीमित करना, रन को दूसरी मशीन पर भेजना, मॉडल की भविष्यवाणियाँ एनोटेटरों को दिखाना, या किसी स्क्रिप्ट से प्रशिक्षण शुरू करना चाहता है। नीचे की हर कुंजी, डिफ़ॉल्ट, रूट और संदेश Potato के कोड से जाँचा गया है। पहले रन के लिए अपना पहला मॉडल प्रशिक्षित करें से शुरू करें। ट्रेनर और उनके पैरामीटर ट्रेनर में सूचीबद्ध हैं।

पूरा config

नीचे का config उत्पाद समीक्षाओं पर एक sentiment क्लासिफ़ायर प्रशिक्षित करता है। auto_retrain हर 25 नए एनोटेशन के बाद sklearn-text को दोबारा फ़िट करता है। डिफ़ॉल्ट TF-IDF फ़ीचर के साथ sklearn-text CPU पर प्रशिक्षित होता है और उसे Potato के सामान्य इंस्टॉल के अलावा कुछ नहीं चाहिए। इसलिए बार-बार के स्वचालित रन की लागत कम है। राइट-बैक एनोटेटरों को वह हर भविष्यवाणी दिखाता है जिसका विश्वास कम से कम 0.8 है। include_unlabeled के साथ रन उन समीक्षाओं पर भी भविष्यवाणी करता है जिन पर किसी ने अभी लेबल नहीं लगाया। hf-text-classification के डिफ़ॉल्ट और gpu-server बैकएंड उन रनों के लिए हैं जो Training पेज से हाथ से शुरू किए जाते हैं:

annotation_task_name: "Review sentiment with model training"
task_dir: "."
data_files:
  - "data/reviews.json"
item_properties:
  id_key: "id"
  text_key: "text"
output_annotation_dir: "annotation_output"
user_config:
  allow_all_users: true
 
annotation_schemes:
  - annotation_type: "radio"
    name: "sentiment"
    description: "Is this review positive or negative?"
    labels: ["positive", "negative"]
 
model_training:
  enabled: true
  split_seed: 0
  splits: {train: 0.7, val: 0.15, test: 0.15}
  aggregation: consensus
  retain_runs: 5
  queue_max: 10
  max_wall_seconds: 3600
  max_ram_mb: 8192
  num_threads: 4
  trainer_params:
    sklearn-text:
      classifier: sklearn.linear_model.LogisticRegression
      classifier_kwargs: {max_iter: 1000}
    hf-text-classification:
      model_name: answerdotai/ModernBERT-base
      epochs: 4
      lora: true
  auto_retrain:
    enabled: true
    trainer: sklearn-text
    schemas: [sentiment]
    min_interval_s: 600
    update_frequency: 25
  writeback:
    schemas: [sentiment]
    min_confidence: 0.8
    include_unlabeled: true
  backends:
    gpu-server:
      type: ssh
      host: gpu-server
      python: /opt/conda/bin/python3
      gpus: auto
      min_free_gpu_mb: 4000

split_seed को अध्ययन के पूरे जीवन में स्थिर रखें। नया सीड हर आइटम को दोबारा बाँट देता है, इसलिए जो आइटम होल्ड-आउट थे वे प्रशिक्षण में चले जाते हैं और बाद के स्कोर पहले के स्कोरों से तुलनीय नहीं रहते। 0.8 की min_confidence सीमा एक शुरुआती बिंदु है, और सही सीमा पहले होल्ड-आउट स्कोर पर निर्भर करती है। include_unlabeled तब चालू करें जब वह स्कोर प्री-लेबल दिखाने का समर्थन करे, क्योंकि प्री-लेबल एनोटेटरों को मॉडल के उत्तर से बाँध देते हैं।

model_training की कुंजियाँ

हर कुंजी model_training के नीचे रहती है:

रन के अपने params trainer_params को अधिलेखित करते हैं, जो ट्रेनर के डिफ़ॉल्ट को अधिलेखित करते हैं। जो पैरामीटर नाम ट्रेनर नहीं लेता वह trainer_params के नीचे होने पर सर्वर शुरू होते समय अस्वीकार होता है, और अन्यथा रन शुरू होते समय। ट्रेनर यह क्रम एक उदाहरण के साथ देता है।

auto_retrain

स्वचालित दोबारा प्रशिक्षण हर एनोटेशन सहेजे जाने के बाद नए रन की जाँच करता है:

जब जाँच रन के विरुद्ध फ़ैसला करती है, तो कारण GET /admin/training/api/status के skip_reason फ़ील्ड में दिखता है, जैसे "waiting for 3 more annotation(s)" या "a run is already in progress"। स्वचालित रन कभी रन कतार में शामिल नहीं होते। कतार खाली होने के बाद सहेजा गया अगला एनोटेशन दोबारा जाँच करता है, और तब प्रशिक्षण के लिए अधिक एनोटेशन होते हैं। Potato एनोटेशन की गिनती मेमोरी में रखता है, इसलिए पुनः आरंभ के बाद, जिस प्रोजेक्ट ने पहले प्रशिक्षण लिया है, वह पुनः आरंभ से नए एनोटेशन गिनता है।

writeback

राइट-बैक तय करता है कि एनोटेटर कौन-सी भविष्यवाणियाँ देखते हैं:

tiling

डिटेक्शन और सेगमेंटेशन ट्रेनर हर चित्र को कुछ सौ पिक्सेल तक छोटा कर देते हैं। उस आकार पर संपूर्ण-स्लाइड चित्र या उपग्रह दृश्य की वस्तुएँ खो जाती हैं। इसलिए image_annotation, microscopy या geo_annotation स्कीम के लिए Potato रन का प्रशिक्षण डेटा बनाते समय हर बड़े चित्र को टाइलों में काट देता है। चित्र का स्प्लिट चित्र को काटने से पहले तय होता है, इसलिए एक स्लाइड की टाइलें कभी दो स्प्लिट में नहीं जातीं। भविष्यवाणियाँ पूरे चित्र पर वापस मैप होती हैं, और होल्ड-आउट स्कोर पूरे चित्रों पर गिने जाते हैं। विज़न ट्यूटोरियल व्यवहार में स्लाइड और नक्शे समझाता है।

स्लाइडें openslide से पढ़ी जाती हैं, जो pip install "potato-annotation[wsi]" से इंस्टॉल होता है, उस मशीन पर जो प्रशिक्षण डेटा बनाती है। रिमोट बैकएंड टाइलें डाउनलोड करता है, स्लाइड कभी नहीं।

रन कतार

एक समय में एक रन चलता है। Training पेज या API से शुरू किया गया रन, जब दूसरा रन चल रहा हो, अस्वीकार होने के बजाय प्रतीक्षा करता है। शुरू करने का अनुरोध 202 लौटाता है, queued: true और रन की position के साथ, और Runs तालिका रन को waiting #N के रूप में Cancel run बटन के साथ सूचीबद्ध करती है। जब चल रहा रन खत्म होता है, तो सबसे पुराना प्रतीक्षारत रन शुरू होता है।

प्रतीक्षारत रन रन बही में दर्ज होते हैं, इसलिए कतार पुनः आरंभ के बाद भी बनी रहती है, और सर्वर लौटने पर पहला प्रतीक्षारत रन शुरू होता है। जिस रन के बीच में पिछला सर्वर था वह उसी समय interrupted चिह्नित हो जाता है। प्रतीक्षारत रन का प्रशिक्षण डेटा रन शुरू होने पर बनता है, इसलिए रन उस क्षण मौजूद एनोटेशन पर प्रशिक्षित होता है। जो शुरुआत अस्वीकार होती, जैसे किसी अज्ञात स्कीम का नाम देने वाली शुरुआत, वह रन की बारी आने पर नहीं बल्कि तुरंत अस्वीकार हो जाती है। जिस रन का स्कीम या ट्रेनर प्रतीक्षा के दौरान config से हट गया, वह invalid_when_dequeued के साथ विफल होता है, और अगला रन शुरू होता है।

कतार में जगह की जगह 409 पाने के लिए अनुरोध की बॉडी में "queue": false भेजें। जब queue_max रन पहले से प्रतीक्षा कर रहे हों, तो नई शुरुआत को 429 मिलता है। GET /admin/training/api/status प्रतीक्षारत रनों को क्रम से queue के नीचे सूचीबद्ध करता है।

रन से पहले की जाँचें

potato validate model_training ब्लॉक की हर समस्या एक साथ रिपोर्ट करता है, और सर्वर उन्हीं समस्याओं पर शुरू होने से मना कर देता है:

potato validate config.yaml --strict

जाँचें इन मामलों को कवर करती हैं:

• splits में train, val और test के अलावा कोई नाम, 0 से कम या संख्या न होने वाला अंश, ऐसे अंश जिनका जोड़ 0 है, या train का न होना।
• ऐसी कुंजी जो writeback या auto_retrain में नहीं है, ऐसी writeback.schemas प्रविष्टि जो स्कीम नहीं है, या 0 से 1 के बाहर की min_confidence। accept_license को accept_licence की गलत वर्तनी के रूप में रिपोर्ट किया जाता है।
• चालू pre_annotation ब्लॉक जिसका field writeback.field से अलग है। ऐसे ब्लॉक के नीचे कोई प्रशिक्षण प्री-लेबल नहीं दिखेगा।
• auto_retrain.enabled के साथ, ऐसा ट्रेनर या स्कीम जो मौजूद नहीं है, ऐसा स्कीम जिसे ट्रेनर सीख नहीं सकता, ऐसे पैरामीटर जो ट्रेनर नहीं लेता या गलत प्रकार के, backends में न मिलने वाला backend, या local के अलावा किसी बैकएंड पर decision-calibrate।
• trainer_params के नीचे ऐसा पैरामीटर जो ट्रेनर नहीं लेता, या गलत प्रकार का। dp के अंदर जाँच हर कुंजी और उसकी सीमा को भी कवर करती है।
• 0 से कम या संख्या न होने वाला grace_seconds, या 0 से कम या पूर्ण संख्या न होने वाला retain_runs या split_seed।
• backends के नीचे, type का न होना या अज्ञात होना, ऐसी कुंजी जो उस प्रकार में नहीं है, host के बिना ssh बैकएंड, auto, none या GPU सूचकांकों के अलावा gpus का मान, local नाम का रिमोट बैकएंड, या ऐसा model_training.backend जो परिभाषित नहीं है।

potato training check किसी बैकएंड को रन द्वारा उपयोग किए जाने से पहले जाँचता है। local के लिए कमांड वह डिवाइस छापती है जो रन उपयोग करेगा, जैसे Apple silicon वाले Mac पर local: this machine, Apple Metal (mps)। ssh बैकएंड के लिए कमांड Python संस्करण, हर GPU और उसकी खाली मेमोरी, वह GPU जो रन को मिलेगा, और वे प्रशिक्षण पैकेज रिपोर्ट करती है जो रिमोट इंटरप्रेटर में नहीं हैं। Training पेज का Check बटन वही जाँच चलाता है, और --json रिपोर्ट को JSON के रूप में छापता है:

potato training check local config.yaml
potato training check gpu-server config.yaml

Training पेज या API से शुरू किया गया रन शुरू होते समय दोबारा जाँचा जाता है। स्थिति कोड रूट के नीचे सूचीबद्ध हैं।

बैकएंड

रन एक बैकएंड पर चलता है, और Training पेज का Runs on मेनू कॉन्फ़िगर किए गए बैकएंड सूचीबद्ध करता है। model_training.backend डिफ़ॉल्ट तय करता है, और API रन या auto_retrain backend से कोई दूसरा बैकएंड बता सकता है। Potato में चार बैकएंड प्रकार हैं:

ssh बैकएंड BatchMode चालू रखकर कुंजी-आधारित प्रमाणीकरण उपयोग करता है, इसलिए पासवर्ड प्रॉम्प्ट अटकने की जगह विफल होता है। slurm बैकएंड केवल sbatch, squeue और scancel उपयोग करता है, और जिन क्लस्टरों में scontrol है उन पर scontrol भी, और उसे ऐसे स्टोरेज पर remote_dir चाहिए जिसे कंप्यूट नोड साझा करते हैं। agent बैकएंड को कोई इनबाउंड पोर्ट नहीं चाहिए, क्योंकि एजेंट हर कनेक्शन खोलता है। local नाम इसी मशीन के लिए आरक्षित है, और decision-calibrate केवल local पर चलता है। GPU सर्वर, SLURM क्लस्टर या NAT के पीछे की मशीन पर प्रशिक्षण तीनों रिमोट प्रकार उनकी कुंजियों के साथ समझाता है।

होल्ड-आउट स्कोर

हर रन अपनी भविष्यवाणियों को val और test आइटम पर समाधानित मानव लेबलों के विरुद्ध स्कोर करता है। मीट्रिक नामों में स्प्लिट होता है, जैसे val_macro_f1 या test_f1। जिस आइटम पर लेबल है पर भविष्यवाणी नहीं, वह गलत गिना जाता है, इसलिए कठिन आइटम छोड़ने से ट्रेनर का स्कोर नहीं बढ़ सकता। <split>_coverage उन आइटम का अंश रिपोर्ट करता है जिन्हें भविष्यवाणी मिली।

मुख्य स्कोर Runs तालिका के Held-out score स्तंभ में दिखता है, और स्प्लिट और मीट्रिक टूलटिप में। मुख्य स्कोर पहले स्कीम की मुख्य मीट्रिक है, val और test में से उस पर जिसमें पहले आइटम हों। जब ट्रेनर ने सबसे अच्छा चेकपॉइंट val स्कोर से चुना हो, तो Potato पहले test आज़माता है, क्योंकि ट्रेनर val स्कोर पहले ही देख चुका है। जो फ़ाइन-ट्यूनिंग ट्रेनर सबसे अच्छा एपोक रखते हैं, जैसे hf-text-classification, torchvision-detect और llm-sft, वे मुख्य स्कोर test से लेते हैं। sklearn-text, setfit, rdkit-property, निर्णय-मॉडल ट्रेनर और इन्फ़रेंस ब्रिज val पर कुछ नहीं चुनते, और इनमें से किसी ट्रेनर का रन जब भी val में आइटम हों, मुख्य स्कोर val से लेता है। जिस रन में कोई val या test आइटम नहीं, वह "not scored" दिखता है।

मुख्य मीट्रिक स्कीम के एनोटेशन प्रकार पर निर्भर करती है, जैसा नीचे की तालिका आम प्रकारों के लिए दिखाती है:

Token F1 उस उत्तर को भी श्रेय देता है जो सही शब्द गलत क्रम में उपयोग करता है, इसलिए token F1 को exact match के साथ पढ़ें। डिटेक्शन का मुख्य स्कोर 0.5 से 0.95 के औसत की जगह IoU 0.5 उपयोग करता है, क्योंकि एक वस्तु के लिए दो एनोटेटरों के बॉक्स शायद ही कभी IoU 0.9 पर ओवरलैप करते हैं। अपस्ट्रीम होल्ड-आउट स्कोर तालिका हर एनोटेशन प्रकार की मीट्रिक सूचीबद्ध करती है।

राइट-बैक

सफल रन के बाद Potato रन की भविष्यवाणियाँ संग्रहीत करता है और उन भविष्यवाणियों को, जो चार जाँचें पास करती हैं, हर आइटम के predictions फ़ील्ड में लिखता है, या उस फ़ील्ड में जिसका नाम writeback.field देता है। जाँचें इसी क्रम में चलती हैं, और रन की राइट-बैक रिपोर्ट हर छोड़ी गई भविष्यवाणी गिनती है:

1. train स्प्लिट के आइटम को कभी प्री-लेबल नहीं मिलता। जाँच बही में अब भी मौजूद हर रन के train स्प्लिट को कवर करती है, और जब बाद का रन किसी आइटम पर प्रशिक्षित होता है तो पहले के रन का छोड़ा प्री-लेबल उस आइटम से हट जाता है।
2. केवल writeback.schemas के स्कीम प्रकाशित होते हैं। सूची डिफ़ॉल्ट रूप से खाली है, इसलिए प्रशिक्षण चालू करने से एनोटेटरों को दिखने वाली कोई चीज़ नहीं बदलती।
3. अस्वीकृत जोड़े छोड़ दिए जाते हैं। मॉडल समीक्षा में reject निर्णय वाला आइटम और स्कीम का जोड़ दोबारा नहीं दिखता।
4. विश्वास सीमा लागू होती है। min_confidence से कम की भविष्यवाणी संग्रहीत होती है और प्रकाशित नहीं होती।

राइट-बैक किसी मानव लेबल को कभी नहीं बदलता, क्योंकि भविष्यवाणियाँ आइटम डेटा में जाती हैं और एनोटेशन हर एनोटेटर की यूज़र स्टेट में रहते हैं। प्री-लेबल पहले से भरे उत्तर के रूप में दिखता है जिसे एनोटेटर संपादित कर सकता है, जैसे चुनाव चुने हुए विकल्प के रूप में और मुक्त-टेक्स्ट उत्तर स्कीम के टेक्स्ट बॉक्स में, और किसी pre_annotation ब्लॉक की ज़रूरत नहीं होती। प्री-लेबल एनोटेटर का उत्तर तभी बनता है जब एनोटेटर उसे संपादित करे या आगे बढ़ जाए। इसलिए जिस प्री-लेबल को किसी ने संपादित नहीं किया या जिससे आगे नहीं बढ़ा, वह कभी प्रशिक्षण लेबल नहीं बनता। जिस एनोटेटर-आइटम जोड़े को ai_support.holdout अध्ययन के बिना-सहायता तुलना समूह में रखता है, उसे कोई प्री-लेबल नहीं दिखता, और उस जोड़े के लिए भेजा गया आइटम डेटा writeback.field और pre_annotation.field दोनों छोड़ देता है। राइट-बैक रिपोर्ट GET /admin/training/api/status का writeback फ़ील्ड है, और रिपोर्ट का summary बताता है कि रन ने कुछ प्रकाशित क्यों नहीं किया।

Potato हर आइटम और स्कीम के लिए एक भविष्यवाणी रखता है, और नए रन की भविष्यवाणी पुराने रन की भविष्यवाणी को बदल देती है। जब नई भविष्यवाणी संग्रहीत होती है पर दिखाई नहीं जाती, क्योंकि वह min_confidence से कम, खाली, या अस्वीकृत है, तो पुराने रन का प्री-लेबल तुरंत आइटम से हट जाता है, और राइट-बैक रिपोर्ट आइटम को n_superseded_cleared में गिनती है। डेटा के साथ दिए गए प्री-लेबल को छुआ नहीं जाता। स्टार्टअप पर writeback.schemas के स्कीमों की संग्रहीत भविष्यवाणियाँ उन्हीं चार जाँचों के तहत आइटम डेटा में वापस लिखी जाती हैं, इसलिए प्री-लेबल पुनः आरंभ में बचे रहते हैं। किसी रन के प्री-लेबल वापस लेने के लिए DELETE /admin/training/api/runs/<run_id>/predictions भेजें। अनुरोध संग्रहीत भविष्यवाणियाँ हटाता है और प्री-लेबल को आइटम से उतार देता है।

सुधार और पिन किए गए आइटम हमेशा प्रशिक्षित होते हैं

दो प्रकार के आइटम हर बाद के रन के train स्प्लिट में जाते हैं, स्थिर स्प्लिट में उनकी जगह चाहे जो हो:

• समीक्षक द्वारा सुधारे गए आइटम। मॉडल समीक्षा में correct निर्णय का अर्थ है कि किसी व्यक्ति ने मॉडल का उत्तर ठीक किया। सुधार उन आइटम से आते हैं जिन पर मॉडल सबसे खराब था, इसलिए val या test में सुधारा गया आइटम मॉडल को उसकी अपनी गलतियों के नमूने पर स्कोर करेगा। accept और reject निर्णय आइटम को वहीं छोड़ देते हैं जहाँ वह था।
• पिन किए गए आइटम। Catalog पेज पर किसी स्लाइस के बगल का Train on these स्लाइस से मेल खाते आइटम को पिन करता है, जैसे अंतर्निहित model-found-nothing स्लाइस। पिन किया हुआ आइटम तब प्रशिक्षित होता है जब कोई उस पर लेबल लगा दे।

जिस रन ने होल्ड-आउट आइटम train में डाले वह गिनती के साथ चेतावनी लॉग करता है। तब रन का होल्ड-आउट स्कोर उन आइटम के बिना गिना जाता है और पहले के रन के स्कोर से सीधे तुलनीय नहीं रहता। गिनतियाँ प्रशिक्षण डेटा की manifest.json में stats.forced_train के नीचे हैं।

स्प्लिट को डेटासेट संस्करण के रूप में सहेजना

रन के पेज पर Keep this split as a dataset रन के val, test या train आइटम को उनके सहमत मानव लेबलों के साथ डेटासेट के नए संस्करण के रूप में सहेजता है। डेटासेट संस्करण बाद में कभी नहीं बदलता, इसलिए बाद के मॉडलों और LLM प्रॉम्प्टों की तुलना ठीक उन्हीं आइटम पर हो सकती है। इस सुविधा के लिए datasets.enabled: true चाहिए। हर सहेजा गया संस्करण एक स्प्लिट रखता है और डेटासेट के पिछले संस्करण में जोड़ने की जगह शून्य से शुरू होता है। रन 2 के val आइटम रन 1 में जोड़ने पर उनमें वे आइटम आ जाते जिन पर रन 2 प्रशिक्षित हुआ था। हर उदाहरण के inputs प्री-लेबल फ़ील्ड छोड़ देते हैं, इसलिए कोई मूल्यांकन मॉडल का उत्तर नहीं पढ़ सकता।

प्री-लेबल कहाँ से आया

GET /admin/model-review समीक्षा कतार के हर उस आइटम के लिए provenance शामिल करता है जिसका प्री-लेबल किसी प्रशिक्षण रन ने लिखा। हर स्कीम के लिए प्रविष्टि रन id, ट्रेनर और रन का होल्ड-आउट स्कोर देती है। डेटा के साथ दिए गए प्री-लेबल की कोई प्रविष्टि नहीं होती।

रन कहाँ संग्रहीत होते हैं

हर रन की एक डायरेक्टरी <task_dir>/<output_annotation_dir>/training/runs/<run_id>/ पर होती है:

रन बही प्रोजेक्ट डेटाबेस <task_dir>/project.sqlite में रहती है, और रन, हर रन के लिए हर आइटम का स्प्लिट, ट्रेन के लिए पिन किए गए आइटम, संग्रहीत भविष्यवाणियाँ, एजेंट टोकन और Hugging Face Hub पर पुश दर्ज करती है। retain_runs बही को छाँटता है और उस रन को कभी नहीं छाँटता जिसकी भविष्यवाणियाँ अब भी संग्रहीत हैं, इसलिए हर प्री-लेबल को उस रन तक खोजा जा सकता है जिसने उसे लिखा। छँटाई रन डायरेक्टरी को डिस्क पर छोड़ देती है।

LoRA रन केवल एडेप्टर सहेजता है, कुछ से लेकर कुछ सौ मेगाबाइट, और भविष्यवाणी करते समय बेस मॉडल model_name से लोड करता है। पूर्ण फ़ाइन-ट्यून पूरा मॉडल सहेजता है। POTATO_MODEL_CACHE एनवायरनमेंट वेरिएबल को किसी डायरेक्टरी पर सेट करें, और प्रशिक्षण प्रोसेस उस डायरेक्टरी को HF_HOME, TRANSFORMERS_CACHE और SENTENCE_TRANSFORMERS_HOME के लिए उपयोग करती है, जब तक वे वेरिएबल पहले से तय न हों। एयर-गैप वाली मशीन पर, ट्रेनरों द्वारा बताए गए मॉडल पहले से उस डायरेक्टरी में रख दें।

रूट

Training पेज और उसके JSON रूट /admin/training के नीचे हैं और उन्हें एडमिन पहुँच चाहिए। एडमिन पहुँच का अर्थ है एडमिन सत्र या X-API-Key हेडर। ब्राउज़र से आने वाले POST और DELETE अनुरोध same-origin होने चाहिए। Potato का OpenAPI spec सभी 26 प्रशिक्षण ऑपरेशनों को x-potato-requires-config: model_training.enabled: true से चिह्नित करता है:

रन अनुरोध trainer, schemas (सूची या एक नाम), params, backend, accept_licence और queue लेता है। हर ट्रेनर केवल बताया गया पहला स्कीम फ़िट करता है। नीचे का अनुरोध उदाहरण के sentiment स्कीम पर sklearn-text रन शुरू करता है:

curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  http://localhost:8000/admin/training/api/runs \
  -d '{"trainer": "sklearn-text", "schemas": ["sentiment"]}'

अस्वीकृत शुरुआत कारण error में देती है:

एजेंट प्रोटोकॉल

model_training.enabled वे रूट भी पंजीकृत करता है जिन्हें प्रशिक्षण एजेंट /api/training के नीचे कॉल करता है। एजेंट अपना टोकन Authorization: Bearer <token> के रूप में भेजता है, और गायब या अमान्य टोकन को 401 मिलता है। बैकएंड पंजीकृत करने के लिए इसकी जगह एडमिन API कुंजी चाहिए। नया एजेंट लिखने वाले के लिए potato/training/protocol.py प्रोटोकॉल का वर्णन करती है, और potato/training/agent.py संदर्भ कार्यान्वयन है:

QLoRA

llm-sft, llm-dpo, hf-text-classification, vlm-sft और reward-model lora: {quantize: 4bit} लेते हैं, जो QLoRA (Dettmers et al., 2023) का सेटअप है। बेस मॉडल 4-बिट NF4 वेट और डबल क्वांटाइज़ेशन के साथ लोड होता है, और उसके ऊपर LoRA एडेप्टर bf16 में प्रशिक्षित होता है जहाँ GPU bf16 का समर्थन करता है। quantize: 8bit बीच का विकल्प है, और भविष्यवाणियाँ बेस मॉडल को उसी तरह लोड करती हैं।

model_training:
  trainer_params:
    llm-sft:
      model_name: Qwen/Qwen2.5-7B-Instruct
      lora: {quantize: 4bit}

4 बिट में बेस वेट उतनी मेमोरी का चौथाई हिस्सा लेते हैं जितनी वही वेट bf16 में लेते हैं, और उसके ऊपर एक्टिवेशन, एडेप्टर और ऑप्टिमाइज़र स्टेट आते हैं। Potato ने अभी तक GPU पर QLoRA रन की मेमोरी नहीं मापी है, इसलिए योजना रन की अपनी "Peak GPU memory" पंक्ति से बनाएँ। हर ट्रांसफ़ॉर्मर रन अंत में वह पंक्ति लॉग करता है। QLoRA को CUDA GPU और उस मशीन के CUDA के लिए बना bitsandbytes चाहिए। रन मॉडल लोड करने से पहले GPU पर कुछ संख्याएँ क्वांटाइज़ करके दोनों की जाँच करता है, और जब दोनों संस्करण मेल नहीं खाते तो त्रुटि दोनों संस्करणों के नाम बताती है। LLM फ़ाइन-ट्यूनिंग ट्यूटोरियल SFT और DPO रनों पर QLoRA को काम में लाता है।

Hugging Face Hub पर प्रकाशन

जिस सफल रन का मॉडल Potato सर्वर पर है, उसके पेज पर Publish to the Hugging Face Hub होता है। पुश मॉडल और रन से लिखा गया README.md मॉडल कार्ड अपलोड करता है, जिसमें ट्रेनर, बेस मॉडल और एडेप्टर, स्कीम और लेबल, स्प्लिट के आकार, होल्ड-आउट स्कोर और वह स्प्लिट जिस पर स्कोर मापा गया, और रन और बंडल id के नाम होते हैं। dp रन के कार्ड में एक "Differential privacy" पंक्ति भी होती है जिसमें लक्ष्य के विरुद्ध खर्च किया गया epsilon, delta और वह train स्प्लिट होता है जिसे गारंटी कवर करती है। रन ने जब लक्ष्य या delta दर्ज नहीं किया हो, तो पंक्ति उसे छोड़ देती है।

अपलोड फ़ाइलों की एक निश्चित सूची है, पूरी artifacts/ डायरेक्टरी नहीं। सूची में वेट फ़ाइलें, जैसे .safetensors, .bin, .pt और .pkl, सहेजी गई model/ डायरेक्टरी की config और टोकनाइज़र फ़ाइलें, स्थानीय पथों की जगह फ़ाइल नामों वाली model_card.json, और calibration.json हैं। प्रोजेक्ट के आइटम पर मॉडल के उत्तर (predictions.jsonl, और निर्णय मॉडलों के लिए raw_answers.jsonl) सर्वर पर ही रहते हैं। चेकपॉइंट, ऑप्टिमाइज़र स्टेट, कुछ ट्रेनरों द्वारा बनाई गई प्रशिक्षण डेटा की कॉपियाँ (yolo_data/, wev_data/, laya_data/), और artifacts/ के बाहर इशारा करने वाला कोई भी सिमलिंक भी छोड़ दिए जाते हैं।

फ़ॉर्म आकस्मिक या सार्वजनिक पुश से कई तरह से बचाता है:

• आप रिपॉज़िटरी का नाम दो बार लिखते हैं, और पुश तभी आगे बढ़ता है जब दोनों नाम मेल खाएँ।
• Private डिफ़ॉल्ट रूप से चुना हुआ है। जब तक Private चुना है, Potato किसी मौजूदा सार्वजनिक रिपॉज़िटरी पर पुश नहीं करता, और API 409 देता है।
• फ़ॉर्म सर्वर का वह एनवायरनमेंट वेरिएबल बताता है, डिफ़ॉल्ट रूप से HF_TOKEN, जिसमें Hugging Face write टोकन है। टोकन स्वयं पेज में कभी नहीं लिखा जाता। वेरिएबल के नाम में TOKEN होना चाहिए या वह HF_ से शुरू होना चाहिए, और मान hf_ से शुरू होना चाहिए, इसलिए किसी और वेरिएबल का मान Hub तक नहीं पहुँच सकता।
• जब Hub यह नहीं बता सकता कि रिपॉज़िटरी मौजूद है या नहीं, तो कुछ पुश नहीं होता, और पुश द्वारा बनाई गई रिपॉज़िटरी अपलोड विफल होने पर फिर से हटा दी जाती है।
• मॉडल कार्ड का लाइसेंस वह Hub लाइसेंस id है जो आप देते हैं, जैसे apache-2.0। कोई न देने पर कार्ड बताता है कि बेस मॉडल का लाइसेंस लागू होता है। जिस ट्रेनर के लाइसेंस की पुष्टि चाहिए, जैसे ultralytics-detect (AGPL-3.0), उसे पुश करने के लिए भी वही पुष्टि चाहिए।
• fetch_artifacts: false के साथ रिमोट होस्ट पर छोड़ा गया या agent बैकएंड पर प्रशिक्षित मॉडल सर्वर से पुश नहीं किया जा सकता, और त्रुटि बताती है कि मॉडल कहाँ है।

हर पुश एक कमिट है। रन का पेज हर पुश को रिपॉज़िटरी, दृश्यता और कमिट के साथ सूचीबद्ध करता है, और बही दर्ज करती है कि पुश किसने किया। API से, POST /admin/training/api/runs/<run_id>/push-to-hub की बॉडी repo_id, confirm_repo_id, private (डिफ़ॉल्ट true), token_env (डिफ़ॉल्ट HF_TOKEN), licence और accept_licence लेती है। रूट कमिट के साथ 201 लौटाता है, बेमेल, गायब टोकन वेरिएबल, कोई मॉडल फ़ाइल न होने, या अपुष्ट लाइसेंस के लिए 400, और Hub के इनकार करने पर 502।

समस्या निवारण

नीचे की प्रविष्टियाँ पहले सेटअप पर सबसे संभावित त्रुटियों को कवर करती हैं। अपस्ट्रीम समस्या निवारण सूची GPU ड्राइवर, CUDA बिल्ड और ट्रेनर-विशिष्ट संदेशों को कवर करती है।

• /admin/training 404 लौटाता है। model_training.enabled true नहीं है, और Potato रूट तभी पंजीकृत करता है जब कुंजी true हो।
• "Only N items in the train split". और आइटम एनोटेट करें, या रन के params में min_instances घटाएँ। train स्प्लिट डिफ़ॉल्ट रूप से लेबल किए गए आइटम का 70% रखता है।
• "Schema 'x' has 1 distinct label(s) in the data". क्लासिफ़ायर को उपयोग में कम से कम दो लेबल चाहिए।
• "No resolved annotations to train on". रन में बताया गया स्कीम उस स्कीम से अलग है जिसे एनोटेट किया जा रहा है, या अभी किसी ने कुछ एनोटेट नहीं किया।
• रन ने कोई प्री-लेबल प्रकाशित नहीं किया। GET /admin/training/api/status में writeback रिपोर्ट पढ़ें। "No predictions were published: write-back is not enabled for any schema" का अर्थ है कि writeback.schemas खाली है, और छोड़ने की गिनतियाँ बताती हैं कि हर जाँच ने कितनी भविष्यवाणियाँ हटाईं।
• <trainer> does not take <name>. रन में या trainer_params के नीचे का कोई पैरामीटर गलत वर्तनी का है या किसी दूसरे ट्रेनर का है। संदेश वे नाम सूचीबद्ध करता है जो ट्रेनर लेता है।
• मशीन की मेमोरी खत्म होने के बाद रन मार दिया गया। प्रोसेस SIGKILL पर निकली, आमतौर पर out-of-memory killer से। छोटा मॉडल या कम आइटम उपयोग करें, या max_ram_mb तय करें ताकि रन अपनी सीमा के भीतर विफल हो।
• "Stopped: the run took longer than model_training.max_wall_seconds". रन समय सीमा तक पहुँच गया। max_wall_seconds बढ़ाएँ, या कम आइटम पर प्रशिक्षित करें।
• "The GPU ran out of memory". batch_size घटाएँ और प्रभावी बैच बनाए रखने के लिए gradient_accumulation बढ़ाएँ, lora: true या lora: {quantize: 4bit} तय करें, या llm-sft के लिए gradient_checkpointing: true तय करें या छोटा मॉडल चुनें।
• "ssh to host failed: Permission denied". Potato ssh को BatchMode=yes के साथ चलाता है, इसलिए सर्वर के खाते से ssh <host> true बिना प्रॉम्प्ट के सफल होना चाहिए। पासफ़्रेज़ वाली कुंजी तब काम करती है जब ssh-agent उसे रखता है।
• agent बैकएंड पर रन कतार में ही रहता है। उस बैकएंड नाम वाला कोई एजेंट पोल नहीं कर रहा। potato training agent --backend <name> से एजेंट शुरू करें, और Training पेज पर Check से टोकन जाँचें।

आगे पढ़ें

• अपने एनोटेशन पर मॉडल प्रशिक्षण: प्रशिक्षण चक्र, Training पेज और एक त्वरित शुरुआत।
• ट्रेनर: हर ट्रेनर, हर ट्रेनर जिन स्कीमों से सीखता है, और इंस्टॉल कमांड।
• GPU सर्वर, SLURM क्लस्टर या NAT के पीछे की मशीन पर प्रशिक्षण: ssh, SLURM और पोलिंग-एजेंट बैकएंड चरण-दर-चरण।
• लूप में मॉडल: एक अध्ययन में राइट-बैक, समीक्षा, auto_retrain और डेटासेट संस्करण।
• सक्रिय अधिगम: आइटम को मॉडल की अनिश्चितता से क्रमबद्ध करना।
• रबर-स्टैंप किए गए प्री-लेबल का पता लगाना: यह जाँचना कि एनोटेटर प्री-लेबल को पढ़े बिना स्वीकार तो नहीं कर रहे।
• अपस्ट्रीम संदर्भ: हर ट्रेनर की पूरी पैरामीटर तालिकाएँ।

संदर्भ

• Dawid, A. P., and Skene, A. M. (1979). Maximum Likelihood Estimation of Observer Error-Rates Using the EM Algorithm. Applied Statistics, 28(1). https://doi.org/10.2307/2346806
• Dettmers, T., Pagnoni, A., Holtzman, A., and Zettlemoyer, L. (2023). QLoRA: Efficient Finetuning of Quantized LLMs. Advances in Neural Information Processing Systems 36 (NeurIPS 2023). https://proceedings.neurips.cc/paper_files/paper/2023/hash/1feb87871436031bdc0f2beaa62a049b-Abstract-Conference.html