1. סקירה כללית
מה זה קריאה לפונקציה ב-Gemini?
Vertex AI Gemini API הוא משפחה של מודלים של AI גנרטיבי שפותחו על ידי Google DeepMind ומיועדים לתרחישי שימוש מולטי-מודאליים. הפעלת פונקציות היא תכונה במודלים של Gemini שמקלה על מפתחים לקבל פלט של נתונים מובְנים ממודלים גנרטיביים.
לאחר מכן, המפתחים יכולים להשתמש בתוצאות האלה כדי לקרוא לממשקי API אחרים ולהחזיר למודל את נתוני התגובה הרלוונטיים. במילים אחרות, קריאה לפונקציה עוזרת לכם לקשר את המודלים הגנרטיביים שלכם למערכות חיצוניות, כך שהתוכן שנוצר יכלול את המידע הכי עדכני ומדויק.
איך פועלת התקשרות לפונקציות
הפונקציות מתוארות באמצעות הצהרות על פונקציות, שעוזרות למודל הגנרטיבי להבין את המטרה והפרמטרים של הפונקציה. אחרי שמעבירים הצהרות על פונקציות בשאילתה למודל גנרטיבי, המודל מחזיר אובייקט מובנה שכולל את השמות של הפונקציות הרלוונטיות ואת הארגומנטים שלהן על סמך השאילתה של המשתמש. חשוב לזכור שבבקשה להפעלת פונקציה, המודל לא באמת מפעיל את הפונקציה. במקום זאת, אתם יכולים להשתמש בפונקציה ובפרמטרים שמוחזרים כדי לקרוא לפונקציה בכל שפה, ספרייה או מסגרת שתרצו.

מה תפַתחו
ב-codelab הזה תבנו צינור AI גנרטיבי באמצעות Vertex AI Gemini API ו-Python. באמצעות האפליקציה, המשתמשים יכולים לשאול על שערי חליפין, והמערכת תאחזר את הנתונים העדכניים ביותר מ-API חיצוני ותשיב למשתמש עם התשובה.
מה תלמדו
- איך מתקשרים עם מודל Gemini באמצעות ספריית הלקוח של Python
- איך מגדירים הצהרת פונקציה ורושמים אותה ככלי
- הדרכה: איך מתקשרים ל-Gemini ומקבלים תשובה של בקשה להפעלת פונקציה
- איך להחזיר את התשובה של הפונקציה ל-Gemini ולהשיב למשתמש
הדרישות
- פרויקט ב-Google Cloud
- דפדפן כמו Chrome
- סביבת פיתוח של Python, כמו Colab או Colab Enterprise
2. הגדרה ודרישות
כדי להתחיל להשתמש בהפעלת פונקציות ב-Gemini, צריך להפעיל את Vertex AI API ולהתקין את הגרסה האחרונה של ספריית הלקוח של Vertex AI Python.
הפעלת Vertex AI API
כדי להפעיל את Vertex AI API, פועלים לפי השלבים הבאים:
- בדפדפן, עוברים אל דף הפרטים של Vertex AI API Service.
- לוחצים על הלחצן Enable כדי להפעיל את Vertex AI API בפרויקט ב-Google Cloud.
התקנה של ספריית לקוח Python ל-Vertex AI
כדי להתקין את ספריות הלקוח של Python ל-Vertex AI, מבצעים את השלבים הבאים:
- פותחים טרמינל בסביבת הפיתוח.
- מוודאים שיש לכם סביבת פיתוח תקינה של Python, ואם צריך, נעזרים בהנחיות האלה.
- מריצים את הפקודה הבאה כדי להתקין את ספריית הלקוח של Python ל-Vertex AI:
pip install --upgrade google-cloud-aiplatform - אם אתם מריצים בסביבת מחברת, יכול להיות שתצטרכו להפעיל מחדש את זמן הריצה או את ליבת המערכת כדי להשתמש בחבילות שהותקנו לאחרונה.
עכשיו אתם מוכנים להשתמש ב-Vertex AI API.
3. הסבר על הבעיה
האם אי פעם השתמשתם במודל שפה גדול (LLM) או במודל AI גנרטיבי ושאלתם אותו על מידע עדכני או על מידע בזמן אמת, וקיבלתם תשובה עם מידע לא מעודכן או לא מדויק?
רוצים לנסות? קודם מייבאים את חבילות Python הרלוונטיות ומאתחלים את מודל Gemini. אפשר להריץ את הקוד הבא בסביבת פיתוח של Python, כמו Colab או Colab Enterprise, ועל ידי התקנת הגרסה האחרונה של Vertex AI SDK ל-Python:
import vertexai
from vertexai.generative_models import GenerativeModel
model = GenerativeModel("gemini-1.5-pro-001")
עכשיו, נשאל שאלה לגבי שער החליפין של מטבעות שונים היום:
response = model.generate_content(
"What's the exchange rate for euros to dollars today?"
)
print(response.text)
המודל אמור ליצור תגובה מוגבלת או לא עדכנית שדומה לתגובה הבאה:
As an AI language model, I don't have access to real-time currency exchange rates. However, as of my last update in September 2021, the approximate exchange rate between euros (EUR) and US dollars (USD) was: 1 EUR ≈ 1.18 USD Please note that currency exchange rates constantly fluctuate and can vary depending on various factors such as economic conditions, supply and demand, political events, and more. To obtain the most up-to-date and accurate exchange rate, I recommend using a reliable currency converter or financial website that provides live rates. [...]
אם משתמש קצה קיבל תשובה מהסוג הזה, הוא צריך לשנות את ההקשר כדי לחפש את המטבעות שמעניינים אותו, לאחזר את שער החליפין העדכני ולבצע המרות בעצמו.
באופן אידיאלי, צינור של מודל גנרטיבי יכול לטפל בחלק מהמשימות האלה או בכולן עבור המשתמש. בקטע הבא ננסה כמה פתרונות נפוצים כדי לקבל תשובות מובנות ממודלים גנרטיביים, כדי שתוכלו להפעיל מערכות חיצוניות.
4. פתרונות נפוצים
כשעובדים עם מודלים גנרטיביים בתרחישים שבהם צריך מידע עדכני או נתונים ממקורות חיצוניים, אפשר לקרוא ל-API חיצוני ואז להזין את התוצאות בחזרה למודל הגנרטיבי כדי שישתמש בהן בתשובה שלו.
לפני שקוראים למערכת חיצונית, צריך לקבוע את הפונקציה הנכונה לשימוש, לחלץ את הפרמטרים הרלוונטיים מהמשתמש ולהכניס את הפרמטרים לאובייקט נתונים מובנה. בדרך כלל צריך להשתמש בהנדסת הנחיות מקיפה כדי לגרום למודל הגנרטיבי להפיק נתונים מובנים תקינים.
נחזור לשאלה ששאלנו בקטע הקודם ונוסיף עוד הוראות למודל. אפשר לנסות לשלוח את הבקשה הבאה למודל Gemini:
user_prompt = "What's the exchange rate from euros to US dollars today?"
response = model.generate_content("""
Your task is to extract parameters from the user's input and return it as a
structured JSON payload. The user will ask about the exchange rate and which
currency they are converting from and converting to.
User input: {user_prompt}
Please extract the currencies as parameters and put them in a JSON object.
""".format(user_prompt=user_prompt))
print(response.text)
התוצאה היא תגובת הטקסט הבאה, שהיא לא בפורמט JSON תקין ולכן יהיה לנו קשה לעבוד איתה:
```json
{
"currency_from": "euros",
"currency_to": "US dollars"
}
```
לדוגמה, השורה הראשונה והשורה האחרונה של תגובת הטקסט כוללות גרשיים הפוכים כדי לתחום את בלוק הקוד, השורה הראשונה כוללת מזהה שפה, והערכים באובייקט JSON הם לא קיצורי המטבעות הסטנדרטיים בני שלוש האותיות ש-API של המרת מטבעות מצפה לקבל כפרמטרים של קלט.
אפשר לנסות להשתמש ב-Python כדי לבצע עיבוד לאחר יצירת הטקסט ולהפוך אותו ל-JSON ולמילון תקינים, להוסיף עוד הוראות להנחיה, לספק דוגמה אחת או יותר של הפלט הרצוי, לבצע כוונון עדין של המודל או לשלוח עוד קריאה למודל הגנרטיבי ולבקש ממנו לנקות את ה-JSON.
אבל יש דרך דטרמיניסטית יותר! במאמר הזה נסביר איך להשתמש ב-Gemini כדי להפעיל פונקציות, לשלוח שאילתות לשירותים חיצוניים ולקבל תשובות רלוונטיות למשתמשי הקצה.
5. איך פועלת התקשרות לפונקציות
לפני שנתחיל בתהליך של חילוץ פרמטרים והפעלת פונקציות, נסביר את השלבים של הפעלת פונקציות ואת הרכיבים שבהם נעשה שימוש בזמן הריצה.

קלט של משתמשים ל-Gemini API
ההנחיה מהמשתמש נשלחת אל Gemini API, ובקריאה ל-API הזו למודל Gemini, המפתח הגדיר הצהרה אחת או יותר על פונקציות בתוך כלי, כדי שמודל Gemini יידע אילו פונקציות הוא יכול להפעיל ואיך להפעיל אותן.
Gemini API מחזיר קריאה לפונקציה
על סמך התוכן של קלט המשתמש וההנחיה, Gemini יחזיר תשובה של בקשה להפעלת פונקציה עם נתונים מובְנים שכוללים את שם הפונקציה לקריאה ואת הפרמטרים המתאימים לשימוש.
שליחת בקשת API
לאחר מכן, תשתמשו בשם הפונקציה ובפרמטרים כדי לשלוח בקשת API לאחזור מידע ממערכת חיצונית או מ-API. בקשת ה-API והתשובה מיושמות על ידי המפתח בקוד האפליקציה, והן מתרחשות מחוץ להיקף של Gemini API ו-SDK. לדוגמה, אפשר להשתמש בספרייה requests ב-Python כדי לשלוח קריאה ל-API בארכיטקטורת REST ולקבל תגובה בפורמט JSON. אפשר גם להפעיל את הפונקציה באמצעות הגישה וספריית הלקוח המועדפות עליכם.
החזרת התשובה של ה-API אל Gemini
לבסוף, מעבירים את התשובה של ה-API בחזרה למודל Gemini כדי שהוא יוכל ליצור תשובה להנחיה הראשונית של משתמש הקצה, או להפעיל תשובה אחרת של קריאה לפונקציה אם מודל Gemini קובע שהוא צריך מידע נוסף.
6. בחירת ה-API
עכשיו, אחרי שהבנתם את התהליך הכללי ואת השלבים הספציפיים של קריאה לפונקציה, תבנו צינור נתונים של AI גנרטיבי כדי לאחזר את שערי החליפין העדכניים. קודם כול, צריך לבחור את ה-API שרוצים להשתמש בו כמקור מידע.
באפליקציה שלנו להמרת מטבעות, נשתמש ב-API בארכיטקטורת REST בכתובת https://www.frankfurter.app/ כדי לאחזר את המידע העדכני ביותר על שערי חליפין גלובליים.
כדי ליצור אינטראקציה עם ה-API בארכיטקטורת REST הזה, יכול להיות שנבצע קריאה ל-API בארכיטקטורת REST עם requests ב-Python באופן הבא:
import requests
url = "https://api.frankfurter.app/latest"
response = requests.get(url)
response.text
או בקשת cURL כמו:
curl https://api.frankfurter.app/latest
שמחזירה תגובה דומה לזו:
{
"amount": 1,
"base": "EUR",
"date": "2023-12-20",
"rates": {
"AUD": 1.6186, "BGN": 1.9558, "BRL": 5.3287,
"CAD": 1.4609, "CHF": 0.946, "CNY": 7.8121,
"CZK": 24.538, "DKK": 7.4565, "GBP": 0.86555,
"HKD": 8.5439, "HUF": 385.23, "IDR": 16994,
"ILS": 3.9983, "INR": 91.06, "ISK": 150.3,
"JPY": 157.12, "KRW": 1425.62, "MXN": 18.6867,
"MYR": 5.0977, "NOK": 11.2895, "NZD": 1.7421,
"PHP": 60.991, "PLN": 4.3413, "RON": 4.9699,
"SEK": 11.129, "SGD": 1.4562, "THB": 38.252,
"TRY": 31.883, "USD": 1.0944, "ZAR": 20.111
}
}
מכיוון שקריאה לפונקציה ב-Gemini לא מבצעת בפועל את הקריאה ל-API החיצוני בשבילכם, אין הגבלות על סוג ה-API שבו אתם משתמשים. אפשר להשתמש בשירות Cloud Run, בפונקציה של Cloud Functions, בבקשת API לשירות Google Cloud או בכל API חיצוני בארכיטקטורת REST.
7. הגדרת פונקציה וכלי
אחרי שבחרתם API בארכיטקטורת REST לשימוש, אפשר להגדיר מפרט API ולרשום את הפונקציה בכלי.
מוודאים שהתקנתם את הגרסה האחרונה של Vertex AI SDK ל-Python.
לאחר מכן, מייבאים את המודולים הנדרשים מ-Python SDK ומפעילים את מודל Gemini:
from vertexai.generative_models import (
Content,
FunctionDeclaration,
GenerativeModel,
Part,
Tool,
)
model = GenerativeModel("gemini-1.5-pro-001")
אם נחזור ל-API בארכיטקטורת REST בכתובת https://api.frankfurter.app/, נראה שהוא מקבל את פרמטרי הקלט הבאים:
פרמטר | סוג | תיאור |
| מחרוזת | המטבע שממנו רוצים להמיר |
| מחרוזת | המטבע שאליו רוצים להמיר |
| מחרוזת | התאריך שלגביו צריך לאחזר את שער החליפין |
הפרמטרים האלה מאפשרים ליצור מפרט OpenAPI חלקי ל-API בארכיטקטורת REST הזה בפורמט YAML:
openapi: 3.0.0
info:
title: Frankfurter Exchange Rate API
description: This API provides current and historical exchange rates
version: 1.0.0
servers:
- url: https://api.frankfurter.app
paths:
/{date}:
get:
summary: Get the latest currency exchange rates.
parameters:
- name: date
in: path
description: Get currency rates for a specific date or 'latest' if a date is not specified
required: true
schema:
type: string
- name: from
in: query
description: The currency to convert from.
required: true
schema:
type: string
- name: to
in: query
description: The currency to convert to.
schema:
type: string
עכשיו נרשום את זה כ-FunctionDeclaration באמצעות Python SDK ל-Gemini:
get_exchange_rate_func = FunctionDeclaration(
name="get_exchange_rate",
description="Get the exchange rate for currencies between countries",
parameters={
"type": "object",
"properties": {
"currency_date": {
"type": "string",
"description": "A date that must always be in YYYY-MM-DD format or the value 'latest' if a time period is not specified"
},
"currency_from": {
"type": "string",
"description": "The currency to convert from in ISO 4217 format"
},
"currency_to": {
"type": "string",
"description": "The currency to convert to in ISO 4217 format"
}
},
"required": [
"currency_from",
"currency_date",
]
},
)
חשוב להשתמש בתיאורים מפורטים ככל האפשר של הפונקציה והפרמטרים, כי המודל הגנרטיבי ישתמש במידע הזה כדי לקבוע איזו פונקציה לבחור ואיך למלא את הפרמטרים בבקשה להפעלת פונקציה.
לבסוף, מגדירים Tool שכולל את הצהרת הפונקציה:
exchange_rate_tool = Tool(
function_declarations=[get_exchange_rate_func],
)
בדוגמה הזו נעשה שימוש בהצהרת פונקציה אחת בכלי, אבל חשוב לדעת שאפשר לרשום הצהרת פונקציה אחת או יותר בכלי, והמודל יבחר את הפונקציה המתאימה לשימוש בזמן הריצה. פרטים נוספים על FunctionDeclaration, Tool ועל מחלקות קשורות ב-Gemini SDK ל-Python זמינים במאמר בנושא הפעלת פונקציות ב-Gemini API.
השלמתם את ההגדרה של הפונקציה והגדרות הכלים. בקטע הבא נשתמש בכלי הזה כדי לקרוא למודל הגנרטיבי ולקבל בחזרה בקשה להפעלת פונקציה שבה נוכל להשתמש כדי לקרוא ל-API בארכיטקטורת REST.
8. יצירת בקשה להפעלת פונקציה
עכשיו אפשר להזין הנחיה למודל הגנרטיבי ולכלול את tool שהגדרתם:
prompt = """What is the exchange rate from Australian dollars to Swedish krona?
How much is 500 Australian dollars worth in Swedish krona?"""
response = model.generate_content(
prompt,
tools=[exchange_rate_tool],
)
בואו נסתכל על אובייקט התגובה:
print(response.candidates[0].content)
role: "model"
parts {
function_call {
name: "get_exchange_rate"
args {
fields {
key: "currency_to"
value {
string_value: "SEK"
}
}
fields {
key: "currency_from"
value {
string_value: "AUD"
}
}
fields {
key: "currency_date"
value {
string_value: "latest"
}
}
}
}
}
נראה שהמודל בחר בפונקציה הזמינה והחזיר בקשה להפעלת פונקציה עבור הפונקציה get_exchange_rate יחד עם הפרמטרים. והפרמטרים הם בפורמט הנכון שרצינו. איזה יופי שהצלחתם לקבל תשובות מובנות ממודלים גנרטיביים!
בקטע הבא תשתמשו במידע שבתשובה כדי לשלוח בקשת API.
9. שליחת בקשת API
חשוב לזכור ש-Gemini לא מבצע בפועל את הקריאה ל-API החיצוני בשבילכם. אלא אתם יכולים להשתמש בכל שפה, ספרייה או framework שתרצו.
בשלב הזה תשתמשו בספריית requests ב-Python כדי לקרוא ל-API בארכיטקטורת REST של שער החליפין.
נפרק את התשובה למילון Python:
params = {}
for key, value in response.candidates[0].content.parts[0].function_call.args.items():
params[key[9:]] = value
params
עכשיו אפשר להתקשר אל requests או אל כל שיטה אחרת:
import requests
url = f"https://api.frankfurter.app/{params['date']}"
api_response = requests.get(url, params=params)
api_response.text
התוצאה היא תגובה שדומה לזו:
'{"amount":1.0,"base":"AUD","date":"2024-01-16","rates":{"SEK":6.8682}}'
קיבלנו את התשובה מ-API בארכיטקטורת REST, עם המידע העדכני על שער החליפין מהיום. בקטע הבא, נעביר את המידע הזה בחזרה למודל כדי שהוא יוכל ליצור תגובה רלוונטית למשתמש.
10. יצירת תשובה
לבסוף, ניצור תשובה למשתמש על ידי העברת התשובה של הפונקציה למודל בתור הבא של השיחה:
response = model.generate_content(
[
Content(role="user", parts=[
Part.from_text(prompt + """Give your answer in steps with lots of detail
and context, including the exchange rate and date."""),
]),
Content(role="function", parts=[
Part.from_dict({
"function_call": {
"name": "get_exchange_rate",
}
})
]),
Content(role="function", parts=[
Part.from_function_response(
name="get_exchange_rate",
response={
"content": api_response.text,
}
)
]),
],
tools=[exchange_rate_tool],
)
response.candidates[0].content.parts[0].text
אחרי שנעביר את התגובה של הפונקציה בחזרה למודל, הוא יגיב להנחיה של המשתמש יחד עם מידע רלוונטי מהתגובה של ה-API.
The exchange rate from Australian dollars to Swedish krona on January 16, 2024, is 1 Australian dollar is equal to 6.8663 Swedish krona. So, 500 Australian dollars would be worth 500 * 6.8663 = 3,433.15 Swedish krona.
11. הצגת הקוד המלא לדוגמה
בשלב הזה, אפשר להכניס את קוד Python ל-API של בק-אנד באמצעות שירות Cloud Run, פונקציה של Cloud Functions או שירות Cloud אחר, ולפרוס אפליקציית קצה קדמי שמשתמשת ב-API של הבק-אנד הזה כדי לבצע שאילתות של מודלים וקריאות ל-API.
זוהי דוגמה מלאה לקוד של הפתרון הסופי:
import requests
from vertexai.generative_models import (
Content,
FunctionDeclaration,
GenerativeModel,
Part,
Tool,
)
model = GenerativeModel("gemini-1.5-pro-001")
get_exchange_rate_func = FunctionDeclaration(
name="get_exchange_rate",
description="Get the exchange rate for currencies between countries",
parameters={
"type": "object",
"properties": {
"currency_date": {
"type": "string",
"description": "A date that must always be in YYYY-MM-DD format or the value 'latest' if a time period is not specified"
},
"currency_from": {
"type": "string",
"description": "The currency to convert from in ISO 4217 format"
},
"currency_to": {
"type": "string",
"description": "The currency to convert to in ISO 4217 format"
}
},
"required": [
"currency_from",
"currency_date",
]
},
)
exchange_rate_tool = Tool(
function_declarations=[get_exchange_rate_func],
)
prompt = """What is the exchange rate from Australian dollars to Swedish krona?
How much is 500 Australian dollars worth in Swedish krona?"""
response = model.generate_content(
prompt,
tools=[exchange_rate_tool],
)
response.candidates[0].content
params = {}
for key, value in response.candidates[0].content.parts[0].function_call.args.items():
params[key[9:]] = value
params
import requests
url = f"https://api.frankfurter.app/{params['date']}"
api_response = requests.get(url, params=params)
api_response.text
response = model.generate_content(
[
Content(role="user", parts=[
Part.from_text(prompt + """Give your answer in steps with lots of detail
and context, including the exchange rate and date."""),
]),
Content(role="function", parts=[
Part.from_dict({
"function_call": {
"name": "get_exchange_rate",
}
})
]),
Content(role="function", parts=[
Part.from_function_response(
name="get_exchange_rate",
response={
"content": api_response.text,
}
)
]),
],
tools=[exchange_rate_tool],
)
response.candidates[0].content.parts[0].text
בהטמעה הזו, השתמשנו בשתי בקשות למודל הגנרטיבי: בקשה אחת ליצירת בקשה להפעלת פונקציה ובקשה נוספת להחזרת התגובה של הפונקציה. חשוב לדעת: זו רק שיטה אחת לטיפול בקריאות לפונקציות ובתשובות לפונקציות באמצעות Gemini. אפשר גם לבצע קריאות נוספות לפונקציות כדי לקבל מידע נוסף על השאילתה, או להשתמש בקריאות לפונקציות עם שיטות צ'אט ואסינכרוניות.
דוגמאות קוד נוספות זמינות במחברת לדוגמה של הפעלת פונקציות ב-Gemini.
12. מזל טוב
השתמשתם בקריאה לפונקציה ב-Gemini כדי ליצור בהצלחה צינור עיבוד נתונים של AI גנרטיבי שמשתמש ב-Vertex AI Gemini API וב-Python. המשתמשים יכולים לשאול על שערי חליפין, והמערכת תאחזר את הנתונים העדכניים ביותר מ-API חיצוני ותשיב עם תשובה.
כשמשתמש קצה מזין הנחיה, התכונה 'קריאה לפונקציה' ב-Gemini בוחרת את הפונקציה המתאימה, מחלצת פרמטרים מההנחיה ומחזירה אובייקט של נתונים מובְנים כדי שתוכלו לבצע קריאה ל-API חיצוני.
העיצוב של קריאות לפונקציות ב-Gemini נועד לתת לכם את הטוב משני העולמות: חילוץ פרמטרים באופן דטרמיניסטי, וגם סיכום ויצירת תוכן על ידי המודל הגנרטיבי. אתם יכולים לנסות ממשקי API והנחיות אחרים בצינור העברת הנתונים ולבדוק את הפונקציות האחרות שקשורות ל-Vertex AI Gemini API.

הסרת המשאבים
כדי להימנע מחיובים בחשבון Google Cloud בגלל השימוש במשאבים שנעשה במסגרת ה-Codelab הזה, אפשר לבצע את פעולות הניקוי הבאות:
- כדי להימנע מחיובים מיותרים ב-Google Cloud, מומלץ למחוק את הפרויקט באמצעות מסוף Google Cloud אם הוא לא נחוץ לכם יותר.
- כדי להשבית את ממשקי ה-API של Vertex AI, עוברים אל דף הפרטים של Vertex AI API Service, לוחצים על Disable API ומאשרים.
מידע נוסף
כדי להמשיך ללמוד על AI גנרטיבי ועל AI בממשק שיחה, אפשר להיעזר במדריכים ובמקורות המידע הבאים:
- סקירה כללית של מודלים של Gemini
- תיעוד של קריאות לפונקציות ב-Gemini
- מחברת לדוגמה לקריאה לפונקציות ב-Gemini
- מחברות לדוגמה ל-Gemini
- AI גנרטיבי ב-Google Cloud
רישיון
עבודה זו מורשית תחת רישיון Creative Commons שמותנה בייחוס 2.0 כללי.