Manual do SCAE

Introdução

Este manual visa explicar como utilizar o SCAE, desde sua instalação e manutenção até sua utilização.

Tutorial sobre o SCAE

Introdução

O Sistema de Codificação Automática de Atividades Econômicas (SCAE) possui a arquitetura mostrada na Figura 1. A Interface do usuário com o sistema é um navegador Internet (browser), que se comunica com o módulo Servidor de Aplicação (SA) do SCAE. Este módulo, por sua vez, se comunica com os outros dois módulos do SCAE: Core e Banco de Dados (BD).

Figura 1: Arquitetura do SCAE

Em uma solicitação de classificação de atividade econômica, o usuário, por meio da Interface, envia ao SA uma descrição de atividade econômica. O SA, por sua vez, envia esta descrição para o Core, que a classifica e retorna códigos CNAE e medidas de confiança quanto às associações destes códigos com a descrição de atividade econômica recebida. De posse dos códigos CNAE, o SA requisita ao BD o texto associado aos códigos CNAE.

O Core também se comunica com o módulo BD, que é responsável por armazenar todo o conhecimento do SCAE (dicionário eletrônico, representação interna ao sistema da tabela CNAE, representação interna ao sistema de descrições de atividades econômicas usadas para treinamento, etc). Além de realizar a classificação, o Core manipula as tabelas do sistema (cria, insere dados, remove dados, etc) guardadas em BD. Diferentes submódulos do Core são responsáveis por esta manipulação. O SA está sendo desenvolvido em PHP, o BD em C, e o Core em C, Perl e Java.

Instalação

Um roteiro detalhado de instalação do SCAE pode ser encontrado em http://www.lcad.inf.ufes.br/svn/scae/Roteiros. Neste tutorial, apresentamos apenas um procedimento de instalação simplificado, que assume que o sistema operacional é o Fedora Core 8 e que várias bibliotecas já estão instaladas (em muitas instalações Fedora, mesmo anteriores à versão 8, ele deve ser o suficiente para colocar o SCAE em operação). Contudo, verifique se as bibliotecas w3c-libwww e xmlrpc-c estão instaladas com os comandos (se elas não estiverem instaladas estes comandos as instalarão):

yum install w3c-libwww
yum install w3c-libwww-devel
yum install xmlrpc-c
yum install xmlrpc-c-devel

Para a iniciar a instalação do SCAE, baixe (download) seus arquivos de instalação. Para isso, vá para o diretório raiz de sua conta e digite o comando (você vai precisar de uma senha para baixar os arquivos; solicite-a via o e-mail de suporte do LCAD):

svn co http://www.lcad.inf.ufes.br/svn/scae/code

Este comando vai criar o diretório code e vários subdiretórios (se você precisar remover todo o diretório code não se esqueça de deletar o arquivo .subversion que fica no seu diretório raiz).

Compilando e executando o BD

Compile o BD (Figura 1) executando os seguintes comandos:

cd code/CORES/DB_CORE
make clean
make

Estes comandos vão criar o executável db_core no diretório code/CORES/DB_CORE. Este executável é um daemon que implementa o BD. Além disso, ele implementa facilidades de criação de tabelas a partir de arquivos .csv (coma separated values). O script abaixo usa o db_core para criar um conjunto básico de tabelas que permitem demonstrar as funcionalidades do SCAE (assuma sempre que o diretório corrente é o último especificado por um comando cd):

./build_tables_subclasse_110.bat

A saída deste comando deve ser:

Locale set to pt_BR.UTF-8.
Loading dictionary .csv
Number of dictionary words = 23160
Number of distincts words = 17365
Loading cnae subclasses .csv
Number of CNAE-Subclasses = 1183
Loading dados de vitoria .csv
Number of economic activities descriptions = 14204
Number of distinct economic activities descriptions = 3281
Lexicon size = 1367. Number palavras com frequencia superior (pfs) = 0.
Saving tables

Os arquivos .csv que servem de entrada para este script estão do diretório CSV_FILES.

A partir deste momento, você pode colocar o daemon db_core em operação com o comando:

nohup db_core init_server ports.cfg&

Mensagens de erro geradas pelo db_core serão gravadas no arquivo nohup.out, conforme mensagem mostrada após a execução do comando acima (nohup: ignoring input and appending output to nohup.out). Com a execução deste comando, o BD da Figura 1 estará em operação. As tabelas mantidas por este banco de dados e necessárias para a operação do SCAE serão carregadas conforme demandadas pelo SCAE. Para interromper o db_core, descubra o seu PID com o comando:

ps -A | grep db_core

e kill o db_core com o comando

kill -9 PID (onde PID é o número do processo informado pelo comando ps)

Compilando e executando o Core VS

O Core da Figura 1, na verdade, pode ser composto por um ou mais classificadores. Na versão atual do SCAE, dois classificadores estão disponíveis: VS e WNN. O Vector Space (VS) Core emprega a técnica de mesmo nome para classificar (na verdade, categorizar) texto, enquanto que o Weightless Neural Network (WNN) Core emprega redes neurais sem peso (do tipo Virtual Generalizing Ramdon Access Memory - VG-RAM) para o mesmo fim. Mais detalhes sobre como estas técnicas podem ser usadas para categorizar objetos sociais de empresas (atividades econômicas) segunda a tabela de Classificação Nacional de Atividades Econômicas (CNAE) podem ser encontrados no trabalho De Souza, A. F.; Pedroni, F.; OLIVEIRA, E.; Ciarelli, P. M.; Henrique, W. F.; Veronese, L. . Automated Free Text Classification of Economic Activities using VG-RAM Weightless Neural Networks. International Conference on Intelligent Systems Design and Applications (ISDA), 2007, Rio de Janeiro. Proceedings of ISDA, 2007..

Para compilar o VS_CORE, volte para o seu diretório raiz e digite os comandos:

cd code/CORES/VS_CORE
make clean
make

Estes comandos vão criar o executável vs_core no diretório code/CORES/VS_CORE. Este executável é um daemon que implementa o Core que classifica segundo a técnica VS. Para colocá-lo em operação, digite:

nohup vs_core&

Com o comando acima, parte do Core da Figura 1 estará em operação. Para interromper o vs_core, descubra o seu PID com o comando:

ps -A | grep vs_core

e kill o vs_core com o comando

kill -9 PID (onde PID é o número do processo informado pelo comando ps)

Compilando e executando o Core WNN

Antes de compilar o Core WNN são necessárias algumas bibliotecas, que podem ser instaladas com os comandos abaixo (você precisa ser root para executar o yum):

yum xxx
yum xxx
...
{Felipe, indique acima os comandos de linha do yum que instalam as bibliotecas necessárias para a MAE. Para isso, examine o roteiro detalhado de instalação e reescreva as linhas acima de acordo com os pacotes indicados lá.}

Para compilar o Core WNN volte para o seu diretório raiz e digite os comandos:

cd code/CORES/MAE
make clean
make –f Makefile.no_interface
cd examples/wnn_cnae
make clean
make

Estes comandos vão criar o executável class_cnae no diretório code/CORES/MAE/examples/wnn_cnae. Este executável é um daemon que implementa o Core que classifica texto usando VG-RAM WNN. Para colocá-lo em operação, digite:

nohup class_cnae&

Com o comando acima, uma segunda parte do Core da Figura 1 estará em operação. Para interromper o class_cnae descubra o seu PID com o comando:

ps -A | grep class_cnae

e kill o class_cnae com o comando

kill -9 PID (onde PID é o número do processo informado pelo comando ps)

Configurando o SA

Com os deamons db_core, vs_core e class_cnae em operação, é possível examinar todas as funcionalidades do SCAE por meio de um browser graças ao seu servidor de aplicação SA (ver Figura 1). O SA foi implementado em PHP e seu código fica no diretório code/scaeweb. Para acessá-lo com um browser, ele precisa "servido" por um servidor http, como o Apache, por exemplo. Se você está instalando o SCAE em uma máquina stand alone, você pode instalar o apache e o php com o comando (você precisa ser root para usar o yum):

yum install apache php

Para que o apache sirva o SA, coloque um link simbólico do diretório scaeweb para o diretório raiz de páginas http do Apache (você precisa ser root para escrever no diretório raiz do Apache):

ln -s code/scaeweb /var/www/http

Você pode então acessar o SCAE com um browser em sua máquina na URL: http://127.0.0.1/scaeweb

Seu browser deve mostrar a imagem da Figura 2. Caso ela não apareça, você tem problemas de configuração no Apache ou PHP. Neste caso, se a mensagem do browser indicar que você não tem permissão de acesso ao diretório scaeweb, experimente copiar todo o conteúdo do diretório code/scaeweb para /var/www/http:

rm /var/www/http/scaeweb
cp -r code/scaeweb /var/www/http

Figura 2: SCAE

Se funcionar, experimente voltar à solução com o link simbólico e reduzir o nível de segurança do SELinux (Security-Enhanced Linux) com a ferramenta Sistema->SELinux Management. Mude System Default Enforcing Mode e Current Enforcing Mode para Permissive. Se funcionar, o SELinux não permite que o Apache (httpd) acesse diretórios de usuário via links simbólicos (e possivelmente muitos outros diretórios). Neste caso, fique com a cópia de scaeweb no /var/www/http, ou deixe o SELinux como indicado acima, ou configure o SELinux para permitir que o Apache acesse links simbólicos e explique aqui como fazê-lo ( :) ).

Se a redução do nível de segurança do SELinux funcionar, o Apache pode não estar configurado para permitir o seu próprio acesso a links simbólicos. Neste caso, consulte a documentação do Apache sobre o assunto na Internet. O problema pode estar, também, no PHP.

Se você conseguir ver a Figura 2 no seu browser, o SCAE está pronto para operar. Experimente categorizar uma atividade econômica por meio da Funcionalidade 8, Classificação de atividades econômicas com o SCAE.

As demais funcionalidade do SCAE (inclusive sua interface via linha de comando) são apresentadas na próxima seção.

Organização do SCAE

Esta seção visa explicar como está organizado o sistema SCAE.

As partes do sistema SCAE

O sistema foi projetado para funcionar em Módulos que se comunicam entre si através de xmlrpc. Os módulos são divididos basicamente em 3 categorias:

• Interface (WEB e linha de comando)
• Classificadores (Redes Neurais, Espaço Vetorial, ..)
• Banco de Dados (DB_CORE)

Comunicação entre os CORES (xmlrpc)

O SCAE usa o protocolo XML-RPC (Extensible Markup Language Remote Process Call) para comunicação entre módulos. Trata-se de um protocolo muito simples que usa http como transporte e XML como codificação, e que permite a comunicação entre aplicações escritas em linguagens diferentes, rodando em computadores diferentes e mesmo em sistemas operacionais diferentes.

Toda a comunicação entre os módulos do SCAE é feita por meio de XML-RPC, o que permite que cada módulo rode em um computador diferente. Em sistemas que empregam XML-RPC, clientes XML-RPC enviam requisições de execução de procedimentos remotos (RPCs) para servidores XML-RPC, os quais, por sua vez, devolvem aos clientes o resultado da execução destas RPCs.

No SCAE, alguns módulos fazem às vezes de cliente, outros de servidor e alguns de cliente e servidor ao mesmo tempo.

Comunicando com o DB_CORE

O DB_CORE é o único CORE que faz o papel de servidor puro, ou seja, ele não realiza nenhuma requisição. Neste CORE encontramos o módulo db_core_rpcs.c, o qual contém as seguintes rpcs:

• get_num_table_lines_rpc
  input: nome da tabela.
  output: número de linhas da tabela.

• get_table_column_rpc
  input: nome da tabela, nome da coluna e número da linha.
  output: campo da tabela.

• get_table_column_and_codes_rpc
  input: nome da tabela, nome da coluna e número da linha.
  output: vetor de códigos de palavras.

• get_lexicon_rpc
  input: nome do lexicon.
  output: vetor de frequências de palavras, vetor de palavras e um vetor de códifgos de palavras canônicas.

• get_train_test_vector_words_rpc
  input: nome da tabela, nome da coluna, número da linha, nome do lexico e o tipo de construção (ADD, OR, COMMON).
  output: vetor de índices, vetor de frequências, vetor de palavras e um vetor de códigos de palavras canônicas.

• get_cnae_codes_rpc
  input: nome da tabela, a linha e o tipo de construção.
  output vetor de códigos CNAE.

• get_train_and_test_vector_rpc
  input: nome da tabela, nome da coluna, a linha, nome do lexicon e o tipo de construção.
  output vetor de treino e teste com tamanho igual ao do lexicon.

Módulos do SCAE (CORE's)

Cada módulo é descrito a seguir.

DB_CORE

Core responsável por armazenar as tabelas de dados do sistema.

Tabelas Existentes no sistema e suas colunas:

Tabela: DICIONARIO

Coluna	Comentários
PALAVRA	a própria palavra
CLASSE	classe gramatical
PALAVRA_CANONICA	palavra canônica
GENERO	gênero
GRAU	grau
LISTA_ELEMENTOS	lista de elementos
LISTA_PREPOSICOES	lista de preposições
LISTA_REGENCIAS	lista de regências
MODO_TEMPO_FORMANOMINAL	modo e/ou tempo e/ou forma nominal
NUMERO	número
LISTA_PAPEIS	lista de papéis
PESSOA	pessoa
CODIGO_PALAVRA_CANONICA	código da palavra canônica
CODIGO_PALAVRA	código da palavra

Tabela: CNAE_110_SUBCLASSE

Coluna	Comentários
CODIGO_SUB_SEC	Código Sequencial da subclasse
CODIGO_SEC
CODIGO_DIV
CODIGO_GRP
CODIGO_CLA
CODIGO_SUB
DV_SUB
DESCRICAO_SUB
CCOMPRE_SUB
TCOMPRE_SUB
NCOMPRE_SUB
NOTAS_SUB
CODIGO_CNAE_SUBCLASSE
VETOR_CODIGOS_CNAE

Tabela: CNAE_200_SUBCLASSE

Coluna	Comentários
CODIGO_SUB_SEC	Código Sequencial da subclasse
CODIGO_SEC
CODIGO_DIV
CODIGO_GRP
CODIGO_CLA
CODIGO_SUB
DV_SUB
DESCRICAO_SUB
CCOMPRE_SUB
TCOMPRE_SUB
NCOMPRE_SUB
NOTAS_SUB
CODIGO_CNAE_SUBCLASSE
VETOR_CODIGOS_CNAE

Tabela: DADOS_VITORIA_110

Coluna	Comentários
NO_IDENTIFICADOR	Um número de identificação que veio junto aos dados que recebemos
OBJETO_SOCIAL	Texto descritivo do objeto em questão
CNAE_FISCAL	Um código CNAE para o qual esta atividade foi classificada; Formato direto de 7 dígitos, sem '-' ou '/'
VETOR_CODIGOS_CNAE	Neste campo, sempre o valor zero, ele é preenchido pelo DB_CORE com os sequenciais que representam as classificações

Tabela: DADOS_VITORIA_200

Coluna	Comentários
NO_IDENTIFICADOR	Um número de identificação que veio junto aos dados que recebemos
OBJETO_SOCIAL	Texto descritivo do objeto em questão
CNAE_FISCAL	Um código CNAE para o qual esta atividade foi classificada; Formato direto de 7 dígitos, sem '-' ou '/'
VETOR_CODIGOS_CNAE	Neste campo, sempre o valor zero, ele é preenchido pelo DB_CORE com os sequenciais que representam as classificações

MAE

Implementação do classificador que utiliza Redes Neurais.

VS_CORE

Implementação do classificador que utiliza Espaço Vetorial.

WISARD_CORE

???

BAYESIAN_CORE

???

Adicionando um CORE ao SCAE

???

Como acessar o Repositório SCAE

É possível acessar o repositório do SCAE através do seu navegador ou ainda baixar os códigos direto para sua máquina. O acesso só é permitido a usuários do Projeto SCAE cadastrados e com conta no LCAD.

Organização do Repositório

O Repositório está dividido da seguinte maneira:

• code
  • CORES (Código dos classificadores)
    • DB_SERVER
    • MAE
    • USER_INTERFACE
    • VS_CORE
    • WISARD_CORE
    • config
  • db_server (Código da API do Oracle -- em desuso no momento)
  • scaeweb (Código da Interface WEB)
• data (Dados do Oracle -- em desuso no momento)
• install (Diretório de instalações)

Navegando no Repositório

Para acessar o repositório de um navegador basta seguir para http://www.lcad.inf.ufes.br/svn/scae e utilizar sua conta/senha do LCAD.

Baixando o SCAE para sua máquina

Antes de baixar o repositório do SCAE, recomenda-se navegar pelo mesmo e identificar qual(is) parte(s) dele serão utilizadas. Dessa forma, é possível fazer o download apenas das partes de interesse, evitando um longo download de todo o conteúdo.

Para baixar o repositório do SCAE completo para sua máquina utilize

svn co http://www.lcad.inf.ufes.br/svn/scae

Para baixar apenas uma parte, por exemplo, um diretório da árvore do repositório, acrescente o caminho ao endereço. Exemplos:

• Download de apenas a instalação das bibliotecas necessárias para isntalação do xmlrpc

svn co http://www.lcad.inf.ufes.br/svn/scae/install/xmlrpc

• Download de apenas os códigos-fonte dos CORES

svn co http://www.lcad.inf.ufes.br/svn/scae/code/CORES

Maiores informações sobre o svn podem ser encontradas no nosso manual de Uso básico do Subversion.