חיבור ספק AI ורישום מודל

שלוש רמות שאין לערבב ביניהן

חיבור מודל ב-Sapphire I.C.D.S. מורכב משלוש רשומות נפרדות. הספק מתאר את השירות החיצוני: המפתח היציב שלו, כתובת הבסיס, המתאם המותקן וסוד הגישה. המודל שומר את מזהה המודל אצל אותו ספק ואת הגבולות הטכניים שלו. הפרופיל מגדיר את התנהגות העבודה בפועל: הוראת מערכת, תקציב הקשר, היקף תשובה ופרמטרים נוספים. ההפרדה הזאת מאפשרת להשתמש באותו מודל בכמה מצבים, בלי לשכפל את מפתח ה-API ובלי להחליף את המגבלות האמיתיות של המודל בהגדרות של משימה יחידה.

ההגדרה מתבצעת באזור הניהול AI Settings. יש להעניק אליו גישה דרך Helix. לפני שמתחילים, יש לקבל מהספק את הערכים העדכניים של base URL, model ID ומגבלות המודל שנבחר, ולוודא שהמתאם המתאים כבר מותקן בסביבת השרת של Sapphire. טקסט בשדה הטופס אינו מתקין ספרייה בעצמו.

שלב 1. יצירת ספק

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

Display name מיועד למפעילים ויכול להיות קריא לבני אדם. בשדה Base URL הזינו את כתובת הבסיס המתועדת ב-HTTPS של API הספק, ללא נתיב של מודל מסוים וללא אסימון ב-query string. אל תעתיקו כתובת ממסוף הדפדפן ואל תוסיפו לה נתיב סיום אקראי. אם הספק מציע כמה ממשקי API תואמים, השתמשו בגרסה שעבורה המתאם מותקן.

Vendor key חייב להתאים לגרסת הספק המותקנת שאותה המטעין התקני של הפלטפורמה מזהה. השדה Provider library הוא בסביבת הריצה הנוכחית fallback metadata לתאימות, וכאשר vendor key אינו ריק הוא בדרך כלל אינו קובע את המתאם. הוא אינו נתיב לקובץ ואינו מנגנון להתקנת ספרייה חדשה. אם גרסת ה-provider הדרושה אינה מותקנת, יש להעביר את המשימה למנהל הפריסה.

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

שלב 2. רישום המודל

עברו לאזור המודלים ובחרו בספק שנוצר זה עתה. Model key חייב להתאים במדויק למזהה שה-API מקבל, כולל מקפים, נקודות וסיומת גרסה. זה אינו כינוי שרירותי. לשם נוח קיים שדה נפרד Display name.

לאחר מכן העתיקו שלוש מגבלות מכרטיס המודל הרשמי. Maximum context הוא הגבול המלא של חלון ההקשר. Maximum input הוא הקלט המרבי המותר. Maximum output הוא גבול התשובה שנוצרת. כל הערכים מוגדרים כמספרים שלמים חיוביים ביחידות token. הקלט והפלט, כל אחד בנפרד, אינם יכולים להיות גדולים מההקשר המלא. אל תשתמשו בערך הקשר שיווקי אם ה-API או המסלול שנבחר מאפשרים פחות.

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

סדר הפעלה בטוח

1. צרו את הספק עם כתובת HTTPS נכונה ומתאם מותקן.
2. שמרו את הסוד וודאו שהרשימה מציגה סימן לכך שהוא קיים.
3. צרו את המודל עם model key מדויק ומגבלות מאומתות.
4. צרו פרופיל נפרד למודל; ללא פרופיל לא מוגדרת מדיניות עבודה.
5. הפעילו תחילה את המודל והספק לבדיקה מוגבלת, ורק לאחר מכן הגדירו את פרופיל ברירת המחדל.

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

שגיאות נפוצות

• שגיאת אימות: בדקו שהסוד קיים, בתוקף ושייך לפרויקט הנכון, והחליפו אותו רק בעת הצורך.
• Model not found: השוו את model key תו אחר תו לתיעוד ה-API וודאו שהחשבון מורשה להשתמש במודל.
• נתיב שגוי: בדקו את base URL, את המתאם שנבחר ואת היעדרו של נתיב מודל מכתובת הבסיס.
• דחיית המגבלות בשמירה: שלושת הערכים חייבים להיות חיוביים, ו-input ו-output אינם יכולים לחרוג מ-context.
• המודל אינו מופיע בזמן העבודה: הספק, המודל והפרופיל חייבים להיות מופעלים; הפרופיל חייב להפנות לאותו זוג ולהיות זמין למשתמש הנוכחי.

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

קבלה ותחזוקה

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

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