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

במדריך הזה מפורטות אסטרטגיות ארכיטקטוניות ליצירת ספריות, פלטפורמות ושערי גישה שמבוססים על 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 Agent Platform: בניגוד ל-SDK, שימוש ישיר ב-API לא מטפל אוטומטית בהבדלים באימות בין AI Studio (מפתח API) לבין Gemini Enterprise Agent Platform‏ (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.5-flash: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