تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

Maps Grounding Lite

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

الأدوات

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

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

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

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

Resolution API

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

Resolve names (REST، MCP): تتيح لك هذه الطريقة مطابقة مجموعة من أسماء المواقع الجغرافية أو عناوينها مع كيانات أماكن محدّدة على "خرائط Google". ويُعدّ ذلك مفيدًا لربط طلبات البحث غير المنظَّمة التي يجريها المستخدمون بأرقام تعريف أماكن ثابتة.
حلّ عناوين URL في "خرائط Google" (REST، MCP): حلّ مجموعة من عناوين URL في "خرائط Google" لكيانات أماكن محدّدة. تشمل التنسيقات المتوافقة عناوين URL العادية للأماكن وعناوين URL المختصرة.

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

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

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

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

طريقة تحصيل الرسوم منك

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

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

يتم إصدار فواتير الطلبات المُرسَلة إلى Resolution API (ResolveNames وResolveMapsUrls) بدون أي رسوم ضمن رمز التخزين التعريفي Places API Text Search Essentials (IDs Only).

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

الحِصص

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

البحث عن الأماكن: ‫300 طلب في الدقيقة لكل مشروع
البحث عن الطقس: ‫300 طلب في الدقيقة لكل مشروع
احتساب المسارات: ‫300 طلب في الدقيقة لكل مشروع
حلّ الأسماء: 600 طلب في الدقيقة لكل مشروع
حلّ عناوين URL في "خرائط Google": ‏600 طلب في الدقيقة لكل مشروع

يتم احتساب كل طلب بيانات من واجهة برمجة التطبيقات Resolution كطلب بحث واحد، بغض النظر عن عدد العناصر التي يحتوي عليها.

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

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

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

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

على سبيل المثال، أنت مسؤول عن ضمان عدم تخزين محتوى "خرائط Google" مؤقتًا أو تخزينه أو استخدامه لتحسين نموذج LLM الذي تختار استخدامه. قبل استخدام 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. بعد ذلك، يمكنك ضبط النماذج اللغوية الكبيرة للوصول إلى خادم MCP. يستخدم خادم Grounding Lite MCP بروتوكول نقل HTTP قابل للبث.

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

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

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

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

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

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

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

يقدّم هذا القسم مثالاً على كيفية ضبط خادم Maps Grounding Lite MCP باستخدام Gemini CLI. لمزيد من التفاصيل، يُرجى الاطّلاع على خوادم MCP مع Gemini CLI.

بعد تثبيت Gemini CLI، يمكنك استخدام الأمر add لضبط خادم Maps Grounding Lite MCP:
```
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 (5 tools)
Tools:
-   compute_routes
-   lookup_weather
-   resolve_maps_urls
-   resolve_names
-   search_places

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

ضبط Grounding Lite باستخدام حزمة Agent Development Kit (ADK)

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

Python

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

الخطوة 1: تحديد وكيلك باستخدام `McpToolset` لـ Grounding Lite في خرائط Google

عدِّل ملف 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، استخدِم النماذج التالية: