Tutorial: Criar um chatbot com o Serviço de Aplicativo do Azure e o Azure OpenAI (Express.js)

2025-05-20

Neste tutorial, você criará um aplicativo de IA inteligente integrando o Azure OpenAI a um aplicativo Node.js e implantando-o no Serviço de Aplicativo do Azure. Você criará um aplicativo Express com um modo de exibição e um controlador que envia solicitações de conclusão de chat para um modelo no Azure OpneAI.

Captura de tela mostrando o chatbot em execução no Serviço de Aplicativo do Azure.

Neste tutorial, aprenderás como:

Crie um recurso do Azure OpenAI e implante um modelo de linguagem.
Crie um aplicativo Express.js que se conecta ao Azure OpenAI.
Implante o aplicativo no Serviço de Aplicativo do Azure.
Implemente a autenticação segura sem senha no ambiente de desenvolvimento e no Azure.

Pré-requisitos

Uma conta do Azure com uma subscrição ativa
Uma conta do GitHub para usar os Codespaces do GitHub

1. Criar um recurso do Azure OpenAI

Nesta seção, você usará o GitHub Codespaces para criar um recurso do Azure OpenAI com a CLI do Azure.

Vá para o GitHub Codespaces e faça login com sua conta do GitHub.
Encontre o modelo em branco do GitHub e selecione Usar este modelo para criar um novo espaço de código em branco.

No terminal do Codespace, instale o Azure CLI.

curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

Inicie sessão na sua conta do Azure:
```
az login
```
Siga as instruções no terminal para autenticar.
Defina variáveis de ambiente para o nome do grupo de recursos, o nome do serviço Azure OpenAI e a localização:
```
export RESOURCE_GROUP="<group-name>"
export OPENAI_SERVICE_NAME="<azure-openai-name>"
export APPSERVICE_NAME="<app-name>"
export LOCATION="eastus2"
```
Importante

A região é crítica, pois está ligada à disponibilidade regional do modelo escolhido. A disponibilidade do modelo e a disponibilidade do tipo de implantação variam de região para região. Este tutorial usa gpt-4o-mini, que está disponível no tipo de implantação Padrão de eastus2. Se você implantar em uma região diferente, esse modelo pode não estar disponível ou exigir uma camada diferente. Antes de alterar as regiões, consulte a tabela de resumo do modelo e a disponibilidade da região para verificar o suporte ao modelo na sua região preferida.

Crie um grupo de recursos e um recurso do Azure OpenAI com um domínio personalizado e, em seguida, adicione um modelo gpt-4o-mini:

# Resource group
az group create --name $RESOURCE_GROUP --location $LOCATION
# Azure OpenAI resource
az cognitiveservices account create \
  --name $OPENAI_SERVICE_NAME \
  --resource-group $RESOURCE_GROUP \
  --location $LOCATION \
  --custom-domain $OPENAI_SERVICE_NAME \
  --kind OpenAI \
  --sku s0
# gpt-4o-mini model
az cognitiveservices account deployment create \
  --name $OPENAI_SERVICE_NAME \
  --resource-group $RESOURCE_GROUP \
  --deployment-name gpt-4o-mini \
  --model-name gpt-4o-mini \
  --model-version 2024-07-18 \
  --model-format OpenAI \
  --sku-name Standard \
  --sku-capacity 1
# Cognitive Services OpenAI User role that lets the signed in Azure user to read models from Azure OpenAI
az role assignment create \
  --assignee $(az ad signed-in-user show --query id -o tsv) \
  --role "Cognitive Services OpenAI User" \
  --scope /subscriptions/$(az account show --query id -o tsv)/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.CognitiveServices/accounts/$OPENAI_SERVICE_NAME

Agora que você tem um recurso do Azure OpenAI, criará um aplicativo Web para interagir com ele.

2. Criar e configurar um aplicativo Web Express.js

No terminal do Codespace, crie um modelo de Express.js no espaço de trabalho e tente executá-lo pela primeira vez.
```
npx express-generator . --view ejs
npm audit fix --force
npm install && npm start
```
Você deve ver uma notificação no GitHub Codespaces indicando que o aplicativo está disponível em uma porta específica. Selecione Abrir no navegador para iniciar o aplicativo em uma nova guia do navegador.
De volta ao terminal Codespace, pare o aplicativo com Ctrl+C.
Instale as dependências do NPM para trabalhar com o Azure OpenAI:
```
npm install openai @azure/openai @azure/identity
```

Abra views/index.ejs e substitua-o pelo código a seguir, para uma interface de chat simples.

<!DOCTYPE html>
<html>
  <head>
    <title><%= title %></title>
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/css/bootstrap.min.css" rel="stylesheet">
  </head>
  <body class="bg-light">
    <div class="container py-4">
      <h1 class="mb-4"><%= title %></h1>
      <div class="card mb-3">
        <div class="card-body" style="min-height: 80px;">
          <form action="/chat" method="POST" class="d-flex gap-2 mb-3">
            <input type="text" name="message" class="form-control" placeholder="Type your message..." autocomplete="off" required />
            <button type="submit" class="btn btn-primary">Send</button>
          </form>
          <% if (aiMessage) { %>
            <div class="mb-2">
              <span class="fw-bold text-success">AI:</span>
              <span class="ms-2"><%= aiMessage %></span>
            </div>
          <% } %>
        </div>
      </div>
    </div>
  </body>
</html>

Abra rotas/index.js e substitua seu conteúdo pelo código a seguir, para uma chamada de conclusão de chat simples com o Azure OpenAI:

var express = require('express');
var router = express.Router();
const { AzureOpenAI } = require('openai');
const { getBearerTokenProvider, DefaultAzureCredential } = require('@azure/identity');

const endpoint = process.env.AZURE_OPENAI_ENDPOINT;
const deployment = 'gpt-4o-mini';
const apiVersion = '2024-10-21';

const credential = new DefaultAzureCredential();
const scope = 'https://cognitiveservices.azure.com/.default';
const azureADTokenProvider = getBearerTokenProvider(credential, scope);

// Initialize Azure OpenAI client using Microsoft Entra authentication
const openai = new AzureOpenAI({ endpoint, azureADTokenProvider, deployment, apiVersion });

router.get('/', function(req, res, next) {
  res.render('index', { title: 'Express Chat', aiMessage: null });
});

router.post('/chat', async function(req, res, next) {
  const userMessage = req.body.message;
  if (!userMessage) {
    return res.redirect('/');
  }
  let aiMessage = '';
  try {
    // Call Azure OpenAI chat completion
    const result = await openai.chat.completions.create({
      model: deployment,
      messages: [
        { role: 'system', content: 'You are a helpful assistant.' },
        { role: 'user', content: userMessage }
      ],
    });
    aiMessage = result.choices[0]?.message?.content || '';
  } catch (err) {
    aiMessage = 'Error: Unable to get response from Azure OpenAI.';
  }
  res.render('index', { title: 'Express Chat', aiMessage });
});

module.exports = router;

No terminal, recupere seu endpoint OpenAI:

az cognitiveservices account show \
  --name $OPENAI_SERVICE_NAME \
  --resource-group $RESOURCE_GROUP \
  --query properties.endpoint \
  --output tsv

Execute a aplicação novamente adicionando AZURE_OPENAI_ENDPOINT e o seu valor da saída da linha de comando.
```
AZURE_OPENAI_ENDPOINT=<output-from-previous-cli-command> npm start
```
Selecione Abrir no navegador para iniciar o aplicativo em uma nova guia do navegador. Envie uma pergunta e veja se você recebe uma mensagem de resposta.

3. Implantar no Serviço de Aplicativo do Azure e configurar a conexão OpenAI

Agora que seu aplicativo funciona localmente, vamos implantá-lo no Serviço de Aplicativo do Azure e configurar uma conexão de serviço com o Azure OpenAI usando a identidade gerenciada.

Primeiro, implante seu aplicativo no Serviço de Aplicativo do Azure usando o comando az webapp upCLI do Azure . Este comando cria um novo aplicativo Web e implanta seu código nele:
```
az webapp up \
  --resource-group $RESOURCE_GROUP \
  --location $LOCATION \
  --name $APPSERVICE_NAME \
  --plan $APPSERVICE_NAME \
  --sku B1 \
  --os-type Linux \
  --track-status false
```
Esse comando pode levar alguns minutos para ser concluído. Ele cria um novo aplicativo Web no mesmo grupo de recursos que seu recurso OpenAI.
Depois que o aplicativo for implantado, crie uma conexão de serviço entre seu aplicativo Web e o recurso OpenAI do Azure usando a identidade gerenciada:
```
az webapp connection create cognitiveservices \
  --resource-group $RESOURCE_GROUP \
  --name $APPSERVICE_NAME \
  --target-resource-group $RESOURCE_GROUP \
  --account $OPENAI_SERVICE_NAME \
  --connection azure-openai \
  --system-identity
```
Este comando cria uma conexão entre seu aplicativo Web e o recurso OpenAI do Azure ao:
- Geração de identidade gerenciada atribuída pelo sistema para o aplicativo Web.
- Adicionar a função de Colaborador OpenAI dos Serviços Cognitivos à identidade gerenciada para o recurso OpenAI do Azure.
- Adicionar a definição da AZURE_OPENAI_ENDPOINT aplicação à sua aplicação Web.
Abra o aplicativo Web implantado no navegador. Encontre a URL do aplicativo Web implantado na saída do terminal. Abra o navegador da Web e navegue até ele.
```
az webapp browse
```
Digite uma mensagem na caixa de texto e selecione "Enviar e dê ao aplicativo alguns segundos para responder com a mensagem do Azure OpenAI.

Seu aplicativo agora está implantado e conectado ao Azure OpenAI com identidade gerenciada.

Perguntas frequentes

E se eu quiser me conectar ao OpenAI em vez do Azure OpenAI?
Posso me conectar ao Azure OpenAI com uma chave de API?
Como funciona o DefaultAzureCredential neste tutorial?

E se eu quiser me conectar ao OpenAI em vez do Azure OpenAI?

Para se conectar ao OpenAI, use o seguinte código:

const { OpenAI } = require('openai');

const client = new OpenAI({
  apiKey: "<openai-api-key>",
});

Para obter mais informações, consulte Autenticação da API OpenAI.

Ao trabalhar com segredos de conexão no Serviço de Aplicativo, você deve usar referências do Cofre de Chaves em vez de armazenar segredos diretamente em sua base de código. Isso garante que as informações confidenciais permaneçam seguras e sejam gerenciadas centralmente.

Posso conectar-me ao Azure OpenAI com uma chave de API?

Sim, você pode se conectar ao Azure OpenAI usando uma chave de API em vez de identidade gerenciada. Para obter mais informações, consulte o início rápido do JavaScript do Azure OpenAI.

Como funciona o DefaultAzureCredential neste tutorial?

O DefaultAzureCredential simplifica a autenticação selecionando automaticamente o melhor método de autenticação disponível:

Durante o desenvolvimento local: após executar az login, são usadas as suas credenciais locais da CLI do Azure.
Quando implantado no Serviço de Aplicativo do Azure: ele usa a identidade gerenciada do aplicativo para autenticação segura e sem senha.

Essa abordagem permite que seu código seja executado de forma segura e transparente em ambientes locais e na nuvem, sem modificações.

Partilhar via