ההארקה באמצעות מפות Google מחברת בין היכולות הגנרטיביות של Gemini לבין הנתונים העשירים, העובדתיים והעדכניים של מפות Google. התכונה הזו מאפשרת למפתחים לשלב בקלות באפליקציות שלהם פונקציונליות שמבוססת על מיקום. כשהשאילתה של המשתמש כוללת הקשר שקשור לנתונים של מפות Google, מודל Gemini משתמש במפות Google כדי לספק תשובות עדכניות ומדויקות מבחינה עובדתית שרלוונטיות למיקום הספציפי או לאזור הכללי שהמשתמש ציין.
- תשובות מדויקות שמודעות למיקום: שימוש בנתונים המקיפים והעדכניים של מפות Google לשאילתות ספציפיות מבחינה גיאוגרפית.
- התאמה אישית משופרת: התאמה של ההמלצות והמידע על סמך המיקומים שהמשתמשים סיפקו.
- ווידג'טים ומידע לפי הקשר: טוקנים של הקשר להצגת ווידג'טים אינטראקטיביים של מפות Google לצד תוכן שנוצר.
שנתחיל?
בדוגמה הזו אפשר לראות איך לשלב Grounding עם מפות Google באפליקציה כדי לספק תשובות מדויקות לשאילתות של משתמשים, בהתאם למיקום שלהם. ההנחיה מבקשת המלצות מקומיות עם מיקום משתמש אופציונלי, ומאפשרת למודל Gemini להשתמש בנתונים של מפות Google.
Python
from google import genai
from google.genai import types
client = genai.Client()
prompt = "What are the best Italian restaurants within a 15-minute walk from here?"
response = client.models.generate_content(
model='gemini-2.5-flash-lite',
contents=prompt,
config=types.GenerateContentConfig(
# Turn on grounding with Google Maps
tools=[types.Tool(google_maps=types.GoogleMaps())],
# Optionally provide the relevant location context (this is in Los Angeles)
tool_config=types.ToolConfig(retrieval_config=types.RetrievalConfig(
lat_lng=types.LatLng(
latitude=34.050481, longitude=-118.248526))),
),
)
print("Generated Response:")
print(response.text)
if grounding := response.candidates[0].grounding_metadata:
if grounding.grounding_chunks:
print('-' * 40)
print("Sources:")
for chunk in grounding.grounding_chunks:
print(f'- [{chunk.maps.title}]({chunk.maps.uri})')
JavaScript
import { GoogleGenAI } from "@google/gnai";
const ai = new GoogleGenAI({});
async function generateContentWithMapsGrounding() {
const response = await ai.models.generateContent({
model: "gemini-2.5-flash",
contents: "What are the best Italian restaurants within a 15-minute walk from here?",
config: {
// Turn on grounding with Google Maps
tools: [{ googleMaps: {} }],
toolConfig: {
retrievalConfig: {
// Optionally provide the relevant location context (this is in Los Angeles)
latLng: {
latitude: 34.050481,
longitude: -118.248526,
},
},
},
},
});
console.log("Generated Response:");
console.log(response.text);
const grounding = response.candidates[0]?.groundingMetadata;
if (grounding?.groundingChunks) {
console.log("-".repeat(40));
console.log("Sources:");
for (const chunk of grounding.groundingChunks) {
if (chunk.maps) {
console.log(`- [${chunk.maps.title}](${chunk.maps.uri})`);
}
}
}
}
generateContentWithMapsGrounding();
REST
curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite:generateContent' \
-H 'Content-Type: application/json' \
-H "x-goog-api-key: ${GEMINI_API_KEY}" \
-d '{
"contents": [{
"role": "user",
"parts": [{
"text": "What are the best Italian restaurants within a 15-minute walk from here?"
}]
}],
"tools": [{"googleMaps": {}}],
"toolConfig": {
"retrievalConfig": {
"latLng": {"latitude": 34.050481, "longitude": -118.248526}
}
}
}'
איך מתבצעת הארקה באמצעות מפות Google
ההארקה באמצעות מפות Google משלבת את Gemini API עם המערכת האקולוגית של Google Geo באמצעות Maps API כמקור הארקה. כששאילתה של משתמש מכילה הקשר גיאוגרפי, מודל Gemini יכול להפעיל את ההארקה באמצעות הכלי 'מפות Google'. לאחר מכן, המודל יכול ליצור תשובות שמבוססות על נתונים ממפות Google שרלוונטיים למיקום שצוין.
התהליך כולל בדרך כלל:
- שאילתת משתמש: משתמש שולח שאילתה לאפליקציה שלכם, שיכולה לכלול הקשר גיאוגרפי (למשל, "coffee shops near me" (בתי קפה בסביבה), "museums in San Francisco" (מוזיאונים בסן פרנסיסקו).
- הפעלת כלי: מודל Gemini מזהה את הכוונה הגיאוגרפית ומפעיל את כלי ההארקה עם מפות Google. אפשר גם לספק לכלי הזה את
latitude
וlongitude
של המשתמש כדי לקבל תוצאות שמתאימות למיקום. - אחזור נתונים: שירות ה-Grounding עם מפות Google שולח שאילתות למפות Google כדי לאחזר מידע רלוונטי (למשל, מקומות, ביקורות, תמונות, כתובות, שעות פתיחה).
- יצירה מבוססת-קרקע: הנתונים שנשלפו ממפות Google משמשים ליצירת התשובה של מודל Gemini, כדי להבטיח דיוק עובדתי ורלוונטיות.
- אסימון של תגובה ווידג'ט: המודל מחזיר תגובה טקסטואלית, שכוללת ציטוטים ממקורות במפות Google. אופציונלית, תגובת ה-API עשויה להכיל גם
google_maps_widget_context_token
, שיאפשר למפתחים להציג בווידג'ט של מפות Google בהקשר המתאים באפליקציה שלהם, כדי ליצור אינטראקציה ויזואלית.
למה ומתי כדאי להשתמש בהארקה באמצעות מפות Google
ההארקה באמצעות מפות Google מתאימה במיוחד לאפליקציות שנדרש בהן מידע מדויק, עדכני וספציפי למיקום. הוא משפר את חוויית המשתמש באמצעות תוכן רלוונטי ומותאם אישית שמבוסס על מסד הנתונים הנרחב של מפות Google, שכולל יותר מ-250 מיליון מקומות ברחבי העולם.
כדאי להשתמש ב-Grounding עם מפות Google כשהאפליקציה צריכה:
- לספק תשובות מלאות ומדויקות לשאלות שקשורות למיקום גיאוגרפי ספציפי.
- פיתוח כלים לשיחה לתכנון טיולים ומדריכים מקומיים.
- המלצה על נקודות עניין על סמך מיקום והעדפות משתמש, כמו מסעדות או חנויות.
- ליצור חוויות מבוססות-מיקום לשירותים חברתיים, קמעונאיים או למשלוחי אוכל.
ההארקה באמצעות מפות Google מצטיינת בתרחישי שימוש שבהם נתונים עובדתיים עדכניים וקרבה הם קריטיים, כמו חיפוש של "בית הקפה הכי טוב בסביבה שלי" או קבלת הוראות הגעה.
שיטות ופרמטרים של API
ההארקה באמצעות מפות Google נחשפת דרך Gemini API ככלי בשיטה generateContent
. כדי להפעיל ולשנות את ההגדרות של Grounding באמצעות מפות Google, צריך לכלול אובייקט googleMaps
בפרמטר tools
של הבקשה.
JSON
{
"contents": [{
"parts": [
{"text": "Restaurants near Times Square."}
]
}],
"tools": { "googleMaps": {} }
}
בנוסף, הכלי googleMaps
יכול לקבל פרמטר בוליאני enableWidget
, שמשמש כדי לקבוע אם השדה googleMapsWidgetContextToken
יוחזר בתגובה. אפשר להשתמש בזה כדי להציג ווידג'ט הקשרי של מקומות.
JSON
{
"contents": [{
"parts": [
{"text": "Restaurants near Times Square."}
]
}],
"tools": { "googleMaps": { "enableWidget": true } }
}
בנוסף, הכלי תומך בהעברת המיקום ההקשרי כ-toolConfig
.
JSON
{
"contents": [{
"parts": [
{"text": "Restaurants near here."}
]
}],
"tools": { "googleMaps": {} },
"toolConfig": {
"retrievalConfig": {
"latLng": {
"latitude": 40.758896,
"longitude": -73.985130
}
}
}
}
הסבר על התגובה לקרקוע
אם התשובה מבוססת על נתונים ממפות Google, היא תכלול את השדה groundingMetadata
.
הנתונים המובנים האלה חיוניים לאימות ההצהרות וליצירת חוויית ציטוט עשירה באפליקציה, וגם לעמידה בדרישות השימוש בשירות.
JSON
{
"candidates": [
{
"content": {
"parts": [
{
"text": "CanteenM is an American restaurant with..."
}
],
"role": "model"
},
"groundingMetadata": {
"groundingChunks": [
{
"maps": {
"uri": "https://maps.google.com/?cid=13100894621228039586",
"title": "Heaven on 7th Marketplace",
"placeId": "places/ChIJ0-zA1vBZwokRon0fGj-6z7U"
},
// repeated ...
}
],
"groundingSupports": [
{
"segment": {
"startIndex": 0,
"endIndex": 79,
"text": "CanteenM is an American restaurant with a 4.6-star rating and is open 24 hours."
},
"groundingChunkIndices": [0]
},
// repeated ...
],
"webSearchQueries": [
"restaurants near me"
],
"googleMapsWidgetContextToken": "widgetcontent/..."
}
}
]
}
Gemini API מחזיר את המידע הבא עם groundingMetadata
:
-
groundingChunks
: מערך של אובייקטים שמכילים את מקורותmaps
(uri
,placeId
ו-title
). -
groundingSupports
: מערך של מקטעים לחיבור טקסט התגובה של המודל למקורות ב-groundingChunks
. כל מקטע מקשר בין טווח טקסט (מוגדר על ידיstartIndex
ו-endIndex
) לביןgroundingChunkIndices
אחד או יותר. זהו המפתח ליצירת ציטוטים בגוף הטקסט. -
googleMapsWidgetContextToken
: אסימון טקסט שאפשר להשתמש בו כדי לעבד ווידג'ט של מקומות בהקשר.
במסמכי ההסבר על Grounding עם חיפוש Google יש דוגמה לקטע קוד שמראה איך להציג ציטוטים בגוף הטקסט.
הצגת הווידג'ט ההקשרי של מפות Google
כדי להשתמש ב-googleMapsWidgetContextToken
שמוחזר, צריך לטעון את Google Maps JavaScript API.
תרחישים לדוגמה
ההארקה באמצעות מפות Google תומכת במגוון תרחישים לדוגמה שמתבססים על מיקום. בדוגמאות הבאות מוסבר איך אפשר להשתמש בהנחיות ובפרמטרים שונים כדי להסתמך על נתונים ממפות Google. המידע בתוצאות המבוססות על נתונים במפות Google עשוי להיות שונה מהמצב בפועל.
איך עונים על שאלות ספציפיות לגבי מקום
אתם יכולים לשאול שאלות מפורטות על מקום ספציפי ולקבל תשובות שמבוססות על ביקורות של משתמשים ב-Google ועל נתונים אחרים במפות Google.
Python
from google import genai
from google.genai import types
client = genai.Client()
prompt = "Is there a cafe near the corner of 1st and Main that has outdoor seating?"
response = client.models.generate_content(
model='gemini-2.5-flash-lite',
contents=prompt,
config=types.GenerateContentConfig(
# Turn on the Maps tool
tools=[types.Tool(google_maps=types.GoogleMaps())],
# Provide the relevant location context (this is in Los Angeles)
tool_config=types.ToolConfig(retrieval_config=types.RetrievalConfig(
lat_lng=types.LatLng(
latitude=34.050481, longitude=-118.248526))),
),
)
print("Generated Response:")
print(response.text)
if grounding := response.candidates[0].grounding_metadata:
if chunks := grounding.grounding_chunks:
print('-' * 40)
print("Sources:")
for chunk in chunks:
print(f'- [{chunk.maps.title}]({chunk.maps.uri})')
```
JavaScript
import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
async function run() {
const prompt = "Is there a cafe near the corner of 1st and Main that has outdoor seating?";
const response = await ai.models.generateContent({
model: 'gemini-2.5-flash',
contents: prompt,
config: {
// Turn on the Maps tool
tools: [{googleMaps: {}}],
// Provide the relevant location context (this is in Los Angeles)
toolConfig: {
retrievalConfig: {
latLng: {
latitude: 34.050481,
longitude: -118.248526
}
}
}
},
});
console.log("Generated Response:");
console.log(response.text);
const chunks = response.candidates[0].groundingMetadata?.groundingChunks;
if (chunks) {
console.log('-'.repeat(40));
console.log("Sources:");
for (const chunk of chunks) {
if (chunk.maps) {
console.log(`- [${chunk.maps.title}](${chunk.maps.uri})`);
}
}
}
}
run();
REST
curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite:generateContent' \
-H 'Content-Type: application/json' \
-H "x-goog-api-key: ${GEMINI_API_KEY}" \
-d '{
"contents": [{
"role": "user",
"parts": [{
"text": "Is there a cafe near the corner of 1st and Main that has outdoor seating?"
}]
}],
"tools": [{"googleMaps": {}}],
"toolConfig": {
"retrievalConfig": {
"latLng": {"latitude": 34.050481, "longitude": -118.248526}
}
}
}'
התאמה אישית על סמך מיקום
לקבל המלצות שמותאמות להעדפות של משתמש ולאזור גיאוגרפי ספציפי.
Python
from google import genai
from google.genai import types
client = genai.Client()
prompt = "Which family-friendly restaurants near here have the best playground reviews?"
response = client.models.generate_content(
model='gemini-2.5-flash',
contents=prompt,
config=types.GenerateContentConfig(
tools=[types.Tool(google_maps=types.GoogleMaps())],
tool_config=types.ToolConfig(retrieval_config=types.RetrievalConfig(
# Provide the location as context; this is Austin, TX.
lat_lng=types.LatLng(
latitude=30.2672, longitude=-97.7431))),
),
)
print("Generated Response:")
print(response.text)
if grounding := response.candidates[0].grounding_metadata:
if chunks := grounding.grounding_chunks:
print('-' * 40)
print("Sources:")
for chunk in chunks:
print(f'- [{chunk.maps.title}]({chunk.maps.uri})')
JavaScript
import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
async function run() {
const prompt = "Which family-friendly restaurants near here have the best playground reviews?";
const response = await ai.models.generateContent({
model: 'gemini-2.5-flash',
contents: prompt,
config: {
tools: [{googleMaps: {}}],
toolConfig: {
retrievalConfig: {
// Provide the location as context; this is Austin, TX.
latLng: {
latitude: 30.2672,
longitude: -97.7431
}
}
}
},
});
console.log("Generated Response:");
console.log(response.text);
const chunks = response.candidates[0].groundingMetadata?.groundingChunks;
if (chunks) {
console.log('-'.repeat(40));
console.log("Sources:");
for (const chunk of chunks) {
if (chunk.maps) {
console.log(`- [${chunk.maps.title}](${chunk.maps.uri})`);
}
}
}
}
run();
REST
curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite:generateContent' \
-H 'Content-Type: application/json' \
-H "x-goog-api-key: ${GEMINI_API_KEY}" \
-d '{
"contents": [{
"role": "user",
"parts": [{
"text": "Which family-friendly restaurants near here have the best playground reviews?"
}],
}],
"tools": [{"googleMaps": {}}],
"toolConfig": {
"retrievalConfig": {
"latLng": {"latitude": 30.2672, "longitude": -97.7431}
}
}
}'
עזרה בתכנון מסלול
יצירת תוכניות לכמה ימים עם הוראות הגעה ומידע על מיקומים שונים, מושלם לאפליקציות נסיעות.
בדוגמה הזו, googleMapsWidgetContextToken
התבקש על ידי הפעלת הווידג'ט בכלי של מפות Google. כשהאפשרות הזו מופעלת, אפשר להשתמש בטוקן שמוחזר כדי להציג ווידג'ט הקשרי של מקומות באמצעות <gmp-places-contextual> component
מ-Google Maps JavaScript API.
Python
from google import genai
from google.genai import types
client = genai.Client()
prompt = "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner."
response = client.models.generate_content(
model='gemini-2.5-flash',
contents=prompt,
config=types.GenerateContentConfig(
tools=[types.Tool(google_maps=types.GoogleMaps(enable_widget=True))],
tool_config=types.ToolConfig(retrieval_config=types.RetrievalConfig(
# Provide the location as context, this is in San Francisco.
lat_lng=types.LatLng(
latitude=37.78193, longitude=-122.40476))),
),
)
print("Generated Response:")
print(response.text)
if grounding := response.candidates[0].grounding_metadata:
if grounding.grounding_chunks:
print('-' * 40)
print("Sources:")
for chunk in grounding.grounding_chunks:
print(f'- [{chunk.maps.title}]({chunk.maps.uri})')
if widget_token := grounding.google_maps_widget_context_token:
print('-' * 40)
print(f'<gmp-place-contextual context-token="{widget_token}"></gmp-place-contextual>')
JavaScript
import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
async function run() {
const prompt = "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner.";
const response = await ai.models.generateContent({
model: 'gemini-2.5-flash',
contents: prompt,
config: {
tools: [{googleMaps: {enableWidget: true}}],
toolConfig: {
retrievalConfig: {
// Provide the location as context, this is in San Francisco.
latLng: {
latitude: 37.78193,
longitude: -122.40476
}
}
}
},
});
console.log("Generated Response:");
console.log(response.text);
const groundingMetadata = response.candidates[0]?.groundingMetadata;
if (groundingMetadata) {
if (groundingMetadata.groundingChunks) {
console.log('-'.repeat(40));
console.log("Sources:");
for (const chunk of groundingMetadata.groundingChunks) {
if (chunk.maps) {
console.log(`- [${chunk.maps.title}](${chunk.maps.uri})`);
}
}
}
if (groundingMetadata.googleMapsWidgetContextToken) {
console.log('-'.repeat(40));
document.body.insertAdjacentHTML('beforeend', `<gmp-place-contextual context-token="${groundingMetadata.googleMapsWidgetContextToken}`"></gmp-place-contextual>`);
}
}
}
run();
REST
curl -X POST 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite:generateContent' \
-H 'Content-Type: application/json' \
-H "x-goog-api-key: ${GEMINI_API_KEY}" \
-d '{
"contents": [{
"role": "user",
"parts": [{
"text": "Plan a day in San Francisco for me. I want to see the Golden Gate Bridge, visit a museum, and have a nice dinner."
}]
}],
"tools": [{"googleMaps": {"enableWidget":"true"}}],
"toolConfig": {
"retrievalConfig": {
"latLng": {"latitude": 37.78193, "longitude": -122.40476}
}
}
}'
כשמעבדים את הווידג'ט, הוא נראה בערך כך:
דרישות לשימוש בשירות
בקטע הזה מתוארות דרישות השימוש בשירות Grounding with Google Maps.
לעדכן את המשתמש לגבי השימוש במקורות של מפות Google
לכל תוצאה מבוססת-קרקע במפות Google, תקבלו מקורות בgroundingChunks
תמיכה לכל תשובה. מוחזרים גם המטא-נתונים הבאים:
- URI במקור
- title
- מזהה
כשמציגים תוצאות מ-Grounding עם מפות Google, צריך לציין את המקורות המשויכים במפות Google ולעדכן את המשתמשים לגבי הדברים הבאים:
- המקורות של מפות Google צריכים להופיע מיד אחרי התוכן שנוצר, שהמקורות תומכים בו. התוכן שנוצר נקרא גם תוצאה מבוססת-קרקע ב-Google Maps.
- מקורות המידע במפות Google צריכים להיות גלויים באינטראקציה אחת של המשתמש.
הצגת מקורות של מפות Google עם קישורים למפות Google
לכל מקור ב-groundingChunks
וב-grounding_chunks.maps.placeAnswerSources.reviewSnippets
, צריך ליצור תצוגה מקדימה של הקישור בהתאם לדרישות הבאות:
- צריך לשייך כל מקור למפות Google בהתאם להנחיות לשיוך טקסט במפות Google.
- הצגת כותרת המקור שסופקה בתשובה.
- אפשר לקשר למקור באמצעות הסמל
uri
אוgoogleMapsUri
שמופיע בתשובה.
בתמונות האלה מוצגות הדרישות המינימליות להצגת המקורות והקישורים למפות Google.
אפשר לכווץ את תצוגת המקורות.
אופציונלי: אפשר לשפר את התצוגה המקדימה של הקישור באמצעות תוכן נוסף, כמו:
- סמל מועדף של מפות Google מוכנס לפני טקסט השיוך של מפות Google.
- תמונה מכתובת ה-URL של המקור (
og:image
).
מידע נוסף על חלק מספקי הנתונים של מפות Google ועל תנאי הרישיון שלהם מופיע בהודעות המשפטיות של מפות Google ו-Google Earth.
הנחיות לציון מקורות במפות Google
כשמייחסים מקורות למפות Google בטקסט, חשוב לפעול לפי ההנחיות הבאות:
- אל תשנו את הטקסט 'מפות Google' בשום צורה:
- אל תשנו את האותיות הרישיות של מפות Google.
- אל תפצלו את כתובת מפות Google לכמה שורות.
- אסור להתאים את מפות Google לשוק המקומי בשפה אחרת.
- כדי למנוע מדפדפנים לתרגם את מפות Google, משתמשים בתכונת ה-HTML translate="no".
- מעצבים את הטקסט במפות Google לפי ההוראות שבטבלה הבאה:
נכס | סגנון |
---|---|
Font family |
Roboto. טעינת הגופן היא אופציונלית. |
Fallback font family |
כל גופן גוף מסוג Sans Serif שכבר נמצא בשימוש במוצר או Sans-Serif כדי להפעיל את גופן המערכת שמוגדר כברירת מחדל |
Font style |
רגיל |
Font weight |
400 |
Font color |
לבן, שחור (#1F1F1F) או אפור (#5E5E5E). שמירה על ניגודיות נגישה (4.5:1) ביחס לרקע. |
Font size |
|
Spacing |
רגיל |
דוגמה ל-CSS
קוד ה-CSS הבא מעבד את מפות Google עם סגנון הטיפוגרפיה והצבע המתאימים על רקע לבן או בהיר.
CSS
@import url('https://fonts.googleapis.com/css2?family=Roboto&display=swap');
.GMP-attribution {
font-family: Roboto, Sans-Serif;
font-style: normal;
font-weight: 400;
font-size: 1rem;
letter-spacing: normal;
white-space: nowrap;
color: #5e5e5e;
}
טוקן הקשר, מזהה המקום ומזהה הביקורת
הנתונים של מפות Google כוללים אסימון הקשר, מזהה מקום ומזהה ביקורת. יכול להיות שתשמרו במטמון, תאחסנו ותייצאו את נתוני התשובות הבאים:
googleMapsWidgetContextToken
placeId
reviewId
המגבלות נגד שמירה במטמון בתנאים של Grounding עם מפות Google לא חלות.
פעילות אסורה ואזור אסור
כדי לשמור על הבטיחות והאמינות של פלטפורמת מפות Google, יש הגבלות נוספות על תוכן ופעילויות מסוימים ב-Grounding עם מפות Google. בנוסף להגבלות השימוש שמפורטות בתנאים, אסור להשתמש ב-Grounding עם מפות Google לפעילויות בסיכון גבוה, כולל שירותי תגובה למקרי חירום. לא תפיצו או תשווקו את האפליקציה שלכם שמציעה Grounding עם מפות Google באזור אסור. האזורים האסורים כרגע הם:
- סין
- חצי האי קרים
- קובה
- הרפובליקה העממית של דונצק
- איראן
- הרפובליקה העממית של לוהנסק
- קוריאה הצפונית
- סוריה
- וייטנאם
יכול להיות שהרשימה הזו תתעדכן מעת לעת.
שיטות מומלצות
- ציון מיקום המשתמש: כדי לקבל תשובות רלוונטיות ומותאמות אישית, תמיד צריך לכלול את
user_location
(קו רוחב וקו אורך) בהגדרה שלgoogleMapsGrounding
כשמיקום המשתמש ידוע. - הצגת הווידג'ט ההקשרי של מפות Google: הווידג'ט ההקשרי מוצג באמצעות טוקן ההקשר,
googleMapsWidgetContextToken
, שמוחזר בתגובת Gemini API ואפשר להשתמש בו כדי להציג תוכן חזותי ממפות Google. מידע נוסף על הווידג'ט ההקשרי זמין במאמר הארקה באמצעות הווידג'ט של מפות Google במדריך למפתחים של Google. - ליידע את משתמשי הקצה: חשוב ליידע את משתמשי הקצה בצורה ברורה שהנתונים של מפות Google משמשים למענה על השאילתות שלהם, במיוחד כשהכלי מופעל.
- מעקב אחרי זמן האחזור: באפליקציות שיש בהן ממשק שיחה, חשוב לוודא שזמן האחזור של תגובות מבוססות-ידע (grounded) בערך P95 נשאר בגבולות הסבירים, כדי לשמור על חוויית משתמש חלקה.
- השבתה כשלא צריך: ההארקה באמצעות מפות Google מושבתת כברירת מחדל. כדי לשפר את הביצועים ולהוזיל עלויות, מפעילים את האפשרות הזו (
"tools": [{"googleMaps": {}}]
) רק כששאילתה כוללת הקשר גיאוגרפי ברור.
מגבלות
- היקף גיאוגרפי: בשלב הזה, ההארקה באמצעות מפות Google זמינה בכל העולם.
- תמיכה במודלים: רק מודלים ספציפיים של Gemini תומכים ב-Grounding עם מפות Google: Gemini 2.5 Flash-Lite, Gemini 2.5 Pro, Gemini 2.5 Flash ו-Gemini 2.0 Flash (אבל לא 2.0 Flash Lite).
- קלט/פלט מולטימודאלי: בשלב הזה, ההארקה באמצעות מפות Google לא תומכת בקלט או בפלט מולטימודאליים מעבר לטקסט ולרכיבי widget של מפות בהקשר.
- מצב ברירת מחדל: הכלי Grounding with Google Maps מושבת כברירת מחדל. צריך להפעיל אותו באופן מפורש בבקשות ל-API.
תמחור ומגבלות על קצב יצירת הבקשות
ההארקה עם תמחור של מפות Google מבוססת על שאילתות. התעריף הנוכחי הוא 25$ ל-1,000 הנחיות עם הארקה. בקשה נספרת רק במסגרת המכסה אם ההנחיה מחזירה בהצלחה לפחות תוצאה אחת מבוססת-קרקע של מפות Google (כלומר, תוצאות שמכילות לפחות מקור אחד של מפות Google). אם נשלחות כמה שאילתות אל מפות Google מבקשה אחת, הן נספרות כבקשה אחת לצורך חישוב מגבלת הקצב.
מידע מפורט על התמחור זמין בדף התמחור של Gemini API.
מודלים נתמכים
היכולות שלהם מפורטות בדף סקירת המודל.
דגם | עיגון באמצעות מפות Google |
---|---|
Gemini 2.5 Pro | ✔️ |
Gemini 2.5 Flash | ✔️ |
Gemini 2.5 Flash-Lite | ✔️ |
Gemini 2.0 Flash | ✔️ |
המאמרים הבאים
- כדאי לנסות את ההארקה באמצעות חיפוש Google ב-Gemini API Cookbook.
- אפשר לקרוא על כלים זמינים אחרים, כמו קריאה לפונקציות.
- כדי לקרוא מידע נוסף על שיטות מומלצות לשימוש אחראי ב-AI ועל מסנני הבטיחות של Gemini API, אפשר לעיין במדריך להגדרות הבטיחות.