Premiers pas avec les modèles de prompts côté serveur

Dans chaque requête adressée à un modèle, vous envoyez un prompt et, éventuellement, un schéma et des configurations pour contrôler la réponse du modèle. Lorsque vous utilisez Firebase AI Logic, vous pouvez envoyer toutes ces informations directement depuis votre code client ou les spécifier côté serveur à l'aide de modèles de prompts côté serveur.

Lorsque vous utilisez des modèles de prompts côté serveur, vous stockez votre prompt, votre schéma et vos configurations côté serveur. Le codebase de votre application ne transmet du client au serveur qu'une clé (l'ID du modèle) faisant référence à un modèle spécifique, ainsi que les entrées requises pour ce modèle. Voici quelques avantages de cette approche :

• Protéger votre prompt contre l'exposition côté client

• Mettre à jour votre prompt et votre configuration sans publier de nouvelle version de l'application

Ce guide explique comment utiliser les modèles de prompt de serveur.

arrow_downward Accéder à la présentation générale arrow_downward Accéder aux instructions détaillées

Modèles et fonctionnalités compatibles

• Utilisez des modèles de prompts côté serveur avec n'importe quel modèle Gemini compatible avec Firebase AI Logic, à l'exception des modèles Gemini Live API.

• Consultez la liste des fonctionnalités non encore compatibles.

Vue d'ensemble

Voici le workflow de base pour utiliser des modèles de prompt côté serveur :

1. Créez le modèle à l'aide de l'interface utilisateur guidée de la console Firebase.

2. Testez le modèle dans une requête réelle à l'aide de l'expérience de test de la console Firebase.

3. Accédez au modèle à partir du code de votre application à l'aide de templateGenerativeModel.

Format de base d'un modèle de prompt côté serveur

Pour Firebase AI Logic, la console Firebase fournit une UI guidée qui vous permet de spécifier le frontmatter et le contenu du modèle.

Les modèles de prompts côté serveur utilisent une syntaxe et un format basés sur Dotprompt. Pour en savoir plus, consultez Format, syntaxe et exemples de modèles.

L'exemple de modèle ci-dessous montre les composants les plus importants d'un modèle pour un exemple de requête adressée à un modèle Gemini :

---
model: 'gemini-3.8-flash'
---

{{role "system"}}
All output must be a clearly structured invoice document.
Use a tabular or clearly delineated list format for line items.

{{role "user"}}
Create an example customer invoice for a customer named {{customerName}}.

• La section supérieure entre les trois tirets contient le nom du modèle, ainsi que, éventuellement, toute configuration de modèle, validation d'entrée ou schéma que vous souhaitez envoyer dans la requête. Il est rédigé sous forme de paires clé/valeur et est communément appelé frontmatter YAML.

• Le corps du modèle contient la requête. Il peut également inclure des instructions système et des valeurs d'entrée (à l'aide de la syntaxe Handlebars).

Utiliser votre modèle dans du code

L'exemple de code client ci-dessous montre comment utiliser le modèle dans votre code :

// ...

// Initialize the Gemini Developer API backend service.
// Create a `TemplateGenerativeModel` instance.
let model = FirebaseAI.firebaseAI(backend: .googleAI()).templateGenerativeModel()

let customerName = "Jane"

do {
    let response = try await model.generateContent(
        // Specify your template ID
        templateID: "my-first-template-v1-0-0",
        // Provide the values for any input variables required by your template.
        inputs: [
            "customerName": customerName
        ]
    )
    if let text = response.text {
        print("Response Text: \(text)")
    }
} catch {
    print("An error occurred: \(error)")
}
print("\n")

// ...

// Initialize the Gemini Developer API backend service.
// Create a `TemplateGenerativeModel` instance.
val model = Firebase.ai(backend = GenerativeBackend.googleAI()).templateGenerativeModel()

val customerName = "Jane"

val response = model.generateContent(
    // Specify your template ID.
    "my-first-template-v1-0-0",
    // Provide the values for any input variables required by your template.
    mapOf(
        "customerName" to customerName
    )
)

val text = response.text
println(text)

// ...

// Initialize the Gemini Developer API backend service.
// Create a `TemplateGenerativeModel` instance.
TemplateGenerativeModel generativeModel = FirebaseAI.getInstance().templateGenerativeModel();

TemplateGenerativeModelFutures model = TemplateGenerativeModelFutures.from(generativeModel);

String customerName = "Jane";

Future response = model.generateContent(
    // Specify your template ID
    "my-first-template-v1-0-0",
    // Provide the values for any input variables required by your template.
    mapOf("customerName", customerName)
);
addCallback(response,
       new FutureCallback() {
           public void onSuccess(GenerateContentResponse result) {
             System.out.println(result.getText());
           }
           public void onFailure(Throwable t) {
             reportError(t);
           }
    }
executor);

// ...

// Initialize the Gemini Developer API backend service.
const ai = getAI(app, { backend: new GoogleAIBackend() });

// Create a `TemplateGenerativeModel` instance.
const model = getTemplateGenerativeModel(ai);

const customerName = 'Jane';

const result = await model.generateContent({
  // Specify your template ID.
  templateId: 'my-first-template-v1-0-0',
  // Provide the values for any input variables required by your template.
  templateVariables: {
    customerName: customerName,
  },
});

const response = result.response;
const text = response.text();

// ...

// Initialize the Gemini Developer API backend service.
// Create a `TemplateGenerativeModel` instance.
var _model = FirebaseAI.googleAI().templateGenerativeModel();

var customerName = 'Jane';

var response = await _model.generateContent(
        // Specify your template ID
        'my-first-template-v1-0-0',
        // Provide the values for any input variables required by your template.
        inputs: {
           'customerName': customerName,
        },
      );

var text = response?.text;
print(text);

// ...

// Initialize the Gemini Developer API backend service.
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.GoogleAI());

// Create a `TemplateGenerativeModel` instance.
var model = firebaseAI.GetTemplateGenerativeModel();

var customerName = "Jane";

try
{
   var response = await model.GenerateContentAsync(
      // Specify your template ID.
      "my-first-template-v1-0-0",
      // Provide the values for any input variables required by your template.
      new Dictionary<string, object> {
         { "customerName", customerName },
      }
   );
   Debug.Log($"Response Text: {response.Text}");
}
catch (Exception e) {
  Debug.LogError($"An error occurred: {e.Message}");
}

Instructions détaillées

Cette section fournit des instructions détaillées pour créer, tester et utiliser des modèles de prompt de serveur.

Avant de commencer

• Si ce n'est pas déjà fait, suivez le guide de démarrage, qui explique comment configurer votre projet Firebase, connecter votre application à Firebase, ajouter le SDK, initialiser le service de backend pour le fournisseur Gemini API de votre choix et créer une instance GenerativeModel.

• Assurez-vous de disposer des autorisations requises pour créer et gérer des modèles de prompt de serveur. Par défaut, toutes ces autorisations sont incluses dans le rôle Propriétaire.

  Afficher les autorisations requises

  • firebasevertexai.googleapis.com/promptTemplates.create
  • firebasevertexai.googleapis.com/promptTemplates.get
  • firebasevertexai.googleapis.com/promptTemplates.update
  • firebasevertexai.googleapis.com/promptTemplates.delete
  • firebasevertexai.googleapis.com/promptTemplates.list
  • firebasevertexai.googleapis.com/promptTemplates.updateLock

• Si vous utilisez Agent Platform Gemini API (formerly Vertex AI) et que votre cas d'utilisation nécessite des restrictions basées sur l'emplacement, nous acceptons les workflows avancés pour les modèles.

Étape 1 : Créez un modèle de prompt de serveur

Dans la plupart des cas d'utilisation, vous créez et gérez des modèles de prompt de serveur dans la consoleFirebase.

1. Dans la console Firebase, accédez à Services d'IA > Logique d'IA > onglet Modèles de prompt.

2. Cliquez sur Créer un modèle, puis sélectionnez une option de modèle de démarrage.

   • Ces modèles de démarrage fournissent le format et la syntaxe de certains cas d'utilisation courants. Quelle que soit l'option que vous sélectionnez, vous pouvez modifier complètement le modèle pour l'adapter à vos besoins.

   • Ce guide de démarrage suppose que vous avez sélectionné l'option Input + System Instructions.

3. Saisissez les identifiants du modèle :

   • Nom du modèle : il s'agit du nom à afficher pour le modèle (par exemple, My First Template). Il n'est visible que dans les interfaces Firebase, comme la console Firebase.

   • ID du modèle : il doit s'agir d'un identifiant unique pour le modèle dans votre projet Firebase (par exemple, my-first-template-v1-0-0). Vous ferez référence à cet identifiant dans la requête provenant de votre application.

     • Nous vous recommandons d'utiliser un système de gestion des versions pour vos ID de modèle.

     • Les ID de modèle peuvent comporter jusqu'à 63 caractères et contenir des lettres minuscules, des chiffres et des traits d'union.

4. Modifiez la section Configuration (frontmatter) du modèle, si nécessaire.

   • Cette section doit inclure au moins un nom de modèle, comme ceci :

     ---
     model: 'gemini-3.8-flash'
     ---
     

   • Vous pouvez également spécifier la configuration du modèle, ainsi que les commandes d'entrée et de sortie, etc. Pour en savoir plus et découvrir d'autres options, consultez Format, syntaxe et exemples de modèles.

5. Modifiez la section Prompt et instructions système (le cas échéant) du modèle, si nécessaire.

   • Cette section doit inclure au moins le prompt textuel à envoyer au modèle.

     Write a story about a magic backpack.
     

   • Vous pouvez également créer des requêtes plus complexes, comme les options suivantes. Pour en savoir plus et découvrir d'autres options, consultez Format, syntaxe et exemples de modèles.

     • (Facultatif et le cas échéant) Spécifiez les instructions système à l'aide de la syntaxe {{role "system"}} et la requête textuelle à l'aide de la syntaxe {{role "user"}}.

     • (Facultatif) Spécifiez les variables d'entrée à l'aide de la syntaxe Handlebars (comme {{customerName}}). Vous pouvez fournir une valeur par défaut dans le modèle, mais la valeur de cette variable d'entrée est généralement transmise dans la requête.

     {{role "system"}}
     All output must be a clearly structured invoice document.
     Use a tabular or clearly delineated list format for line items.
     
     {{role "user"}}
     Create an example customer invoice for a customer named {{customerName}}.
     

Étape 2 : Testez votre modèle dans la console Firebase

La console Firebase vous permet de tester votre modèle. Cette expérience vous permet de voir ce qui se passera lorsque votre modèle sera utilisé, à la fois le format de la requête et le résultat d'une requête réelle.

1. Cliquez sur Enregistrer le modèle pour pouvoir le tester.

   Vous pourrez toujours modifier ou même supprimer le modèle plus tard. La seule valeur que vous ne pourrez pas modifier ultérieurement est l'ID du modèle.

2. Si votre requête utilise des variables d'entrée, incluez des valeurs de test dans le champ Entrée de test. Pour cet exemple :

     {
       "customerName": "Jane"
     }
   

3. Si plusieurs fournisseurs Gemini API sont activés dans votre projet Firebase, vous pouvez choisir celui à utiliser pour la requête de test. Si cette option s'affiche dans la console, sélectionnez Gemini Developer API ou Agent Platform Gemini API (anciennement Vertex AI).

   Notez que cette sélection ne s'applique qu'aux requêtes envoyées via l'expérience de test de la console Firebase. Dans la requête réelle de votre application, vous spécifiez le fournisseur Gemini API de votre choix, comme vous le feriez pour n'importe quelle requête.

4. Cliquez sur le bouton Créer une requête de test formatée.

   Examinez la requête de test mise en forme qui s'affiche à droite de l'écran, puis effectuez une itération sur l'un des champs de votre modèle.

   Développer pour afficher un exemple de requête de test formatée

   {
     "model": "projects/YOUR_PROJECT_ID/models/gemini-3.8-flash",
     "contents": [{
       "parts": [{
         "text": "Create an example customer invoice for a customer named Jane"
       }],
       "role": "user"
     }],
     "systemInstruction": {
       "parts": [{
         "text": "All output must be a clearly structured invoice document.\nUse a tabular or clearly delineated list format for line items."
       }]
     }
   }
   

5. Lorsque vous êtes satisfait de la requête de test formatée, cliquez sur le bouton Exécuter le test de prompt.

   Examinez la réponse de test obtenue à droite de l'écran, puis modifiez les champs de votre modèle si nécessaire.

   Développer pour afficher un exemple de réponse de test

   {
     "candidates": [{
       "content": {
         "parts": [{
           "text": "```\n--------------------------------------------------------------------------------\n                         **INVOICE**\n--------------------------------------------------------------------------------\n\n**Creative Solutions Inc.**\n123 Business Lane, Suite 100\nAnytown, USA 12345\nPhone: (555) 123-4567\nEmail: info@creativesolutions.com\n\n**INVOICE NO:** INV-2023-001\n**INVOICE DATE:** October 26, 2023\n**DUE DATE:** November 25, 2023\n\n**BILL TO:**\nJane\n456 Client Street, Apt 2B\nAnytown, USA 12346\nPhone: (555) 987-6543\nEmail: jane@example.com\n\n--------------------------------------------------------------------------------\n**ITEM DESCRIPTION**               **QTY**   **UNIT PRICE**   **AMOUNT**\n--------------------------------------------------------------------------------\nWebsite Design Services            1         $800.00          $800.00\nContent Creation (Blog Posts)      4         $120.00          $480.00\nMonthly Hosting \u0026 Maintenance      1         $50.00           $50.00\nConsultation Fee                   2         $75.00           $150.00\n--------------------------------------------------------------------------------\n\n**SUMMARY:**\nSubtotal:                                                     $1,480.00\nSales Tax (8%):                                               $118.40\n--------------------------------------------------------------------------------\n**TOTAL DUE:**                                                **$1,598.40**\n--------------------------------------------------------------------------------\n\n**PAYMENT TERMS:**\nPayment is due within 30 days of the invoice date. Please make checks payable to Creative Solutions Inc. For electronic payments, please contact us for details.\n\nThank you for your business!\n```"
         }],
         "role": "model"
       },
       "finishReason": "STOP",
       "index": 0
     }],
     "usageMetadata": {
       "promptTokenCount": 34,
       "candidatesTokenCount": 418,
       "totalTokenCount": 890,
       "promptTokensDetails": [{
         "modality": "TEXT",
         "tokenCount": 34
       }],
       "thoughtsTokenCount": 438
     },
     "modelVersion": "gemini-3.8-flash",
     "responseId": "3w4Vad6yF-y1vdIP_q_zgAw",
     "turnToken": "v1:ChczdzRWYWQ2eUYteTF2ZElQX3FfemdBdxIXM3c0VmFkNnlGLXkxdmRJUF9xX3pnQXc"
   }
   

6. Si vous êtes prêt à accéder au modèle à partir du code de votre application, verrouillez le modèle en cliquant sur l'icône lock Verrouiller en haut à droite du modèle.

7. Cliquez sur Fermer pour quitter l'interface de modification.

Étape 3 : Accédez à votre modèle à partir de votre code

Une requête utilisant un modèle de prompt côté serveur ressemble à d'autres requêtes, avec les ajustements suivants :

• Utilisez un templateGenerativeModel.
• Indiquez l'ID du modèle.
• Indiquez les valeurs des entrées de variables requises par votre modèle.

Notez qu'après avoir créé ou mis à jour votre modèle, vous devrez peut-être attendre quelques minutes qu'il se propage sur les serveurs Firebase avant d'y accéder depuis votre code.

// ...

// Initialize the Gemini Developer API backend service.
// Create a `TemplateGenerativeModel` instance.
let model = FirebaseAI.firebaseAI(backend: .googleAI()).templateGenerativeModel()

let customerName = "Jane"

do {
    let response = try await model.generateContent(
        // Specify your template ID
        templateID: "my-first-template-v1-0-0",
        // Provide the values for any input variables required by your template.
        inputs: [
            "customerName": customerName
        ]
    )
    if let text = response.text {
        print("Response Text: \(text)")
    }
} catch {
    print("An error occurred: \(error)")
}
print("\n")

// ...

// Initialize the Gemini Developer API backend service.
// Create a `TemplateGenerativeModel` instance.
val model = Firebase.ai(backend = GenerativeBackend.googleAI()).templateGenerativeModel()

val customerName = "Jane"

val response = model.generateContent(
    // Specify your template ID.
    "my-first-template-v1-0-0",
    // Provide the values for any input variables required by your template.
    mapOf(
        "customerName" to customerName
    )
)

val text = response.text
println(text)

// ...

// Initialize the Gemini Developer API backend service.
// Create a `TemplateGenerativeModel` instance.
TemplateGenerativeModel generativeModel = FirebaseAI.getInstance().templateGenerativeModel();

TemplateGenerativeModelFutures model = TemplateGenerativeModelFutures.from(generativeModel);

String customerName = "Jane";

Future response = model.generateContent(
    // Specify your template ID
    "my-first-template-v1-0-0",
    // Provide the values for any input variables required by your template.
    mapOf("customerName", customerName)
);
addCallback(response,
       new FutureCallback() {
           public void onSuccess(GenerateContentResponse result) {
             System.out.println(result.getText());
           }
           public void onFailure(Throwable t) {
             reportError(t);
           }
    }
executor);

// ...

// Initialize the Gemini Developer API backend service.
const ai = getAI(app, { backend: new GoogleAIBackend() });

// Create a `TemplateGenerativeModel` instance.
const model = getTemplateGenerativeModel(ai);

const customerName = 'Jane';

const result = await model.generateContent({
  // Specify your template ID.
  templateId: 'my-first-template-v1-0-0',
  // Provide the values for any input variables required by your template.
  templateVariables: {
    customerName: customerName,
  },
});

const response = result.response;
const text = response.text();

// ...

// Initialize the Gemini Developer API backend service.
// Create a `TemplateGenerativeModel` instance.
var _model = FirebaseAI.googleAI().templateGenerativeModel();

var customerName = 'Jane';

var response = await _model.generateContent(
        // Specify your template ID
        'my-first-template-v1-0-0',
        // Provide the values for any input variables required by your template.
        inputs: {
           'customerName': customerName,
        },
      );

var text = response?.text;
print(text);

// ...

// Initialize the Gemini Developer API backend service.
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.GoogleAI());

// Create a `TemplateGenerativeModel` instance.
var model = firebaseAI.GetTemplateGenerativeModel();

var customerName = "Jane";

try
{
   var response = await model.GenerateContentAsync(
      // Specify your template ID.
      "my-first-template-v1-0-0",
      // Provide the values for any input variables required by your template.
      new Dictionary<string, object> {
         { "customerName", customerName },
      }
   );
   Debug.Log($"Response Text: {response.Text}");
}
catch (Exception e) {
  Debug.LogError($"An error occurred: {e.Message}");
}

Étape suivante

• Découvrez les bonnes pratiques et considérations pour l'utilisation des modèles de prompts côté serveur.

• Découvrez plus en détail le format et la syntaxe des modèles, ainsi que des exemples.

• Découvrez comment gérer les modèles, y compris les modifier, les verrouiller et contrôler les versions.

• Découvrez les workflows avancés, par exemple l'utilisation de modèles de manière programmatique à l'aide de notre API REST ou le déploiement de vos modèles dans des emplacements spécifiques.