ארנקים חיצוניים

ארנק חיצוני הוא שירות שאתם מפעילים, שמנהל את התקציב המשותף של כל לקוח, ושפריסה ייעודית של Nodaro Cloud פונה אליו לפני שהיא מוציאה קרדיטים. Nodaro מבקש מהארנק לשריין קרדיטים לפני כל יצירה, מבצע אחר כך חיוב סופי של הסכום המדויק, וקורא את היתרה כדי להציג אותה ללקוח. חשבון החיוב של הפריסה עדיין משלם על השימוש בפלטפורמה מתוך המאגר שלו, ששולם מראש; הארנק קובע כמה מהמאגר הזה כל לקוח יכול להוציא, בכל המוצרים שלכם.

איך החלקים משתלבים

• חשבון חיוב משלם. הפריסה מגדירה חשבון חיוב אחד (billing.payerAccount בפרופיל הממשק שלה), והמאגר שלו, ששולם מראש, משלם על כל פעולה בפריסה. ראו את הדף מהדורות ופרופילי ממשק.
• ה-SSO מזהה את הלקוח. לקוחות מתחברים דרך ספק ה-SSO של הפריסה. ה-subject שהספק נותן ללקוח, שנשלח כ-sso_subject, הוא הדרך שבה הארנק שלכם מזהה את הלקוח.
• הארנק מחליט. בכל בקשה להרצת רכיב יחיד ובכל רכיב בתהליך, Nodaro בודק את המאגר של חשבון החיוב, ששולם מראש, ואז מבקש מהארנק שלכם לשריין מתוך התקציב המשותף של הלקוח. ליתרת הקרדיטים המקומית של הלקוח ב-Nodaro אין שום תפקיד.

כשהמאגר ששולם מראש ריק, הבקשה יכולה להיעצר עוד לפני שפונים לארנק. אחרי שפונים אליו, ההחלטה של הארנק היא סופית לגבי התקציב המשותף של הלקוח.

הגדרת הפריסה

הגדירו את המשתנים האלה ב-API וב-workers:

• הגדירו את שלושת הראשונים יחד. כדי להשאיר את החיוב הקיים של הפריסה, השאירו את שלושתם לא מוגדרים.
• כבו את המכסות המקומיות. אכיפת המכסות לכל משתמש, billing.allowances: "enforce", חייבת להיות כבויה. תצורה שמשלבת את השניים נדחית בהפעלה.
• סכמו קודם על היחידה. לפני שאתם מפעילים את הארנק, סכמו על שער ההמרה בין קרדיטים של Nodaro לבין התקציב של המוצר שלכם. הגדירו בהתאם את billing.unitRate ואת billing.unitLabel בפרופיל הממשק, כדי ששני המוצרים יציגו את אותו מספר.

חוזה הבקשות

Nodaro שולח כל קריאה כבקשת POST עם גוף JSON שכולל את contract: 1 ואת unit: "nodaro_credit", ועם הכותרת Authorization: Bearer <token>. הסכומים הם בקרדיטים של Nodaro. לעולם אל תתייחסו אליהם כיחידות של המוצר שלכם בלי המרה מפורשת שהארנק שלכם אחראי עליה.

שריון

{
  "contract": 1,
  "unit": "nodaro_credit",
  "action": "reserve",
  "operation_id": "a3354131-4e5e-43a6-8f61-3914f09c658e",
  "job_id": null,
  "user_id": "5bf0d884-47b1-468e-a7b2-2433f957b267",
  "sso_provider": "partner",
  "sso_subject": "customer-123",
  "model_identifier": "example-model",
  "reserved_credits": 30
}

לפני שאתם עונים, שריינו את הסכום באופן אטומי מתוך התקציב המשותף הזמין של הלקוח. כדי לאשר את הבקשה:

{"contract":1,"unit":"nodaro_credit","operation_id":"a3354131-4e5e-43a6-8f61-3914f09c658e","decision":"allow","reserved_credits":30}

כשאין מספיק יתרה, או כשלחשבון אסור להוציא, ענו HTTP 200 עם אותה מעטפת ועם "decision": "deny"; אין צורך בסכום. על שגיאת שירות ענו עם סטטוס מחוץ לטווח 2xx.

שום דבר לא מגיע למודל אם הארנק שלכם לא מאשר את הבקשה. פסק זמן, תשובה פגומה, סכום או מזהה שלא תואמים, זהות חסרה ודחייה עוצרים כולם את הבקשה. הכותרת Idempotency-Key של הבקשה היא <operation_id>:reserve.

חיוב סופי או שחרור

כשהעבודה מסתיימת, Nodaro שולח את אותם שדות של הפעולה עם "action": "settle" ועם actual_credits. גבו בדיוק את הסכום הזה ושחררו את שאר השריון. חיוב סופי של 0 משחרר את כל השריון.

{"contract":1,"unit":"nodaro_credit","operation_id":"a3354131-4e5e-43a6-8f61-3914f09c658e","settled":true,"actual_credits":12}

• המפתח הוא <operation_id>:settle. כל בקשה נמסרת לפחות פעם אחת. ניסיון חוזר חייב להחזיר את התוצאה המקורית, בלי לגבות שוב.
• אל תקבלו התנגשויות. דחו בקשה לאותה פעולה עם זהות אחרת, תקרת שריון אחרת או סכום סופי אחר.
• חיוב סופי יכול להגיע לפני שריון שהתעכב. חיוב סופי של 0 חייב ליצור רשומה סופית וקבועה, גם לפעולה שעדיין לא מוכרת לכם. אסור ששריון שמגיע אחריו יפתח אותה מחדש.
• לשריונות אין תאריך תפוגה. יצירה, ובדיקה אנושית של התוצאה שלה, יכולות להימשך יותר מכל בקשת HTTP. שמרו כל שריון עד החיוב הסופי שלו, ושמרו את רשומות האידמפוטנטיות שלכם. לעולם אל תשחררו שריון פעיל בגלל שקריאה חוזרת מתעכבת.

יתרה

{"contract":1,"unit":"nodaro_credit","action":"balance","user_id":"5bf0d884-47b1-468e-a7b2-2433f957b267","sso_provider":"partner","sso_subject":"customer-123"}

{"contract":1,"unit":"nodaro_credit","sso_subject":"customer-123","available_credits":250}

• זמין פירושו אחרי השריונות. השדה available_credits מנכה את כל השריונות הפתוחים, בכל המוצרים שלכם.
• כאן מותרים שברים. היתרה יכולה לכלול שברים, כך שאפשר להציג גם שארית שקטנה מקרדיט אחד שאפשר לגבות. סכומי השריון והחיוב הסופי הם תמיד קרדיטים שלמים.
• מספר אחד באולפן. האולפן ממיר את היתרה פעם אחת ליחידת התצוגה של הפריסה, ומסתיר את תצוגת המכסה לכל משתמש שבו. כשהיתרה לא זמינה, היא מוצגת כלא ידועה.
• השריון מכריע במצבי מרוץ. כשבקשות מגיעות באותו רגע, הקריאה לשריון היא הקובעת, לא היתרה.

מסירה והתאוששות

• Nodaro מנסה למסור כל חיוב סופי מיד. אם המסירה נכשלת, worker שרץ כל דקה מנסה שוב, בהשהיה שהולכת וגדלה עד שעה אחת. חיובים סופיים שלא אושרה קבלתם נשמרים עד שהם נמסרים.
• Nodaro מבטל מעצמו רק שריונות שאף פעם לא אושרו. משימות מאושרות שרצות עוברות את ההתאוששות הרגילה של משימות.
• לעולם אל תסירו את תצורת הארנק, ואל תפנו אותה לארנק אחר, כל עוד יש פעולות פתוחות. כדי להחליף את האסימון, החליפו אותו באותו ארנק.

הכלים של חשבון החיוב

חשבון החיוב מנהל את המאגר של הפריסה בדף משלו, /billing-admin, כשהוא מחובר בסשן שלו.

טעינה אוטומטית של המאגר

בדף /billing-admin אפשר להפעיל טעינה אוטומטית. כשהמאגר יורד מתחת לסף, שנקבע בקרדיטים גולמיים, הכרטיס שנשמר בפעם האחרונה שחשבון החיוב קנה בכרטיס מחויב אוטומטית.

• המגבלות הרגילות חלות. כל חיוב הוא מ-$5 עד $1,000. יש לכל היותר 3 חיובים ביום, בהפרש של 10 דקות זה מזה, והטעינה האוטומטית נעצרת אחרי 3 חיובים שנכשלו.
• רק עבודה שהתחילה במוצר עצמו יכולה לגרום לחיוב. אסימוני API אישיים, אפליקציות OAuth, מופעים מחוברים וטריגרים של Webhook, של תזמון ושל טלגרם מוציאים קרדיטים מהמאגר, אבל אף פעם לא מחייבים את הכרטיס. כשהם מורידים את המאגר אל מתחת לסף, הוא נטען ביצירה הבאה שמתחילה באפליקציה.
• הכרטיס של לקוח אף פעם לא מחויב. הטעינה האוטומטית מיועדת רק למאגר של חשבון החיוב.
• קריאת הסטטוס. התגובה של GET /v1/deployment-billing/balance כוללת את autoRecharge: אם הטעינה האוטומטית מופעלת ופעילה, הסף, הסכום, החיובים שנכשלו והניסיון האחרון. הערך של autoRecharge הוא null כשאי אפשר לקרוא את הסטטוס.

טעינה אוטומטית דורשת פריסה שמקבלת תשלומים בכרטיס. בפריסה בלי תשלומים בכרטיס, מנהל השרת שלה טוען את המאגר בעצמו.

מפתחות לאינטגרציית חיוב

בדף /billing-admin אפשר גם ליצור מפתחות לאינטגרציית חיוב, למערכת אחרת כמו מערכת הניהול הפנימית שלכם. מפתח כזה ניגש רק ל-/v1/deployment-billing/*. הסוג שלו נקבע כשיוצרים אותו:

השתמשו במפתח לקריאה בלבד בכל מקום שבו צריך רק ניטור.

גילוי מחירים

הנתיב GET /v1/deployment-billing/pricing מחזיר את המחירון של הפריסה, לתצוגה ולתכנון של הארנק שלכם. נקודת הקצה דורשת את הסשן של חשבון החיוב או אחד ממפתחות אינטגרציית החיוב שלו.

• החיוב על מודלי טקסט הוא לפי מודל. ה-creditIdentifier של מודל טקסט הוא מפתח המחיר שלו ברכיב יצירת טקסט, llm-chat:<model>, עם :direct כשקריאת ברירת המחדל רצה ב-API של יצרן המודל עצמו. ה-creditCost שלו הוא אומדן: קריאה טיפוסית, שמחויבת לפי השימוש בפועל בטוקנים. הציגו אותו כמספר משוער, ≈N. על ה-Copilot, על רכיב מתכון תוכן ועל רכיב רעיונות לתוכן החיוב עדיין לפי שורת מדרגה, ואין בשורות שלהם estimate.
• מודל טקסט שאין לו מחיר בנתיב שלו מופיע ב-missing. הערכים isEnabled ו-category של מודל טקסט מגיעים מהשורה llm-chat.
• וריאנטים של מדיה מקבלים את המחיר שבתוקף. וריאנט בלי מחיר מוגדר נשאר null, עם קוד שגיאה.
• הגדרות, כמות, משך ושימוש מדוד יכולים לשנות את החיוב הסופי. בהנהלת החשבונות, הסתמכו על סכומי השריון והחיוב הסופי, ולעולם לא על תעריף בסיסי מהרשימה הזאת.
• כדי לזהות שינויים, עדיפה בקשה מלאה עם If-None-Match. הפרמטר since מתבסס על חותמות הזמן של שורות המחיר, ולא יכול לזהות כל שינוי בתצורה של סביבת הריצה.