تستخدم 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.

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

Resolution API

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

حلّ الأسماء (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 (المعرّفات فقط).

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

الحصص

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

البحث عن أماكن: 300 طلب في الدقيقة الواحدة لكل مشروع
الاطّلاع على حالة الطقس: 300 طلب في الدقيقة الواحدة لكل مشروع
Compute routes: 300 طلب في الدقيقة لكل مشروع
حلّ الأسماء: 600 طلب في الدقيقة لكل مشروع
‫Resolve Maps URLs: ‏600 طلب في الدقيقة الواحدة لكل مشروع

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

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

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

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

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

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

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

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

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

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

يوفّر حقل search_places الأداة 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 API في كلّ من مشروع 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

يقدّم هذا القسم مثالاً على كيفية ضبط خادم 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 (5 tools)
Tools:
-   compute_routes
-   lookup_weather
-   resolve_maps_urls
-   resolve_names
-   search_places

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

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

يقدّم هذا القسم أمثلة توضّح كيفية ضبط خادم Grounding Lite MCP باستخدام حزمة تطوير الوكلاء (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 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، استخدِم النماذج التالية: