SDK של Python לארגזי חול ב־5 דקות: מ־pip install eqvps ועד ההרצה הראשונה

המדריך הזה לוקח אתכם מאפס עד ארגז חול שעובד ב־Python. תפעילו microVM מבודד של Firecracker, תריצו בו קוד, תתקינו חבילה, תעבירו קובץ פנימה והחוצה ותריצו משהו ארוך ברקע. כל שלב הוא כמה שורות שמדביקים כמו שהן.

צריך Python 3.8 ומעלה וחשבון EQVPS. ל־SDK אין תלויות.

1. השיגו טוקן

ארגזי החול משולמים מיתרת החשבון, ולכן ה־SDK צריך טוקן של החשבון. בעמוד חיבור החשבון מוסברות שלוש דרכים להשיג אותו: לוח הבקרה, ה־API או שרת ה־MCP. אחר כך שימו אותו במשתני הסביבה:

export EQVPS_API_KEY="your-token"

עדיין אין יתרה? אין בעיה. בפעם הראשונה שחשבון חדש יוצר ארגז חול בלי מספיק יתרה, הוא מקבל קרדיט של 1 דולר לארגזי חול, בתוקף ל־14 ימים.

2. התקינו את ה־SDK

pip install eqvps

3. הפעילו ארגז חול והריצו קוד

שמרו את זה בשם hello.py והריצו:

from eqvps import Sandbox

with Sandbox.create(tariff="small") as sb:
    print(sb.id)
    r = sb.run("import platform; print(platform.python_version())")
    print(r.exit_code, r.stdout)

תראו את מזהה ארגז החול (sb_ ועוד 24 תווים), ואחריו 0 3.12.x. ארגז החול עלה בתוך כשנייה, הריץ את הקוד ונמחק כשבלוק ה־with הסתיים.

כדאי לדעת על התוצאה:

• r.ok הוא true כשקוד היציאה 0 והפקודה לא הגיעה למגבלת הזמן;
• קוד יציאה שאינו אפס אינו חריגה, לכן בדקו את r.ok בעצמכם;
• stdout ו־stderr מוגבלים ל־1 MiB כל אחד, ו־r.truncated אומר אם הפלט נחתך.

4. התקינו חבילה והריצו פקודות shell

בתוך ארגז החול אתם root במערכת Linux קטנה עם Python, ‏Node.js, ‏git ו־curl. ‏exec מריץ כל פקודת shell:

from eqvps import Sandbox

with Sandbox.create(tariff="small") as sb:
    sb.exec("pip install --quiet requests", timeout=55)
    r = sb.run("import requests; print(requests.get('https://example.com').status_code)")
    print(r.stdout)   # 200

מגבלת הזמן ברירת המחדל היא 30 שניות, וקריאה סינכרונית נמשכת לכל היותר 55. התקנות גדולות מקומן במשימת רקע (שלב 6).

5. העבירו קבצים פנימה והחוצה

from eqvps import Sandbox

with Sandbox.create() as sb:
    sb.upload("/root/data.csv", "a,b\n1,2\n3,4\n")
    sb.run("""
import csv
rows = list(csv.DictReader(open('/root/data.csv')))
open('/root/sum.txt', 'w').write(str(sum(int(r['b']) for r in rows)))
""")
    print(sb.download_text("/root/sum.txt"))   # 6

הנתיבים חייבים להיות מוחלטים. העברה אחת מוגבלת ל־5 MB; ‏download מחזיר בייטים, ו־download_text מחרוזת.

6. הריצו משימה ארוכה ברקע

העבירו background=True ותקבלו משימה מיד, בלי לחכות. אין לה מגבלה של 55 שניות:

from eqvps import Sandbox

with Sandbox.create(tariff="standard") as sb:
    task = sb.exec("for i in 1 2 3 4 5; do echo step $i; sleep 20; done", background=True)
    result = task.wait(on_output=lambda out, err: print(out, end=""))
    print(result.state, result.exit_code)   # done 0

‏task.wait() בודק כל 2 שניות ומדפיס פלט חדש ברגע שהוא מגיע. אפשר גם לקרוא בעצמכם ל־task.logs(), או ל־task.kill() כדי לעצור. כל עוד משימה רצה, ארגז החול לא נמחק בגלל חוסר פעילות.

כמה זה עלה

כל בלוק with למעלה חי כמה שניות וחויב לפי המינימום של 60 שניות. ב־small זה 0.00055 דולר לבלוק, כך שחמש הדוגמאות יחד עולות בערך שליש סנט. המחירים של כל התעריפים, המצב הקבוע ומגבלות ההוצאה מופיעים במגבלות וחיוב של ארגזי חול.

כשמשהו נכשל

שגיאות ה־API הן חריגות שאפשר לתפוס:

from eqvps import Sandbox, InsufficientBalanceError, RateLimitError

try:
    with Sandbox.create() as sb:
        print(sb.run("print(1)").stdout)
except InsufficientBalanceError:
    print("Top up the balance")
except RateLimitError as e:
    print("Too many at once, retry in", e.retry_after)

ה־SDK כבר מנסה שוב תגובות 429 ו־503 עד שלוש פעמים כשהשרת אומר כמה לחכות. כל 11 מחלקות השגיאה מופיעות במדריך ה־SDK.

השלבים הבאים

• אותם שלבים ב־JavaScript: SDK של TypeScript לארגזי חול ב־5 דקות.
• תנו למודל AI לכתוב את הקוד ולהריץ אותו כאן: משימת הסוכן הראשונה שלכם בארגז חול.
• תעריפים, קרדיט ניסיון ומה יש בתוך ארגז חול: עמוד ארגזי החול.