सामग्री पर जाएं

आपकी IT टीम के लिए Potato सर्वर की आवश्यकताएँ

यह पृष्ठ अपनी IT या रिसर्च कंप्यूटिंग टीम को भेजें। Potato HTTPS के पीछे लिखने योग्य डिस्क के साथ एक प्रोसेस के रूप में चलता है और हर एनोटेशन उसी सर्वर पर रखता है।

Potato एनोटेशन अध्ययनों के लिए सेल्फ़-होस्टेड वेब ऐप्लिकेशन है। एक Potato प्रोसेस एक अध्ययन को सेवा देता है, हर एनोटेशन को अध्ययन के फ़ोल्डर के भीतर फ़ाइलों और SQLite डेटाबेस में रखता है, और HTTPS के लिए प्रोसेस के सामने रिवर्स प्रॉक्सी चाहता है। डिफ़ॉल्ट इंस्टॉल बाहरी सेवाओं को कुछ नहीं भेजता, और डेटा सर्वर से केवल उन सुविधाओं के ज़रिए निकलता है जिन्हें अध्ययन का कॉन्फ़िगरेशन चालू करता है।

यह पृष्ठ उन लोगों के लिए लिखा गया है जो किसी विश्वविद्यालय, अस्पताल या कंपनी में सर्वर चलाते हैं। जो शोधकर्ता अपना अध्ययन होस्ट करवाना चाहता है, वह इस पृष्ठ को जस का तस भेज सकता है, प्रोजेक्ट फ़ोल्डर और अगले खंड में सूचीबद्ध उत्तरों के साथ। अपना Potato अध्ययन ऑनलाइन करें उन रूटों को कवर करता है जो शोधकर्ता IT टीम के बिना ले सकता है।

शोध टीम से जानकारी

शोध टीम प्रोजेक्ट फ़ोल्डर भेजती है, जिसे Study Designer Download project (.zip) के रूप में निर्यात करता है। फ़ोल्डर में config.yaml है, जो अध्ययन का कॉन्फ़िगरेशन है, और वे डेटा फ़ाइलें हैं जिनके नाम कॉन्फ़िगरेशन देता है। फ़ोल्डर के साथ शोध टीम इन सवालों के उत्तर देती है:

  • कितने एनोटेटर भाग लेते हैं, और क्या एनोटेटर संस्था के खातों से साइन इन करते हैं या शोधकर्ता की सूची के यूज़रनेम से?
  • अध्ययन कब शुरू और ख़त्म होता है?
  • क्या आइटम या उत्तरों में व्यक्तिगत या संवेदनशील जानकारी है, और अध्ययन किस एथिक्स अनुमोदन के तहत चलता है?
  • क्या कॉन्फ़िगरेशन ऐसी AI सुविधाओं का उपयोग करता है जो आइटम को किसी मॉडल प्रोवाइडर को भेजती हैं? config.yaml में ai_support, chat_support और solo_mode जैसे ब्लॉक ऐसी सुविधाओं को दर्शाते हैं।

सॉफ़्टवेयर

Potato Flask पर बना Python वेब ऐप्लिकेशन है। सबसे सरल इंस्टॉल प्रकाशित Docker इमेज ghcr.io/davidjurgens/potato है, जो linux/amd64 और linux/arm64 के लिए बनी है। इमेज लगभग 900 MB की है, gunicorn के तहत Python 3.11 को बिना विशेषाधिकार वाले उपयोगकर्ता potato (uid 1000) के रूप में चलाती है, और पोर्ट 7860 पर सुनती है। प्रोजेक्ट फ़ोल्डर /app पर माउंट होता है:

bash
docker run -d --name potato-study --restart unless-stopped \
  -p 127.0.0.1:8000:7860 \
  -v /srv/potato/my-study:/app \
  -e POTATO_SECRET_KEY="$(openssl rand -hex 32)" \
  ghcr.io/davidjurgens/potato:2.14.0

कमांड अध्ययन को केवल होस्ट के लूपबैक इंटरफ़ेस के पोर्ट 8000 पर प्रकाशित करती है। तब रिवर्स प्रॉक्सी अंदर आने का एकमात्र रास्ता है। latest टैग Potato की डेवलपमेंट ब्रांच का पीछा करता है, और अध्ययन को संस्करण टैग पिन करना चाहिए। POTATO_SECRET_KEY को एक बार बनाएँ और मान रखें, क्योंकि हर शुरुआत पर नई कुंजी हर रीस्टार्ट पर हर एनोटेटर को साइन आउट कर देती है। /app uid 1000 के लिए लिखने योग्य न होने पर कंटेनर शुरू होने से मना कर देता है। कंटेनर को --user "$(id -u):$(id -g)" के साथ चलाएँ या फ़ोल्डर uid 1000 को दें। Docker में Potato चलाएँ इमेज के टैग और एनवायरनमेंट वेरिएबल कवर करता है।

Docker के बिना, Potato PyPI से Python 3.9 या नए संस्करण पर pip install potato-annotation से इंस्टॉल होता है। बैकअप और सिंगल साइन-ऑन के लिए hosting extra जोड़ें, और SAML साइन-इन के लिए saml extra जोड़ें, जो सिस्टम के libxmlsec1 के विरुद्ध बनता है। potato start config.yaml डेवलपमेंट सर्वर चलाता है जो हर प्रतिक्रिया के बाद कनेक्शन बंद कर देता है। इंटरनेट पर काम करने वाले एनोटेटरों के लिए Potato को gunicorn के तहत चलाएँ, जैसा प्रोडक्शन सेटअप दिखाता है, या potato start के सामने रिवर्स प्रॉक्सी लगाएँ।

प्रोसेस और वर्कर की संख्या

Potato आइटम पूल, असाइनमेंट कतार और हर एनोटेटर की स्थिति एक प्रोसेस की मेमोरी में रखता है। दूसरा gunicorn वर्कर या दूसरी रेप्लिका इन तीनों की अलग प्रति रखती है, ऐसे आइटम बाँट देती है जो पहला प्रोसेस पहले ही असाइन कर चुका है, और पहले प्रोसेस के सेव को अधिलेखित कर देती है। इसलिए इमेज GUNICORN_WORKERS के 1 से ऊपर होने पर शुरू होने से मना कर देती है। अधिक समवर्तिता के लिए GUNICORN_THREADS को डिफ़ॉल्ट 8 से बढ़ाएँ। Potato के अपने Docker दस्तावेज़ीकरण में आठ थ्रेड को उतना माना गया है जितने दर्जनों एक साथ काम करने वाले एनोटेटर किसी आम अध्ययन में होते हैं। कई अध्ययन कई कंटेनरों के रूप में चलाएँ, हर कंटेनर के अलग फ़ोल्डर और पोर्ट के साथ।

सर्वर का आकार

मेमोरी आइटमों की संख्या के साथ बढ़ती है। Potato के मापों में हर आइटम मेमोरी में 0.9 से 1.4 KB लेता है, और Potato के संदर्भ डेटासेट पर सर्वर ने लगभग 365 MB इस्तेमाल किया। Potato की अपनी क्लाउड कमांड potato deploy अधिकांश होस्टों पर 1 या 2 vCPU और 2 GB मेमोरी वाली मशीन चुनती है, जो शुरुआत के लिए उचित आकार है।

डिस्क स्थायी और लिखने योग्य होनी चाहिए, और उसमें डेटा फ़ाइलों, आइटमों में शामिल किसी भी मीडिया फ़ाइल और एनोटेशन के लिए जगह होनी चाहिए। जिस कंटेनर की डिस्क रीस्टार्ट पर मिट जाती है वह हर एनोटेशन खो देता है, जब तक नीचे बताया बिल्ट-इन बैकअप चालू न हो।

नेटवर्क एक्सेस और HTTPS

Potato को nginx, Apache या Caddy जैसे रिवर्स प्रॉक्सी से उपलब्ध कराएँ। प्रॉक्सी TLS प्रमाणपत्र रखता है और अनुरोधों को कंटेनर के पोर्ट पर भेजता है। इंटरनेट के लिए केवल पोर्ट 443 खुले होने चाहिए, और रीडायरेक्ट व प्रमाणपत्र नवीनीकरण के लिए 80। रिवर्स प्रॉक्सी दिखाता है कि Potato को https://host.example.edu/my-study/ जैसे URL पाथ के नीचे कैसे चलाएँ, X-Forwarded-Prefix हेडर के साथ POTATO_PROXY_FIX=1 से या POTATO_URL_PREFIX से। लाइव एजेंट व्यूअर server-sent events से स्ट्रीम करते हैं। अगर अध्ययन उन व्यूअरों का उपयोग करता है तो /api/ लोकेशन पर प्रॉक्सी बफ़रिंग बंद करें।

GET /health को प्रमाणीकरण नहीं चाहिए और सर्वर तैयार होने पर {"status": "ok"} लौटाता है, और जब तक सर्वर डेटा लोड कर रहा हो तब तक 503। लोड बैलेंसर या मॉनिटरिंग जाँच को उसी रूट पर लगाएँ।

Potato को डिफ़ॉल्ट रूप से आउटबाउंड नेटवर्क एक्सेस नहीं चाहिए। एनोटेटरों के ब्राउज़र जो स्क्रिप्ट, स्टाइलशीट और फ़ॉन्ट लोड करते हैं वे सर्वर से ही आते हैं, और एयर-गैप्ड और ऑफ़लाइन तैनाती सूचीबद्ध करता है कि Potato डिफ़ॉल्ट इंस्टॉल को ऑफ़लाइन कैसे रखता है। आउटबाउंड एक्सेस केवल उन सुविधाओं के लिए चाहिए जिन्हें कॉन्फ़िगरेशन चालू करता है:

  • AI सुविधाएँ उस मॉडल एंडपॉइंट को बुलाती हैं जिसका नाम कॉन्फ़िगरेशन देता है, जब तक एंडपॉइंट Ollama जैसा लोकल मॉडल सर्वर न हो।
  • बैकअप उस Hugging Face डेटासेट या S3 बकेट में लिखते हैं जिसका नाम कॉन्फ़िगरेशन देता है।
  • सिंगल साइन-ऑन पहचान प्रोवाइडर से संपर्क करता है।
  • रिमोट डेटा स्रोत उस बकेट या डेटाबेस से पढ़ते हैं जिसका नाम कॉन्फ़िगरेशन देता है।
  • जिन आइटमों में मीडिया का लिंक URL से दिया है, उनके लिए एनोटेटर का ब्राउज़र उस URL से मीडिया लाता है।

Potato कौन सी फ़ाइलें लिखता है

Potato सब कुछ अध्ययन के फ़ोल्डर में लिखता है:

प्रोजेक्ट फ़ोल्डर में पाथसामग्री
<output_annotation_dir>/<username>/user_state.jsonहर एनोटेटर के उत्तर, हर सेव पर पूरी तरह दोबारा लिखे जाते हैं
user_config.json, आउटपुट फ़ोल्डर के बगल मेंखातों की सूची, salted PBKDF2-SHA256 पासवर्ड हैश के साथ
project.sqlite, datasets.sqliteप्रोजेक्ट डेटा जैसे मेमो, कोडबुक और समीक्षा की स्थिति, SQLite के WAL मोड में
admin_api_key.txtबनाई गई एडमिन कुंजी, जो केवल सर्वर के उपयोगकर्ता द्वारा पढ़ी जा सकती है, जब कोई कुंजी सेट नहीं है
potato.logसर्वर लॉग

इसलिए एक डायरेक्टरी में पूरा अध्ययन रहता है। output_annotation_dir config.yaml की एक सेटिंग है, और Study Designer इसका मान output रखता है।

बैकअप

प्रोजेक्ट फ़ोल्डर का रात्रिकालीन बैकअप एनोटेशन फ़ाइलों और खातों की सूची को कवर करता है। दोनों SQLite फ़ाइलों को फ़ाइल की तरह नहीं, SQLite की अपनी backup कमांड से कॉपी करें, क्योंकि WAL मोड में चल रहे डेटाबेस की फ़ाइल-प्रति दूषित हो सकती है या हाल के लेखन छोड़ सकती है:

bash
sqlite3 /srv/potato/my-study/project.sqlite ".backup /backups/my-study/project.sqlite"

Potato का बिल्ट-इन बैकअप हर पाँच मिनट पर एनोटेशन आउटपुट और डेटाबेस के स्नैपशॉट को S3-संगत बकेट या निजी Hugging Face डेटासेट में कॉपी करता है। शुरू होने पर, डिस्क ख़ाली होने पर बैकअप बकेट से बहाल करता है, और डिस्क पर पहले से मौजूद एनोटेशन को कभी अधिलेखित नहीं करता। नीचे का ब्लॉक कॉपी को विश्वविद्यालय के ऑब्जेक्ट स्टोर में भेजता है। ब्लॉक को अध्ययन की config.yaml में जोड़ें, और कंटेनर के एनवायरनमेंट में POTATO_S3_ACCESS_KEY_ID और POTATO_S3_SECRET_ACCESS_KEY सेट करें:

yaml
backup:
  schedule_minutes: 5
  restore_on_boot: true
  sinks:
    - type: s3
      bucket: research-backups
      prefix: potato/my-study
      endpoint_url: https://s3.example.edu

प्रकाशित इमेज में बैकअप क्लाइंट शामिल हैं। pip इंस्टॉल को hosting extra चाहिए।

साइन-इन के विकल्प

Potato एनोटेटरों के साइन इन करने के कई तरीके समर्थित करता है, जो config.yaml में सेट होते हैं:

तरीकाकिसके लिएसर्वर को क्या चाहिए
पासवर्ड वाले नामित खाते (डिफ़ॉल्ट)एनोटेटरों की ज्ञात सूचीuser_config.users यूज़रनेम सूचीबद्ध करता है, allow_all_users: false के साथ। जो सूची में नहीं है उसका रजिस्ट्रेशन Potato अस्वीकार करता है
केवल यूज़रनेम (require_password: false)कम जोखिम वाले टास्क और कक्षा के अभ्यासऔर कुछ नहीं। यूज़रनेम की सूची फिर भी लागू रहती है
OAuth और OpenID ConnectGoogle, GitHub या Hugging Face खाते, या कोई OpenID Connect प्रोवाइडर जैसे Microsoft Entra ID या Oktaक्लाइंट ID और सीक्रेट, और प्रोवाइडर के पास पंजीकृत कॉलबैक URL https://<host>/auth/callback/<provider>
SAML 2.0Shibboleth, ADFS, और Okta व Microsoft Entra में SAML ऐपsaml extra, या --build-arg POTATO_EXTRAS=saml से बनी इमेज। Potato सर्विस-प्रोवाइडर मेटाडेटा /saml/metadata पर देता है और असर्शन /saml/acs पर लेता है
क्राउडसोर्सिंग प्लेटफ़ॉर्म के लिंकProlific, SONA, CloudResearch Connect और ऐसे ही प्लेटफ़ॉर्मप्लेटफ़ॉर्म का अध्ययन URL, जो सर्वर की ओर इंगित हो

पासवर्ड PBKDF2-SHA256 से 100,000 इटरेशन और हर उपयोगकर्ता के salt के साथ हैश होते हैं। भूला हुआ पासवर्ड एक बार इस्तेमाल होने वाले लिंक से रीसेट होता है जिसे Potato स्क्रीन पर दिखाता है, और Potato कोई ईमेल नहीं भेजता। जो प्रॉक्सी TLS समाप्त करता है, उसके पीछे SAML के लिए sp_base_url को सार्वजनिक पते पर सेट करें, वरना पहचान प्रोवाइडर की प्रतिक्रिया Potato की गंतव्य जाँच में विफल होती है। SSO और OAuth, पासवर्ड प्रबंधन और क्राउडसोर्सिंग इंटीग्रेशन हर तरीके का कॉन्फ़िगरेशन देते हैं।

एडमिन एक्सेस

/admin पर एडमिन डैशबोर्ड प्रगति, सहमति और हर एनोटेटर के उत्तर दिखाता है, और नतीजे डाउनलोड करता है। डैशबोर्ड एडमिन कुंजी से खुलता है। कुंजी POTATO_ADMIN_API_KEY से सेट करें, या Potato को पहली बार इस्तेमाल पर प्रोजेक्ट फ़ोल्डर में admin_api_key.txt बनाने दें, और कुंजी शोधकर्ता को ऐसे चैनल से दें जिस पर आपकी संस्था भरोसा करती है। किसी भी सर्वर पर config.yaml में debug: false रखें, क्योंकि डीबग मोड उन अनुरोधों के लिए एडमिन पेज बिना कुंजी के खोल देता है जो लोकल दिखते हैं, और उसी मशीन का प्रॉक्सी हर अनुरोध को लोकल दिखा सकता है।

डेटा सुरक्षा

Potato सेल्फ़-होस्टेड है, इसलिए एनोटेशन, खातों की सूची और आइटम उसी सर्वर पर रहते हैं जिसे आप चलाते हैं। Potato में कोई एनालिटिक्स या उपयोग रिपोर्टिंग नहीं है, और डिफ़ॉल्ट इंस्टॉल कोई आउटबाउंड कनेक्शन नहीं बनाता। डेटा सर्वर से केवल उन सुविधाओं के ज़रिए निकलता है जो नेटवर्क एक्सेस और HTTPS के नीचे सूचीबद्ध हैं, जिनमें से हर एक को अध्ययन के कॉन्फ़िगरेशन को चालू करना और गंतव्य बताना पड़ता है।

अध्ययन के एथिक्स अनुमोदन के विरुद्ध तीन बिंदु जाँचें:

  • एनोटेशन फ़ाइलें हर एनोटेटर को यूज़रनेम से नामित करती हैं, इसलिए ईमेल पते वाले यूज़रनेम डेटा में ईमेल पते डाल देते हैं।
  • अध्ययन के सर्वे पृष्ठ व्यक्तिगत जानकारी इकट्ठा कर सकते हैं, और उत्तर उन्हीं प्रति-एनोटेटर फ़ाइलों में रहते हैं।
  • जब कॉन्फ़िगरेशन आइटम को होस्टेड मॉडल प्रोवाइडर को भेजता है, तो आइटम उस प्रोवाइडर की शर्तों के तहत सर्वर से बाहर जाते हैं।

अध्ययन ख़त्म होने पर शोध टीम एडमिन डैशबोर्ड से नतीजे डाउनलोड करती है। टीम के साथ तय करें कि सर्वर की प्रति कितने समय रखी जाए, और उस तारीख़ के बाद प्रोजेक्ट फ़ोल्डर और कोई भी बैकअप बकेट हटा दें।

आगे पढ़ें