الاستناد إلى "خرائط Google"

تتيح ميزة Grounding with Google Maps ربط نموذج Gemini ببيانات جغرافية مكانية من Google Maps، ما يتيح لك إنشاء وظائف تستند إلى الموقع الجغرافي في تطبيقاتك.

يوفّر استخدام Google Maps المزايا التالية:

  • زيادة الدقة الواقعية: تقليل الهلوسة في النماذج من خلال استناد الردود إلى قاعدة بيانات Google التي تضم أكثر من 250 مليون مكان ونشاط تجاري في العالم الحقيقي
  • الوصول إلى معلومات في الوقت الفعلي: الإجابة عن الأسئلة باستخدام بيانات مباشرة، مثل ساعات العمل الحالية والحالة في الوقت الفعلي لمحطات شحن المركبات الكهربائية
  • توفير المصادر: يمكنك تعزيز ثقة المستخدمين من خلال عرض 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

تعرَّف على كيفية اختيار نموذج مناسبَين لحالة الاستخدام والتطبيق.

أفضل الممارسات والنصائح لتحسين النتائج

يوضّح هذا القسم بعض أفضل الممارسات العامة لاستخدام Grounding مع Google Maps، بالإضافة إلى كيفية الاستفادة من سمات المكان لتحسين النتائج.

أفضل الممارسات العامة

  • توفير الأداة عند الحاجة إليها فقط: لتحسين الأداء والتكلفة، امنح النموذج إذن الوصول إلى أداة Grounding with Google Maps فقط عندما يكون لحالة الاستخدام سياق جغرافي واضح.

  • توفير الموقع الجغرافي للمستخدم: للحصول على الردود الأكثر صلة وتخصيصًا (وعندما يكون الموقع الجغرافي للمستخدم معروفًا)، أدرِج الموقع الجغرافي للمستخدم (باستخدام خطوط الطول والعرض من خلال latLng) في إعدادات أداة Grounding with Google Maps.

  • إبلاغ المستخدمين النهائيين: يجب إبلاغ المستخدمين النهائيين بوضوح بأنّه يتم استخدام بيانات Google Maps للإجابة عن طلبات البحث التي يرسلونها. يُعدّ تزويد المستخدمين النهائيين بالمصادر من Google Maps أحد متطلبات استخدام الخدمة لأداة "الاستناد إلى مصادر" مع Google Maps.

استخدام خصائص الأماكن في الطلبات

يسرد هذا القسم خصائص الأماكن المستخدَمة لوصف المواقع الجغرافية والتي تستخدمها ميزة Grounding with Google Maps لإنشاء الردود. تُستخدَم هذه الخصائص لتحديد أنواع الأسئلة التي يمكن أن تجيب عنها ميزة "الاستناد إلى مصادر" مع Google Maps.

نماذج لخصائص الأماكن

تقدّم هذه القائمة عيّنة مرتّبة أبجديًا من الخصائص المتعلّقة بالأماكن التي يمكن أن يستخدمها النموذج لإنشاء ردود.

  • العنوان
  • الإيصال إلى السيارة
  • بطاقة السحب الآلي
  • المسافة
  • موقف سيارات مجاني
  • موسيقى حية
  • قائمة طعام الأطفال
  • ساعات العمل
  • خيارات الدفع (مثل الدفع نقدًا أو بطاقة الائتمان)
  • الإجابة المتعلقة بالمكان
  • يُسمَح باصطحاب الحيوانات الأليفة
  • تقديم البيرة
  • يقدّم المكان المأكولات النباتية
  • أنشطة مناسبة لأصحاب الكراسي المتحرّكة
  • Wifi

إجابات الأماكن هي ردود من Grounding with Google Maps استنادًا إلى معلومات مستخلَصة من مراجعات المستخدمين.

أمثلة على الطلبات التي تستخدم سمات الأماكن

تستخدِم الأمثلة التالية سمات الأماكن في الطلبات المتعلقة بأنواع مختلفة من الأماكن. تستخدِم عملية الربط بالبيانات في Google Maps السمات لفهم نيتك، ثم تقدّم إجابات ذات صلة استنادًا إلى البيانات المرتبطة بالأماكن في Google Maps.

  • التخطيط لعشاء عائلي: تحديد ما إذا كان المطعم مناسبًا للعائلات وما إذا كان يقدّم خدمة ملائمة

    • مثال على الطلب: هل مطعم "المكان الإيطالي" مناسب للأطفال، وهل يقدّم خدمة توصيل الطلبات؟ ما هو تقييمهم؟
  • التحقّق من إمكانية الوصول إلى مكان ما لصديق: يمكنك معرفة ما إذا كان المكان يستوفي احتياجات الوصول المحدّدة.

    • مثال على الطلب: أحتاج إلى مطعم يوفّر مدخلاً صالحًا للكراسي المتحركة.
  • العثور على مكان لتناول وجبة خفيفة في وقت متأخر من الليل: يمكنك العثور على مؤسسة مفتوحة تقدّم وجبة معيّنة خلال وقت محدّد.

    • مثال على الطلب: هل مطعم "برجر جوينت" مفتوح الآن؟ هل يقدّمون العشاء؟ ما هي ساعات العمل يوم الجمعة؟
  • مقابلة عميل لتناول القهوة: تقييم مدى ملاءمة مقهى لعقد اجتماع عمل استنادًا إلى وسائل الراحة والعروض وخيارات الدفع

    • مثال على طلب: هل يتوفّر في "مقهى سنترال" شبكة Wi-Fi؟ هل يقدّم هذا المكان القهوة؟ ما هو مستوى الأسعار وهل يقبلون بطاقات الائتمان؟

يُرجى العِلم أنّ المعلومات الواردة في Google Maps النتائج المستندة إلى بيانات واقعية قد تختلف عن الظروف الفعلية للطريق.

طريقة عمل ميزة Grounding with Google Maps

عند تزويد النموذج GoogleMaps بالأداة، سيتولّى النموذج تلقائيًا سير العمل الكامل المتمثل في البحث عن المعلومات ومعالجتها والاقتباس منها.

في ما يلي سير عمل النموذج:

  1. تلقّي الطلب: يرسل تطبيقك طلبًا إلى نموذج Gemini مع تفعيل الأداة GoogleMaps.

  2. تحليل الطلب: يحلّل النموذج الطلب ويحدّد ما إذا كان بإمكان Google Maps تحسين الردّ، مثلاً، إذا كان الطلب يتضمّن سياقًا جغرافيًا (مثل "مقاهٍ بالقرب مني" أو "متاحف في القاهرة").

  3. استخدام الأداة: يتعرّف النموذج على النية الجغرافية، ويستخدم أداة Grounding with 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 التي تدعم كل ردّ. يتم أيضًا عرض البيانات الوصفية التالية:

  • عنوان URI المصدر
  • العنوان
  • رقم التعريف

عند عرض نتائج من Grounding with 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إرشادات تحديد مصدر النص.
  • عرض عنوان المستند المصدر المقدَّم في الردّ
  • انقر على uri من الردّ للانتقال إلى مصدر المعلومات.

طلب يتضمّن ردًا يعرض المصادر

يمكنك تصغير عرض المستندات المصدر.

تم تصغير الطلب مع الرد والمصادر

يمكنك اختياريًا تحسين معاينة الرابط باستخدام محتوى إضافي، مثل:

لمزيد من المعلومات حول بعض Google Mapsمقدّمي البيانات وبنود الترخيص الخاصة بهم، يُرجى الاطّلاع على الإشعارات القانونية في "خرائط Google" وGoogle Earth.

Google Maps إرشادات تحديد المصدر النصي

عند الإشارة إلى مصادر ضمن النص باستخدام Google Maps، اتّبِع الإرشادات التالية:

  • لا تعدِّل النص Google Maps بأي طريقة:

    • لا تغيِّر استخدام الأحرف اللاتينية الكبيرة في النص Google Maps.
    • لا تلتفّ الكلمة Google Maps على أسطر متعددة.
    • لا تحوّل النص Google Maps إلى لغة أخرى.
    • لمنع المتصفّحات من ترجمة النص Google Maps، استخدِم سمة HTML ‏translate="no".
  • نسِّق النص Google Maps كما هو موضّح في الجدول التالي:

    الموقع النمط
    مجموعة الخطوط Roboto تحميل الخط اختياري.
    مجموعة الخطوط الاحتياطية أي خط sans serif مستخدَم حاليًا في منتجك أو "Sans-Serif" لاستدعاء خط النظام التلقائي
    نمط الخط عادي
    عرض الخط 400
    لون الخط أبيض أو أسود (#1F1F1F) أو رمادي (#5E5E5E) الحفاظ على تباين يسهل الوصول إليه (4.5:1) مع الخلفية
    حجم الخط الحد الأدنى لحجم الخط: 12sp
    الحد الأقصى لحجم الخط: 16sp
    لمزيد من المعلومات حول sp، راجِع وحدات حجم الخط على موقع 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

لا تنطبق القيود المفروضة على التخزين المؤقت في "بنود خدمة Grounding with Google Maps" على هذه البيانات.

الأنشطة والمناطق المحظورة

يفرض استخدام ميزة "الاستناد إلى معلومات خارجية" مع Google Maps قيودًا إضافية على بعض المحتوى والأنشطة للحفاظ على أمان المنصة وموثوقيتها. بالإضافة إلى قيود الاستخدام الواردة في "بنود الخدمة" الخاصة بمزوّد خدمة Gemini API الذي اخترته: Gemini Developer API أو Agent Platform Gemini API (formerly Vertex AI) (راجِع قسم بنود الخدمة ضمن "البنود الخاصة بالخدمة").

  • لن تستخدم Grounding مع Google Maps في الأنشطة عالية الخطورة، بما في ذلك خدمات الاستجابة لحالات الطوارئ.

  • لن توزّع أو تسوّق تطبيقك الذي يوفّر ميزة Grounding مع Google Maps في منطقة محظورة. لمزيد من المعلومات، يُرجى الاطّلاع على المناطق المحظورة في "منصة خرائط Google". قد يتم تعديل قائمة "المناطق المحظورة" من حين لآخر.

النتائج المستندة إلى مصادر موثوقة وتتبّع استخدام الذكاء الاصطناعي في وحدة تحكّم Firebase

إذا فعّلت ميزة تتبّع استخدام الذكاء الاصطناعي في Firebase، سيتم تخزين الردود في Cloud Logging. تتوفّر هذه البيانات تلقائيًا لفترة احتفاظ تبلغ 30 يومًا.

وتقع على عاتقك مسؤولية التأكّد من أنّ فترة الاحتفاظ هذه، أو أي فترة مخصّصة تحدّدها، تتوافق تمامًا مع حالة الاستخدام المحدّدة وأي متطلبات إضافية للامتثال لدى مقدّم خدمة 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).