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, é possível enviar todas essas informações diretamente do seu código do cliente ou especificar essas informações no 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 no lado do servidor, e seu app passa 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 no 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 seu comando no lado do cliente

• Atualizar o comando e a configuração sem lançar uma nova versão do app

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

arrow_downward Ir para a visão geral de alto nível arrow_downward Ir para instruções detalhadas

Modelos e recursos compatíveis

• Use modelos de comandos do servidor com qualquer um dos modelos Gemini e Imagen que o Firebase AI Logic oferece suporte, exceto os modelos do Gemini Live.

• Consulte 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 solicitação do servidor:

1. Crie o modelo usando a interface guiada no console Firebase.

2. Teste o modelo em uma solicitação real usando a experiência de teste do console do Firebase.

3. Acesse o modelo no seu app.

Formato básico dos modelos de comandos do servidor

Para Firebase AI Logic, o console Firebase oferece uma interface guiada para 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 um exemplo de solicitação para um modelo Gemini:

---
model: 'gemini-2.5-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}}.

• A seção superior dentro dos 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. Ele é escrito como pares de chave-valor e é comumente chamado de frontmatter do YAML.

• O corpo do modelo contém o comando. Também é possível incluir instruções do sistema e valores de entrada (usando a sintaxe Handlebars).

Usar o modelo no código

Veja como usar o modelo no seu código:

// ...

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

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

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 tiver feito isso, conclua o guia de início, 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 solicitação do servidor. Por padrão, todas essas permissões estão incluídas na função 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ê usa o Vertex AI Gemini API e o se o caso de uso exigir restrições com base em local, oferecemos suporte a fluxos de trabalho avançados para modelos.

Etapa 1: criar um modelo de solicitação do servidor

Na maioria dos casos de uso, você cria e gerencia modelos de solicitação do servidor no console Firebase.

1. No console do Firebase, acesse a guia Modelos de comandos do Firebase AI Logic.

2. Clique em Criar 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, é possível mudar completamente o modelo para atender às suas necessidades, seja qual for a opção selecionada.

   • Este guia para iniciantes pressupõe que você selecionou a opção Input + System Instructions.

3. Insira os identificadores do modelo:

   • Nome do modelo: é o nome de exibição do modelo (por exemplo, My First Template). Ele só aparece nas interfaces do Firebase, como o console Firebase.

   • 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 referenciar esse ID na solicitação do seu app.

     • Recomendamos usar um sistema de controle de versões para seus IDs de modelo.

     • Os IDs de modelo podem ter até 63 caracteres e conter letras minúsculas, números e hifens.

4. Modifique a seção Configuração (frontmatter) do modelo, conforme necessário.

   • Esta seção precisa incluir pelo menos um nome de modelo, assim:

     ---
     model: 'gemini-2.5-flash'
     ---
     

   • Você também pode especificar a configuração do modelo e os controles de entrada e saída etc. Para mais detalhes e opções, consulte Formato, sintaxe e exemplos de modelo.

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

   • Você também pode 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 sintaxe {{role "system"}} e o comando de texto usando a sintaxe {{role "user"}}.

     • (Opcional) Especifique 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: teste seu modelo no console Firebase

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

1. Clique em Salvar modelo para testar o modelo.

   É possível editar ou excluir o modelo depois. O único valor que não pode ser mudado depois é o ID do modelo.

2. Se o comando usar variáveis de entrada, inclua valores de teste no campo Test input. Neste exemplo:

     {
       "customerName": "Jane"
     }
   

3. Se você tiver vários provedores Gemini API ativados no projeto do Firebase, escolha qual deles usar para a solicitação de teste. Se essa opção aparecer no console, selecione Gemini Developer API ou Vertex AI Gemini API.

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

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

   Analise o Pedido de teste formatado resultante no lado direito da tela e faça iterações em qualquer um dos campos do modelo.

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

   {
     "model": "projects/YOUR_PROJECT_ID/models/gemini-2.5-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. Quando estiver satisfeito com a solicitação de teste formatada, clique no botão Executar teste de comando.

   Analise a Resposta do teste resultante no lado direito da tela e faça iterações em qualquer um dos campos do modelo.

   Clique para abrir um exemplo de resposta do 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-2.5-flash",
     "responseId": "3w4Vad6yF-y1vdIP_q_zgAw",
     "turnToken": "v1:ChczdzRWYWQ2eUYteTF2ZElQX3FfemdBdxIXM3c0VmFkNnlGLXkxdmRJUF9xX3pnQXc"
   }
   

6. Se você quiser acessar o modelo no código do app, bloqueie o modelo clicando no ícone de bloqueio lock no canto superior direito do modelo.

7. Clique em Fechar para sair da experiência de edição.

Etapa 3: acessar o modelo no seu código

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).
• Informe o ID do modelo.
• Informe os valores de todas as entradas de variáveis necessárias para seu 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 ser acessado pelo código.

// ...

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

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

A seguir

• Saiba mais sobre práticas recomendadas e considerações para usar modelos de comandos do servidor.

• Saiba mais sobre o formato e a sintaxe do modelo, além de exemplos.

• Gerenciar modelos, incluindo edição, bloqueio e controle de versões.