این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

نقشه‌های Grounding Lite

پلتفرم نقشه‌های گوگل (Google Maps Platform Grounding Lite) سرویسی با پشتیبانی از پروتکل مدل زمینه (MCP) است که اتصال برنامه‌های هوش مصنوعی شما را با داده‌های مکانی قابل اعتماد از نقشه‌های گوگل آسان می‌کند. سرور MCP ابزارهایی را ارائه می‌دهد که به LLMها اجازه می‌دهد به قابلیت‌های مکان‌ها، آب و هوا و مسیرها دسترسی داشته باشند. می‌توانید Maps Grounding Lite را با فعال کردن آن در هر ابزاری که از سرورهای MCP پشتیبانی می‌کند، امتحان کنید.

ابزارها

Maps Grounding Lite ابزارهایی را ارائه می‌دهد که به LLMها اجازه می‌دهد به قابلیت‌های زیر در نقشه‌های گوگل دسترسی داشته باشند:

جستجوی مکان‌ها : اطلاعاتی در مورد مکان‌ها درخواست کنید و خلاصه داده‌های مکانی تولید شده توسط هوش مصنوعی، و همچنین شناسه‌های مکان، مختصات طول و عرض جغرافیایی و پیوندهای نقشه‌های گوگل برای هر یک از مکان‌های موجود در خلاصه را دریافت کنید. می‌توانید از شناسه‌های مکان و مختصات طول و عرض جغرافیایی بازگشتی با سایر APIهای پلتفرم نقشه‌های گوگل برای نمایش مکان‌ها روی نقشه استفاده کنید.
جستجوی آب و هوا : درخواست اطلاعات در مورد آب و هوا و ارائه شرایط فعلی، پیش‌بینی‌های ساعتی و پیش‌بینی‌های روزانه.
محاسبه مسیرها : درخواست اطلاعات در مورد مسیرهای رانندگی یا پیاده‌روی بین دو مکان و اطلاعات مسافت و مدت زمان مسیر رفت و برگشت.
توجه: Maps Grounding Lite مسیریابی گام به گام، مسیرها، ترافیک لحظه‌ای یا اطلاعات ناوبری را ارائه نمی‌دهد.

فعال کردن سرور Maps Grounding Lite MCP به LLMها اجازه می‌دهد تا ابزارهای جدید ارائه شده توسط سرور را فراخوانی کنند تا اطلاعات زمینی اضافی را برای انواع داده‌های ذکر شده در بالا برگردانند. در حالی که LLM می‌تواند از این اطلاعات اضافی برای زمینه استفاده کند، پاسخی که LLM در نهایت تولید می‌کند ممکن است شامل اطلاعات دقیق برگردانده شده توسط سرور MCP نباشد. شما باید صحت پاسخ تولید شده را تأیید کنید.

برنامه نمونه Maps Grounding Lite را امتحان کنید (در یک برگه جدید باز کنید)

صورتحساب و سهمیه‌ها

نحوه محاسبه هزینه برای شما

با مدل قیمت‌گذاری پرداخت به ازای استفاده پلتفرم نقشه‌های گوگل، میزان استفاده از Maps Grounding Lite برای هر درخواست محاسبه می‌شود، که در آن هر درخواست نشان دهنده یک رویداد صورتحساب است. میزان استفاده برای هر SKU محصول ردیابی می‌شود. صورتحساب شما علاوه بر کل هزینه‌های شما، یک ردیف برای هر SKU نشان می‌دهد. برای اطلاعات بیشتر به نمای کلی گزارش‌دهی مراجعه کنید.

برای جزئیات قیمت‌گذاری، به جدول قیمت‌گذاری اصلی و جدول قیمت‌گذاری هند مراجعه کنید.

Maps Grounding Lite همچنین از طریق بسته‌های Essentials و Pro Subscribe to save ارائه می‌شود.

سهمیه‌ها

سهمیه‌های زیر برای ابزارهای ارائه شده توسط Maps Grounding Lite اعمال می‌شود:

مکان‌های جستجو : ۳۰۰ پرس‌وجو در دقیقه، برای هر پروژه.
جستجوی آب و هوا : ۳۰۰ درخواست در دقیقه، برای هر پروژه.
محاسبه مسیرها : ۳۰۰ پرس‌وجو در دقیقه، برای هر پروژه.

سیاست‌ها و شرایط خدمات

Maps Grounding Lite تابع شرایط خدمات پلتفرم Google Maps ، از جمله شرایط خاص سرویس برای این سرویس است. این بخش الزامات اضافی استفاده از سرویس برای Maps Grounding Lite، از جمله LLM های سازگار و الزامات انتساب منبع را شرح می‌دهد.

الزامات LLM های سازگار

شما فقط می‌توانید از Maps Grounding Lite با مدرک کارشناسی ارشد مدیریت (LLM) که با شرایط خدمات پلتفرم Google Maps سازگار است، استفاده کنید.

برای مثال، شما مسئول هستید که اطمینان حاصل کنید محتوای نقشه‌های گوگل توسط LLM مورد استفاده شما ذخیره، ذخیره یا برای بهبود آن استفاده نمی‌شود. قبل از استفاده از Maps Grounding Lite، باید شرایط خدمات هر مدلی را که قصد استفاده از آن را با Maps Grounding Lite دارید، بررسی کنید. شما نباید از Maps Grounding Lite با هیچ مدلی که از داده‌های ورودی به مدل برای آموزش یا بهبود مدل استفاده می‌کند، استفاده کنید. شما مسئول هستید که اطمینان حاصل کنید که استفاده شما از مدل به طور کامل با محدودیت‌های محتوای نقشه‌های گوگل در شرایط خدمات پلتفرم نقشه‌های گوگل، از جمله شرایط خاص سرویس، مطابقت دارد.

الزامات انتساب برای منابع نقشه‌های گوگل

هر پاسخ ابزار از Maps Grounding Lite شامل منابعی است. هنگام ارائه نتایجی که از ابزارهای ارائه شده توسط Maps Grounding Lite استفاده می‌کنند، باید منابع مرتبط Google Maps را به گونه‌ای درج کنید که الزامات زیر را برآورده کند:

منابع نقشه‌های گوگل باید بلافاصله پس از محتوای تولید شده‌ای که منابع از آن پشتیبانی می‌کنند، قرار گیرند. این محتوای تولید شده همچنین به عنوان خروجی زمینی (Grounded Output) شناخته می‌شود.
منابع نقشه‌های گوگل باید در یک تعامل کاربری قابل مشاهده باشند.

منابع ابزار جستجوی مکان‌ها

فیلد places در ابزار search_places منابعی را ارائه می‌دهد که از summary پشتیبانی می‌کنند. برای places ، فراداده‌های زیر برگردانده می‌شوند:

place (نام منبع)
id
location
googleMapsLinks

برای هر مکان، باید پیش‌نمایش لینکی ایجاد کنید که این الزامات را برآورده کند:

هر منبع را با پیروی از دستورالعمل‌های انتساب متن Maps Grounding Lite به Google Maps نسبت دهید.
با استفاده از 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 در پروژه خود:

در کنسول گوگل کلود ، پروژه‌ای را که می‌خواهید برای Maps Grounding Lite استفاده کنید، انتخاب کنید.
فعال کردن صورتحساب برای پروژه در کنسول گوگل کلود .
Maps Grounding Lite را در کتابخانه API کنسول ابری گوگل فعال کنید.

احراز هویت با استفاده از کلید API

شما می‌توانید از یک کلید API موجود با Maps Grounding Lite استفاده کنید یا یک کلید جدید ایجاد کنید، البته تا زمانی که سرویس API Maps Grounding Lite را هم در پروژه Google Cloud و هم در کلید فعال کرده باشید.

برای احراز هویت با استفاده از کلید API:

با دنبال کردن مراحل موجود در «شروع به کار با پلتفرم نقشه‌های گوگل»، یک کلید API ایجاد یا پیکربندی کنید.
کلید را با استفاده از هدر X-Goog-Api-Key به سرور MCP ارسال کنید. شما باید این را به عنوان یک هدر HTTP سفارشی در پیکربندی ابزار MCP مربوط به LLM مشخص کنید.

احراز هویت با استفاده از OAuth

شما می‌توانید با استفاده از OAuth و با ایجاد اعتبارنامه‌های OAuth و ارسال آنها به میزبان MCP یا برنامه سرور MCP، احراز هویت کنید.

برای احراز هویت با استفاده از OAuth:

در کنسول گوگل کلود ، پروژه‌ای را که می‌خواهید برای Maps Grounding Lite استفاده کنید، انتخاب کنید.
در منوی API & Services ، گزینه Credentials را انتخاب کنید.
در منوی بالا، گزینه‌ی «ایجاد اعتبارنامه‌ها» > «شناسه‌ی کلاینت OAuth» را انتخاب کنید.
اگر پروژه صفحه رضایت پیکربندی‌شده ندارد، روی پیکربندی صفحه رضایت کلیک کنید و دستورالعمل‌های روی صفحه را دنبال کنید.
در بخش معیارها ، روی ایجاد کلاینت OAuth کلیک کنید.
در صفحه ایجاد شناسه کلاینت OAuth ، نوع برنامه را انتخاب کرده و نامی برای شناسه کلاینت وارد کنید.
جزئیات اضافی مرتبط با نوع برنامه خود را مشخص کنید. برای مثال، اگر در حال ایجاد یک برنامه وب هستید، URI های مجاز برای درخواست های مرورگر و سرور را اضافه کنید.
پس از ایجاد کلاینت، شناسه و رمز کلاینت را ذخیره کنید.
هنگام پیکربندی میزبان MCP یا برنامه سرور MCP خود برای دسترسی به Maps Grounding Lite، شناسه و رمز کلاینت OAuth خود را وارد کنید. همچنین باید محدوده زیر را درخواست کنید: https://www.googleapis.com/auth/maps-platform.mapstools .

برای اطلاعات بیشتر، به استفاده از OAuth 2.0 برای دسترسی به API های گوگل مراجعه کنید.

پیکربندی LLMها برای دسترسی به سرور Maps Grounding Lite MCP

زمانی که یک پروژه Google Cloud با سرویس API فعال Maps Grounding Lite و اعتبارنامه‌های معتبر، مانند کلید API یا شناسه و رمز کلاینت OAuth، داشته باشید، می‌توانید LLMها را برای دسترسی به سرور MCP با دنبال کردن مستندات پیکربندی MCP مربوطه و با استفاده از آدرس اینترنتی سرور Maps Grounding Lite MCP پیکربندی کنید: https://mapstools.googleapis.com/mcp

برای اطلاعات بیشتر، به پیکربندی MCP در یک برنامه هوش مصنوعی مراجعه کنید.

پیکربندی Maps Grounding Lite با Gemini CLI

این بخش مثالی از نحوه پیکربندی سرور Maps Grounding Lite MCP با استفاده از Gemini CLI ارائه می‌دهد. برای جزئیات بیشتر، به سرورهای MCP با Gemini CLI مراجعه کنید.

پس از نصب رابط خط فرمان Gemini، می‌توانید از دستور 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 (3 tools)
Tools:
-   compute_routes
-   lookup_weather
-   search_places

شروع به پرسیدن سوالات مربوط به نقشه‌ها با رابط خط فرمان (CLI) کنید. برای مثال، عبارت «چند رستوران در مانتین ویو به من پیشنهاد بده» را امتحان کنید که باید ابزار search_places را از طرف شما فراخوانی کند.

پیکربندی Grounding Lite با کیت توسعه عامل (ADK)

این بخش مثال‌هایی ارائه می‌دهد که نحوه پیکربندی سرور Grounding Lite MCP را با استفاده از کیت توسعه عامل (ADK) و پایتون، جاوا یا تایپ‌اسکریپت نشان می‌دهد.

پایتون

مرحله ۱: نماینده خود را با `McpToolset` برای Google Maps Grounding Lite تعریف کنید

فایل 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"
                }
            )
        )
    ]
)

مرحله ۲: اطمینان حاصل کنید که `init.py` وجود دارد

مطمئن شوید که فایل __init__.py در همان دایرکتوری که فایل agent.py قرار دارد، قرار دارد:

from . import agent

مرحله ۳: اجرای `adk web` و Interact

متغیر محیطی را تنظیم کنید :
کلید API نقشه‌های گوگل خود را به عنوان یک متغیر محیطی در ترمینال خود تنظیم کنید:
```
export GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_GOOGLE_MAPS_API_KEY"
        
```
اجرای adk web :
برای شروع رابط وب ADK، دستور زیر را اجرا کنید:
```
adk web
        
```
تعامل در رابط کاربری :
- travel_planner_agent را انتخاب کنید.
- پیشنهادهایی مانند موارد زیر را امتحان کنید:
  - «من فردا در سانفرانسیسکو خواهم بود. هوا چطور است؟»
  - «کافی شاپ‌های نزدیک پارک گلدن گیت را پیدا کنید.»
  - «از گوگل‌پلکس تا SFO مسیر پیدا کنید.»

جاوا

یک عامل تعریف کنید که McpToolset در جاوا مقداردهی اولیه کند. اگر از متغیر محیطی استفاده نمی‌کنید، 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();
        }
    }
}

تایپ اسکریپت

یک عامل تعریف کنید که 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، از فرم‌های زیر استفاده کنید: