Maps Grounding Lite

‫Google Maps Platform Grounding Lite הוא שירות עם תמיכה ב-Model Context Protocol ‏(MCP) שמאפשר לעגן בקלות את אפליקציות ה-AI שלכם באמצעות נתונים גיאו-מרחביים מהימנים ממפות Google. שרת ה-MCP מספק כלים שמאפשרים למודלים גדולים של שפה (LLM) לגשת ליכולות שקשורות למקומות, למזג האוויר ולמסלולים. אתם יכולים לנסות את Maps Grounding Lite על ידי הפעלתו בכל כלי שתומך בשרתי MCP.

כלים

‫Maps Grounding Lite מספקת כלים שמאפשרים למודלים גדולים של שפה (LLM) לגשת ליכולות הבאות של מפות Google:

חיפוש מקומות: בקשת מידע על מקומות וקבלת סיכומים של נתוני מקומות שנוצרו על ידי AI, וכן מזהי מקומות, קואורדינטות של קווי רוחב ואורך וקישורים למפות Google לכל אחד מהמקומות שנכללים בסיכום. אתם יכולים להשתמש במזהי המקומות ובקואורדינטות של קווי האורך והרוחב שמוחזרים עם ממשקי API אחרים של Google Maps Platform כדי להציג מקומות במפה.
Lookup weather: בקשת מידע על מזג האוויר והחזרת התנאים הנוכחיים, תחזיות שעתיות ותחזיות יומיות.
‫Compute routes: בקשת מידע על מסלולי נסיעה או הליכה בין שני מיקומים והחזרת מידע על מרחק ומשך המסלול.

הערה: Maps Grounding Lite לא מספקת מסלולים מפורטים, הוראות, מידע על מצב התנועה בזמן אמת או מידע על ניווט.

הפעלת שרת ה-MCP של Maps Grounding Lite מאפשרת למודלים גדולים של שפה (LLM) להפעיל את הכלים החדשים שנחשפים על ידי השרת כדי להחזיר מידע נוסף על העיגון של סוגי הנתונים שצוינו למעלה. ה-LLM יכול להשתמש במידע הנוסף הזה כדי לקבל הקשר, אבל יכול להיות שהתשובה שהוא יפיק בסופו של דבר לא תכלול את המידע המדויק שהוחזר משרת ה-MCP. חשוב לאמת את הדיוק של התשובה שנוצרה.

אפשר לנסות את אפליקציית הדוגמה Maps Grounding Lite (פתיחה בכרטיסייה חדשה)

חיוב ומכסות

איך מתבצע החיוב

במודל התמחור של Google Maps Platform בתשלום לפי שימוש, השימוש ב-Maps Grounding Lite מחושב לכל בקשה, כאשר כל בקשה מייצגת אירוע חיוב אחד. השימוש מתועד לכל מק"ט של מוצר. בחשבון שלכם מופיע פריט לכל מק"ט, בנוסף לחיובים הכוללים. מידע נוסף מופיע בסקירה הכללית על דיווח.

פרטי התמחור מופיעים בטבלת התמחור הראשית ובטבלת התמחור בהודו.

השירות Maps Grounding Lite מוצע גם בחבילות Essentials ו-Pro. אפשר להירשם כדי לחסוך.

מכסות

המכסות הבאות חלות על הכלים שמוצעים ב-Maps Grounding Lite:

‫Search places: 300 שאילתות לדקה, לכל פרויקט.
חיפוש מזג אוויר: 300 שאילתות בדקה, לכל פרויקט.
‫Compute routes: 300 שאילתות לדקה, לכל פרויקט.

מדיניות ותנאים והגבלות

השימוש ב-Grounding Lite במפות Google כפוף לתנאים ולהגבלות של Google Maps Platform, כולל לתנאים הספציפיים של השירות. בקטע הזה מפורטות דרישות נוספות לשימוש בשירות Maps Grounding Lite, כולל מודלים תואמים של LLM ודרישות לשיוך מקורות.

הדרישות לגבי מודלים תואמים של LLM

מותר להשתמש ב-Maps Grounding Lite רק עם מודל LLM שעומד בתנאים ובהגבלות של Google Maps Platform.

לדוגמה, באחריותכם לוודא שתוכן מפות Google לא נשמר במטמון, לא מאוחסן ולא משמש לשיפור מודל שפה גדול (LLM) שבחרתם להשתמש בו. לפני השימוש ב-Grounding Lite במפות Google, צריך לעיין בתנאים ובהגבלות של כל מודל שמתכוונים להשתמש בו עם Grounding Lite במפות Google. אסור להשתמש ב-Maps Grounding Lite עם מודלים שמשתמשים בנתונים שמוזנים למודל לאימון או לשיפור של המודל. באחריותך לוודא שהשימוש שלך במודל עומד באופן מלא בהגבלות על תוכן של מפות Google שמפורטות בתנאים ובהגבלות של Google Maps Platform, כולל התנאים הספציפיים לשירות.

דרישות ייחוס למקורות במפות Google

כל תשובה של כלי מ-Maps Grounding Lite כוללת מקורות. כשמציגים תוצאות שנוצרו באמצעות כלים שסופקו על ידי Maps Grounding Lite, צריך לכלול את המקורות המשויכים במפות Google באופן שעומד בדרישות הבאות:

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

מקורות לכלי 'חיפוש מקומות'

הכלי search_places מספק מקורות שתומכים בשדה places summary. עבור places, מוחזרים המטא-נתונים הבאים:

place (שם המשאב)
id
location
googleMapsLinks

לכל מקום, צריך ליצור תצוגה מקדימה של קישור שעומדת בדרישות הבאות:

צריך לשייך כל מקור למפות Google, בהתאם להנחיות לשיוך טקסט של Maps Grounding Lite.
מקשרים למקור באמצעות places.googleMapsLinks.placeUrl מהתגובה.

הגדרת מודלים גדולים של שפה (LLM) לשימוש בשרת MCP

כדי להשתמש ב-Maps Grounding Lite, קודם צריך פרויקט בענן ב-Google Cloud שבו מופעל שירות ה-API של Maps Grounding Lite, וגם מפתח API או מזהה לקוח OAuth. לאחר מכן, תוכלו להגדיר מודלים של שפה גדולה (LLM) כדי לגשת לשרת ה-MCP. שרת Grounding Lite MCP משתמש בתעבורת HTTP שניתנת להזרמה.

הפעלת השירות Maps Grounding Lite בפרויקט ב-Google Cloud

כדי להפעיל את ה-API בפרויקט:

במסוף Google Cloud, בוחרים את הפרויקט שרוצים להשתמש בו ב-Maps Grounding Lite.
מפעילים את החיוב בפרויקט במסוף Google Cloud.
מפעילים את Maps Grounding Lite בספריית ה-API של מסוף Google Cloud.

אימות באמצעות מפתח API

אתם יכולים להשתמש במפתח API קיים עם Maps Grounding Lite או ליצור מפתח חדש, בתנאי שתפעילו את שירות ה-API של Maps Grounding Lite בפרויקט ב-Google Cloud ובמפתח.

כדי לבצע אימות באמצעות מפתח API:

כדי ליצור או להגדיר מפתח API, פועלים לפי השלבים במאמר תחילת העבודה עם Google Maps Platform.
מעבירים את המפתח לשרת ה-MCP באמצעות הכותרת X-Goog-Api-Key. צריך לציין את זה ככותרת HTTP מותאמת אישית בהגדרת כלי ה-MCP של ה-LLM.

אימות באמצעות OAuth

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

כדי לבצע אימות באמצעות OAuth:

במסוף Google Cloud, בוחרים את הפרויקט שרוצים להשתמש בו ב-Maps Grounding Lite.
בתפריט API & Services, בוחרים באפשרות Credentials.
בתפריט העליון, בוחרים באפשרות Create credentials > OAuth client ID (יצירת פרטי כניסה > מזהה לקוח OAuth).
אם בפרויקט לא מוגדר מסך הסכמה, לוחצים על Configure consent screen ופועלים לפי ההוראות במסך.
בקטע מדדים, לוחצים על יצירת לקוח OAuth.
במסך Create OAuth client ID (יצירת מזהה לקוח OAuth), בוחרים סוג אפליקציה ומזינים שם למזהה הלקוח.
מציינים את הפרטים הנוספים שרלוונטיים לסוג הבקשה. לדוגמה, אם אתם יוצרים אפליקציית אינטרנט, צריך להוסיף כתובות URI מורשות לבקשות של דפדפן ושרת.
אחרי שיוצרים את הלקוח, שומרים את מספר הלקוח ואת הסוד.
כשמגדירים את אפליקציית השרת או המארח של MCP כדי לגשת ל-Maps Grounding Lite, צריך להעביר את מזהה הלקוח והסוד של לקוח OAuth. בנוסף, צריך לבקש את ההיקף הבא: https://www.googleapis.com/auth/maps-platform.mapstools.

למידע נוסף, תוכלו לקרוא את המאמר שימוש ב-OAuth 2.0 לגישה ל-Google APIs.

הגדרת מודלים של שפה גדולה (LLM) כדי לגשת לשרת ה-MCP של Grounding Lite במפות

אחרי שיש לכם פרויקט בענן ב-Google Cloud עם השירות Maps Grounding Lite API מופעל ועם פרטי כניסה תקפים, כמו מפתח API או מזהה לקוח וסוד של OAuth, אתם יכולים להגדיר מודלים של LLM כדי לגשת לשרת MCP. לשם כך, צריך לפעול לפי מסמכי התיעוד של הגדרת MCP ולהשתמש בכתובת ה-URL של שרת MCP של Maps Grounding Lite: ‏ https://mapstools.googleapis.com/mcp

מידע נוסף זמין במאמר בנושא הגדרת MCP באפליקציית AI.

הגדרת Maps Grounding Lite באמצעות Gemini CLI

בקטע הזה מוסבר איך להגדיר את שרת ה-MCP של Maps Grounding Lite באמצעות Gemini CLI. לפרטים נוספים, אפשר לעיין במאמר בנושא שרתי MCP עם Gemini CLI.

אחרי שמתקינים את Gemini CLI, אפשר להשתמש בפקודה add כדי להגדיר את שרת ה-MCP של Maps Grounding Lite:
```
gemini mcp add -s user -t http -H 'X-Goog-Api-Key: API_KEY' maps-grounding-lite-mcp https://mapstools.googleapis.com/mcp
```
אם ההגדרה הושלמה בהצלחה, אמור להופיע אישור שהשרת נוסף להגדרות המשתמש.

כדי לוודא שהשרת פועל בצורה תקינה, מריצים את הפקודה /mcp list:

> /mcp list

Configured MCP servers:

maps-grounding-lite-mcp - Ready (3 tools)
Tools:
-   compute_routes
-   lookup_weather
-   search_places

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

הגדרה של Grounding Lite באמצעות ערכה לפיתוח סוכנים (ADK)

בקטע הזה מופיעות דוגמאות שמראות איך להגדיר את שרת Grounding Lite MCP באמצעות ערכה לפיתוח סוכנים (ADK) ו-Python,‏ Java או TypeScript.

Python

שלב 1: הגדרת הסוכן באמצעות `McpToolset` ל-Grounding Lite בפלטפורמה של מפות Google

משנים את הקובץ agent.py. מחליפים את YOUR_GOOGLE_MAPS_API_KEY במפתח ה-API בפועל.

# ./adk_agent_samples/mcp_agent/agent.py
import os
from google.adk.agents.llm_agent import Agent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

# Retrieve the API key from an environment variable or directly insert it.
GOOGLE_MAPS_API_KEY = os.getenv("GOOGLE_MAPS_API_KEY")
if not GOOGLE_MAPS_API_KEY:
    GOOGLE_MAPS_API_KEY = "YOUR_GOOGLE_MAPS_API_KEY_HERE"

if GOOGLE_MAPS_API_KEY == "YOUR_GOOGLE_MAPS_API_KEY_HERE":
    print("WARNING: GOOGLE_MAPS_API_KEY is not set.")

root_agent = Agent(
    model='gemini-flash-latest',
    name='travel_planner_agent',
    description='A helpful assistant for planning travel routes.',
    tools=[
        McpToolset(
            connection_params=StreamableHTTPConnectionParams(
                url="https://mapstools.googleapis.com/mcp",
                headers={
                    "X-Goog-Api-Key": GOOGLE_MAPS_API_KEY,
                    "Content-Type": "application/json",
                    "Accept": "application/json, text/event-stream"
                }
            )
        )
    ]
)

שלב 2: מוודאים שהרכיב `init.py` קיים

מוודאים שיש לכם __init__.py באותה ספרייה כמו agent.py:

from . import agent

שלב 3: מריצים את `adk web` ויוצרים אינטראקציה

הגדרת משתנה סביבה:
מגדירים את מפתח Google Maps API כמשתנה סביבה במסוף:
```
export GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_GOOGLE_MAPS_API_KEY"
        
```
מריצים את adk web:
מריצים את הפקודה הבאה כדי להפעיל את ממשק האינטרנט של ADK:
```
adk web
        
```
אינטראקציה בממשק המשתמש:
- בחר את רשת ה-travel_planner_agent.
- הנה כמה דוגמאות להנחיות:
  - "I will be in San Francisco tomorrow. מה מזג האוויר?"
  - ‫"Find coffee shops near Golden Gate Park" (חיפוש בתי קפה ליד גולדן גייט פארק).
  - ‫"Get directions from GooglePlex to SFO" (קבלת מסלול נסיעה מ-GooglePlex אל SFO).

Java

הגדרת סוכן שמפעיל את McpToolset ב-Java. אם לא משתמשים במשתנה סביבה, מחליפים את הערך YOUR_GOOGLE_MAPS_API_KEY_HERE במפתח ה-API האמיתי שקיבלתם.

package agents;

import com.google.adk.agents.LlmAgent;
import com.google.adk.runner.InMemoryRunner;
import com.google.adk.sessions.SessionKey;
import com.google.adk.tools.mcp.McpToolset;
import com.google.adk.tools.mcp.StreamableHttpServerParameters;
import com.google.genai.types.Content;
import com.google.genai.types.Part;
import java.util.HashMap;
import java.util.Map;

public class MapsAgentCreator {
    public static void main(String[] args) {
        String googleMapsApiKey = System.getenv("GOOGLE_MAPS_API_KEY");
        if (googleMapsApiKey == null || googleMapsApiKey.trim().isEmpty()) {
            googleMapsApiKey = "YOUR_GOOGLE_MAPS_API_KEY_HERE";
            if ("YOUR_GOOGLE_MAPS_API_KEY_HERE".equals(googleMapsApiKey)) {
                System.out.println("WARNING: GOOGLE_MAPS_API_KEY is not set.");
            }
        }

        Map<String, String> headers = new HashMap<>();
        headers.put("X-Goog-Api-Key", googleMapsApiKey);
        headers.put("Content-Type", "application/json");
        headers.put("Accept", "application/json, text/event-stream");

        StreamableHttpServerParameters serverParams = StreamableHttpServerParameters.builder("https://mapstools.googleapis.com/mcp")
                .headers(headers)
                .build();

        try (McpToolset toolset = new McpToolset(serverParams)) {
            LlmAgent agent = LlmAgent.builder()
                    .model("gemini-flash-latest")
                    .name("travel_planner_agent")
                    .description("A helpful assistant for planning travel routes.")
                    .tools(toolset)
                    .build();

            System.out.println("Agent created: " + agent.name());

            InMemoryRunner runner = new InMemoryRunner(agent);
            String userId = "maps-user-" + System.currentTimeMillis();
            String sessionId = "maps-session-" + System.currentTimeMillis();
            String promptText = "Please give me directions to the nearest pharmacy to Madison Square Garden.";

            SessionKey sessionKey = runner.sessionService().createSession(runner.appName(), userId, null, sessionId).blockingGet().sessionKey();
            System.out.println("Session created: " + sessionId + " for user: " + userId);

            Content promptContent = Content.fromParts(Part.fromText(promptText));
            System.out.println("\nSending prompt: \"" + promptText + "\" to agent...\n");

            runner.runAsync(sessionKey, promptContent)
                    .blockingForEach(event -> {
                        System.out.println("Event received: " + event.toJson());
                    });
        } catch (Exception e) {
            System.err.println("An error occurred: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

TypeScript

מגדירים סוכן שמאתחל את MCPToolset ב-TypeScript:

import 'dotenv/config';
import {LlmAgent, MCPToolset} from "@google/adk";

const googleMapsApiKey = process.env.GOOGLE_MAPS_API_KEY;
if (!googleMapsApiKey) {
    console.warn("WARNING: GOOGLE_MAPS_API_KEY is not set.");
    throw new Error('GOOGLE_MAPS_API_KEY is not provided, please run "export GOOGLE_MAPS_API_KEY=YOUR_ACTUAL_KEY" to add that.');
}

export const rootAgent = new LlmAgent({
    model: "gemini-flash-latest",
    name: "travel_planner_agent",
    description: "A helpful assistant for planning travel.",
    tools: [
        new MCPToolset({
            type: "SseConnectionParams",
            url: "https://mapstools.googleapis.com/mcp",
            headers: {
                "X-Goog-Api-Key": googleMapsApiKey,
                "Content-Type": "application/json",
                "Accept": "application/json, text/event-stream"
            }
        })
    ],
});

שיתוף משוב

כדי לשתף משוב על Grounding Lite במפות Google, אפשר להשתמש בטפסים הבאים: