The latest Gemini models, like Gemini 3.1 Flash Image (Nano Banana 2), are available to use with Firebase AI Logic! Learn more.

Gemini 2.0 Flash and Flash-Lite models will shut down on June 1, 2026. To avoid service disruption, update to a newer model like gemini-2.5-flash-lite. Learn more.

All Imagen models will shut down on June 24, 2026. Learn about migrating your apps to use Nano Banana.

Começar a usar modelos de comandos do servidor

Em cada solicitação a um modelo, você envia um comando e, opcionalmente, um esquema e configurações para controlar a resposta do modelo. Ao usar Firebase AI Logic, você pode enviar todas essas informações diretamente do código do cliente ou especificar essas informações do lado do servidor usando modelos de comandos do servidor.

Ao usar modelos de comandos do servidor, você armazena o comando, o esquema e as configurações do lado do servidor, e seu app transmite do cliente para o servidor apenas a chave (o ID do modelo) que faz referência a um modelo específico, bem como as entradas necessárias para esse modelo.

Ao usar modelos de comandos do servidor, você armazena o comando e as configurações do lado do servidor e só fornece uma chave (o ID do modelo) na base de código do app. Confira alguns benefícios dessa abordagem:

Proteção contra a exposição do comando no lado do cliente
Atualização do comando e da configuração sem lançar uma nova versão do app

Este guia descreve como começar a usar modelos de comandos do servidor.

Ir para a visão geral detalhada Ir para instruções detalhadas

Modelos e recursos compatíveis

Use modelos de comandos do servidor com qualquer um dos Gemini e Imagen modelos com suporte da Firebase AI Logic, com exceção dos modelos Gemini Live.
Confira a lista de recursos que ainda não têm suporte.

Visão geral detalhada

Confira o fluxo de trabalho básico para usar modelos de comandos do servidor:

Crie o modelo usando a interface guiada no Firebase console.
Teste o modelo em uma solicitação real usando a experiência de teste do console Firebase.
Acesse o modelo no seu app.

Formato básico de modelos de comandos do servidor

Para Firebase AI Logic, o console Firebase oferece uma interface guiada para você especificar o conteúdo de um 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.

Confira os componentes mais importantes de uma solicitação de exemplo para um Gemini modelo:

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

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

A seção superior entre os três traços contém o nome do modelo e, opcionalmente, qualquer configuração, validação de entrada ou esquema que você queira enviar na solicitação. Ela é escrita como pares de chave-valor e é comumente chamada de frontmatter YAML.
O corpo do modelo contém o comando. Ele também pode incluir instruções do sistema e valores de entrada (usando a sintaxe Handlebars).

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.

Saiba como usar o modelo no código:

Swift


// ...

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

Kotlin


// ...

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

Java


// ...

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

Web


// ...

// 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
  'my-first-template-v1-0-0',
  // Provide the values for any input variables required by your template
  {
    customerName: customerName,
  }
);

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

Dart


// ...

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

Unity


// ...

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

Instruções detalhadas

Esta seção fornece instruções detalhadas para criar, testar e usar modelos de comandos do servidor.

Antes de começar

Se ainda não fez isso, conclua o guia de iniciação, que descreve como configurar seu projeto do Firebase, conectar seu app ao Firebase, adicionar o SDK, inicializar o serviço de back-end para o provedor Gemini API escolhido e criar uma instância GenerativeModel.
Verifique se você tem as permissões necessárias para criar e gerenciar modelos de comandos do servidor. Por padrão, todas essas permissões estão incluídas no papel de proprietário.
Ver as permissões necessárias
- 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
Se você usar o Vertex AI Gemini API e se o caso de uso exigir restrições baseadas em local, vamos oferecer suporte a fluxos de trabalho avançados para modelos.

Etapa 1: criar um modelo de comando do servidor

Para a maioria dos casos de uso, você cria e gerencia modelos de comandos do servidor no Firebase console.

No Firebase console, acesse a guia Firebase AI Logic Modelos de comandos.
Clique em Criar novo modelo e selecione uma opção de modelo inicial.
- Esses modelos iniciais fornecem o formato e a sintaxe para alguns casos de uso comuns. No entanto, não importa qual opção você selecione, é possível mudar completamente o modelo para atender às suas necessidades.
- Este guia de iniciação considera que você selecionou a opção Input + System Instructions.
Insira os identificadores do modelo:
- Nome do modelo: é um nome de exibição para o modelo (por exemplo, My First Template). Ele só aparece nas interfaces do Firebase, como o Firebase console.
- ID do modelo: precisa ser um ID exclusivo do modelo no seu projeto do Firebase (por exemplo, my-first-template-v1-0-0). Você vai fazer referência a este ID na solicitação do seu app.
  - Recomendamos o uso de um sistema de controle de versões para os IDs de modelo.
  - Os IDs de modelo podem ter no máximo 63 caracteres e podem conter letras minúsculas, números e hifens.
Modifique a seção Configuração (frontmatter) do modelo, conforme necessário.
- Essa seção precisa incluir pelo menos um nome de modelo, como este:
```
---
model: 'gemini-3-flash-preview'
---
```
- Também é possível especificar a configuração do modelo e os controles de entrada & saída etc. Para mais detalhes e opções, consulte Formato, sintaxe e exemplos de modelos.
Modifique a seção Comando e instruções do sistema (conforme aplicável) do modelo, conforme necessário.
- Essa seção precisa incluir pelo menos o comando de texto a ser enviado ao modelo.
```
Write a story about a magic backpack.
```
- Também é possível criar comandos mais complexos, como as opções a seguir. Para mais detalhes e opções, consulte Formato, sintaxe e exemplos de modelos.
  - (Opcional e conforme aplicável) Especifique as instruções do sistema usando a {{role "system"}} sintaxe e o comando de texto usando a {{role "user"}} sintaxe.
  - (Opcional) Especifique as variáveis de entrada usando a sintaxe Handlebars (como {{customerName}}). É possível fornecer um valor padrão no modelo, mas o valor dessa variável de entrada geralmente é transmitido na solicitação.
```
{{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}}.
```

Etapa 2: testar o modelo no console Firebase

O console Firebase oferece uma experiência de teste para o modelo. Essa experiência permite que você veja o que vai acontecer quando o modelo for usado: o formato da solicitação e a saída de uma solicitação real.

Clique em Salvar modelo para testar o modelo.

Você sempre pode editar ou até mesmo excluir o modelo mais tarde. O único valor que não pode ser mudado mais tarde é o ID do modelo.
Se o comando usar variáveis de entrada, inclua valores de teste no campo Entrada de teste. Para este exemplo:
```
  {
    "customerName": "Jane"
  }
```
Se você tiver vários Gemini API provedores ativados no projeto do Firebase, poderá escolher qual deles usar para a solicitação de teste. Se essa opção for exibida no console, selecione Gemini Developer API ou Vertex AI Gemini API.

Essa seleção só se aplica a solicitações enviadas pela Firebase experiência de teste do console. Na solicitação real do seu app, você especifica o provedor Gemini API escolhido da mesma forma que faria para qualquer solicitação.

Clique no botão Criar solicitação de teste formatada.

Analise a solicitação de teste formatada resultante no lado direito da tela e itere em qualquer um dos campos do modelo.

Clique para abrir o exemplo de solicitação de teste formatada

{
  "model": "projects/YOUR_PROJECT_ID/models/gemini-3-flash-preview",
  "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."
    }]
  }
}

Quando estiver tudo certo com a solicitação de teste formatada, clique no botão Executar teste de comando.

Analise a resposta de teste resultante no lado direito da tela e itere em qualquer um dos campos do modelo.

Clique para abrir o exemplo de resposta de teste

{
  "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-flash-preview",
  "responseId": "3w4Vad6yF-y1vdIP_q_zgAw",
  "turnToken": "v1:ChczdzRWYWQ2eUYteTF2ZElQX3FfemdBdxIXM3c0VmFkNnlGLXkxdmRJUF9xX3pnQXc"
}

Se você estiver pronto para acessar o modelo no código do app, bloqueie-o clicando no ícone de cadeado no canto superior direito do modelo.
Clique em Fechar para sair da experiência de edição.

Etapa 3: acessar 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.

Uma solicitação que usa um modelo de comando do servidor é semelhante a outras solicitações, com os seguintes ajustes:

Use um templateGenerativeModel (ou templateImagenModel, conforme necessário).
Forneça o ID do modelo.
Forneça os valores de todas as entradas de variáveis exigidas pelo modelo.

Depois de criar ou atualizar o modelo, talvez seja necessário aguardar alguns minutos para que ele seja propagado nos servidores do Firebase antes de acessá-lo no código.