O embasamento com o
O embasamento com
- Aumentar a precisão factual: reduzir as alucinações do modelo com base nas respostas do banco de dados do Google de mais de 250 milhões de lugares e empresas do mundo real.
- Acessar informações em tempo real: responda a perguntas usando dados dinâmicos, como horário de funcionamento atual e status em tempo real dos eletropostos.
- Forneça contexto visual: crie confiança do usuário integrando widgets de mapa interativos, fotos e o Street View diretamente ao lado das declarações baseadas em localização do modelo.
Modelos compatíveis
gemini-3.1-pro-previewgemini-3.5-flashgemini-3.1-flash-litegemini-2.5-progemini-2.5-flashgemini-2.5-flash-lite
Idiomas compatíveis
Consulte os idiomas disponíveis para modelos Gemini.
Basear o modelo em 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 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.
// (Optional) Set `enableWidget` to control whether the response contains a `googleMapsWidgetContextToken`.
tools: [ { googleMaps: { enableWidget: true } } ],
// 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',
),
);
// 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
Esta seção descreve algumas práticas recomendadas gerais para usar o embasamento com
Práticas recomendadas gerais
Forneça a ferramenta somente quando necessário: para otimizar o desempenho e o custo, dê ao modelo acesso à ferramenta de embasamento com
Google Maps somente quando o caso de uso tiver um contexto geográfico claro.Forneça 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 comGoogle Maps .Informe os usuários finais: deixe claro para os usuários finais que os dados de
Google Maps estão sendo usados para responder às consultas deles. Fornecer aos usuários finais as fontes doGoogle Maps é um requisito de uso do serviço da ferramenta Embasamento comGoogle Maps .(Somente SDK da Web) Renderize o widget contextual
Google Maps : o widget contextual é renderizado usando o token de contexto,googleMapsWidgetContextToken, que é retornado na resposta Gemini API e pode ser usado para renderizar conteúdo visual deGoogle Maps . Para mais informações sobre o widget contextual, consulte Fundamentação com o widgetGoogle Maps na documentação doGoogle Maps .
Usar propriedades de lugar em comandos
Esta seção lista as propriedades de lugar usadas para descrever locais
e usadas pelo embasamento com
Exemplo 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 infantil
- 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 de lugar são uma resposta do embasamento com
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 ele oferece um serviço conveniente.
- Exemplo de comando: O restaurante "The Italian Place" é bom para crianças? Ele oferece comida para viagem? Qual é a classificação deles?
Verificar a acessibilidade para um amigo: determine se o local atende a necessidades específicas de acessibilidade.
- Exemplo de comando: Preciso de um restaurante com entrada acessível a pessoas em cadeira de rodas.
Encontrar um lugar para comer algo tarde da noite: encontre um estabelecimento aberto que sirva uma refeição específica em um determinado horário.
- Exemplo de comando: A "Burger Joint" está aberta agora? Eles servem jantar? Qual é o horário de funcionamento na sexta-feira?
Encontrar um cliente para tomar um café: avalie a adequação de um café para uma reunião de negócios com base nas comodidades, ofertas e opções de pagamento.
- Comando de exemplo: O "Café Central" tem Wi-Fi? Eles servem café? Qual é o nível de preços e eles aceitam cartões de crédito?
As informações nos
Como o embasamento com o Google Maps funciona
Quando você fornece a ferramenta GoogleMaps ao modelo, ele processa todo o fluxo de trabalho de pesquisa, tratamento e citação de informações automaticamente.
Este é o fluxo de trabalho do modelo:
Recebe 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 "cafés 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
Google Maps .Envia consultas para
Google Maps : o serviço de embasamento comGoogle Maps consultaGoogle Maps para informações relevantes (por exemplo, lugares, avaliações, fotos, endereços, horário de funcionamento).Você pode incluir latitude e longitude na configuração da ferramenta (ou até mesmo no comando) para receber resultados mais relevantes e personalizados de
Google Maps . A ferramenta é de pesquisa textual e funciona de maneira semelhante à pesquisa noGoogle Maps . As consultas locais ("perto de mim") usam as coordenadas, enquanto as consultas específicas ou não locais provavelmente não serã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
Google Maps resultado embasado: o modelo retorna uma resposta final e fácil de usar que é embasada nos resultados doGoogle Maps . Essa resposta inclui:- A resposta de texto do modelo.
- Um objeto
groundingMetadatacom os resultados e as fontes deGoogle Maps . - (Somente SDK da Web) Opcionalmente, um googleMapsWidgetContextToken que permite renderizar um widget contextual
Google Maps no seu app para interação visual. Para mais informações sobre o widget contextual, consulte Fundamentação com o widgetGoogle Maps na documentação doGoogle Maps .
Fornecer groundingMetadata e, portanto, não é um resultado embasado
Entender o resultado embasado
Se o modelo fundamentar a resposta em resultados do groundingMetadata que contém dados estruturados essenciais para verificar declarações e criar uma experiência de fonte avançada no seu aplicativo.
O objeto groundingMetadata em um
groundingChunks: uma matriz de objetos que contém as fontesmaps(uri,placeIdetitle).groundingSupports: uma matriz de partes para conectar a resposta do modelotextàs fontes emgroundingChunks. Cada trecho 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.- (Somente SDK da Web)
googleMapsWidgetContextToken: um token de texto que pode ser usado para renderizar um widget contextual do Places. Esse campo só é retornado ao usar o SDK da Web e se você definiu o parâmetroenableWidgetcomotrue.
Confira 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]
}
],
"googleMapsWidgetContextToken": "widgetcontent/..."
}
}
]
}
Requisitos de uso do serviço
Nesta seção, descrevemos os requisitos de uso do serviço para o embasamento com
Informar os usuários sobre as fontes do Google Maps
Com cada groundingChunks que apoiam cada resposta. Os seguintes metadados também são retornados:
- source uri
- título
- ID
No seu app, ao apresentar resultados do embasamento com
As fontes
Google Maps precisam seguir imediatamente o conteúdo gerado que elas apoiam. Esse conteúdo gerado também é chamado deGoogle Maps resultado embasado.As fontes
Google Maps precisam estar visíveis em uma interação do usuário.
Saiba como extrair valores para mostrar fontes 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 fonte em groundingChunks,
uma prévia de link precisa ser gerada seguindo estes requisitos:
- Atribua cada fonte a
Google Maps seguindo as diretrizes de atribuição de textoGoogle Maps . - Mostra o título da fonte fornecido na resposta.
- Vincule à fonte usando o
urida resposta.
É possível recolher a visualização das fontes.
Se quiser, você pode melhorar a prévia do link com conteúdo adicional, como:
- Um favicon
Google Maps inserido antes da atribuição de textoGoogle Maps . - Uma foto do URL de origem (
og:image).
Para mais informações sobre alguns dos provedores de dados
Google Maps diretrizes de atribuição de texto
Ao atribuir fontes a
Não modifique o texto
Google Mapsde forma alguma:- Não mude a capitalização do texto
Google Maps. - Não quebre o texto
Google Mapsem várias linhas. - Não localize o texto
Google Mapspara outro idioma. - Impeça que os navegadores traduzam o texto
Google Mapsusando o atributo HTMLtranslate="no".
- Não mude a capitalização 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: 12sp
Tamanho máximo da fonte: 16sp
Para saber mais sobre sp, consulte "Unidades de tamanho da fonte" no site do Material Design.Espaçamento Normal
Exemplo de CSS
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 token de contexto e do ID de lugar
O
- (Somente SDK da Web)
googleMapsWidgetContextToken placeId
As restrições contra 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 o
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
Google Maps em um Território Vetado. 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 monitoramento de IA no console do Firebase, as respostas são armazenadas em Cloud Logging. Por padrão, esses dados têm um período de armazenamento 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 outros requisitos de compliance do provedor de Gemini API escolhido: Gemini Developer API ou Vertex AI Gemini API (consulte a seção Termos de Serviço nos Termos Específicos do 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 embasamento com preços do
Confira os detalhes sobre preços, disponibilidade de modelos e limites para
fundamentação com