Maps Grounding Lite

Google Maps Platform Grounding Lite là một dịch vụ có hỗ trợ Giao thức bối cảnh mô hình (MCP) giúp bạn dễ dàng liên kết các ứng dụng AI với dữ liệu không gian địa lý đáng tin cậy từ Google Maps. Máy chủ MCP cung cấp các công cụ cho phép Mô hình ngôn ngữ lớn (LLM) truy cập vào các chức năng về địa điểm, thời tiết và tuyến đường. Bạn có thể dùng thử Maps Grounding Lite bằng cách bật dịch vụ này trong mọi công cụ hỗ trợ máy chủ MCP.

Công cụ

Maps Grounding Lite cung cấp các công cụ cho phép LLM truy cập vào các chức năng sau đây của Google Maps:

• Tìm địa điểm: Yêu cầu thông tin về địa điểm và nhận dữ liệu địa điểm được AI tạo, cũng như Mã địa điểm, toạ độ vĩ độ và kinh độ, và đường liên kết đến Google Maps cho từng địa điểm có trong bản tóm tắt. Bạn có thể sử dụng Mã địa điểm và toạ độ vĩ độ và kinh độ được trả về với các API khác của Nền tảng Google Maps để hiển thị địa điểm trên bản đồ.
• Tra cứu thời tiết: Yêu cầu thông tin về thời tiết và trả về điều kiện hiện tại, dự báo theo giờ và dự báo hằng ngày.

• Tính toán tuyến đường: Yêu cầu thông tin về tuyến đường lái xe hoặc đi bộ giữa hai địa điểm và trả về thông tin về khoảng cách và thời lượng của tuyến đường.

Việc bật máy chủ MCP của Maps Grounding Lite cho phép LLM gọi các công cụ mới do máy chủ này cung cấp để trả về thông tin liên kết bổ sung cho các loại dữ liệu được liệt kê ở trên. Mặc dù LLM có thể sử dụng thông tin bổ sung này cho bối cảnh, nhưng phản hồi mà LLM tạo ra cuối cùng có thể không bao gồm thông tin chính xác do máy chủ MCP trả về. Bạn nên xác minh tính chính xác của phản hồi được tạo.

API phân giải (thử nghiệm)

Maps Grounding Lite cung cấp API phân giải, cho phép bạn phân giải văn bản và URL vị trí ở dạng tự do thành các giá trị nhận dạng địa điểm có cấu trúc của Google Maps. API phân giải bao gồm 2 điểm cuối:

• Phân giải tên: Phân giải một nhóm tên hoặc địa chỉ vị trí thành các thực thể địa điểm cụ thể trên Google Maps. Điều này hữu ích cho việc liên kết các truy vấn không có cấu trúc của người dùng thành Mã địa điểm ổn định.
• Phân giải URL trên Maps: Phân giải một nhóm URL trên Google Maps thành các thực thể địa điểm cụ thể. Các định dạng được hỗ trợ bao gồm URL địa điểm tiêu chuẩn và URL rút gọn.

Bạn có thể sử dụng các điểm cuối này để liên kết các truy vấn hoặc đường liên kết không có cấu trúc của người dùng thành Mã địa điểm ổn định để tích hợp với các API khác của Nền tảng Google Maps.

Hãy xem bài viết API phân giải công cụ Maps (thử nghiệm) để biết thêm thông tin.

Dùng thử ứng dụng mẫu Maps Grounding Lite (Mở trong thẻ mới)

Thanh toán và hạn mức

Cách tính phí

Với mô hình giá trả tiền theo mức dùng của Google Maps Platform, mức sử dụng Maps Grounding Lite được tính cho từng yêu cầu, trong đó mỗi yêu cầu đại diện cho một sự kiện thanh toán. Mức sử dụng được theo dõi cho từng sản phẩm SKU. Hoá đơn của bạn sẽ hiển thị một mục hàng cho từng SKU ngoài tổng phí. Hãy xem bài viết Tổng quan về báo cáo để biết thêm thông tin.

Hãy xem Bảng giá chính và Bảng giá ở Ấn Độ để biết thông tin chi tiết về giá.

Maps Grounding Lite cũng được cung cấp thông qua các gói thuê bao Essentials và Pro để tiết kiệm chi phí.

Hạn mức

Các hạn mức sau đây áp dụng cho các công cụ và API do Maps Grounding Lite cung cấp:

• Tìm địa điểm: 300 lượt truy vấn mỗi phút trên mỗi dự án.
• Tra cứu thời tiết: 300 lượt truy vấn mỗi phút trên mỗi dự án.
• Tính toán tuyến đường: 300 lượt truy vấn mỗi phút trên mỗi dự án.
• Phân giải tên (thử nghiệm): 600 lượt truy vấn mỗi phút trên mỗi dự án.
• Phân giải URL trên Maps (thử nghiệm): 600 lượt truy vấn mỗi phút trên mỗi dự án.

Chính sách và điều khoản dịch vụ

Maps Grounding Lite tuân theo Điều khoản dịch vụ của Google Maps Platform, bao gồm cả các điều khoản dành riêng cho dịch vụ này. Phần này mô tả các yêu cầu bổ sung về việc sử dụng dịch vụ đối với Maps Grounding Lite, bao gồm cả các LLM tương thích và yêu cầu về việc ghi công nguồn.

Yêu cầu đối với LLM tương thích

Bạn chỉ có thể sử dụng Maps Grounding Lite với một LLM tuân thủ Điều khoản dịch vụ của Google Maps Platform.

Ví dụ: bạn có trách nhiệm đảm bảo rằng Nội dung trên Google Maps không được lưu vào bộ nhớ đệm, được lưu trữ hoặc được dùng để cải thiện LLM mà bạn chọn sử dụng. Trước khi sử dụng Maps Grounding Lite, bạn cần xem Điều khoản dịch vụ cho mọi mô hình mà bạn dự định sử dụng với Maps Grounding Lite. Bạn không được sử dụng Maps Grounding Lite với bất kỳ mô hình nào sử dụng dữ liệu đầu vào trong mô hình cho bất kỳ hoạt động huấn luyện hoặc cải thiện mô hình nào. Bạn có trách nhiệm đảm bảo rằng việc sử dụng mô hình của bạn tuân thủ đầy đủ các hạn chế đối với Nội dung trên Google Maps trong Điều khoản dịch vụ của Google Maps Platform, bao gồm cả các điều khoản dành riêng cho dịch vụ.

Yêu cầu về việc ghi công đối với các nguồn trên Google Maps

Mỗi phản hồi của công cụ từ Maps Grounding Lite đều bao gồm các nguồn. Khi trình bày kết quả sử dụng các công cụ do Maps Grounding Lite cung cấp, bạn phải đưa các nguồn liên kết trên Google Maps vào theo cách đáp ứng các yêu cầu sau:

• Các nguồn trên Google Maps phải xuất hiện ngay sau nội dung được tạo mà các nguồn đó hỗ trợ. Nội dung được tạo này còn được gọi là Đầu ra được liên kết.
• Các nguồn trên Google Maps phải có thể xem được trong một lượt tương tác của người dùng.

Các nguồn cho công cụ Tìm địa điểm

Trường places của công cụ search_places cung cấp các nguồn hỗ trợ summary. Đối với places, siêu dữ liệu sau đây sẽ được trả về:

• place (tên tài nguyên)
• id
• location
• googleMapsLinks

Đối với mỗi địa điểm, bạn phải tạo bản xem trước đường liên kết đáp ứng các yêu cầu sau:

• Ghi công từng nguồn cho Google Maps, tuân theo nguyên tắc ghi công văn bản của Maps Grounding Lite.
• Liên kết đến nguồn bằng cách sử dụng places.googleMapsLinks.placeUrl từ phản hồi.

Định cấu hình LLM để sử dụng máy chủ MCP

Để sử dụng Maps Grounding Lite, trước tiên, bạn cần có một dự án trên đám mây của Google Cloud đã bật dịch vụ API Maps Grounding Lite, cũng như khoá API hoặc Ứng dụng OAuth. Sau đó, bạn có thể định cấu hình LLM để truy cập vào máy chủ MCP. Máy chủ MCP của Grounding Lite sử dụng giao thức truyền tải HTTP có thể truyền trực tuyến.

Bật dịch vụ Maps Grounding Lite trên dự án trên đám mây của Google

Cách bật API trên dự án:

1. Trong Google Cloud Console, hãy chọn dự án mà bạn muốn sử dụng cho Maps Grounding Lite.
2. Bật tính năng thanh toán cho dự án trong Google Cloud Console.
3. Bật Maps Grounding Lite trong Google Cloud Thư viện API của Console.

Xác thực bằng khoá API

Bạn có thể sử dụng khoá API hiện có với Maps Grounding Lite hoặc tạo một khoá API mới, miễn là bạn bật dịch vụ API Maps Grounding Lite trên cả dự án trên đám mây Google Cloud và khoá API.

Cách xác thực bằng khoá API:

1. Tạo hoặc định cấu hình khoá API bằng cách làm theo các bước trong bài viết Bắt đầu sử dụng Google Maps Platform.
2. Truyền khoá đến máy chủ MCP bằng tiêu đề X-Goog-Api-Key. Bạn cần chỉ định tiêu đề này là tiêu đề HTTP tuỳ chỉnh trong cấu hình công cụ MCP của LLM.

Xác thực bằng OAuth

Bạn có thể xác thực bằng OAuth bằng cách tạo thông tin xác thực OAuth và truyền thông tin đó đến máy chủ lưu trữ MCP hoặc ứng dụng máy chủ MCP.

Cách xác thực bằng OAuth:

1. Trong Google Cloud Console, hãy chọn dự án mà bạn muốn sử dụng cho Maps Grounding Lite.
2. Trong trình đơn API và dịch vụ, hãy chọn Thông tin xác thực.
3. Trong trình đơn trên cùng, hãy chọn Tạo thông tin xác thực > Mã ứng dụng OAuth.
4. Nếu dự án chưa có màn hình xin phép được định cấu hình, hãy nhấp vào Định cấu hình màn hình xin phép rồi làm theo hướng dẫn trên màn hình.
5. Trong phần Chỉ số, hãy nhấp vào Tạo ứng dụng OAuth.
6. Trên màn hình Tạo mã ứng dụng khách OAuth, hãy chọn một loại ứng dụng và nhập tên cho mã ứng dụng khách.
7. Chỉ định các thông tin bổ sung liên quan đến loại ứng dụng của bạn. Ví dụ: nếu bạn đang tạo một ứng dụng web, hãy thêm các URI được uỷ quyền cho các yêu cầu của trình duyệt và máy chủ.
8. Sau khi tạo ứng dụng khách, hãy lưu mã ứng dụng khách và khoá bí mật.
9. Khi định cấu hình ứng dụng máy chủ lưu trữ MCP hoặc máy chủ MCP để truy cập vào Maps Grounding Lite, hãy truyền mã ứng dụng OAuth và khoá bí mật. Bạn cũng phải yêu cầu phạm vi sau: https://www.googleapis.com/auth/maps-platform.mapstools.

Để biết thêm thông tin, hãy xem bài viết Sử dụng OAuth 2.0 để truy cập vào các API của Google.

Định cấu hình LLM để truy cập vào máy chủ MCP của Maps Grounding Lite

Sau khi có một dự án trên đám mây của Google Cloud đã bật dịch vụ Maps Grounding Lite API và thông tin xác thực hợp lệ, chẳng hạn như khoá API hoặc Ứng dụng OAuth và khoá bí mật, bạn có thể định cấu hình LLM để truy cập vào máy chủ MCP bằng cách làm theo tài liệu cấu hình MCP tương ứng và sử dụng URL máy chủ MCP của Maps Grounding Lite: https://mapstools.googleapis.com/mcp

Để biết thêm thông tin, hãy xem bài viết Định cấu hình MCP trong ứng dụng AI.

Định cấu hình Maps Grounding Lite bằng Gemini CLI

Phần này cung cấp ví dụ về cách định cấu hình máy chủ MCP của Maps Grounding Lite bằng Gemini CLI. Để biết thêm thông tin chi tiết, hãy xem bài viết Máy chủ MCP bằng Gemini CLI.

1. Sau khi cài đặt Gemini CLI, bạn có thể sử dụng lệnh add để định cấu hình máy chủ MCP của 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
   

   Nếu định cấu hình thành công, bạn sẽ thấy thông báo xác nhận rằng máy chủ đã được thêm vào chế độ cài đặt người dùng.

2. Để xác thực rằng máy chủ đang hoạt động đúng cách, hãy chạy lệnh /mcp list:

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

3. Bắt đầu đặt câu hỏi liên quan đến Maps bằng CLI. Ví dụ: hãy thử câu lệnh "Recommend me some restaurants in Mountain View" (Đề xuất cho tôi một số nhà hàng ở Mountain View). Câu lệnh này sẽ gọi công cụ search_places thay cho bạn.

Định cấu hình Grounding Lite bằng Bộ công cụ phát triển tác nhân (ADK)

Phần này cung cấp các ví dụ cho thấy cách định cấu hình máy chủ MCP của Grounding Lite bằng Bộ công cụ phát triển tác nhân (ADK) và Python, Java hoặc TypeScript.

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

Chia sẻ ý kiến phản hồi

Để chia sẻ ý kiến phản hồi về Maps Grounding Lite, hãy sử dụng các biểu mẫu sau:

• Báo cáo lỗi
• Gửi yêu cầu về tính năng
• Gửi ý kiến phản hồi