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

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

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

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

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

  • gemini-3.1-pro-preview
  • ‫gemini-3.8-flash (و gemini-3.7-flash، gemini-3.6-flash، و gemini-3.5-flash بزرگ‌تر)
  • ‫gemini-3.5-flash-lite (و gemini-3.1-flash-lite قدیمی‌تر)

مدل‌های Gemini 2.5 با کاربرد عمومی از این قابلیت پشتیبانی می‌کنند، اما همه آن‌ها منسوخ شده‌اند.

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

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

مدل را با Google Maps زمین‌گیر کنید

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

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

Swift


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: [Tool.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

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

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

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

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

    • پیام‌واره نمونه: آیا «The Italian Place» برای کودکان مناسب است و آیا خدمات بیرون‌بر ارائه می‌دهد؟ امتیاز آن‌ها چیست؟
  • بررسی دسترس‌پذیری برای دوست: تعیین کنید که مکان موردنظر نیازهای دسترس‌پذیری خاص را برآورده می‌کند یا نه.

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

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

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

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

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

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

گردش کار مدل به این صورت است:

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

  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 درج شد.
  • عکسی از نشانی وب منبع (og:image).

برای اطلاعات بیشتر درباره برخی‌از ارائه‌دهندگان داده 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

‫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

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

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

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

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

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

نتایج مستند و پایش هوش مصنوعی در کنسول 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).