Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Maps Grounding Lite

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

الأدوات

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

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

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

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

‫Resolution API (تجريبية)

توفّر Maps Grounding Lite واجهة برمجة التطبيقات Resolution API التي تتيح لك تحويل نص وعناوين URL غير منظّمة للموقع الجغرافي إلى معرّفات أماكن منظّمة في "خرائط Google". تتألف Resolution API من نقطتَي نهاية:

**Resolve names**: يمكنك تحويل مجموعة من أسماء المواقع الجغرافية أو العناوين إلى كيانات أماكن معيّنة على "خرائط Google". ويفيد ذلك في ربط طلبات البحث غير المنظّمة للمستخدمين بأرقام تعريف أماكن ثابتة.
حلّ عناوين URL في "خرائط Google": يمكنك تحويل مجموعة من عناوين URL في "خرائط Google" إلى كيانات أماكن معيّنة. تشمل التنسيقات المتوافقة عناوين URL العادية للأماكن وعناوين URL المختصرة.

يمكن استخدام نقطتَي النهاية هاتَين لتحديد مصدر طلبات البحث أو الروابط غير المنظّمة للمستخدمين بأرقام تعريف أماكن ثابتة من أجل الدمج مع واجهات برمجة التطبيقات الأخرى في منصة خرائط Google.

لمزيد من المعلومات، يُرجى الاطّلاع على Maps Tools Resolution API (تجريبية)

**تجريبية:** إنّ واجهتَي برمجة التطبيقات ResolveNames وResolveMapsUrls في مرحلة التجربة (ما قبل التوفّر للجمهور العام). قد يكون الدعم المقدّم للمنتجات والميزات في مرحلة ما قبل التوفّر للجمهور العام محدودًا، وقد لا تكون التغييرات التي يتم إجراؤها على المنتجات والميزات هنا متوافقة مع الإصدارات الأخرى من هذه المرحلة. تخضع عروض مرحلة ما قبل التوفّر للجمهور العام لبنود الخدمة المحدّدة في منصة خرائط Google. لمزيد من المعلومات، يُرجى الاطّلاع على أوصاف مراحل الإطلاق. لا يتم تحصيل أي رسوم مقابل استخدام ResolveNames وResolveMapsUrls أثناء مرحلة التجربة.

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

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

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

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

للاطّلاع على تفاصيل التسعير، يُرجى الرجوع إلى جدول التسعير الرئيسي و جدول التسعير في الهند.

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

الحصص

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

البحث عن أماكن: 300 طلب في الدقيقة لكل مشروع
الاطّلاع على أحال الطقس: 300 طلب في الدقيقة لكل مشروع
حساب الطرق: 300 طلب في الدقيقة لكل مشروع
Resolve names (تجريبية): 600 طلب في الدقيقة لكل مشروع
Resolve Maps URLs (تجريبية): 600 طلب في الدقيقة لكل مشروع

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

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

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

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

في Google Cloud Console، اختَر المشروع الذي تريد استخدامه لـ Maps Grounding Lite.
فعِّل الفوترة للمشروع في الـ Google Cloud Console.
فعِّل Maps Grounding Lite في Google Cloud Console API Library.

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

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

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

أنشِئ مفتاح واجهة برمجة تطبيقات أو اضبطه باتّباع الخطوات الواردة في بدء الاستخدام مع منصة خرائط 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 في تطبيق ذكاء اصطناعي.

إعداد 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 باستخدام Agent Development Kit (ADK)

يقدّم هذا القسم أمثلة توضّح كيفية إعداد خادم MCP في Grounding Lite باستخدام Agent Development Kit (ADK) وإما Python أو Java أو TypeScript.

Python

يمكنك العثور على عملية تنفيذ كاملة لهذا المثال على GitHub في الـ مستودع adk-samples.

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

جافا

حدِّد وكيلًا يهيئ 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، استخدِم النماذج التالية: