שילובים עם שותפים וספריות

במדריך הזה מפורטות אסטרטגיות ארכיטקטוניות ליצירת ספריות, פלטפורמות ושערי גישה שמבוססים על Gemini API. המאמר כולל הסברים מפורטים על ההבדלים הטכניים בין שימוש בערכות ה-SDK הרשמיות של AI גנרטיבי, ב-Direct API (REST/gRPC) ובשכבת התאימות של OpenAI.

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

מה זה שילוב שותף?

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

מסגרת אקוסיסטם

• מי אתם: מנהלים של מסגרת קוד פתוח (לדוגמה, LangChain,‏ LlamaIndex, ‏ Spring AI) או לקוחות ספציפיים לשפה.
• המטרה שלכם: תאימות רחבה. אתם רוצים שהספרייה תפעל בכל סביבה שהמשתמש יבחר בלי ליצור קונפליקטים.

סביבת זמן ריצה ופלטפורמת קצה

• מי אתם: פלטפורמות SaaS, שערים של AI או ספקי תשתית ענן (למשל, Vercel,‏ Cloudflare,‏ Zapier) שבהם מתבצעת הרצת קוד בסביבות מוגבלות.
• המטרה שלכם: ביצועים. אתם צריכים חבילה קטנה ככל האפשר, זמן אחזור נמוך והפעלה מהירה במצב התחלתי (cold start).

אתר אגרגטור

• מי אתם: פלטפורמות, שרתי proxy או 'גני מודלים' פנימיים שמנרמלים את הגישה למגוון רחב של ספקי מודלים גדולים של שפה (LLM) שונים (לדוגמה, OpenAI,‏ Anthropic, ‏ Google) לממשק יחיד.
• המטרה: ניידות ואחידות.

שער לארגונים

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

השוואה בקצרה

שיטה מומלצת לכל העולם: כל השותפים צריכים לשלוח את x-goog-api-client הכותרת ללא קשר לנתיב שנבחר.

שילוב של Google GenAI SDK

במקרה של מסגרות, הדרך הפשוטה ביותר היא בדרך כלל להטמיע את Google GenAI SDK, כי הוא כולל את מספר השורות הכי קטן של קוד בשפות נתמכות.

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

הטבות:

• ממשק מאוחד להעברה של Gemini Enterprise Agent Platform: מפתחים פנימיים יוצרים לעיתים קרובות אב טיפוס באמצעות מפתחות API ‏ (Gemini API) ומבצעים פריסה ב-Gemini Enterprise Agent Platform ‏ (IAM) לצורך תאימות לייצור. ערכת ה-SDK מסתירה את ההבדלים האלה באימות. באופן דומה, כשמדובר במסגרות, אפשר להטמיע נתיב קוד אחד ולתמוך בשתי קבוצות של משתמשים.
• עזרים בצד הלקוח: ערכת ה-SDK כוללת כלי עזר אידיומטיים שמצמצמים את הקוד הסטנדרטי למשימות מורכבות.
  • דוגמאות: תמיכה באובייקטים של תמונות PIL ישירות בהנחיות, קריאה אוטומטית לפונקציות וסוגים מקיפים.
• גישה לפיצ'רים ביום ההשקה: תכונות חדשות של API זמינות בזמן ההשקה דרך ערכות ה-SDK.
• תמיכה משופרת ביצירת קוד: התקנת ה-SDK המקומי חושפת הגדרות של סוגים ומחרוזות של תיעוד לעוזרים בתכנות (למשל, Cursor, ‏ Copilot). ההקשר הזה משפר את הדיוק של יצירת הקוד בהשוואה ליצירת בקשות REST גולמיות.

הפשרה:

• משקל ומורכבות של יחסי תלות: לערכות ה-SDK יש יחסי תלות משלהן, שיכולים להגדיל את גודל החבילה ולהגדיל את הסיכון בשרשרת האספקה.
• ניהול גרסאות: תכונות חדשות של API מוצמדות לרוב לגרסאות SDK מינימליות. יכול להיות שתצטרכו לשלוח עדכונים למשתמשים כדי שהם יוכלו לגשת לתכונות או למודלים חדשים. במקרים מסוימים, יכול להיות שיהיה צורך לבצע שינויים בתלות טרנזיטיבית שמשפיעה על המשתמשים.
• מגבלות פרוטוקול: ערכות ה-SDK תומכות רק ב-HTTPS עבור ה-API הראשי וב-WebSockets ‏ (WSS) עבור Live API. אין תמיכה ב-gRPC באמצעות לקוחות SDK ברמה גבוהה.
• תמיכה בשפות: ערכות ה-SDK תומכות בגרסאות שפה עדכניות. אם אתם צריכים לתמוך בגרסאות שהגיעו לסוף החיים (למשל, Python 3.9), תצטרכו לשמור על הסתעפות.

שיטה מומלצת:

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

שילוב ישיר של API

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

הטבות:

• גישה מלאה לפיצ'רים: בניגוד לשכבת התאימות של OpenAI, שימוש ישיר ב-API מאפשר גישה לפיצ'רים ספציפיים של Gemini, כמו העלאה ל-File API, יצירת מטמון תוכן ושימוש ב-Live API הדו-כיווני.
• תלות מינימלית: בסביבה שבה התלות רגישה בגלל גודל או עלויות ביקורת. שימוש ב-API ישירות דרך ספרייה רגילה כמו fetch או דרך wrapper כמו httpx מבטיח שהספרייה תישאר קלה.
• לא תלוי בשפה: זו הדרך היחידה לשפות שלא נכללות ב-SDK, כמו Rust,‏ PHP ו-Ruby, כי אין הגבלות על השפה.
• ביצועים: ל-Direct API אין תקורה של אתחול, ולכן הוא מצמצם את ההפעלה הקרה בפונקציות ללא שרת.

הפשרה:

• הטמעה ידנית של פלטפורמת הסוכנים של Gemini Enterprise: בניגוד ל-SDK, שימוש ישירות ב-API לא מטפל אוטומטית בהבדלים באימות בין AI Studio (מפתח API) לבין פלטפורמת הסוכנים של Gemini Enterprise‏ (IAM). אם רוצים לתמוך בשתי הסביבות, צריך להטמיע אמצעי טיפול נפרדים באימות.
• אין טיפוסים או עוזרים מקוריים: לא תקבלו השלמות קוד או בדיקות בזמן ההידור לאובייקטים של בקשות, אלא אם תטמיעו אותם בעצמכם. אין "עזרים" ללקוח (למשל, ממירים של פונקציות לסכימות), ולכן צריך לכתוב את הלוגיקה הזו באופן ידני.

שיטה מומלצת

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

• נקודת קצה (endpoint): https://generativelanguage.googleapis.com/$discovery/OPENAPI3_0

שילוב של OpenAI SDK

אם אתם משתמשים בפלטפורמה שבה יש עדיפות לסכימה מאוחדת (OpenAI Chat Completions) על פני תכונות ספציפיות למודל, זהו המסלול המהיר ביותר.

הטבות:

• הוספה פשוטה: בדרך כלל אפשר להוסיף תמיכה ב-Gemini על ידי שינוי התגים baseURL ו-apiKey. זו דרך מהירה לשלב הטמעות של 'הבאת מפתח משלך', ולהוסיף תמיכה ב-Gemini בלי לכתוב קוד חדש.
• הגבלות: מומלץ להשתמש בנתיב הזה רק אם אתם מוגבלים ל-OpenAI SDK ולא נדרשות לכם תכונות מתקדמות של Gemini כמו File API, או אם אתם מוסיפים תמיכה באופן ידני בכלים כמו עיגון באמצעות חיפוש Google.

הפשרה:

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

שיטה מומלצת

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

שיטה מומלצת לכל השותפים: זיהוי לקוחות

כשמבצעים קריאות ל-Gemini API כפלטפורמה או כספרייה, צריך לזהות את הלקוח באמצעות הכותרת x-goog-api-client.

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

משתמשים בפורמט company-product/version (לדוגמה, acme-framework/1.2.0).

דוגמאות להטמעה

from google import genai

client = genai.Client(
    api_key="...",
    http_options={
        "headers": {
            "x-goog-api-client": "acme-framework/1.2.0",
        }
    }
)

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent?key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -H 'x-goog-api-client: acme-framework/1.2.0' \
    -d '{...}'

from openai import OpenAI

client = OpenAI(
    api_key="...",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
    default_headers={
        "x-goog-api-client": "acme-framework-oai/1.2.0",
    }
)

השלבים הבאים

• בסקירה הכללית של הספריות אפשר לקרוא על ערכות ה-SDK של AI גנרטיבי
• עיון בהפניית ה-API
• קריאת מדריך התאימות של OpenAI