O embasamento com
O embasamento com
- Aumentar a precisão factual: reduza as alucinações do modelo com base em respostas no banco de dados do Google de 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 horário de funcionamento atual e status em tempo real de estações de carregamento de veículos elétricos.
- Fornecer contexto visual: crie confiança do usuário integrando widgets de mapas 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 compatíveis com os modelos Gemini.
Embasar o modelo com Google Maps
|
Clique no provedor Gemini API para conferir o conteúdo específico do provedor e o código nesta página. |
Ao criar a instância GenerativeModel, forneça GoogleMaps como uma 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 apenas quando necessário: para otimizar o desempenho e o custo, forneça ao modelo acesso à ferramenta de embasamento com
Google Maps apenas quando o caso de uso tiver um contexto geográfico claro.Forneça a localização do usuário: para as respostas mais relevantes e personalizadas (e quando a localização do usuário for 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
Google Maps estão sendo usados para responder às consultas deles. Fornecer as fontes aos usuários finaisGoogle Maps é um requisito de uso do serviço para a ferramenta de 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 o widget de embasamento comGoogle Maps widget na documentação.Google Maps
Usar propriedades de lugar em comandos
Esta seção lista as propriedades de lugar usadas para descrever locais
e usadas pelo embasamento com o
Exemplos de propriedades de lugar
Esta lista fornece uma amostra 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
- Cardápio infantil
- Horário de funcionamento
- Opções de pagamento (como dinheiro ou cartão de crédito)
- Resposta sobre o lugar
- Animais são permitidos
- Serve cerveja
- Serve comida vegetariana
- Acessibilidade para pessoas em cadeira de rodas
- Wi-Fi
As respostas sobre o 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
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 "The Italian Place" é bom para crianças e oferece comida para viagem? 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 com entrada acessível para cadeirantes.
Encontrar um local para um lanche tarde da noite: encontre um estabelecimento aberto que sirva uma refeição específica durante um determinado período.
- Exemplo de comando: O "Burger Joint" está aberto agora? Eles servem jantar? Qual é o horário de funcionamento deles na sexta-feira?
Encontrar um cliente para 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.
- Exemplo de comando: O "Cafe Central" tem Wi-Fi? Eles servem café? Qual é o nível de preço deles e eles aceitam cartões de crédito?
As informações nos
Como o embasamento com Google Maps funciona
Quando você fornece a ferramenta GoogleMaps ao modelo, 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
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
Google Maps .Envia consultas a
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).Opcionalmente, você pode incluir latitude e longitude na configuração da ferramenta (ou até mesmo apenas no comando diretamente) para resultados mais relevantes e personalizados
Google Maps A ferramenta é uma ferramenta de pesquisa textual e se comporta de maneira semelhante à pesquisa noGoogle Maps . As consultas locais ("perto de mim") usam as coordenadas, enquanto as consultas específicas ou não locais têm pouca probabilidade de serem influenciadas pelo local explícito.Processa os resultados
Google Maps : o modelo processa os resultadosGoogle 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 é baseada nosGoogle Maps resultados. Essa resposta inclui:- A resposta de texto do modelo.
- Um objeto
groundingMetadatacom os resultadosGoogle Maps e fontes. - (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 Embasamento com o widget na documentação.Google Maps Google Maps
Observe que fornecer groundingMetadata e, portanto,
não é um
Entender o resultado embasado
Se o modelo basear a resposta nos resultados 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 blocos para conectar a resposta do modelotextàs fontes emgroundingChunks. Cada bloco vincula umsegmentde texto (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 de lugares. Esse campo só é retornado ao usar o SDK da Web e se você tiver definido 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
Esta seção descreve os requisitos de uso do serviço para o embasamento com
Informar aos usuários sobre as fontes Google Maps
Com cada groundingChunks que oferecem suporte a cada resposta. Os seguintes metadados também são retornados:
- URI de origem
- 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 oferecem suporte. Esse conteúdo gerado também é chamado deGoogle Maps resultado embasado.As fontes
Google Maps precisam ser visualizadas em uma interação do usuário.
Saiba como receber 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 fontes Google Maps com links Google Maps
Para cada fonte em groundingChunks, uma visualização do link precisa ser gerada seguindo estes requisitos:
- Atribua cada fonte a
Google Maps seguindo asGoogle Maps diretrizes de atribuição de texto. - Mostre o título da fonte fornecido na resposta.
- Vincule à fonte usando o
urida resposta.
É possível recolher a visualização das fontes.
Opcionalmente, você pode melhorar a visualização do link com conteúdo adicional, como:
- Um
Google Maps favicon inserido antes daGoogle Maps atribuição de texto. - Uma foto do URL de origem (
og:image).
Para mais informações sobre alguns dos
Diretrizes de atribuição de texto Google Maps
Ao atribuir fontes a
Não modifique o texto
Google Mapsde forma alguma:- Não altere 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 altere 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 substitutas 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 o contraste acessível (4,5:1) com o 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
CSS de exemplo
O CSS a seguir renderiza o texto Google Maps com o estilo e a cor tipográficos adequados em um plano de 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 do lugar
O
- (Somente SDK da Web)
googleMapsWidgetContextToken placeId
As restrições contra o armazenamento em cache nos Termos de embasamento com o Google Maps não se aplicam a esses dados.
Atividade e territórios proibidos
O embasamento com
Não use o embasamento com
Google Maps para atividades de alto risco incluindo serviços de resposta a emergências.Não distribua nem comercializar seu aplicativo que oferece embasamento com
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 Firebase
Se você ativou o monitoramento de IA no consoleFirebase, as respostas serã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 retenção, ou qualquer período personalizado definido, esteja totalmente alinhado ao seu caso de uso específico e a quaisquer outros requisitos de conformidade para o provedor escolhido: ou (consulte a seção Termos de serviço nos Termos específicos do serviço).Gemini APIGemini Developer APIVertex AI Gemini API 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
Confira os detalhes sobre preços, disponibilidade do modelo e limites para
embasamento com