Começar a usar modelos de comandos do servidor

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

Ao usar modelos de comandos do lado do servidor, você armazena o comando, o esquema e as configurações no lado do servidor, e a base de código do app transmite do cliente para o servidor apenas uma chave (o ID do modelo) que faz referência a um modelo específico, além das entradas necessárias para esse modelo. Veja alguns benefícios dessa abordagem:

• Proteja-se contra a exposição do comando no lado do cliente

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

Neste guia, descrevemos como começar a usar modelos de comando do servidor.

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

Modelos e recursos compatíveis

• Use modelos de comando do servidor com qualquer um dos modelos do Gemini compatíveis com o Firebase AI Logic, exceto os modelos do Gemini Live API.

• Confira a lista de recursos que ainda não são compatíveis.

Visão geral detalhada

Este é o fluxo de trabalho básico para usar modelos de comando do servidor:

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

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

3. Acesse o modelo no código do app usando templateGenerativeModel.

Formato básico de um modelo de comando do servidor

Para Firebase AI Logic, o console do Firebase oferece uma interface guiada para você especificar o frontmatter e o conteúdo do modelo.

Os modelos de comando 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 para um exemplo de solicitação para um modelo 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}}.

• A seção superior dentro dos traços triplos contém o nome do modelo e, opcionalmente, qualquer configuração de modelo, 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 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

O exemplo de código do cliente abaixo mostra 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.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}");
}

Instruções detalhadas

Nesta seção, você encontra instruções detalhadas para criar, testar e usar modelos de comando do servidor.

Antes de começar

• Se você 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 de GenerativeModel.

• Verifique se você tem as permissões necessárias para criar e gerenciar modelos de comando 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
  • firebasevertexai.googleapis.com/promptTemplates.updateLock

• Se você usar o Agent Platform Gemini API (formerly Vertex AI) e se o caso de uso exigir restrições baseadas em localização, oferecemos suporte a fluxos de trabalho avançados para modelos.

Etapa 1: criar um modelo de comando do servidor

Na maioria dos casos de uso, você cria e gerencia modelos de comando do servidor no console do Firebase.

1. No console do Firebase, acesse Serviços de IA > Lógica de IA > guia Modelos de comando.

2. 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 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 do 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 os IDs de modelo.

     • Os IDs de modelo podem ter no máximo 63 caracteres e conter letras minúsculas, números e hifens.

4. 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.8-flash'
     ---
     

   • Também é possível 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 modelos.

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 que 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 sintaxe {{role "system"}} e o comando de texto usando a sintaxe {{role "user"}}.

     • (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 do Firebase

O console do Firebase oferece uma experiência de teste para seu modelo. Essa experiência permite que você veja o que vai acontecer quando o 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.

   Você pode editar ou até mesmo excluir o modelo mais tarde. O único valor que não pode ser alterado posteriormente é o ID do modelo.

2. Se o comando usar variáveis de entrada, inclua valores de teste no campo Entrada de teste. Para este exemplo:

     {
       "customerName": "Jane"
     }
   

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

   Essa seleção se aplica apenas às solicitações enviadas pela experiência de teste do console do Firebase. Na solicitação real do app, especifique o provedor do Gemini API escolhido, como faria para qualquer solicitação.

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

   Revise a Solicitação de teste formatada resultante no lado direito da tela e faça iterações 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.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. Quando estiver tudo certo 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 itera em qualquer um dos campos do modelo.

   Clique para abrir o 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-3.8-flash",
     "responseId": "3w4Vad6yF-y1vdIP_q_zgAw",
     "turnToken": "v1:ChczdzRWYWQ2eUYteTF2ZElQX3FfemdBdxIXM3c0VmFkNnlGLXkxdmRJUF9xX3pnQXc"
   }
   

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

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

Etapa 3: acessar o modelo pelo código

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

• Use um templateGenerativeModel.
• Informe o ID do modelo.
• Informe 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 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.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}");
}

A seguir

• Aprenda mais sobre as 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.

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

• Aprenda mais sobre fluxos de trabalho avançados, como trabalhar com modelos de forma programática usando nossa API REST ou implantar seus modelos em locais específicos.