Capítulo 4: Serviços Auxiliares e Persistência de Dados

4.3 Chatbot com OCI Language

4.3.1 O que é um Chatbot?

Um Chatbot, também conhecido como Assistente Virtual Inteligente (AVI), é um programa de computador projetado para interagir e auxiliar os clientes de uma empresa. Ele é desenvolvido para interpretar a linguagem natural, possibilitando simular uma conversa humana com os usuários por meio de interfaces de chat. Essas interfaces podem ser integradas de diversas maneiras, como em páginas da web, assistentes de voz como a Amazon Alexa, ou em aplicativos de mensagens, incluindo WhatsApp, Telegram, Facebook ou Instagram Messenger.

Uma vez que o chatbot pode interpretar e "entender" linguagem natural, ou seja, a linguagem que os humanos utilizam no dia a dia, ele pode ser programado, por exemplo, para realizar ações como fornecer informações sobre produtos e serviços e manter diálogos complexos com os usuários.

No caso da aplicação OCI PIZZA, o chatbot tem a função de auxiliar os clientes da pizzaria em diversas questões, como:

• Fazer pedidos de pizza
• Verificar o andamento de um pedido já realizado
• Cancelar um pedido
• Consultar o cardápio e preços
• Verificar a viabilidade de entrega no endereço solicitado

Para compreender melhor o funcionamento de um chatbot, seus conceitos e como ele pode ser desenvolvido, é necessário entender como as máquinas interpretam palavras, frases e expressões por meio do Processamento de Linguagem Natural, tema que será abordado a seguir.

4.3.2 Processamento de Linguagem Natural (PLN)

Um computador é uma máquina projetada para processar números, o que significa que ele não consegue interpretar ou processar letras, palavras ou textos nativamente. Em outras palavras, o computador não consegue, por conta própria, compreender a linguagem humana.

Por exemplo, como fazer com que o computador compreenda a ação presente em uma frase que solicita a entrega de uma pizza para um determinado endereço?

No contexto de uma pizzaria, é possível desenvolver um código que verifique que qualquer texto que siga as palavras "Rua" ou "Avenida", tem alta probabilidade de indicar uma solicitação para entrega de pizza em um endereço específico.

Dessa forma, conseguimos reduzir a ambiguidade e os limites de interpretação, considerando que a palavra "Aparecida" faz referência exclusiva a uma "Rua" ou "Avenida", e não a uma cidade ou a um verbo.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

#!/usr/bin/env python3

import re

def verifica_entrega(localidade: str):
    print('Localidade Encontrada!')

frase = 'É possível entregar uma pizza grande na Rua Aparecida n123?'

# Retorna a string rua ou avenida, se presentes na frase.
palavra_chave = ', '.join(re.findall(r'\b(rua|avenida)\b', frase, re.IGNORECASE)).lower()

if palavra_chave:
    # Encontra a posição numérica da palavra chave na frase (rua ou avenida).
    posicao = frase.lower().index(palavra_chave)

    # Extrai o texto após a palavra chave. O resultado será "Rua Aparecida n123?".
    texto_apos_palvra_chave = frase[posicao + len(palavra_chave):].strip()

    # Remove todos os caracteres especiais. O resultado será "Rua Aparecida n123".
    localidade = re.sub(r'[^\w\s]', '', texto_apos_palvra_chave)

    # Chama uma função para verificar se é possível entregar uma pizza
    # no endereço solicitado.
    verifica_entrega(localidade)

else:
    print('Desculpe, não consegui entender ou não é possível entregar no endereço solicitado.')

Os primeiros chatbots eram capazes de fornecer respostas para prompts específicos. Foram programados de maneira semelhante, baseando-se na extração de palavras-chave dos textos para verificar se havia uma resposta ou ação pré-programada.

No entanto, com o tempo, novas possibilidades de diálogo surgem, exigindo mais código e estruturas if...else para executar ações de correspondência. Com mais código, aumentam as chances de bugs e, ao interpretar a linguagem humana, a probabilidade de erros de interpretação também cresce.

Determinar o número de palavras utilizadas na linguagem natural é uma tarefa quase impossível. O vocabulário da linguagem natural cresce constantemente a cada ano e, por exemplo, difere de uma linguagem de programação, onde existe um conjunto fixo de palavras reservadas que são usadas para especificar ações exatas (if, then, else, elif, except, while, continue, def, class, entre outras).

Na linguagem humana, por outro lado, as palavras podem ter múltiplos significados (duplo sentido), especialmente quando escritas em frases diferentes. Para compreender o significado de uma frase, é necessário analisar o contexto como um todo, e não apenas palavra por palavra. Tentar processar cada palavra individualmente pode não fazer sentido e pode levar a erros de interpretação.

Nesse cenário, imagine desenvolver um chatbot que possa interpretar contextos mais amplos, além do ambiente de uma pizzaria. Nesse caso, a palavra "Aparecida", do exemplo anterior, pode ter diversos significados, como:

1. Nome próprio feminino comum no Brasil.
2. Pode se referir a uma localidade, como a cidade de Aparecida do Norte.
3. Nossa Senhora Aparecida padroeira do Brasil.
4. Verbo "aparecer", significando que algo ou alguém tornou-se visível.

Não se programam regras gramaticais. Em vez disso, são desenvolvidos modelos estatísticos que permitem identificar as probabilidades entre as palavras de um texto. Isso torna o processo muito mais assertivo ao programar algo capaz de "entender" e "responder" em linguagem humana, sem recorrer a um monte de if...else.

Para superar as limitações que levam a erros de interpretação ao processar a linguagem humana, é necessário converter esses textos em representações numéricas por meio de um conjunto de técnicas conhecidas como Processamento de Linguagem Natural.

Processamento de Linguagem Natural (PLN), ou em inglês, Natural Language Processing (NLP), é uma subárea da Inteligência Artificial (IA) voltada para o processamento e análise de dados em linguagem natural.

Aplicações que utilizam técnicas de Processamento de Linguagem Natural podem "entender" sentenças faladas e escritas por humanos, ou seja, em linguagem natural. Elas são capazes de gerar respostas úteis e manter diálogos complexos.

A seguir, examinaremos como o serviço OCI Language pode ajudar nas questões que envolvem o Processamento de Linguagem Natural.

4.3.3 Introdução ao OCI Language

Language é um serviço de Processamento de Linguagem Natural (NLP) oferecido pelo OCI no qual permite os desenvolvedores processar, analisar e extrair informações importantes a partir de textos não estruturados.

O Language disponibiliza, através de sua API REST, as seguintes funcionalidades para o processamento de textos:

• Detecção de Idioma

  • Identifica o idioma do texto fornecido, apresentando uma pontuação de confiança associada.

• Classificação de Texto

  • Determina a categoria e subcategoria à qual o texto pertence.

• Reconhecimento de Entidade Nomeada

  • Identifica nomes de pessoas, lugares, organizações e outras entidades relevantes.

• Extração de Palavras-Chave

  • Extrai um conjunto significativo de frases de um bloco de texto.

• Análise de Sentimentos

  • Classifica o texto como positivo, negativo ou neutro.

• Tradução de Texto

  • Traduz o texto para o idioma desejado.

• Informações de Identificação Pessoal

  • Identifica, classifica e anonimiza informações sensíveis em textos.

Algumas das funcionalidades já estão disponíveis para uso imediato, utilizando modelos pré-treinados pela Oracle. Esses modelos são treinados com um conjunto abrangente de dados genéricos, que, em muitos casos, podem não atender a contextos específicos de certas aplicações.

Para superar essa limitação, é possível desenvolver e treinar modelos utilizando dados específicos do seu negócio. O primeiro passo nesse processo é a criação de um projeto, seguido pela preparação dos dados de treinamento. Após essa etapa, os dados devem ser enviados para um bucket no OCI. Em seguida, pode-se realizar o treinamento do modelo e, por fim, executar testes para validar a eficácia do modelo após o treinamento.

Projeto

Um projeto serve basicamente como um meio ou contêiner para organizar tarefas relacionadas ao Processamento de Linguagem Natural para processar dados específicos do seu contexto de negócio.

A aplicação chatbot do OCI PIZZA utiliza um projeto localizado nas regiões sa-saopaulo-1 e sa-vinhedo-1, dentro da estrutura de compartimento cmp-prd:cmp-appl, denominado chatbot-project.

Para criar o projeto na região sa-saopaulo-1 dentro da estrutura de compartimento cmp-prd:cmp-appl, utilize o seguinte comando:

1
2
3
4
5
6

$ oci ai language project create \
> --region "sa-saopaulo-1" \
> --compartment-id "ocid1.compartment.oc1..aaaaaaaaaaaaaaaabbbbbbbbccc" \
> --display-name "chatbot-project" \
> --description "Projeto OCI Language para Chatbot da região \"sa-saopaulo-1\"." \
> --wait-for-state "SUCCEEDED"

Dados de Treinamento

Algo que o OCI Language não faz sozinho é identificar qual é a intenção do usuário. No contexto do chatbot, essa é uma das tarefas mais primordiais que ele deve desempenhar.

O termo "intenção" é frequentemente utilizado no contexto de chatbots para descrever o processo de identificar, a partir de uma sentença ou texto, o que um usuário deseja. Uma vez que a intenção foi corretamente identificada, o chatbot pode executar determinadas ações, como, por exemplo, invocar uma função que consulta um banco de dados para fornecer uma resposta.

Para que o OCI Language possa identificar corretamente a intenção do usuário, é necessário treiná-lo com um conjunto de dados específico, comumente chamado de Dados de Treinamento (dataset).

Neste caso, os dados de treinamento consistem em um conjunto de sentenças comuns, frequentemente utilizadas por usuários de uma pizzaria, como por exemplo:

Quanto maior e mais diversificado for o número de sentenças de exemplo, mais assertivo e preciso será o OCI Language na identificação das intenções dos usuários.

No diretório "scripts/capitulo-4/data" do repositório de códigos da aplicação OCI PIZZA, há dois arquivos que contêm sentenças de exemplo de interações típicas de usuários da pizzaria. São eles:

• chatbot-train-intents.csv

  • Arquivo que contém exemplos de sentenças que são utilizados no processo de treinamento.

• chatbot-test-intents.csv

  • Arquivo que contém exemplos de sentenças que são utilizados exclusivamente para testes.

Classificação de Texto

Classificação de Texto é uma técnica de aprendizagem supervisionada que usa dados previamente rotulados.

O OCI Language possui a funcionalidade para realizar a Classificação de Texto, a qual retorna uma string específica — ou, nos termos do OCI Language, um label ou categoria — com base em uma sentença ou texto de entrada.

Essa funcionalidade é extremamente útil em aplicações de chatbot, pois o objetivo é, a partir da sentença do usuário, retornar uma string que identifique uma intenção. Essa intenção pode ser então avaliada pela lógica da aplicação para gerar uma resposta apropriada.

Para tarefas de Classificação de Texto, o arquivo que contém os dados de treinamento a serem enviados ao OCI Language deve seguir a seguinte estrutura:

1
2
3
4
5
6

$ head -5 capitulo-4/data/chatbot-train-intents.csv
text,labels
"Errei o pedido, cancela por favor",cancelar_pedido
Gostaria de pedir uma pizza grande muçarela por favor,fazer_pedido
"Boa noite, obrigado",despedida
"Olá, gostaria de fazer um pedido",ver_cardapio

Alguns detalhes que devem ser levados em consideração ao criar um arquivo para Classificação de Texto que são:

• text,labels

  • É obrigatório que a primeira linha do arquivo contenha as palavras text e labels, separadas por vírgula. Caso contrário, o processo de treinamento falhará.

• text

  • O texto das sentenças é de livre escolha e pode incluir letras maiúsculas, minúsculas, acentos e caracteres especiais. Como regra geral, se a sentença contiver uma vírgula, toda ela deve estar entre aspas duplas ("texto, com, vírgula"), caso contrário, o processo de treinamento falhará.

• labels

  • String que identifica a intenção com base na sentença contida na coluna text. O identificador de intenção pode ser multilabel e se este for o caso, deve seguir o formato label_1|label_2|....

O conjunto de intenções que o chatbot do OCI PIZZA processa incluem:

• saudacao
• fazer_pedido
• ver_cardapio
• confirmar_pedido
• cancelar_pedido
• agradecimento

Treinamento

Uma vez que existem dados previamente classificados, é possível iniciar a etapa de treinamento, que resulta na criação do que chamamos de modelo de Inteligência Artificial, ou simplesmente, modelo.

De forma simplificada, um modelo pode ser comparado a um banco de dados que contém probabilidades. Ele é o resultado matemático do processo de treinamento, onde "treinar" significa "alimentar" algoritmos de Inteligência Artificial com uma grande quantidade de dados. Isso possibilita a criação de um modelo capaz de fazer previsões ou classificações sobre conjuntos de dados ainda não vistos. Em outras palavras, o modelo resultante do treinamento é habilitado para realizar previsões.

Para treinar um modelo no OCI Language voltado para tarefas de Classificação de Texto, é necessário, primeiramente, enviar os arquivos chatbot-train-intents.csv e chatbot-test-intents.csv para o Object Storage. Isso irá permitir que o OCI Language acesse esses dados e, a partir daí, crie, treine e teste o modelo que será utilizado pelo chatbot da aplicação OCI PIZZA.

O comando abaixo cria um bucket privado chamado chatbot-data na região sa-saopaulo-1, dentro da estrutura de compartimento cmp-prd:cmp-appl, que será utilizado para o upload e armazenamento dos arquivos chatbot-train-intents.csv e chatbot-test-intents.csv:

1
2
3
4
5

$ oci os bucket create \
> --region "sa-saopaulo-1" \
> --compartment-id "ocid1.compartment.oc1..aaaaaaaaaaaaaaaabbbbbbbbccc" \
> --name "chatbot-data" \
> --public-access-type "NoPublicAccess"

Após a criação do bucket, é o momento de enviar os arquivos utilizando os comandos abaixo:

1
2
3
4
5
6
7

$ oci os object put \
> --region "sa-saopaulo-1" \
> --bucket-name "chatbot-data" \
> --file "data/chatbot-train-intents.csv" \
> --content-type "text/csv" \
> --verify-checksum \
> --force

1
2
3
4
5
6
7

$ oci os object put \
> --region "sa-saopaulo-1" \
> --bucket-name "chatbot-data" \
> --file "data/chatbot-test-intents.csv" \
> --content-type "text/csv" \
> --verify-checksum \
> --force

Como última tarefa relacionada à disponibilização dos dados para treinamento, é necessário conceder acesso ao bucket chatbot-data ao OCI Language. Esse acesso é concedido pela criação de um Grupo Dinâmico e uma Política IAM.

Para criar o Grupo Dinâmico que faz referência ao serviço OCI Language e à Política IAM, utilize os comandos abaixo:

1
2
3
4
5
6

$ oci iam dynamic-group create \
> --compartment-id "ocid1.tenancy.oc1..aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
> --name "language-dyngrp" \
> --description "Grupo dinâmico para o serviço OCI Language." \
> --matching-rule "ALL {resource.type='ailanguagemodel'}" \
> --wait-for-state "ACTIVE"

1
2
3
4
5
6

$ oci iam policy create \
> --compartment-id "ocid1.tenancy.oc1..aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
> --name "language-policy" \
> --description "Políticas de Acesso para o Grupo Dinâmico \"language-dyngrp\" acessar os objetos do bucket \"chatbot-data\"." \
> --statements '["Allow dynamic-group language-dyngrp to manage objects in tenancy where target.bucket.name='chatbot-data'"]' \
> --wait-for-state "ACTIVE"

Com os dados prontos, disponibilizados e o acesso concedido, chega o momento de treinar o modelo. Porém, antes disso, serão necessárias duas informações: o OCID do projeto recém-criado e o namespace do Object Storage. Ambas as informações serão utilizadas como parte do comando usado para treinar o modelo.

O comando abaixo retorna o namespace do Object Storage:

1
2
3
4

$ oci os ns get
{
  "data": "WYYdXX82dnaS"
}

Já o comando abaixo retorna o OCID do projeto de Classificação de Texto recém-criado:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

$ oci ai language project list \
> --region "sa-saopaulo-1" \
> --compartment-id "ocid1.compartment.oc1..aaaaaaaaaaaaaaaabbbbbbbbccc" \
> --display-name "chatbot-project" \
> --lifecycle-state "ACTIVE" \
> --all \
> --query "data.items[].id"
[
  "ocid1.ailanguageproject.oc1.sa-saopaulo-1.abcdefghai"
]

Com as informações à disposição, é possível criar e treinar o modelo de Classificação de Texto dentro da estrutura do compartimento cmp-prd:cmp-appl, na região sa-saopaulo-1, utilizando o comando abaixo:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

$ oci ai language model create \
> --region "sa-saopaulo-1" \
> --compartment-id "ocid1.compartment.oc1..aaaaaaaaaaaaaaaabbbbbbbbccc" \
> --project-id "ocid1.ailanguageproject.oc1.sa-saopaulo-1.abcdefghai" \
> --display-name "model-text-classification" \
> --description "Modelo para Classificação de Texto." \
> --model-details "{
>    \"modelType\": \"TEXT_CLASSIFICATION\",
>    \"languageCode\": \"en\",
>    \"version\": \"V1.0\",
>    \"classificationMode\": { 
>        \"classificationMode\": \"MULTI_CLASS\" 
>    }
> }" \
> --training-dataset "{
>    \"locationDetails\": {
>        \"locationType\": \"OBJECT_LIST\",
>        \"bucketName\": \"chatbot-data\",
>        \"namespaceName\": \"WYYdXX82dnaS\",
>        \"objectNames\": [\"chatbot-train-intents.csv\"]
>    },
>    \"datasetType\": \"OBJECT_STORAGE\"
> }" \
> --test-strategy "{
>    \"testingDataset\": {
>        \"locationDetails\": {
>             \"locationType\": \"OBJECT_LIST\",
>             \"bucketName\": \"chatbot-data\",
>             \"namespaceName\": \"WYYdXX82dnaS\",
>             \"objectNames\": [\"chatbot-test-intents.csv\"]
>        },
>        \"datasetType\": \"OBJECT_STORAGE\"
>   },
>   \"strategyType\": \"TEST_AND_VALIDATION_DATASET\"
> }" \
> --wait-for-state "ACCEPTED"

Acompanhando o Processo de Treinamento

Todo o processo de treinamento e testes pode levar algum tempo para ser concluído. É possível acompanhar o progresso consultando o Work Request relacionado à criação do modelo.

Para consultar o Work Request, é necessário, primeiramente, obter o OCID do modelo de Classificação de Texto que foi submetido para criação, utilizando o comando abaixo:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

$ oci ai language model list \
> --region "sa-saopaulo-1" \
> --compartment-id "ocid1.compartment.oc1..aaaaaaaaaaaaaaaabbbbbbbbccc" \
> --display-name "model-text-classification" \
> --lifecycle-state "CREATING" \
> --all \
> --query 'data.items[].id'
[
  "ocid1.ailanguagemodel.oc1.sa-saopaulo-1.abcdefghaikkkk"
]

Com o OCID do modelo, é possível listar e obter os OCIDs correspondentes aos Work Request utilizando o seguinte comando:

1
2
3
4
5
6
7
8
9

$ oci ai language work-request list \
> --region "sa-saopaulo-1" \
> --compartment-id "ocid1.compartment.oc1..aaaaaaaaaaaaaaaabbbbbbbbccc" \
> --resource-id "ocid1.ailanguagemodel.oc1.sa-saopaulo-1.abcdefghaikkkk" \
> --all \
> --query 'data.items[].id'
[
  "ocid1.ailanguageworkrequest.oc1..yubvgsjalsoiauxnah"
]

Por fim, utiliza-se o OCID do Work Request para exibir as mensagens relacionadas ao processo de treinamento com o seguinte comando:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

$ oci ai language work-request log list \
> --region "sa-saopaulo-1" \
> --work-request-id "ocid1.ailanguageworkrequest.oc1..yubvgsjalsoiauxnah" \
> --all \
> --query "data.items[].{log:message,hora:timestamp}" \
> --output table
+----------------------------------+------------------------------------------+
| hora                             | log                                      |
+----------------------------------+------------------------------------------+
| 2025-11-16T12:51:07.152000+00:00 | Model Training execution In Progress     |
| 2025-11-16T12:51:06.889000+00:00 | Model Training initiation In Progress    |
| 2025-11-16T12:51:05.731000+00:00 | Preparing data for training and testing. |
| 2025-11-16T12:51:04.842000+00:00 | Successfully started model creation.     |
| 2025-11-16T12:51:04.150000+00:00 | Starting model creation.                 |
+----------------------------------+------------------------------------------+

Endpoint

Para utilizar o modelo treinado, é necessário criar um endpoint, o que pode ser feito com o comando abaixo:

1
2
3
4
5
6
7

$ oci ai language endpoint create \
> --region "sa-saopaulo-1" \
> --compartment-id "ocid1.compartment.oc1..aaaaaaaaaaaaaaaabbbbbbbbccc" \
> --model-id "ocid1.ailanguagemodel.oc1.sa-saopaulo-1.abcdefghaikkkk" \
> --display-name "endpoint-chatbot-text-classification" \
> --description "Endpoint para Acesso ao Modelo de Classificação de Texto." \
> --wait-for-state "SUCCEEDED"

Testando o Modelo

Com o endpoint criado, é possível testar o modelo para verificar se, ao processar novos dados, o modelo treinado consegue de fato classificar corretamente a intenção.

Antes de testar o modelo com novos dados, é necessário obter o OCID do endpoint recém-criado. Isso pode ser feito utilizando o comando a seguir:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

$ oci ai language endpoint list \
> --region "sa-saopaulo-1" \
> --compartment-id "ocid1.compartment.oc1..aaaaaaaaaaaaaaaabbbbbbbbccc" \
> --display-name "endpoint-chatbot-text-classification" \
> --lifecycle-state "ACTIVE" \
> --all \
> --query 'data.items[].id'
[
  "ocid1.ailanguageendpoint.oc1.sa-saopaulo-1.amaaaaaa7bbbbbbbbbb"
]

Com o OCID do endpoint, é possível submeter um texto ao modelo utilizando o comando abaixo:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

$ oci ai language batch-detect-text-classification \
> --region "sa-saopaulo-1" \
> --compartment-id "ocid1.compartment.oc1..aaaaaaaaaaaaaaaabbbbbbbbccc" \
> --endpoint-id "ocid1.ailanguageendpoint.oc1.sa-saopaulo-1.amaaaaaa7bbbbbbbbbb" \
> --documents '[{"key": "1", "text": "Vocês tem pizza de abobrinha?"}]"
{
  "data": {
    "documents": [
      {
        "key": "1",
        "language-code": "en",
        "text-classification": [
          {
            "label": "ver_cardapio",
            "score": 0.47043633460998535
          }
        ]
      }
    ],
    "errors": []
  }
}

Algumas informações importantes sobre o resultado que são:

• key

  • Identificador único do documento definido pelo usuário. Você pode escolher qualquer valor numérico para key, que normalmente é utilizado para correlacionar o texto de entrada com o label de saída.

• label

  • String que representa a intenção identificada pelo modelo treinado.

• score

  • Pontuação de confiabilidade que indica a precisão da classificação das intenções. Quanto maior a pontuação, mais preciso o modelo está na identificação da intenção.

4.3.4 Arquitetura do Chatbot