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

במדריך הזה מפורטות אסטרטגיות ארכיטקטוניות לבניית ספריות, פלטפורמות ושערי גישה על בסיס Gemini API. במאמר מפורטים השיקולים הטכניים בין שימוש בערכות ה-SDK הרשמיות של GenAI, ב-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, כי הוא כולל את מספר השורות הכי קטן של קוד בשפות נתמכות.

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

הטבות:

• ממשק מאוחד להעברה אל Vertex AI: מפתחים פנימיים יוצרים לעיתים קרובות אב טיפוס באמצעות מפתחות API ‏ (Gemini API) ומבצעים פריסה אל Vertex AI ‏ (IAM) לצורך תאימות לייצור. ערכת ה-SDK מסתירה את ההבדלים האלה באימות. באופן דומה, כשמדובר במסגרות, אפשר להטמיע נתיב קוד אחד ולתמוך בשתי קבוצות של משתמשים.
• רכיבי עזר בצד הלקוח: ה-SDK כולל כלי עזר אידיומטיים שמצמצמים את הקוד הסטנדרטי למשימות מורכבות.
  • דוגמאות: תמיכה באובייקטים של תמונות PIL ישירות בהנחיות, קריאה אוטומטית לפונקציות וסוגים מקיפים.
• גישה לתכונות ביום ההשקה: תכונות חדשות של API זמינות בזמן ההשקה דרך ערכות ה-SDK.
• תמיכה משופרת ביצירת קוד: התקנה מקומית של SDK חושפת הגדרות של סוגים ומחרוזות docstring לעוזרים בתכנות (למשל, סמן, 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 אין תקורה של אתחול, ולכן הוא מצמצם את הזמן של אתחול קר בפונקציות ללא שרת.

הפשרה:

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

שיטה מומלצת

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

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

שילוב של OpenAI SDK

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

הטבות:

• הוספה פשוטה: בדרך כלל אפשר להוסיף תמיכה ב-Gemini על ידי שינוי התגים baseURL ו-apiKey. זו דרך מהירה לשלב הטמעות של 'הבאת מפתח משלך', ולהוסיף תמיכה ב-Gemini בלי לכתוב קוד חדש.
• הגבלות: מומלץ להשתמש בנתיב הזה רק אם אתם מוגבלים ל-OpenAI SDK ולא נדרשות לכם תכונות מתקדמות של Gemini כמו File API, או אם אתם מוסיפים תמיכה באופן ידני בכלים כמו Grounding עם חיפוש 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