MaaS API: פיתוח עטיפה למודל AI עם FastAPI וניטור

פיתוח מעטפת API למודל AI: מה נשבר תחת עומס

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

בזרימה אמיתית זה הופך לפסיקות זמן בבקשות — התשובה האיטית הראשונה מחזיקה את החיבור, הלקוח נופל לפי מגבלת ההמתנה שלו, והשרת ממשיך לספור טוקנים.

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

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

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

מה נותנת המעטפת: השהיה, עמידות וניתוח כשלים

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

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

השני — שיעור הפניות המוצלחות. חזרות עם השהיה גדלה, הגבלת בקשות במקביל ושימוש חוזר בתשובות שכבר חושבו מנטרלים חלק מהכשלים לפני שהלקוח רואה אותם. שיעור הפניות המוצלחות מגיע ל-99%+ ומפסיק לרדת בשעות שיא.

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

העמידות של שירות AI נשענת על כך שלכל מחלקה יש תגובה משלה: חזרה, מעבר למודל חלופי או תשובת שגיאה מהירה וכנה במקום בקשה תקועה.

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

פורמטים של מעטפת API למודל AI: סינכרוני, זורם, באצוות

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

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

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

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

שלבי ההטמעה: מביקורת המודל ועד מסירת השירות

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

1. ביקורת אינטגרציות. אוספים את מקורות הבקשות, פורמטי הנתונים, דרישות ההרשאות ומגבלות המעגל: רשתות סגורות, תורים, שירותים שיקראו למודל.
2. סכמת האינטראקציה. מתארים את החוזה: מסלולים, מבנה הבקשה והתשובה, פעולות סינכרוניות ורקעיות, מגבלות קצב, זיהוי לקוחות ונוהל החלפת גרסת מודל.
3. הגדרת המעטפת. בונים את השירות על FastAPI: ולידציה של הקלט, פסיקות זמן וחזרות בכשלי מודל, מטמון, פורמט שגיאות אחיד ותשובות צפויות לצד הקורא.
4. נראות והגנה. מדדי השהיה ושיעור שגיאות, תיעוד בקשות (tracing), לוגים ללא נתונים אישיים, מפתחות גישה ותפקידים.
5. בדיקה תחת עומס. מריצים פרופיל של תעבורה אמיתית ובוחנים התנהגות בעת דעיכה: כשל של המודל או הפעלה מחדש שלו לא אמורים לעבור את המעטפת.
6. קבלת השירות. משווים את התוצאה לחוזה המוסכם, עוברים על התרחישים, מתעדים מדידות, מוסרים תיעוד, הרשאות ותקנון עדכונים.

תארו את המשימה — נחזור עם הערכת לוחות זמנים ותוכנית עבודה לפי השלבים האלה.

ערכת המסירה: קונפיגורציות, סכמות, תקנונים, הרשאות

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

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

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

קייס: איך השירות הפסיק ליפול בבקשות שיא

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

איך זה היה

שיעור השגיאות בשיא הגיע ל-9% — כמעט כל בקשה עשירית הסתיימה בסירוב או בחריגה ממגבלת הזמן. זמן התשובה הממוצע עמד על כ-5 שניות וגדל יחד עם העומס, ובקשות מסוימות בכלל לא החזירו תוצאה.

ניטור לא היה: על התקלה נודע מתלונות, ואי אפשר היה לומר מה בדיוק נכשל ראשון — השירות עצמו, המודל החיצוני או הרשת אליו.

מה שינו ומה נהיה

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

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

באותו עומס שיא שיעור השגיאות ירד ל-0,4%, וזמן התשובה לבקשה טיפוסית — ל-0,8 שניות. השירות מחזיק שיא של פי עשרה בלי התערבות ידנית, ואת הדעיכה רואים בהתראות לפני שהמשתמש מבחין בה.

במה נבדלת המעטפת מקריאה ישירה למודל?

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

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

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

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

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

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

ספקות טכניים: תורים, מטמון, עמידות בכשלים

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

האם תשובות המודל נשמרות במטמון?

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

מה יקרה בעת אי-זמינות של המודל?

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

איך מפרקים תקרית בדיעבד?

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

נדבר על המשימה: מה לשלוח להערכה ולתוכנית

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

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

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