O embasamento com o
O embasamento com
- Aumentar a precisão factual: reduza as alucinações do modelo baseando as respostas no banco de dados do Google com mais de 250 milhões de lugares e empresas reais.
- Acessar informações em tempo real: responda a perguntas usando dados em tempo real, como o horário de funcionamento atual e o status em tempo real de eletropostos.
- Forneça fontes: conquiste a confiança do usuário mostrando
Google Maps fontes de lugares e links diretamente ao lado das declarações do modelo com base na localização.
Modelos compatíveis
gemini-4-argongemini-3.8-flash(e as versões mais antigasgemini-3.7-flash,gemini-3.6-flashegemini-3.5-flash)gemini-3.5-flash-lite(e ogemini-3.1-flash-litemais antigo)
Os modelos gemini-3.1-pro-preview e Gemini 2.5 de uso geral (que
foram descontinuados) também são compatíveis com esse recurso.
Idiomas compatíveis
Consulte os idiomas disponíveis para modelos Gemini.
Embasar o modelo com Google Maps
|
Clique no seu provedor de Gemini API para conferir o conteúdo e o código específicos do provedor nesta página. |
Ao criar a instância GenerativeModel, forneça GoogleMaps como um tool
que o modelo pode usar para gerar a resposta.
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
Saiba como escolher um modelo adequado para seu caso de uso e app.
Práticas recomendadas e dicas para melhorar os resultados
Nesta seção, descrevemos algumas práticas recomendadas gerais para usar o embasamento com o
Práticas recomendadas gerais
Forneça a ferramenta apenas quando necessário: para otimizar o desempenho e o custo, forneça ao modelo acesso ao embasamento com a ferramenta
Google Maps apenas quando o caso de uso tiver um contexto geográfico claro.Fornecer a localização do usuário: para respostas mais relevantes e personalizadas (e quando a localização do usuário é conhecida), inclua a localização do usuário (usando latitude e longitude via
latLng) na configuração da ferramenta de embasamento com oGoogle Maps .Informe os usuários finais: informe claramente aos usuários finais que os dados do
Google Maps estão sendo usados para responder às consultas deles. Fornecer aos usuários finais as fontes deGoogle Maps é um requisito de uso do serviço para a ferramenta de embasamento comGoogle Maps .
Usar propriedades de lugar em comandos
Nesta seção, listamos as propriedades de lugares usadas para descrever locais
e usadas pelo embasamento com o
Exemplos de propriedades de lugar
Esta lista fornece uma amostra em ordem alfabética de propriedades sobre lugares que podem ser usadas pelo modelo para gerar respostas.
- Endereço
- Retirada
- Cartão de débito
- Distância
- Estacionamento gratuito
- Música ao vivo
- Menu para crianças
- Horário de funcionamento
- Opções de pagamento (como dinheiro ou cartão de crédito)
- Resposta sobre o lugar
- Aceita animais de estimação
- Serve cerveja
- Serve comida vegetariana
- Acessibilidade para pessoas em cadeira de rodas
- Wi-Fi
As respostas sobre lugares são uma resposta do embasamento com o
Exemplos de comandos que usam propriedades de lugar
Os exemplos a seguir usam
propriedades de lugar
em comandos sobre diferentes tipos de lugares. O embasamento com o
Planejar um jantar em família: determine se um restaurante é adequado para uma família e se oferece um serviço conveniente.
- Exemplo de comando: O restaurante "The Italian Place" é bom para crianças e oferece serviço de retirada? Qual é a classificação dele?
Verificar a acessibilidade para um amigo: determine se o local atende a necessidades específicas de acessibilidade.
- Exemplo de comando: Preciso de um restaurante que tenha uma entrada acessível para pessoas em cadeira de rodas.
Encontrar um local para um lanche noturno: encontre um estabelecimento aberto que sirva uma refeição específica em um determinado horário.
- Exemplo de comando: A lanchonete "Burger Joint" está aberta agora? O local serve jantar? Qual é o horário de funcionamento na sexta-feira?
Encontrar um cliente para tomar um café: avalie se um café é adequado para uma reunião de negócios com base nas comodidades, ofertas e opções de pagamento.
- Exemplo de comando: O "Café Central" tem Wi-Fi? Eles servem café? Qual é o nível de preço e se eles aceitam cartões de crédito?
As informações nos Resultados embasados do
Como funciona o embasamento com Google Maps
Quando você fornece ao modelo a ferramenta GoogleMaps, ele processa todo o fluxo de trabalho de pesquisa, processamento e citação de informações automaticamente.
Confira o fluxo de trabalho do modelo:
Recebe o comando: seu app envia um comando ao modelo do Gemini com a ferramenta
GoogleMapsativada.Analisa o comando: o modelo analisa o comando e determina se o
Google Maps pode melhorar a resposta. Por exemplo, se o comando contém contexto geográfico (como "cafeterias perto de mim", "museus em São Francisco").Invoca a ferramenta: o modelo, reconhecendo a intenção geográfica, invoca a ferramenta de embasamento com o
Google Maps .Envia consultas para
Google Maps : o serviço de embasamento comGoogle Maps consultaGoogle Maps para encontrar informações relevantes (por exemplo, lugares, avaliações, fotos, endereços, horário de funcionamento).Se quiser, inclua a latitude e a longitude na configuração da ferramenta (ou até mesmo diretamente no comando) para receber resultados mais relevantes e personalizados do
Google Maps . A ferramenta é de pesquisa textual e se comporta de maneira semelhante à pesquisa noGoogle Maps , em que as consultas locais ("perto de mim") usam as coordenadas, enquanto as consultas específicas ou não locais provavelmente não são influenciadas pelo local explícito.Processa os resultados de
Google Maps : o modelo processa os resultados deGoogle Maps e formula uma resposta ao comando original.Retorna um resultado embasado do
Google Maps : o modelo retorna uma resposta final, fácil de usar e embasada nos resultados doGoogle Maps . Essa resposta inclui:- A resposta em texto do modelo.
- Um objeto
groundingMetadatacom os resultados e as fontes deGoogle Maps .
Fornecer groundingMetadata e, portanto,
não será um resultado embasado em
Entender o resultado embasado
Se o modelo embasar a resposta nos resultados de groundingMetadata com dados estruturados
essenciais para verificar as declarações e criar uma experiência de fonte rica no seu
aplicativo.
O objeto groundingMetadata em um resultado embasado de
groundingChunks: uma matriz de objetos que contém as origens demaps(uri,placeIdetitle).groundingSupports: uma matriz de fragmentos para conectar a resposta do modelotextàs fontes emgroundingChunks. Cada bloco vincula um textosegment(definido porstartIndexeendIndex) a um ou maisgroundingChunkIndices. Esse campo ajuda a criar links de origem inline. Saiba como atender aos requisitos de uso do serviço mais adiante nesta página.
Veja um exemplo de resposta que inclui um objeto 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]
}
]
}
}
]
}
Requisitos de uso do serviço
Esta seção descreve os requisitos de uso do serviço para o embasamento com o
Informar os usuários sobre as fontes do Google Maps
Com cada resultado embasado do groundingChunks que dão suporte a cada resposta. Os seguintes metadados também são
retornados:
- URI de origem
- título
- ID
No app, ao apresentar resultados do embasamento com o
As fontes
Google Maps precisam seguir imediatamente o conteúdo gerado que elas apoiam. Esse conteúdo gerado também é chamado de resultado embasado doGoogle Maps .As fontes de
Google Maps precisam estar visíveis em uma interação do usuário.
Veja como receber valores para exibir fontes do
resultado embasado do
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
}
}
}
Mostrar Google Maps fontes com Google Maps links
Para cada origem em groundingChunks,
uma prévia de link precisa ser gerada de acordo com estes requisitos:
- Atribua cada fonte ao
Google Maps seguindo as diretrizes de atribuição de texto doGoogle Maps . - Mostre o título da fonte fornecido na resposta.
- Vincule à fonte usando o
urida resposta.
Você pode recolher a visualização das fontes.
Se quiser, você pode melhorar a prévia do link com mais conteúdo, como:
- Um
favicon do
Google Maps inserido antes da atribuição de texto doGoogle Maps . - Uma foto do URL de origem (
og:image).
Para mais informações sobre alguns dos provedores de dados do
Google Maps diretrizes de atribuição de texto
Ao atribuir fontes ao
Não modifique o texto
Google Mapsde forma alguma:- Não mude as letras maiúsculas e minúsculas do texto
Google Maps. - Não quebre o texto
Google Mapsem várias linhas. - Não traduza o texto
Google Mapspara outro idioma. - Impeça que os navegadores traduzam o texto
Google Mapsusando o atributo HTMLtranslate="no".
- Não mude as letras maiúsculas e minúsculas do texto
Estilize o texto
Google Mapsconforme descrito na tabela a seguir:Propriedade Estilo Família de fontes Roboto. O carregamento da fonte é opcional. Família de fontes substituta Qualquer fonte Sans Serif já usada no seu produto ou "Sans-Serif" para invocar a fonte padrão do sistema Estilo da fonte Normal Espessura da fonte 400 Cor da fonte Branco, preto (#1F1F1F) ou cinza (#5E5E5E). Mantenha um contraste acessível (4.5:1) em relação ao plano de fundo. Tamanho da fonte Tamanho mínimo da fonte: 12 sp
Tamanho máximo da fonte: 16 sp
Para saber mais sobre sp, consulte as unidades de tamanho de fonte no site do Material Design.Espaçamento Normal
CSS de exemplo
O CSS a seguir renderiza o texto Google Maps com o estilo tipográfico e a cor apropriados em um fundo branco ou claro.
@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;
}
Armazenamento em cache do ID de lugar
O resultado embasado do
placeId
As restrições contra o armazenamento em cache nos Termos do Embasamento com o Google Maps não se aplicam a esses dados.
Atividades e territórios proibidos
O embasamento com
Você não vai usar o embasamento com
Google Maps para atividades de alto risco, incluindo serviços de resposta a emergências.Você não vai distribuir nem comercializar seu aplicativo que oferece embasamento com o
Google Maps em um território proibido. Para mais informações, consulte Territórios proibidos da Plataforma Google Maps. A lista de Territórios Proibidos pode ser atualizada periodicamente.
Resultados embasados e monitoramento de IA no console do Firebase
Se você ativou o AI monitoring no console do Firebase, as respostas são armazenadas no Cloud Logging. Por padrão, esses dados têm um período de retenção de 30 dias.
É sua responsabilidade garantir que esse período de armazenamento, ou qualquer período personalizado definido por você, esteja totalmente alinhado ao seu caso de uso específico e a todos os requisitos de conformidade adicionais do provedor de Gemini API escolhido: Gemini Developer API ou Agent Platform Gemini API (formerly Vertex AI) (consulte a seção Termos de Serviço nos Termos Específicos de Serviço). Talvez seja necessário ajustar o período de armazenamento no Cloud Logging para atender a esses requisitos.
Preços e limites de taxa
O preço do embasamento com o
Confira os detalhes sobre preços, disponibilidade de modelos e limites para
embasamento com