Este guia se aplica a qualquer capacidade que dependa de interações com várias interações, incluindo:
Conversa com várias interações (chat), incluindo chat somente com saída de texto e edição iterativa de imagens
Visão geral detalhada
Para interações com várias interações, os Firebase AI Logic SDKs gerenciam o estado da conversa. Isso também se aplica ao usar modelos de comandos do servidor.
O fluxo de trabalho básico para interações com várias interações e modelos de comandos do servidor é fundamentalmente o mesmo que para solicitações de interação única, com algumas diferenças importantes:
Crie o modelo usando a interface guiada no Firebase console.
Para interações com várias interações, adicione a
{{history}}tag ao conteúdo do modelo, que informa onde inserir as interações da conversa gerenciadas pelo SDK do cliente.Teste o modelo em uma solicitação real usando a experiência de teste no Firebase console.
Para interações com várias interações, a experiência de teste do console só pode ajudar a testar a interação inicial. Você pode testar como as interações subsequentes (o histórico) são processadas usando o modelo com seu app real.
Acesse o modelo no código do app usando
templateGenerativeModel.Para interações com várias interações, use
startChatesendMessage, assim como você faz para interações com várias interações quando não usa modelos de comandos do servidor.
Para chamadas de função, há mais algumas diferenças, que são descritas nesta seção mais adiante nesta página.
Conversa com várias interações (chat)
Se ainda não fez isso, consulte o guia geral para criar conversas com várias interações (chat) quando não usar modelos de comandos do servidor.
Formato básico de um modelo de comando do servidor
Para Firebase AI Logic, o console Firebase oferece uma interface guiada para especificar o frontmatter e o conteúdo do modelo.
Os modelos de comandos do servidor usam uma sintaxe e um formato baseados em Dotprompt. Para mais detalhes, consulte Formato, sintaxe e exemplos de modelos.
O modelo de exemplo abaixo mostra os componentes mais importantes de um modelo ao criar uma conversa com várias interações (chat). Observe a adição da
{{history}} tag ao conteúdo do modelo,
que informa onde inserir as interações da conversa gerenciadas pelo
SDK do cliente.
---
model: 'gemini-3.5-flash'
---
{{role "system"}}
You help customers with their invoices, including answering questions or providing their invoices to them.
If an invoice is requested, it must be a clearly structured invoice document that uses a tabular or clearly delineated list format for line items.
{{history}}
Usar o modelo no código
|
Clique no provedor Gemini API para conferir o conteúdo específico do provedor e o código nesta página. |
O exemplo de código do cliente abaixo mostra como usar o modelo no código. Observe o uso de templateGenerativeModel com startChat e sendMessage ao criar interações com várias interações.
Swift
For Swift, using server prompt templates with multi-turn interactions is not yet supported. Check back soon!
Kotlin
// ...
// Initialize the Gemini Developer API backend service
// Create a `TemplateGenerativeModel` instance.
val model = Firebase.ai(backend = GenerativeBackend.googleAI())
.templateGenerativeModel()
// Start a chat session with a template.
val chatSession = model.startChat(
// Specify your template ID
templateId= "my-chat-template-v1-0-0",
inputs = emptyMap()
)
// Send messages.
// The template's system instructions and model config apply to every turn automatically.
// The SDK automatically manages the state of the conversation.
val response = chatSession.sendMessage(
content("user") { text("I need a copy of my invoice.") }
)
val text = response.text
println(text)
Java
For Java, using server prompt templates with multi-turn interactions is not yet supported. Check back soon!
Web
// ...
// Initialize the Gemini Developer API backend service.
const ai = getAI(app, { backend: new GoogleAIBackend() });
// Create a `TemplateGenerativeModel` instance.
const model = getTemplateGenerativeModel(ai);
// Start a chat session with a template.
const chatSession = model.startChat({
// Specify your template ID.
templateId: 'my-chat-template-v1-0-0',
});
// Send messages.
// The template's system instructions and model config apply to every turn automatically.
// The SDK automatically manages the state of the conversation.
const result = await chatSession.sendMessage("I need a copy of my invoice.");
const text = result.response.text();
console.log(text);
Dart
// ...
// Initialize the Gemini Developer API backend service.
// Create a `TemplateGenerativeModel` instance.
final model = FirebaseAI.googleAI().templateGenerativeModel();
// Start a chat session with a template.
final chatSession = model.startChat(
// Specify your template ID.
templateId: 'my-chat-template-v1-0-0',
);
// Send messages.
// The template's system instructions and model config apply to every turn automatically.
// The SDK automatically manages the state of the conversation.
final response = await chatSession.sendMessage(
Content.text('I need a copy of my invoice.'),
);
final text = response.text;
print(text);
Unity
// ...
// Initialize the Gemini Developer API backend service.
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.GoogleAI());
// Create a `TemplateGenerativeModel` instance.
var model = firebaseAI.GetTemplateGenerativeModel();
// Start a chat session with a template.
var chatSession = model.StartChat(
// Specify your template ID.
"my-chat-template-v1-0-0"
);
// Send messages.
// The template's system instructions and model config apply to every turn automatically.
// The SDK automatically manages the state of the conversation.
try
{
var response = await chatSession.SendMessageAsync(ModelContent.Text("I need a copy of my invoice."));
Debug.Log($"Response Text: {response.Text}");
}
catch (Exception e) {
Debug.LogError($"An error occurred: {e.Message}");
}
Chamadas de função
Se ainda não fez isso, consulte o guia geral para chamadas de função quando não usar modelos de comandos do servidor. Este guia sobre o uso de modelos de comandos do servidor pressupõe que você entenda como as chamadas de função funcionam em geral.
Formato básico de um modelo de comando do servidor
Para Firebase AI Logic, o console Firebase oferece uma interface guiada para especificar o frontmatter e o conteúdo do modelo.
Os modelos de comandos do servidor usam uma sintaxe e um formato baseados em Dotprompt. Para mais detalhes, consulte Formato, sintaxe e exemplos de modelos.
O modelo de exemplo abaixo mostra os componentes mais importantes de um modelo ao usar chamadas de função. Observe o seguinte:
No frontmatter do modelo, liste as funções a que o modelo tem acesso fornecendo declarações de função no objeto
tools.Defina o
name(obrigatório) e adescription(opcional) para cada função a que o modelo tem acesso.Defina o esquema para cada função a que o modelo tem acesso.
O modelo de exemplo abaixo pressupõe que você está definindo esquemas de função no modelo. No entanto, você pode fornecer o esquema da função no código do cliente. O esquema definido no código do cliente vai substituir qualquer esquema definido no modelo. Mais adiante nesta página, encontre um exemplo de um modelo e código do cliente para definir o esquema no código do cliente.
No conteúdo do modelo, adicione a
{{history}}tag, que informa onde inserir as interações da conversa gerenciadas pelo SDK do cliente.
Modelo de exemplo com esquema de função definido no modelo
---
model: gemini-3.5-flash
tools:
- name: fetchWeather
description: Get the weather conditions for a specific city on a specific date.
input:
schema:
location(object, The name of the city and its state for which to get the weather. Only cities in the USA are supported.):
city: string, The city of the location.
state: string, The state of the location.
date: string, The date for which to get the weather. Date must be in the format YYYY-MM-DD.
---
What was the weather like in Boston, Massachusetts on 10/17 in year 2024?
{{history}}
Usar o modelo no código
|
Clique no provedor Gemini API para conferir o conteúdo específico do provedor e o código nesta página. |
O exemplo de código do cliente abaixo mostra como usar o modelo no código. Observe o seguinte:
Use
templateGenerativeModelcomstartChatesendMessageao usar interações com várias interações.Durante a inicialização do modelo no código do cliente, não liste as funções a que o modelo tem acesso. Em vez disso, as funções precisam ser listadas no objeto
toolsdo frontmatter do modelo (consulte acima).O exemplo de código do cliente abaixo pressupõe que você está definindo esquemas de função no modelo. Se você decidir definir o esquema no código do cliente, ele vai substituir o esquema definido pelo modelo. Mais adiante nesta página, confira um modelo de exemplo e um código do cliente para definir o esquema no código do cliente.
Verifique se o modelo retorna uma chamada de função como parte do atendimento de uma solicitação. Se isso acontecer, seu app precisará executar a lógica local e enviar o resultado de volta ao modelo.
Exemplo de código do cliente com esquema de função definido no modelo
Swift
For Swift, using server prompt templates with multi-turn interactions is not yet supported. Check back soon!
Kotlin
// ...
// Initialize the Gemini Developer API backend service.
// Create a `TemplateGenerativeModel` instance.
val model = Firebase.ai(backend = GenerativeBackend.googleAI())
.templateGenerativeModel()
// Start a chat session with a template that has functions listed as tools.
val chatSession = model.startChat(
// Specify your template ID
templateId = "my-function-calling-template-v1-0-0",
inputs = emptyMap()
)
// Send a message that might trigger a function call.
val response = chatSession.sendMessage(
content("user") { text(userMessage) }
)
// When the model responds with one or more function calls, invoke the function(s).
// Note that this is the same as when *not* using server prompt templates.
val functionCalls = response.functionCalls
val fetchWeatherCall = functionCalls.find { it.name == "fetchWeather" }
// Forward the structured input data from the model to the hypothetical external API.
val functionResponse = fetchWeatherCall?.let {
// Alternatively, if your `Location` class is marked as @Serializable, you can use
// val location = Json.decodeFromJsonElement(it.args["location"]!!)
val location = Location(
it.args["location"]!!.jsonObject["city"]!!.jsonPrimitive.content,
it.args["location"]!!.jsonObject["state"]!!.jsonPrimitive.content
)
val date = it.args["date"]!!.jsonPrimitive.content
fetchWeather(location, date)
}
Java
For Java, using server prompt templates with multi-turn interactions is not yet supported. Check back soon!
Web
// ...
// Initialize the Gemini Developer API backend service.
const ai = getAI(app, { backend: new GoogleAIBackend() });
// Create a `TemplateGenerativeModel` instance.
const model = getTemplateGenerativeModel(ai);
// Start a chat session with a template that has functions listed as tools.
const chatSession = model.startChat({
// Specify your template ID
templateId: 'my-function-calling-template-v1-0-0',
});
// Send a message that might trigger a function call.
const result = await chatSession.sendMessage(userMessage);
// When the model responds with one or more function calls, invoke the function(s).
// Note that this is the same as when *not* using server prompt templates.
const functionCalls = result.response.functionCalls();
let functionCall;
let functionResult;
if (functionCalls.length > 0) {
for (const call of functionCalls) {
if (call.name === "fetchWeather") {
// Forward the structured input data prepared by the model
// to the hypothetical external API.
functionResult = await fetchWeather(call.args);
functionCall = call;
}
}
}
Dart
// ...
// Initialize the Gemini Developer API backend service.
// Create a `TemplateGenerativeModel` instance.
final model = FirebaseAI.googleAI().templateGenerativeModel()
// Start a chat session with a template that has functions listed as tools.
var chatSession = model.startChat(
// Specify your template ID
'my-function-calling-template-v1-0-0',
);
// Send a message that might trigger a function call.
var response = await chatSession.sendMessage(
Content.text(userMessage),
);
// Check if the model wants to call a function.
// Note that this is the same as when *not* using server prompt templates.
final functionCalls = response?.functionCalls.toList();
// When the model responds with one or more function calls, invoke the function(s).
if (functionCalls != null && functionCalls.isNotEmpty) {
for (final functionCall in functionCalls) {
if (functionCall.name == 'fetchWeather') {
Map<String, dynamic> location =
functionCall.args['location']! as Map<String, dynamic>;
var date = functionCall.args['date']! as String;
var city = location['city'] as String;
var state = location['state'] as String;
final functionResult =
await fetchWeather(Location(city, state), date);
// Send the response to the model so that it can use the result to
// generate text for the user.
response = await chatSession.sendMessage(
Content.functionResponse(functionCall.name, functionResult),
);
}
}
}
Unity
// ...
// Initialize the Gemini Developer API backend service.
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.GoogleAI());
// Create a `TemplateGenerativeModel` instance.
var model = firebaseAI.GetTemplateGenerativeModel();
// Start a chat session with a template that has functions listed as tools.
var chatSession = model.StartChat(
// Specify your template ID
"my-function-calling-template-v1-0-0"
);
try
{
// Send a message that might trigger a function call.
var response = await chatSession.SendMessageAsync(ModelContent.Text(userMessage));
var functionResponses = new List();
// When the model responds with one or more function calls, invoke the function(s).
// Note that this is the same as when *not* using server prompt templates.
foreach (var functionCall in response.FunctionCalls) {
if (functionCall.Name == "fetchWeather") {
// TODO(developer): Handle invalid arguments.
var location = functionCall.Args["location"] as Dictionary<string, object>;
var city = location["city"] as string;
var state = location["state"] as string;
var date = functionCall.Args["date"] as string;
functionResponses.Add(ModelContent.FunctionResponse(
name: functionCall.Name,
// Forward the structured input data prepared by the model
// to the hypothetical external API.
response: FetchWeather(city: city, state: state, date: date)
));
}
// TODO(developer): Handle other potential function calls, if any.
}
// Send the function responses back to the model.
var functionResponseResult = await chatSession.SendMessageAsync(functionResponses);
}
catch (Exception e) {
Debug.LogError($"An error occurred: {e.Message}");
}
Chamada de função: definir o esquema no código do cliente
Consulte as seções acima sobre como as chamadas de função funcionam com
modelos de comandos do servidor (em particular, o uso da
{{history}} tag no conteúdo do
modelo). Esta seção fornece um modelo de exemplo e um código do cliente se você quiser definir o esquema de função no código do cliente (em vez de no modelo).
Observe o seguinte sobre a definição do esquema de função no código do cliente:
Se você definir o esquema de uma função no código do cliente (conforme mostrado no exemplo abaixo), o esquema do lado do cliente vai substituir qualquer esquema definido pelo modelo para essa função.
Para definir o esquema de função no código do cliente, escreva a declaração de função e, em seguida, forneça a declaração em
startChat, não durante a inicialização do modelo (que é o que você faz quando não usa modelos de comandos do servidor).Embora a declaração de função especifique um
name, o modelo ainda precisa listar as funções a que você quer que o modelo tenha acesso. Onameno modelo precisa corresponder aonameno código do cliente.
Modelo de exemplo com esquema de função definido no código do cliente
---
model: gemini-3.5-flash
tools:
- name: fetchWeather
description: Get the weather conditions for a specific city on a specific date.
---
What was the weather like in Boston, Massachusetts on 10/17 in year 2024, formatted in CELSIUS?
{{history}}
Exemplo de código do cliente com esquema de função definido no código do cliente
(para detalhes omitidos neste exemplo, consulte o
exemplo de código do cliente acima)
Swift
For Swift, using server prompt templates with multi-turn interactions is not yet supported. Check back soon!
Kotlin
// ...
// Initialize your desired Gemini API backend service.
// Create a `TemplateGenerativeModel` instance.
...
// Define the schema for any functions listed in your template.
val fetchWeatherTool = functionDeclarations(
functionDeclarations = listOf(
FunctionDeclaration(
name = "fetchWeather",
description = "Returns the weather for a given location at a given time",
parameters = mapOf(
"location" to Schema.obj(
description = "The name of the city and its state for which to get the weather. Only cities in the USA are supported.",
properties = mapOf(
"city" to Schema.string(
description = "The city of the location."
),
"state" to Schema.string(
description = "The state of the location."
),
"zipCode" to Schema.string(
description = "Optional zip code of the location.",
nullable = true
)
),
optionalProperties = listOf("zipCode")
),
"date" to Schema.string(
description = "The date for which to get the weather. Date must be in the format: YYYY-MM-DD."
),
"unit" to Schema.enumeration(
description = "The temperature unit.",
values = listOf("CELSIUS", "FAHRENHEIT"),
nullable = true
)
),
optionalParameters = listOf("unit"),
)
)
)
// Start a chat session with a template that has functions listed as tools.
var chatSessionWithSchemaOverride = model.startChat(
// Specify your template ID.
templateId = "my-function-calling-template-with-no-function-schema-v1-0-0",
// In `startChat`, provide the schema for any functions listed in your template.
// This client-side schema will override any schema defined in the template.
tools = listOf(fetchWeatherTool)
)
// Send a message that might trigger a function call.
...
// When the model responds with one or more function calls, invoke the function(s).
// Note that this is the same as when *not* using server prompt templates.
...
// Forward the structured input data from the model to the hypothetical external API.
...
Java
For Java, using server prompt templates with multi-turn interactions is not yet supported. Check back soon!
Web
// ...
// Initialize your desired Gemini API backend service.
...
// Create a `TemplateGenerativeModel` instance.
...
// Start a chat session with a template that has functions listed as tools.
const chatSessionWithSchemaOverride = model.startChat({
// Specify your template ID.
templateId: 'my-function-calling-template-with-no-function-schema-v1-0-0',
// In `startChat`, provide the schema for any functions listed in your template.
// This client-side schema will override any schema defined in the template.
tools: [
{
functionDeclarations: [
{
name: "fetchWeather",
parameters: {
type: Type.OBJECT,
properties: {
location: {
type: Type.OBJECT,
description: "The name of the city and its state for which to get the weather. Only cities in the USA are supported.",
properties: {
city: {
type: Type.STRING,
description: "The city of the location."
},
state: {
type: Type.STRING,
description: "The state of the location."
},
zipCode: {
type: Type.INTEGER,
description: "Optional zip code of the location.",
nullable: true
},
},
required: ["city", "state"],
},
date: {
type: Type.STRING,
description: "The date for which to get the weather. Date must be in the format: YYYY-MM-DD.",
},
unit: {
type: Type.STRING,
description: "The temperature unit.",
enum: ["CELSIUS", "FAHRENHEIT"],
nullable: true,
},
},
required: ["location", "date"],
},
},
],
}
],
});
// Send a message that might trigger a function call.
...
// When the model responds with one or more function calls, invoke the function(s).
// Note that this is the same as when *not* using server prompt templates.
...
Dart
// ...
// Initialize your desired Gemini API backend service.
// Create a `TemplateGenerativeModel` instance.
...
// Start a chat session with a template that has functions listed as tools.
final chatSessionWithSchemaOverride = model?.startChat(
// Specify your template ID.
'my-function-calling-template-with-no-function-schema-v1-0-0',
inputs: {},
// In `startChat`, provide the schema for any functions listed in your template.
// This client-side schema will override any schema defined in the template.
tools: [
TemplateTool.functionDeclarations(
[
TemplateFunctionDeclaration(
'fetchWeather',
parameters: {
'location': JSONSchema.object(
description:
'The name of the city and its state for which to get '
'the weather. Only cities in the USA are supported.',
properties: {
'city': JSONSchema.string(
description: 'The city of the location.',
),
'state': JSONSchema.string(
description: 'The state of the location.',
),
'zipCode': JSONSchema.integer(
description: 'Optional zip code of the location.',
nullable: true,
),
},
optionalProperties: ['zipCode'],
),
'date': JSONSchema.string(
description: 'The date for which to get the weather. '
'Date must be in the format: YYYY-MM-DD.',
),
'unit': JSONSchema.enumString(
enumValues: ['CELSIUS', 'FAHRENHEIT'],
description: 'The temperature unit.',
nullable: true,
),
},
optionalParameters: ['unit'],
),
],
),
],
);
// Send a message that might trigger a function call.
...
// Check if the model wants to call a function.
// Note that this is the same as when *not* using server prompt templates.
...
Unity
// ...
// Initialize your desired Gemini API backend service.
...
// Create a `TemplateGenerativeModel` instance.
...
// Define the schema for any functions listed in your template.
var fetchWeatherTool = new TemplateTool.FunctionDeclaration(
name: "fetchWeather",
parameters: new Dictionary<string, JsonSchema>() {
{ "location", JsonSchema.Object(
description: "The name of the city and its state for which to get the weather. Only cities in the USA are supported.",
properties: new Dictionary<string, JsonSchema>() {
{ "city", JsonSchema.String(description: "The city of the location.") },
{ "state", JsonSchema.String(description: "The state of the location.") },
{ "zipCode", JsonSchema.Int(description: "Optional zip code of the location.", nullable: true) }
},
optionalProperties: new[] { "zipCode" })
},
{ "date", JsonSchema.String(description: "The date for which to get the weather. Date must be in the format: YYYY-MM-DD.")},
{ "unit", JsonSchema.Enum(
values: new[] { "CELSIUS", "FAHRENHEIT" },
description: "The temperature unit.",
nullable: true)
}
},
optionalParameters: new[] { "unit" }
);
// Start a chat session with a template that has functions listed as tools.
var chatSessionWithSchemaOverride = model.StartChat(
// Specify your template ID.
templateId: "my-function-calling-template-with-no-function-schema-v1-0-0",
// In `startChat`, provide the schema for any functions listed in your template.
// This client-side schema will override any schema defined in the template.
tools: new[] { fetchWeatherTool }
);
try
{
// Send a message that might trigger a function call.
...
// When the model responds with one or more function calls, invoke the function(s).
// Note that this is the same as when *not* using server prompt templates.
...
}
// ...
A seguir
Saiba mais sobre as práticas recomendadas e considerações para usar modelos de comandos do servidor.
Saiba mais detalhes sobre o formato e a sintaxe do modelo, além de exemplos.
Gerenciar modelos, incluindo edição, bloqueio e controle de versões.