Interaktionen mit mehreren Durchgängen mit Server-Promptvorlagen


Dieser Leitfaden gilt für alle Funktionen, die von Multi-Turn-Interaktionen abhängen, darunter:

Gesamtübersicht

Bei Multi-Turn-Interaktionen verwalten die Firebase AI Logic-SDKs den Status der Unterhaltung. Das gilt auch, wenn Sie Server-Prompt-Vorlagen verwenden.

Der grundlegende Workflow für Interaktionen mit mehreren Durchgängen und Server-Promptvorlagen ist im Grunde derselbe wie für Anfragen mit einem Durchgang, es gibt jedoch einige wichtige Unterschiede:

  1. Erstellen Sie die Vorlage über die geführte Benutzeroberfläche in der Firebase-Konsole.

    Bei Interaktionen mit mehreren Schritten müssen Sie das {{history}}-Tag in den Inhalt der Vorlage einfügen. Dadurch wird angegeben, wo die vom Client-SDK verwalteten Gesprächsrunden eingefügt werden sollen.

  2. Testen Sie die Vorlage in einer echten Anfrage mit der Testfunktion in der Firebase-Konsole.

    Bei Interaktionen mit mehreren Durchgängen kann die Console-Testfunktion nur für den ersten Durchgang verwendet werden. Sie können testen, wie nachfolgende Turns (der Verlauf) behandelt werden, indem Sie die Vorlage mit Ihrer tatsächlichen App verwenden.

  3. Greifen Sie mit templateGenerativeModel über den Code Ihrer App auf die Vorlage zu.

    Für Multi-Turn-Interaktionen müssen Sie startChat und sendMessage verwenden, genau wie bei Multi-Turn-Interaktionen, wenn Sie keine Server-Prompt-Vorlagen verwenden.

Für Funktionsaufrufe gibt es einige weitere Unterschiede, die später auf dieser Seite beschrieben werden.


Unterhaltung in mehreren Runden (Chat)

Wenn Sie keine Server-Promptvorlagen verwenden, sollten Sie sich den allgemeinen Leitfaden zum Erstellen von Unterhaltungen mit mehreren Runden (Chat) ansehen, sofern Sie dies noch nicht getan haben.

Grundlegendes Format einer Server-Promptvorlage

Für Firebase AI Logic bietet die Firebase-Konsole eine geführte Benutzeroberfläche, über die Sie das Frontmatter und den Inhalt der Vorlage angeben können.

Server-Prompt-Vorlagen verwenden eine auf Dotprompt basierende Syntax und ein auf Dotprompt basierendes Format. Weitere Informationen finden Sie unter Vorlagenformat, ‑syntax und ‑beispiele.

Die Beispielvorlage unten zeigt die wichtigsten Komponenten einer Vorlage für die Erstellung eines wechselseitigen Chats. Beachten Sie, dass dem Inhalt der Vorlage das Tag {{history}} hinzugefügt wurde. Damit wird angegeben, an welcher Stelle die vom Client-SDK verwalteten Gesprächsrunden eingefügt werden sollen.

---
model: 'gemini-3-flash-preview'
---

{{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}}

Vorlage im Code verwenden

Klicken Sie auf Ihren Gemini API-Anbieter, um anbieterspezifische Inhalte und Code auf dieser Seite aufzurufen.

Der Beispielclientcode unten zeigt, wie Sie die Vorlage in Ihrem Code verwenden. Beachten Sie die Verwendung von templateGenerativeModel zusammen mit startChat und sendMessage beim Erstellen von Multi-Turn-Interaktionen.

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);

Einheit 


// ...

// 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}");
}


Funktionsaufrufe

Wenn Sie es noch nicht getan haben, lesen Sie den allgemeinen Leitfaden zum Funktionsaufruf, wenn Sie keine Server-Promptvorlagen verwenden. In dieser Anleitung zur Verwendung von Server-Promptvorlagen wird davon ausgegangen, dass Sie die allgemeine Funktionsweise von Funktionsaufrufen kennen.

Grundlegendes Format einer Server-Promptvorlage

Für Firebase AI Logic bietet die Firebase-Konsole eine geführte Benutzeroberfläche, über die Sie das Frontmatter und den Inhalt der Vorlage angeben können.

Server-Prompt-Vorlagen verwenden eine auf Dotprompt basierende Syntax und ein auf Dotprompt basierendes Format. Weitere Informationen finden Sie unter Vorlagenformat, ‑syntax und ‑beispiele.

Die Beispielvorlage unten zeigt die wichtigsten Komponenten einer Vorlage bei der Verwendung von Funktionsaufrufen. Wichtige Hinweise:

  • Listen Sie im Frontmatter der Vorlage die Funktionen auf, auf die das Modell Zugriff hat, indem Sie Funktionsdeklarationen im tools-Objekt angeben.

    • Definieren Sie die name (erforderlich) und die description (optional) für jede Funktion, auf die das Modell Zugriff hat.

    • Definieren Sie das Schema für jede Funktion, auf die das Modell Zugriff hat.

      In der folgenden Beispielvorlage wird davon ausgegangen, dass Sie Funktionsschemata in der Vorlage definieren. Sie können das Schema der Funktion jedoch stattdessen im Clientcode angeben. Das im Clientcode definierte Schema überschreibt alle im Template definierten Schemas. Weiter unten auf dieser Seite finden Sie ein Beispiel für eine Vorlage und Clientcode zum Definieren des Schemas im Clientcode.

  • Fügen Sie im Inhalt der Vorlage das Tag {{history}} ein. Damit wird der Vorlage mitgeteilt, wo die vom Client SDK verwalteten Gesprächsrunden eingefügt werden sollen.

Beispielvorlage mit im Template definiertem Funktionsschema

---
model: gemini-3-flash-preview
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}}

Vorlage im Code verwenden

Klicken Sie auf Ihren Gemini API-Anbieter, um anbieterspezifische Inhalte und Code auf dieser Seite aufzurufen.

Der Beispielclientcode unten zeigt, wie Sie die Vorlage in Ihrem Code verwenden. Wichtige Hinweise:

  • Verwenden Sie templateGenerativeModel zusammen mit startChat und sendMessage bei Multi-Turn-Interaktionen.

  • Listen Sie bei der Initialisierung des Modells in Ihrem Clientcode nicht die Funktionen auf, auf die das Modell Zugriff hat. Stattdessen müssen Funktionen im tools-Objekt des Frontmatter des Templates aufgeführt werden (siehe oben).

  • Im folgenden Beispielclientcode wird davon ausgegangen, dass Sie Funktionsschemas in der Vorlage definieren. Wenn Sie das Schema stattdessen in Ihrem Clientcode definieren, wird es durch das im Template definierte Schema überschrieben. Weiter unten auf dieser Seite finden Sie eine Beispielvorlage und einen Beispielclientcode zum Definieren des Schemas im Clientcode.

  • Prüfen Sie, ob das Modell als Teil der Erfüllung einer Anfrage einen Funktionsaufruf zurückgibt. Wenn ja, muss Ihre App die lokale Logik ausführen und das Ergebnis dann an das Modell zurücksenden.

Beispiel für Clientcode mit Funktionsschema, das in der Vorlage definiert ist

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),
      );
    }
  }
}

Einheit 


// ...

// 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}");
}


Funktionsaufrufe – Schema im Clientcode definieren

Lesen Sie sich die Abschnitte oben durch, in denen beschrieben wird, wie Funktionsaufrufe mit Server-Prompt-Vorlagen funktionieren, insbesondere die Verwendung des {{history}}-Tags im Inhalt der Vorlage. In diesem Abschnitt finden Sie eine Beispielvorlage und einen Beispiel-Clientcode, wenn Sie Ihr Funktionsschema im Clientcode (anstatt in der Vorlage) definieren möchten.

Beachten Sie Folgendes beim Definieren des Funktionsschemas im Clientcode:

  • Wenn Sie das Schema einer Funktion in Ihrem Clientcode definieren (wie im Beispiel unten gezeigt), wird das clientseitige Schema für diese Funktion durch ein beliebiges vorlagendefiniertes Schema überschrieben.

  • Um das Funktionsschema im Clientcode zu definieren, schreiben Sie die Funktionsdeklaration und stellen Sie die Deklaration dann in startChat bereit, nicht während der Modellinitialisierung (was Sie tun, wenn Sie keine Server-Promptvorlagen verwenden).

  • Auch wenn in der Funktionsdeklaration ein name angegeben ist, müssen in der Vorlage die Funktionen aufgeführt werden, auf die das Modell Zugriff haben soll. Der name in der Vorlage muss mit dem name im Clientcode übereinstimmen.

Beispielvorlage mit Funktionsschema, das im Clientcode definiert ist

---
model: gemini-3-flash-preview
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}}

Beispiel für Clientcode mit im Clientcode definiertem Funktionsschema
(Details, die in diesem Beispiel ausgelassen wurden, finden Sie im Beispiel für Clientcode oben)

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.
...

Einheit 

// ...

// 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.
  ...
}

// ...


Nächste Schritte