پایه‌مندسازی با Google Maps

«پایه‌سازی با Google Maps» مدل Gemini را به داده‌های زمین‌مکانی از Google Maps متصل می‌کند تا بتوانید قابلیت‌های آگاه از مکان را در برنامه‌هایتان بسازید.

پایه‌سازی با Google Maps مزایای زیر را دارد:

  • افزایش دقت واقعی: کاهش توهمات مدل با پایه‌گذاری پاسخ‌ها بر پایگاه داده Google که شامل بیش از ۲۵۰ میلیون مکان و کسب‌وکار واقعی است.
  • دسترسی به اطلاعات هم‌زمان: پاسخ دادن به سؤالات بااستفاده از داده‌های زنده، مثل ساعات کاری فعلی و وضعیت هم‌زمان ایستگاه‌های شارژ خودرو برقی.
  • ارائه منابع: با نشان دادن منابع مکان Google Maps و پیوندها مستقیماً در کنار ادعاهای مبتنی بر مکان مدل، اعتماد کاربر را جلب کنید.

مدل‌های پشتیبانی‌شده

  • gemini-4-argon
  • gemini-3.8-flash
  • ‫gemini-3.5-flash-lite (و gemini-3.1-flash-lite قدیمی‌تر)

مدل‌های قدیمی‌تر Gemini 3.x Flash با کاربرد عمومی از این قابلیت پشتیبانی می‌کنند، اما به‌دلیل تاریخ‌های خاموشی آتی و/یا مسیریابی خودکار به مدل‌های جدیدتر، دیگر برای استفاده توصیه نمی‌شوند.

زبان‌های پشتیبانی‌شده

زبان‌های پشتیبانی‌شده برای مدل‌های Gemini را ببینید.

مستندسازی مدل با Google Maps

روی ارائه‌دهنده Gemini API کلیک کنید تا محتوا و کد مختص ارائه‌دهنده را در این صفحه ببینید.

وقتی نمونه GenerativeModel را ایجاد می‌کنید، GoogleMaps را به‌عنوان tool ارائه دهید تا مدل بتواند از آن برای تولید پاسخ خود استفاده کند.

Swift


import CoreLocation
import FirebaseAILogic

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())

// Example: Coordinates for New York City
let latAndLong = CLLocationCoordinate2D(latitude: 40.7128, longitude: -74.0060)

// (Optional) Define a RetrievalConfig to configure the Grounding with Google Maps tool.
// You can optionally provide a location's coordinates and/or a language code
// for more relevant and personalized Google Maps results.
let retrievalConfig = RetrievalConfig(
    location: latAndLong,
    // Example: Language code for English (US).
    languageCode: "en-US"
)

// Wrap the RetrievalConfig inside a ToolConfig.
let toolConfig = ToolConfig(retrievalConfig: retrievalConfig)

// Create a `GenerativeModel` instance with a model that supports your use case.
let model = ai.generativeModel(
    modelName: "GEMINI_MODEL_NAME",
    // Provide Google Maps as a tool that the model can use to generate its response.
    tools: [.googleMaps()],
    // Add the configuration for the Grounding with Google Maps tool
    // (if this optional config was defined above).
    toolConfig: toolConfig
)

let response = try await model.generateContent("restaurants near me?")
print(response.text ?? "No text in response.")

// Make sure to comply with the "Grounding with Google Maps" usage requirements,
// which includes how you meet service usage requirements

Kotlin


// (Optional) Define a RetrievalConfig to configure the Grounding with Google Maps tool.
// You can optionally provide a location's coordinates and/or a language code
// for more relevant and personalized Google Maps results.
val retrievalConfig = RetrievalConfig(
    // Example: Coordinates for New York City
    latLng = LatLng(latitude = 40.7128, longitude = -74.0060),
    // Example: Language code for English (US)
    languageCode = "en-US"
)

// Wrap the RetrievalConfig inside a ToolConfig.
val toolConfig = ToolConfig(
    retrievalConfig = retrievalConfig
)

// Initialize the Gemini Developer API backend service.
// Create a `GenerativeModel` instance with a model that supports your use case.
val model = Firebase.ai(backend = GenerativeBackend.googleAI()).generativeModel(
    modelName = "GEMINI_MODEL_NAME",
    // Add the configuration for the Grounding with Google Maps tool
    // (if this optional config was defined above).
    toolConfig = toolConfig,
    // Provide Google Maps as a tool that the model can use to generate its response.
    tools = listOf(Tool.googleMaps())
)

val response = model.generateContent("restaurants near me?")
print(response.text)

// Make sure to comply with the "Grounding with Google Maps" usage requirements,
// which includes how you meet service usage requirements

Java


// (Optional) Define a ToolConfig to configure the Grounding with Google Maps tool.
// You can optionally provide a location's coordinates and/or a language code
// for more relevant and personalized Google Maps results.
ToolConfig toolConfig = new ToolConfig(
    null,
    new RetrievalConfig(
        // Example: Coordinates for New York City.
        new LatLng(40.7128, -74.0060),
        // Example: Language code for English (US).
       "en-US"
    )
);

// Initialize the Gemini Developer API backend service.
// Create a `GenerativeModel` instance with a model that supports your use case.
GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.googleAI())
                .generativeModel("GEMINI_MODEL_NAME",
                        null,
                        null,
                        // Provide Google Maps as a tool that the model can use to generate its response.
                        List.of(Tool.googleMaps()),
                        // Add the configuration for the Grounding with Google Maps tool
                        // (if this optional config was defined above).
                        toolConfig);

// Use the GenerativeModelFutures Java compatibility layer which offers
// support for ListenableFuture and Publisher APIs.
GenerativeModelFutures model = GenerativeModelFutures.from(ai);

ListenableFuture response = model.generateContent("restaurants near me?");
  Futures.addCallback(response, new FutureCallback() {
      @Override
      public void onSuccess(GenerateContentResponse result) {
          String resultText = result.getText();
          System.out.println(resultText);
      }

      @Override
      public void onFailure(Throwable t) {
          t.printStackTrace();
      }
  }, executor);

// Make sure to comply with the "Grounding with Google Maps" usage requirements,
// which includes how you meet service usage requirements

Web


import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend } from "firebase/ai";

// TODO(developer): Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service.
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// (Optional) Define a toolConfig to configure the Grounding with Google Maps tool.
// You can optionally provide a location's coordinates and/or a language code
// for more relevant and personalized Google Maps results.
const toolConfig = {
  retrievalConfig: {
    // Example: Coordinates for New York City
    latLng: {
      latitude: 40.7128,
      longitude: -74.0060
    },
    // Example: Language code for English (US)
    languageCode: 'en-US'
  }
};

// Create a `GenerativeModel` instance with a model that supports your use case
const model = getGenerativeModel(
  ai,
  {
    model: "GEMINI_MODEL_NAME",
    // Provide Google Maps as a tool that the model can use to generate its response.
    tools: [ { googleMaps: {} } ],
    // Add the configuration for the Grounding with Google Maps tool
    // (if this optional config was defined above).
    toolConfig
  }
);

const result = await model.generateContent("restaurants near me?");

console.log(result.response.text());

// Make sure to comply with the "Grounding with Google Maps" usage requirements,
// which includes how you meet service usage requirements

Dart


import 'package:firebase_core/firebase_core.dart';
import 'package:firebase_ai/firebase_ai.dart';
import 'firebase_options.dart';

// Initialize FirebaseApp.
await Firebase.initializeApp(
  options: DefaultFirebaseOptions.currentPlatform,
);

// (Optional) Define a ToolConfig to configure the Grounding with Google Maps tool.
// You can optionally provide a location's coordinates and/or a language code
// for more relevant and personalized Google Maps results.
final toolConfig = ToolConfig(
  retrievalConfig: RetrievalConfig(
    // Example: Coordinates for New York City.
    latLng: LatLng(latitude: 40.712728, longitude: -74.006015),
    // Example: Language code for English (US).
    languageCode: 'en-US',
  ),
);

// Initialize the Gemini Developer API backend service.
// Create a `GenerativeModel` instance with a model that supports your use case.
final model = FirebaseAI.googleAI().generativeModel(
  model: 'GEMINI_MODEL_NAME',
  // Provide Google Maps as a tool that the model can use to generate its response.
  tools: [
    Tool.googleMaps(),
  ],
  // Add the configuration for the Grounding with Google Maps tool
  // (if this optional config was defined above).
  toolConfig: toolConfig,
);

final response = await model.generateContent([Content.text("restaurants near me?")]);
print(response.text);

// Make sure to comply with the "Grounding with Google Maps" usage requirements,
// which includes how you meet service usage requirements

Unity


using Firebase;
using Firebase.AI;

// Initialize the Gemini Developer API backend service.
var ai = FirebaseAI.GetInstance(FirebaseAI.Backend.GoogleAI());

// Example: Coordinates for New York City
var latLng = new LatLng(40.7128, -74.0060);

// (Optional) Define a RetrievalConfig to configure the Grounding with Google Maps tool.
// You can optionally provide a location's coordinates and/or a language code
// for more relevant and personalized Google Maps results.
var retrievalConfig = new RetrievalConfig(latLng, languageCode: "en");

// Wrap the RetrievalConfig inside a ToolConfig.
var toolConfig = new ToolConfig(retrievalConfig: retrievalConfig);

// Create a `GenerativeModel` instance with a model that supports your use case.
var model = ai.GetGenerativeModel(
  modelName: "GEMINI_MODEL_NAME",
  // Provide Google Maps as a tool that the model can use to generate its response.
  tools: new[] { new Tool(new GoogleMaps()) },
  // Add the configuration for the Grounding with Google Maps tool
  // (if this optional config was defined above).
  toolConfig: toolConfig
);

var response = await model.GenerateContentAsync("restaurants near me?");
UnityEngine.Debug.Log(response.Text ?? "No text in response.");

// Make sure to comply with the "Grounding with Google Maps" usage requirements,
// which includes how you meet service usage requirements

با نحوه انتخاب مدل مناسب برای مورد استفاده و برنامه خود آشنا شوید.

روال‌های مطلوب و نکته‌هایی برای بهبود نتایج

این بخش برخی‌از روال‌های مطلوب کلی را برای استفاده از «پایه‌گذاری» با Google Maps و همچنین نحوه بهره‌برداری از ویژگی‌های مکان برای بهبود نتایج شرح می‌دهد.

روال‌های مطلوب عمومی

  • ابزار را فقط درصورت نیاز ارائه دهید: برای بهینه‌سازی عملکرد و هزینه، دسترسی به ابزار «پایه‌سازی با Google Maps» را فقط زمانی به مدل ارائه دهید که مورد استفاده دارای بافت جغرافیایی واضحی باشد.

  • ارائه مکان کاربر: برای دریافت مرتبط‌ترین و شخصی‌سازی‌شده‌ترین پاسخ‌ها (و زمانی که مکان کاربر مشخص است)، مکان کاربر را (بااستفاده از طول و عرض جغرافیایی ازطریق latLng) در پیکربندی ابزار «پایه‌سازی با Google Maps» اضافه کنید.

  • اطلاع‌رسانی به کاربران نهایی: به‌وضوح به کاربران نهایی خود اطلاع دهید که از داده‌های Google Maps برای پاسخ دادن به پُرسمان‌های آن‌ها استفاده می‌شود. ارائه منابع از Google Maps به کاربران نهایی یکی از الزامات استفاده از سرویس برای ابزار «پایه‌سازی با Google Maps» است.

استفاده از ویژگی‌های مکان در پیام‌واره‌ها

این بخش ویژگی‌های مکان را فهرست می‌کند که برای توصیف مکان‌ها استفاده می‌شوند و توسط «پایه‌سازی» با Google Maps برای تولید پاسخ‌ها استفاده می‌شوند. این ویژگی‌ها برای تعیین انواع سؤالاتی که «پایه‌سازی با Google Maps» می‌تواند پاسخ دهد استفاده می‌شود.

ویژگی‌های نمونه مکان

این فهرست نمونه‌ای الفبایی از ویژگی‌های مکان‌ها را ارائه می‌دهد که مدل شما می‌تواند از آن‌ها برای تولید پاسخ استفاده کند.

  • نشانی
  • تحویل در خیابان
  • کارت نقدی
  • مسافت
  • پارکینگ سرباز رایگان
  • موسیقی زنده
  • منو کودکان
  • ساعت شروع به‌کار
  • گزینه‌های پرداخت (مانند نقدی یا کارت اعتباری)
  • پاسخ درباره جاها
  • حیوان‌خانگی‌پذیر
  • پذیرایی با آبجو
  • غذای گیاه‌خواری سرو می‌کند
  • دسترس‌پذیر با صندلی چرخدار
  • Wi-Fi

پاسخ‌های مکان پاسخی از «پایه‌سازی» با Google Maps براساس اطلاعات برگرفته از مرورهای کاربر است.

پیام‌واره‌های نمونه‌ای که از ویژگی‌های مکان استفاده می‌کنند

مثال‌های زیر از ویژگی‌های مکان در پیام‌واره‌های مربوط به انواع مختلف مکان‌ها استفاده می‌کنند. «پایه‌سازی با Google Maps» از این ویژگی‌ها برای درک قصد شما استفاده می‌کند و سپس پاسخ‌های مربوط را براساس داده‌های مرتبط با مکان‌ها در Google Maps ارائه می‌دهد.

  • برنامه‌ریزی شام خانوادگی: تعیین کنید که آیا رستوران برای خانواده مناسب است یا نه و آیا رستوران خدمات مناسبی ارائه می‌دهد یا نه.

    • نمونه پیام‌واره: آیا «رستوران ایتالیایی» برای کودکان مناسب است و غذای بیرون‌بر دارد؟ رده‌بندی آن چیست؟
  • بررسی دسترس‌پذیری برای دوست: تعیین کنید که آیا مکان نیازهای دسترس‌پذیری خاصی را برآورده می‌کند یا نه.

    • نمونه پیام‌واره: رستورانی می‌خواهم که ورودی دسترس‌پذیر با صندلی چرخدار داشته باشد.
  • پیدا کردن مکانی برای میان‌وعده آخر شب: پیدا کردن مکانی باز که غذای خاصی را در زمان مشخصی سرو می‌کند.

    • نمونه پیام‌واره: آیا «برگر جوینت» الآن باز است؟ شام سرو می‌کنند؟ ساعات کاری آن‌ها در روز جمعه چیست؟
  • ملاقات با مشتری برای صرف قهوه: مناسب بودن کافه برای جلسه کاری را براساس امکانات رفاهی، خدمات، و گزینه‌های پرداخت ارزیابی کنید.

    • پیام‌واره نمونه: آیا «کافه سنترال» Wi-Fi دارد؟ قهوه سرو می‌کنند؟ سطح قیمت آن چقدر است و آیا کارت اعتباری می‌پذیرد؟

توجه داشته باشید که اطلاعات موجود در Google Maps نتایج مستدل ممکن است با شرایط واقعی جاده متفاوت باشد.

نحوه کار «پایه‌گذاری با Google Maps»

وقتی ابزار GoogleMaps را دراختیار مدل قرار می‌دهید، مدل کل گردش کار جستجو، پردازش، و ارجاع اطلاعات را به‌طور خودکار انجام می‌دهد.

گردش کار مدل در اینجا آمده است:

  1. دریافت پیام‌واره: برنامه شما پیام‌واره‌ای را به مدل Gemini ارسال می‌کند که GoogleMaps ابزار فعال‌شده دارد.

  2. پیام‌واره را تحلیل می‌کند: مدل پیام‌واره را تحلیل می‌کند و تعیین می‌کند که آیا Google Maps می‌تواند پاسخ آن را بهبود بخشد یا نه، مثلاً اگر پیام‌واره حاوی بافت جغرافیایی باشد (مثل «قهوه‌سراهای نزدیک من»، «موزه‌های سان‌فرانسیسکو»).

  3. ابزار را فراخوانی می‌کند: مدل، با تشخیص قصد جغرافیایی، ابزار «مستندسازی با Google Maps» را فراخوانی می‌کند.

  4. ارسال پُرسمان به Google Maps: سرویس «پایه‌سازی با Google Maps» برای اطلاعات مرتبط (برای مثال، مکان‌ها، مرورها، عکس‌ها، نشانی‌ها، ساعت کاری) در Google Maps پُرسمان می‌کند.

    می‌توانید به‌طور اختیاری عرض و طول جغرافیایی را در پیکربندی ابزار (یا حتی مستقیماً در پیام‌واره) اضافه کنید تا نتایج Google Maps مرتبط‌تر و شخصی‌سازی‌شده‌تری دریافت کنید. این ابزار یک ابزار جستجوی نوشتاری است و رفتاری مشابه جستجو در Google Maps دارد، به‌طوری‌که پُرسمان‌های محلی («نزدیک من») از مختصات استفاده می‌کنند، درحالی‌که پُرسمان‌های خاص یا غیرمحلی احتمالاً تحت تأثیر مکان صریح قرار نمی‌گیرند.

  5. پردازش نتایج Google Maps: مدل نتایج Google Maps را پردازش می‌کند و پاسخی برای پیام‌واره اصلی تدوین می‌کند.

  6. Google Maps نتیجه پایه‌مندشده را برمی‌گرداند: مدل یک پاسخ نهایی و کاربرپسند برمی‌گرداند که براساس نتایج Google Maps پایه‌مند شده است. این پاسخ شامل موارد زیر است:

    • پاسخ نوشتاری مدل.
    • شیء groundingMetadata با نتایج و منابع Google Maps.

توجه داشته باشید که ارائه Google Maps به‌عنوان ابزار به مدل الزام نمی‌کند که مدل همیشه از ابزار Google Maps برای تولید پاسخ خود استفاده کند. در این موارد، پاسخ حاوی شیء groundingMetadata نخواهد بود و بنابراین Google Maps«نتیجه مستدل» نیست.

درک نتیجه مستندشده

اگر مدل پاسخ خود را براساس نتایج Google Maps ارائه دهد، پاسخ شامل یک شیء groundingMetadata است که حاوی داده‌های ساختاریافته‌ای است که برای تأیید ادعاها و ایجاد یک تجربه منبع غنی در برنامه شما ضروری است.

شیء groundingMetadata در Google Maps نتیجه مستند حاوی اطلاعات زیر است:

  • groundingChunks: آرایه‌ای از اشیاء حاوی منابع maps (uri، placeId، و title).
  • groundingSupports: آرایه‌ای از تکه‌ها برای متصل کردن پاسخ مدل text به منابع در groundingChunks. هر بخش، نوشتاری segment (تعریف‌شده با startIndex و endIndex) را به یک یا چند groundingChunkIndices پیوند می‌دهد. این فیلد به شما کمک می‌کند پیوندهای منبع درون‌خطی بسازید. در ادامه این صفحه، با نحوه برآورده کردن الزامات استفاده از سرویس آشنا شوید.

در اینجا نمونه‌ای از پاسخ حاوی شیء groundingMetadata آورده شده است:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "CanteenM is an American restaurant with..."
          }
        ],
        "role": "model"
      },
      "groundingMetadata": {
        "groundingChunks": [
          {
            "maps": {
              "uri": "https://maps.google.com/?cid=13100894621228039586",
              "title": "Heaven on 7th Marketplace",
              "placeId": "places/ChIJ0-zA1vBZwokRon0fGj-6z7U"
            }
          }
        ],
        "groundingSupports": [
          {
            "segment": {
              "startIndex": 0,
              "endIndex": 79,
              "text": "CanteenM is an American restaurant with a 4.6-star rating and is open 24 hours."
            },
            "groundingChunkIndices": [0]
          }
        ]
      }
    }
  ]
}

الزامات استفاده از سرویس

این بخش الزامات استفاده از سرویس را برای «اتصال به واقعیت» با Google Maps برای ارائه‌دهنده Gemini API انتخابی شما شرح می‌دهد: Gemini Developer API یا Agent Platform Gemini API (formerly Vertex AI) (به بخش شرایط سرویس در «شرایط خاص سرویس» مراجعه کنید).

اطلاع‌رسانی به کاربران درباره Google Maps منبع

با هر Google Maps نتیجه پایه‌مند، منابعی را در groundingChunks دریافت خواهید کرد که از هر پاسخ پشتیبانی می‌کنند. فراداده زیر نیز برگردانده می‌شود:

  • شناسه منبع یکسان منبع
  • عنوان
  • شناسه

در برنامه‌تان، هنگام ارائه نتایج از «پایه‌سازی با Google Maps»، باید منابع Google Maps مرتبط را مشخص کنید و موارد زیر را به کاربران اطلاع دهید:

  • منابع Google Maps باید بلافاصله پس‌از محتوای تولیدشده‌ای که منابع از آن پشتیبانی می‌کنند، بیایند. به این محتوای تولیدشده Google Maps نتیجه مستند نیز گفته می‌شود.

  • Google Maps منبع باید در یک تعامل کاربر قابل‌مشاهده باشد.

در اینجا نحوه دریافت مقادیر برای نمایش منابع از Google Maps نتیجه مستدل آورده شده است:

Swift

// ...

// Get the model's response
let text = response.text

// Get the grounding metadata
if let candidate = response.candidates.first,
   let groundingMetadata = candidate.groundingMetadata {

  // Get sources
  let groundingChunks = groundingMetadata.groundingChunks
  for chunk in groundingChunks {
    if let maps = chunk.maps {
      let title = maps.title  // for example, "Heaven on 7th Marketplace"
      let url = maps.url  // for example, "https://maps.google.com/?cid=13100894621228039586"
      let placeID = maps.placeID  // for example, "places/ChIJ0-zA1vBZwokRon0fGj-6z7U"
      // TODO(developer): show source in the UI
    }
  }
}

Kotlin

// ...

// Get the model's response
val text = response.text

// Get the grounding metadata
val groundingMetadata = response.candidates.firstOrNull()?.groundingMetadata

// Get sources
val groundingChunks = groundingMetadata?.groundingChunks
groundingChunks?.let { chunks ->
  for (chunk in chunks) {
    val title = chunk.maps?.title  // for example, "Heaven on 7th Marketplace"
    val uri = chunk.maps?.uri  // for example, "https://maps.google.com/?cid=13100894621228039586"
    val placeId = chunk.maps?.placeId  // for example, "places/ChIJ0-zA1vBZwokRon0fGj-6z7U"
    // TODO(developer): show source in the UI
  }
}

Java

// ...

Futures.addCallback(response, new FutureCallback() {
  @Override
  public void onSuccess(GenerateContentResponse result) {
    // Get the model's response
    String text = result.getText();

    // Get the grounding metadata
    GroundingMetadata groundingMetadata =
        result.getCandidates()[0].getGroundingMetadata();

    if (groundingMetadata != null) {
      // Get sources
      List chunks = groundingMetadata.getGroundingChunks();
      if (chunks != null) {
        for(GroundingChunk chunk : chunks) {
          GoogleMapsGroundingChunk maps = chunk.getMaps();
          if (maps != null) {
            String title = maps.getTitle();  // for example, "Heaven on 7th Marketplace"
            String uri = maps.getUri();  // for example, "https://maps.google.com/?cid=13100894621228039586"
            String placeId = maps.getPlaceId();  // for example, "places/ChIJ0-zA1vBZwokRon0fGj-6z7U"
            // TODO(developer): show sources in the UI
          }
        }
      }
    }
  }

  @Override
  public void onFailure(Throwable t) {
    t.printStackTrace();
  }
}, executor);

Web

// ...

// Get the model's text response
const text = result.response.text();

// Get the grounding metadata
const groundingMetadata = result.response.candidates?.[0]?.groundingMetadata;

// Get sources
const groundingChunks = groundingMetadata?.groundingChunks;
if (groundingChunks) {
  for (const chunk of groundingChunks) {
    const title = chunk.maps?.title;  // for example, "Heaven on 7th Marketplace"
    const uri = chunk.maps?.uri;  // for example, "https://maps.google.com/?cid=13100894621228039586"
    const placeId = chunk.maps?.placeId;  // for example, "places/ChIJ0-zA1vBZwokRon0fGj-6z7U"
    // TODO(developer): show sources in the UI
  }
}

Dart

// ...

// Get the model's response
final text = response.text;

// Get the grounding metadata
final groundingMetadata = response.candidates.first.groundingMetadata;

// Get sources
final groundingChunks = groundingMetadata?.groundingChunks;
if (groundingChunks != null) {
  for (var chunk in groundingChunks) {
    final title = chunk.maps?.title;  // for example, "Heaven on 7th Marketplace"
    final uri = chunk.maps?.uri;  // for example, "https://maps.google.com/?cid=13100894621228039586"
    final placeId = chunk.maps?.placeId;  // for example, "places/ChIJ0-zA1vBZwokRon0fGj-6z7U"
    // TODO(developer): show sources in the UI
  }
}

Unity

// ...

// Get the model's response.
var text = response.Text;

// Get the grounding metadata.
var groundingMetadata = response.Candidates.First().GroundingMetadata;

// Get sources.
if (groundingMetadata != null) {
  foreach(GroundingChunk chunk in groundingMetadata?.GroundingChunks) {
    if (chunk.Maps != null) {
      var title = chunk.Maps?.Title;  // for example, "Heaven on 7th Marketplace"
      var uri = chunk.Maps?.Uri;  // for example, "https://maps.google.com/?cid=13100894621228039586"
      var placeId = chunk.Maps?.PlaceId;  // for example, "places/ChIJ0-zA1vBZwokRon0fGj-6z7U"
      // TODO(developer): show sources in the UI
    }
  }
}

برای هر منبع در groundingChunks، پیش‌نمایش پیوند باید طبق این الزامات تولید شود:

پیام‌واره با پاسخ نشان‌دهنده منابع

می‌توانید نمای منابع را جمع کنید.

پیام‌واره با پاسخ و منابع جمع شد

درصورت تمایل می‌توانید پیش‌نمایش پیوند را با محتوای اضافی بهبود دهید، ازجمله:

برای اطلاعات بیشتر درباره برخی‌از ارائه‌دهندگان داده‌های Google Maps و شرایط پروانه آن‌ها، اعلامیه‌های حقوقی Google Maps و Google Earth را ببینید.

‫Google Maps رهنمودهای انتساب نوشتار

وقتی منابع را به Google Maps در نوشتار نسبت می‌دهید، این دستورالعمل‌ها را دنبال کنید:

  • نوشتار Google Maps را به هیچ وجه تغییر ندهید:

    • بزرگ‌نویسی نوشتار Google Maps را تغییر ندهید.
    • نوشتار Google Maps را در چند خط نپیچید.
    • نوشتار Google Maps را به زبان دیگری بومی‌سازی نکنید.
    • بااستفاده از مشخصه HTML translate="no"، از ترجمه نوشتار Google Maps توسط مرورگرها جلوگیری کنید.
  • نوشتار Google Maps را همان‌طور که در جدول زیر شرح داده شده است سبک‌بندی کنید:

    دارایی سبک
    خانواده قلم Roboto. بار کردن قلم اختیاری است.
    خانواده قلم جایگزین هر قلم سن‌سریف نوشتار اصلی که قبلاً در محصولتان استفاده شده است یا «سن‌سریف» برای فراخوانی قلم پیش‌فرض سیستم
    سبک قلم عادی
    وزن قلم 400
    رنگ قلم سفید، سیاه (‎#1F1F1F)، یا خاکستری (‎#5E5E5E). کنتراست دسترس‌پذیر (۴.۵:۱) را درمقابل پس‌زمینه حفظ کنید.
    اندازه قلم حداقل اندازه قلم: ۱۲ اس‌پی
    حداکثر اندازه قلم: ۱۶ اس‌پی
    برای آشنایی با اس‌پی، به بخش «واحدهای اندازه قلم» در وب‌سایت Material Design مراجعه کنید.
    فاصله‌گذاری عادی

سرویس مقایسه قیمت نمونه

CSS زیر نوشتار Google Maps را با سبک و رنگ تایپوگرافی مناسب در پس‌زمینه سفید یا روشن ارائه می‌کند.

@import url('https://fonts.googleapis.com/css2?family=Roboto&display=swap');

.GMP-attribution {
  font-family: Roboto, Sans-Serif;
  font-style: normal;
  font-weight: 400;
  font-size: 1rem;
  letter-spacing: normal;
  white-space: nowrap;
  color: #5e5e5e;
}

ذخیره شناسه مکان در حافظه نهان

Google Mapsنتیجه مستند ممکن است شامل شناسه مکان باشد. می‌توانید داده‌های پاسخ زیر را ذخیره، صادر، و در حافظه نهان ذخیره کنید:

  • placeId

محدودیت‌های مربوط به ذخیره‌سازی در حافظه نهان در «شرایط Grounding with Google Maps» برای این داده‌ها اعمال نمی‌شود.

فعالیت‌ها و قلمروهای ممنوعه

«پایه‌گذاری با Google Maps» برای برخی‌از محتواها و فعالیت‌ها محدودیت‌های بیشتری دارد تا پلاتفرمی ایمن و قابل‌اطمینان حفظ شود. علاوه‌بر محدودیت‌های استفاده در «شرایط» برای ارائه‌دهنده Gemini API انتخابی شما: Gemini Developer API یا Agent Platform Gemini API (formerly Vertex AI) (به بخش شرایط خدمات در «شرایط خاص سرویس» مراجعه کنید).

  • از «پایه‌سازی با Google Maps» برای فعالیت‌های پرخطر ازجمله خدمات پاسخ اضطراری استفاده نخواهید کرد.

  • برنامه‌تان را که «پایه‌سازی با Google Maps» ارائه می‌دهد در «قلمرو ممنوعه» توزیع یا بازاریابی نخواهید کرد. برای اطلاعات بیشتر، قلمروهای ممنوعه Google Maps Platform را ببینید. فهرست «قلمروهای ممنوعه» ممکن است هرچندوقت یک‌بار به‌روز شود.

نتایج مستدل و پایش هوش مصنوعی در کنسول Firebase

اگر پایش هوش مصنوعی را در کنسول Firebase فعال کرده باشید، پاسخ‌ها در Cloud Logging ذخیره می‌شوند. به‌طور پیش‌فرض، این داده‌ها دوره نگهداری ۳۰ روزه دارند.

مسئولیت اطمینان از اینکه این دوره نگهداری یا هر دوره سفارشی که تنظیم می‌کنید کاملاً با مورد استفاده خاص شما و هرگونه الزامات رعایت اضافی برای ارائه‌دهنده Gemini API انتخابی شما مطابقت داشته باشد برعهده شما است: Gemini Developer API یا Agent Platform Gemini API (formerly Vertex AI) (بخش شرایط خدمات را در «شرایط مختص سرویس» ببینید). ممکن است لازم باشد دوره نگهداری را در Cloud Logging اصلاح کنید تا این الزامات برآورده شود.

قیمت‌گذاری و حد نرخ

قیمت‌گذاری «پایه‌سازی با Google Maps» براساس پُرسمان‌ها است. درخواست فقط زمانی در سهمیه Google Maps محاسبه می‌شود که پیام‌واره حداقل یک Google Mapsنتیجه مستند را باموفقیت برگرداند (یعنی پاسخ حاوی حداقل یک منبع Google Maps باشد). اگر چند پُرسمان از یک درخواست به Google Maps ارسال شود، به‌عنوان یک درخواست برای محدودیت نرخ محاسبه می‌شود.

حتماً جزئیات مربوط به قیمت‌گذاری، دردسترس بودن مدل، و محدودیت‌های «پایه‌سازی» با Google Maps را در اسناد ارائه‌دهنده Gemini API انتخابی‌تان مرور کنید: Gemini Developer API | Agent Platform Gemini API (formerly Vertex AI).