Maps Grounding Lite

Grounding Lite على "منصة خرائط Google" هي خدمة تتوافق مع بروتوكول سياق النموذج (MCP) وتسهّل تحديد المصدر في تطبيقات الذكاء الاصطناعي باستخدام بيانات جغرافية مكانية موثوقة من "خرائط Google". يوفّر خادم MCP أدوات تتيح للنماذج اللغوية الكبيرة الوصول إلى إمكانات متعلقة بالأماكن والطقس والطرق. يمكنك تجربة Maps Grounding Lite من خلال تفعيلها في أي أداة تتوافق مع خوادم MCP.

الأدوات

توفّر Maps Grounding Lite أدوات تتيح للنماذج اللغوية الكبيرة الوصول إلى إمكانات "خرائط Google" التالية:

البحث عن أماكن: طلب معلومات عن أماكن والحصول على ملخّصات بيانات عن الأماكن من إنشاء الذكاء الاصطناعي، بالإضافة إلى أرقام تعريف الأماكن وإحداثيات خط العرض وخط الطول وروابط في "خرائط Google" لكل مكان مضمّن في الملخّص يمكنك استخدام معرّفات الأماكن وإحداثيات خطوط الطول والعرض التي تم إرجاعها مع واجهات برمجة تطبيقات أخرى من Google Maps Platform لعرض الأماكن على الخريطة.
البحث عن معلومات الطقس: يمكنك طلب معلومات عن الطقس والحصول على أحوال الطقس الحالية والتوقعات كل ساعة والتوقعات اليومية.
حساب المسارات: طلب معلومات حول مسارات القيادة أو المشي بين موقعَين جغرافيَين وعرض معلومات حول مسافة المسار ومدته.

ملاحظة: لا يوفّر تطبيق Maps Grounding Lite اتجاهات مفصّلة أو مسارات أو معلومات عن حركة المرور في الوقت الفعلي أو معلومات التنقّل.

يتيح تفعيل خادم Maps Grounding Lite MCP للنماذج اللغوية الكبيرة استدعاء الأدوات الجديدة التي يعرضها الخادم لعرض معلومات إضافية حول أنواع البيانات المذكورة أعلاه. مع أنّ النموذج اللغوي الكبير يمكنه استخدام هذه المعلومات الإضافية لفهم السياق، قد لا يتضمّن الرد الذي ينشئه النموذج في النهاية المعلومات نفسها التي يعرضها خادم MCP. عليك التأكّد من دقة الرد الذي تم إنشاؤه.

تجربة نموذج تطبيق Maps Grounding Lite (يفتح في علامة تبويب جديدة)

الفوترة والحصص

كيفية إصدار الفواتير لك

باستخدام نموذج تسعير الدفع حسب الاستخدام في "منصة خرائط Google"، يتم احتساب استخدام Maps Grounding Lite لكل طلب، حيث يمثّل كل طلب حدث فوترة واحدًا. يتم تتبُّع الاستخدام لكل رمز تخزين تعريفي للمنتج. يعرض فاتورتك تفاصيل الإعلان لكل رمز تخزين تعريفي بالإضافة إلى إجمالي الرسوم. يمكنك الاطّلاع على نظرة عامة عن إعداد التقارير لمزيد من المعلومات.

راجِع جدول الأسعار الرئيسي وجدول الأسعار في الهند للاطّلاع على تفاصيل الأسعار.

تتوفّر حزمة Maps Grounding Lite أيضًا من خلال حزمتَي Essentials وPro الاشتراك لتوفير المال.

الحصص

تنطبق الحصص التالية على الأدوات التي توفّرها Maps Grounding Lite:

البحث عن أماكن: 300 طلب في الدقيقة لكل مشروع
الاطّلاع على حالة الطقس: 300 طلب في الدقيقة الواحدة لكل مشروع
Compute Routes: 300 طلب في الدقيقة لكل مشروع

السياسات وبنود الخدمة

تخضع خدمة Maps Grounding Lite لبنود خدمة منصة خرائط Google، بما في ذلك بنود الخدمة المحدّدة لهذه الخدمة. يصف هذا القسم متطلبات استخدام خدمة إضافية لـ Maps Grounding Lite، بما في ذلك نماذج اللغات الكبيرة المتوافقة ومتطلبات تحديد المصدر.

متطلبات نماذج اللغات الكبيرة المتوافقة

لا يمكنك استخدام Maps Grounding Lite إلا مع نموذج لغوي كبير متوافق مع بنود خدمة منصة خرائط Google.

على سبيل المثال، تتحمّل أنت مسؤولية ضمان عدم تخزين المحتوى الخاص بـ "خرائط Google" مؤقتًا أو تخزينه أو استخدامه لتحسين نموذج اللغة الكبير الذي تختار استخدامه. قبل استخدام Maps Grounding Lite، عليك مراجعة بنود الخدمة الخاصة بأي نموذج تنوي استخدامه مع Maps Grounding Lite. يجب عدم استخدام Maps Grounding Lite مع أي نماذج تستخدم البيانات المُدخَلة في النموذج لأي غرض من أغراض تدريب النماذج أو تحسينها. تتحمّل أنت مسؤولية التأكّد من أنّ استخدامك للنموذج يتوافق تمامًا مع القيود المفروضة على محتوى "خرائط Google" في بنود خدمة "منصة خرائط Google"، بما في ذلك بنود الخدمة المحدّدة.

متطلبات تحديد المصدر في "خرائط Google"

يتضمّن كل رد من أداة Maps Grounding Lite المصادر. عند عرض نتائج تستخدم أدوات توفّرها Maps Grounding Lite، يجب تضمين مصادر "خرائط Google" المرتبطة بطريقة تستوفي المتطلبات التالية:

يجب أن تتبع مصادر "خرائط Google" المحتوى الذي تم إنشاؤه مباشرةً والذي تستند إليه هذه المصادر. يُشار أيضًا إلى هذا المحتوى الذي تم إنشاؤه باسم الناتج المستند إلى بيانات واقعية.
يجب أن تكون مصادر "خرائط Google" قابلة للعرض من خلال تفاعل واحد من المستخدم.

مصادر أداة "البحث عن أماكن"

يوفّر حقل places في أداة search_places مصادر تؤيّد summary. بالنسبة إلى places، يتم عرض البيانات الوصفية التالية:

place (اسم المورد)
id
location
googleMapsLinks

يجب إنشاء معاينة للرابط لكل مكان تستوفي المتطلبات التالية:

يجب الإشارة إلى أنّ المصدر هو "خرائط Google"، وذلك باتّباع الإرشادات المتعلقة بالإشارة إلى المصدر في Maps Grounding Lite.
اربط النص المصدر باستخدام places.googleMapsLinks.placeUrl من الردّ.

ضبط نماذج اللغات الكبيرة لاستخدام خادم MCP

لاستخدام Maps Grounding Lite، يجب أولاً إنشاء مشروع على Google Cloud وتفعيل خدمة واجهة برمجة التطبيقات Maps Grounding Lite فيه، بالإضافة إلى مفتاح واجهة برمجة التطبيقات أو معرّف عميل OAuth. بعد ذلك، يمكنك ضبط إعدادات نماذج اللغات الكبيرة (LLM) للوصول إلى خادم MCP. يستخدم خادم Grounding Lite MCP بروتوكول نقل البيانات HTTP القابل للبث.

تفعيل خدمة Maps Grounding Lite في مشروعك على Google Cloud

لتفعيل واجهة برمجة التطبيقات في مشروعك، اتّبِع الخطوات التالية:

في Google Cloud Console، اختَر المشروع الذي تريد استخدامه مع Maps Grounding Lite.
فعِّل الفوترة للمشروع في وحدة تحكّم Google Cloud.
فعِّل Maps Grounding Lite في مكتبة واجهات برمجة التطبيقات في Google Cloud Console.

المصادقة باستخدام مفتاح واجهة برمجة تطبيقات

يمكنك استخدام مفتاح حالي لواجهة برمجة التطبيقات مع Maps Grounding Lite أو إنشاء مفتاح جديد، شرط تفعيل خدمة Maps Grounding Lite API في كلّ من مشروع على السحابة الإلكترونية من Google والمفتاح.

للمصادقة باستخدام مفتاح واجهة برمجة التطبيقات، اتّبِع الخطوات التالية:

أنشئ مفتاح واجهة برمجة تطبيقات أو اضبطه باتّباع الخطوات الواردة في بدء استخدام منصة "خرائط Google".
مرِّر المفتاح إلى خادم MCP باستخدام العنوان X-Goog-Api-Key. يجب تحديد ذلك كعنوان HTTP مخصّص في إعدادات أداة MCP الخاصة بالنموذج اللغوي الكبير.

المصادقة باستخدام OAuth

يمكنك المصادقة باستخدام OAuth من خلال إنشاء بيانات اعتماد OAuth وتمريرها إلى مضيف MCP أو تطبيق خادم MCP.

للمصادقة باستخدام OAuth، اتّبِع الخطوات التالية:

في Google Cloud Console، اختَر المشروع الذي تريد استخدامه مع Maps Grounding Lite.
في قائمة واجهات برمجة التطبيقات والخدمات، اختَر بيانات الاعتماد.
في القائمة العلوية، اختَر إنشاء بيانات اعتماد > معرّف عميل OAuth.
إذا لم يكن المشروع يتضمّن شاشة طلب الموافقة تم ضبطها، انقر على ضبط شاشة طلب الموافقة واتّبِع التعليمات الظاهرة على الشاشة.
في قسم المقاييس، انقر على إنشاء عميل OAuth.
في شاشة إنشاء معرّف عميل OAuth، اختَر نوع التطبيق وأدخِل اسمًا لمعرّف العميل.
حدِّد التفاصيل الإضافية ذات الصلة بنوع طلبك. على سبيل المثال، إذا كنت بصدد إنشاء تطبيق ويب، أضِف معرّفات الموارد المنتظمة (URI) المصرّح بها لطلبات المتصفّح والخادم.
بعد إنشاء العميل، احفظ معرّف العميل وسر العميل.
عند ضبط مضيف MCP أو تطبيق خادم MCP للوصول إلى Maps Grounding Lite، مرِّر معرّف عميل OAuth وسرّه. يجب أيضًا طلب النطاق التالي: https://www.googleapis.com/auth/maps-platform.mapstools.

لمزيد من المعلومات، يُرجى الاطّلاع على استخدام بروتوكول OAuth 2.0 للوصول إلى Google APIs.

ضبط نماذج اللغات الكبيرة للوصول إلى خادم MCP الخاص بأداة Maps Grounding Lite

بعد إنشاء مشروع على السحابة الإلكترونية على Google Cloud وتفعيل خدمة Maps Grounding Lite API والحصول على بيانات اعتماد صالحة، مثل مفتاح واجهة برمجة التطبيقات أو معرّف عميل OAuth وكلمة المرور، يمكنك إعداد النماذج اللغوية الكبيرة للوصول إلى خادم 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

ابدأ بطرح أسئلة متعلقة بـ "خرائط Google" باستخدام واجهة سطر الأوامر. على سبيل المثال، جرِّب طلب "اقتراح بعض المطاعم في ماونتن فيو"، ما سيؤدي إلى استدعاء أداة search_places نيابةً عنك.

إعداد Grounding Lite باستخدام "حزمة تطوير الوكلاء" (ADK)

يقدّم هذا القسم أمثلة توضّح كيفية ضبط خادم Grounding Lite MCP باستخدام حزمة تطوير الوكلاء (ADK) ولغة Python أو Java أو TypeScript.

Python

الخطوة 1: تحديد "الوكيل" باستخدام `McpToolset` لخدمة Google Maps Grounding Lite

عدِّل ملف agent.py. استبدِل YOUR_GOOGLE_MAPS_API_KEY بمفتاح واجهة برمجة التطبيقات الفعلي.

# ./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.
- جرِّب طلبات مثل:
  - "سأكون في دبي غدًا. ما حالة الطقس؟"
  - ابحث عن مقاهٍ بالقرب من متنزّه غولدن غيت.
  - "أريد الحصول على الاتجاهات من GooglePlex إلى مطار سان فرانسيسكو الدولي".

جافا

حدِّد وكيلًا يبدأ McpToolset في Java. استبدِل YOUR_GOOGLE_MAPS_API_KEY_HERE بمفتاح واجهة برمجة التطبيقات الفعلي الذي حصلت عليه إذا كنت لا تستخدم متغيّر بيئة.

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"
            }
        })
    ],
});

مشاركة الملاحظات

لمشاركة ملاحظاتك حول Maps Grounding Lite، استخدِم النماذج التالية: