Haritalar Grounding Lite

Google Haritalar Platformu Grounding Lite, Model Context Protocol (MCP) desteği sunan bir hizmettir. Bu hizmet, Google Haritalar'daki güvenilir coğrafi verilerle yapay zeka uygulamalarınızı temellendirmenizi kolaylaştırır. MCP sunucusu, LLM'lerin yerler, hava durumu ve rotalarla ilgili özelliklere erişmesine olanak tanıyan araçlar sağlar. MCP sunucularını destekleyen herhangi bir araçta etkinleştirerek Maps Grounding Lite'ı deneyebilirsiniz.

Araçlar

Maps Grounding Lite, LLM'lerin aşağıdaki Google Haritalar özelliklerine erişmesine olanak tanıyan araçlar sağlar:

• Yerleri arama: Yerlerle ilgili bilgi isteyin ve yapay zeka tarafından oluşturulan yer verisi özetlerinin yanı sıra özetlere dahil edilen her yer için yer kimlikleri, enlem ve boylam koordinatları ile Google Haritalar bağlantılarını alın. Yerleri haritada göstermek için döndürülen yer kimliklerini ve enlem ile boylam koordinatlarını diğer Google Haritalar Platformu API'leriyle birlikte kullanabilirsiniz.
• Hava durumunu arama: Hava durumu hakkında bilgi isteyin ve mevcut koşulları, saatlik tahminleri ve günlük tahminleri döndürün.

• Rotaları hesaplama: İki konum arasındaki araba veya yaya rotaları hakkında bilgi isteyin ve rota mesafesi ile süresi bilgilerini döndürün.

Maps Grounding Lite MCP sunucusunun etkinleştirilmesi, LLM'lerin yukarıda listelenen veri türleri için ek temellendirme bilgileri döndürmek üzere sunucu tarafından kullanıma sunulan yeni araçları çağırmasına olanak tanır. LLM bu ek bilgileri bağlam için kullanabilse de LLM'nin nihai olarak oluşturduğu yanıt, MCP sunucusu tarafından döndürülen bilgilerin aynısını içermeyebilir. Oluşturulan yanıtın doğruluğunu doğrulamanız gerekir.

Maps Grounding Lite örnek uygulamasını deneyin (Yeni sekmede açılır)

Faturalandırma ve kotalar

Nasıl faturalandırılırsınız?

Google Haritalar Platformu'nun kullandıkça öde fiyatlandırma modelinde, Maps Grounding Lite kullanımı her istek için hesaplanır. Her istek bir faturalandırma etkinliğini temsil eder. Kullanım, her ürün SKU'su için izlenir. Faturanızda, toplam ücretlerinize ek olarak her SKU için bir satır öğesi gösterilir. Daha fazla bilgi için Raporlara genel bakış bölümüne bakın.

Fiyatlandırma ayrıntıları için Ana fiyatlandırma tablosu ve Hindistan fiyatlandırma tablosu'na bakın.

Maps Grounding Lite, Essentials ve Pro paketlerinde de sunulur. İndirimden yararlanmak için abone olun

Kotalar

Maps Grounding Lite tarafından sağlanan araçlar için aşağıdaki kotalar geçerlidir:

• Yer arama: Proje başına dakikada 300 sorgu.
• Hava durumunu arama: Proje başına dakikada 300 sorgu.
• Rota hesaplama: Proje başına dakikada 300 sorgu.

Politikalar ve hizmet şartları

Haritalar Grounding Lite, bu hizmete ilişkin hizmete özgü şartlar da dahil olmak üzere Google Haritalar Platformu Hizmet Şartları'na tabidir. Bu bölümde, uyumlu LLM'ler ve kaynak ilişkilendirme şartları da dahil olmak üzere Maps Grounding Lite için ek hizmet kullanımı şartları açıklanmaktadır.

Uyumlu LLM'lerle ilgili koşullar

Maps Grounding Lite'ı yalnızca Google Haritalar Platformu Hizmet Şartları'na uygun bir LLM ile kullanabilirsiniz.

Örneğin, Google Haritalar İçeriği'nin, kullanmayı seçtiğiniz LLM tarafından önbelleğe alınmamasını, depolanmamasını veya LLM'yi iyileştirmek için kullanılmamasını sağlamak sizin sorumluluğunuzdadır. Maps Grounding Lite'ı kullanmadan önce, Maps Grounding Lite ile kullanmayı planladığınız tüm modellerin Hizmet Şartları'nı incelemeniz gerekir. Maps Grounding Lite'ı, modele girilen verileri model eğitimi veya iyileştirme için kullanan modellerle birlikte kullanmamalısınız. Modeli kullanımınızın, hizmete özgü şartlar da dahil olmak üzere Google Haritalar Platformu Hizmet Şartları'ndaki Google Haritalar İçeriği ile ilgili kısıtlamalara tamamen uygun olmasını sağlamak sizin sorumluluğunuzdadır.

Google Haritalar kaynakları için atıf şartları

Maps Grounding Lite'ın her araç yanıtında kaynaklar yer alır. Maps Grounding Lite tarafından sağlanan araçları kullanan sonuçları sunarken ilişkili Google Haritalar kaynaklarını aşağıdaki şartları karşılayacak şekilde eklemeniz gerekir:

• Google Haritalar kaynakları, kaynakların desteklediği oluşturulmuş içeriği hemen takip etmelidir. Bu üretilmiş içerik, Temellendirilmiş Çıkış olarak da adlandırılır.
• Google Haritalar kaynakları, tek bir kullanıcı etkileşimi içinde görüntülenebilmelidir.

Yer arama aracı için kaynaklar

search_places Aracı places alanı, summary destekleyen kaynaklar sağlar. places için aşağıdaki meta veriler döndürülür:

• place (kaynak adı)
• id
• location
• googleMapsLinks

Her yer için aşağıdaki koşulları karşılayan bir bağlantı önizlemesi oluşturmanız gerekir:

• Maps Grounding Lite metin ilişkilendirme yönergelerini uygulayarak her kaynağı Google Haritalar ile ilişkilendirin.
• Yanıtın places.googleMapsLinks.placeUrl simgesini kullanarak kaynağa bağlantı verin.

LLM'leri MCP sunucusunu kullanacak şekilde yapılandırma

Maps Grounding Lite'ı kullanmak için öncelikle Maps Grounding Lite API hizmetinin etkinleştirildiği bir Google Cloud projenizin yanı sıra bir API anahtarı veya OAuth istemci kimliğinizin olması gerekir. Ardından, LLM'leri MCP sunucusuna erişecek şekilde yapılandırabilirsiniz. Grounding Lite MCP sunucusu, Streamable HTTP aktarımı kullanır.

Google Cloud projenizde Maps Grounding Lite hizmetini etkinleştirin.

Projenizde API'yi etkinleştirmek için:

1. Google Cloud Console'da, Maps Grounding Lite için kullanmak istediğiniz projeyi seçin.
2. Google Cloud Console'da proje için faturalandırmayı etkinleştirin.
3. Google Cloud Console API Kitaplığı'nda Maps Grounding Lite'ı etkinleştirin.

API anahtarı kullanarak kimlik doğrulama

Google Cloud projesinde ve anahtarda Maps Grounding Lite API hizmetini etkinleştirdiğiniz sürece Maps Grounding Lite ile mevcut bir API anahtarını kullanabilir veya yeni bir anahtar oluşturabilirsiniz.

API anahtarı kullanarak kimlik doğrulamak için:

1. Google Haritalar Platformu'nu kullanmaya başlama bölümündeki adımları uygulayarak bir API anahtarı oluşturun veya yapılandırın.
2. X-Goog-Api-Key üstbilgisini kullanarak anahtarı MCP sunucusuna iletin. Bunu, LLM'nin MCP aracı yapılandırmasında özel bir HTTP üst bilgisi olarak belirtmeniz gerekir.

OAuth kullanarak kimlik doğrulaması yapma

OAuth kimlik bilgileri oluşturup bunları MCP ana makinesine veya MCP sunucu uygulamasına ileterek OAuth kullanarak kimlik doğrulaması yapabilirsiniz.

OAuth kullanarak kimlik doğrulaması yapmak için:

1. Google Cloud Console'da, Maps Grounding Lite için kullanmak istediğiniz projeyi seçin.
2. API ve Hizmetler menüsünde Kimlik Bilgileri'ni seçin.
3. Üst menüde Kimlik bilgileri oluştur > OAuth istemci kimliği'ni seçin.
4. Projenin yapılandırılmış bir kullanıcı rızası ekranı yoksa Kullanıcı rızası ekranını yapılandır'ı tıklayın ve ekrandaki talimatları uygulayın.
5. Metrikler bölümünde OAuth istemcisi oluştur'u tıklayın.
6. OAuth istemci kimliği oluşturun ekranında bir uygulama türü seçin ve istemci kimliği için bir ad girin.
7. Uygulama türünüzle ilgili ek ayrıntıları belirtin. Örneğin, bir web uygulaması oluşturuyorsanız tarayıcı ve sunucu istekleri için yetkili URI'ler ekleyin.
8. İstemciniz oluşturulduktan sonra istemci kimliğini ve gizli anahtarını kaydedin.
9. MCP ana makinenizi veya MCP sunucu uygulamanızı Maps Grounding Lite'a erişecek şekilde yapılandırırken OAuth istemci kimliğinizi ve gizli anahtarınızı iletin. Ayrıca şu kapsamı da istemeniz gerekir: https://www.googleapis.com/auth/maps-platform.mapstools.

Daha fazla bilgi için Google API'lerine Erişmek için OAuth 2.0'ı Kullanma başlıklı makaleyi inceleyin.

LLM'leri Maps Grounding Lite MCP sunucusuna erişecek şekilde yapılandırma

Maps Grounding Lite API hizmetinin etkinleştirildiği bir Google Cloud projeniz ve API anahtarı veya OAuth istemci kimliği ve gizli anahtar gibi geçerli kimlik bilgileriniz olduğunda, ilgili MCP yapılandırma belgelerini izleyerek ve Maps Grounding Lite MCP sunucu URL'sini (https://mapstools.googleapis.com/mcp) kullanarak LLM'leri MCP sunucusuna erişecek şekilde yapılandırabilirsiniz.

Daha fazla bilgi için Yapay zeka uygulamasında MCP'yi yapılandırma başlıklı makaleyi inceleyin.

Gemini CLI ile Haritalar Grounding Lite'ı yapılandırma

Bu bölümde, Gemini CLI'yı kullanarak Maps Grounding Lite MCP sunucusunun nasıl yapılandırılacağına dair bir örnek verilmektedir. Daha fazla bilgi için Gemini CLI ile MCP sunucuları başlıklı makaleyi inceleyin.

1. Gemini CLI'yı yükledikten sonra, Maps Grounding Lite MCP sunucusunu yapılandırmak için add komutunu kullanabilirsiniz:

   gemini mcp add -s user -t http -H 'X-Goog-Api-Key: API_KEY' maps-grounding-lite-mcp https://mapstools.googleapis.com/mcp
   

   Yapılandırma başarılıysa sunucunun kullanıcı ayarlarınıza eklendiğini onaylayan bir mesaj görürsünüz.

2. Sunucunun doğru şekilde çalıştığını doğrulamak için /mcp list komutunu çalıştırın:

   > /mcp list
   
   Configured MCP servers:
   
   maps-grounding-lite-mcp - Ready (3 tools)
   Tools:
   -   compute_routes
   -   lookup_weather
   -   search_places
   

3. KSA ile Haritalar ile ilgili sorular sormaya başlayın. Örneğin, "Mountain View'daki restoranlardan bazılarını öner" istemini deneyin. Bu istem, sizin adınıza search_places aracını çağırmalıdır.

Agent Development Kit (ADK) ile Grounding Lite'ı yapılandırma

Bu bölümde, Agent Development Kit (ADK) ve Python, Java veya TypeScript kullanarak Grounding Lite MCP sunucusunun nasıl yapılandırılacağını gösteren örnekler verilmektedir.

# ./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"
                }
            )
        )
    ]
)
    

from . import agent
    

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();
        }
    }
}
    

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

Geri bildirim paylaşma

Haritalar Grounding Lite ile ilgili geri bildirimlerinizi paylaşmak için aşağıdaki formları kullanın:

• Hata bildirme
• Özellik isteği gönderme
• Geri bildirim gönderin