{"id":22809033,"url":"https://github.com/ccuffs/aura-nlp","last_synced_at":"2025-03-30T21:17:51.123Z","repository":{"id":86668552,"uuid":"391963529","full_name":"ccuffs/aura-nlp","owner":"ccuffs","description":"Módulo de processamento de linguagem natural utilizado pela aura para entender textos de usuários","archived":false,"fork":false,"pushed_at":"2022-01-28T19:30:00.000Z","size":435,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-06T00:31:37.670Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ccuffs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE-OF-CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-08-02T13:40:38.000Z","updated_at":"2021-10-25T11:52:12.000Z","dependencies_parsed_at":null,"dependency_job_id":"be9899c1-4add-4102-9039-3e0dc617e579","html_url":"https://github.com/ccuffs/aura-nlp","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":"ccuffs/template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccuffs%2Faura-nlp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccuffs%2Faura-nlp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccuffs%2Faura-nlp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccuffs%2Faura-nlp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ccuffs","download_url":"https://codeload.github.com/ccuffs/aura-nlp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246379363,"owners_count":20767696,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-12T11:13:17.917Z","updated_at":"2025-03-30T21:17:51.115Z","avatar_url":"https://github.com/ccuffs.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg width=\"800\" src=\".github/logo.png\" title=\"Logo do projeto\"\u003e\u003cbr /\u003e\n    \u003cimg src=\"https://img.shields.io/maintenance/yes/2022?style=for-the-badge\" title=\"Status do projeto\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/workflow/status/ccuffs/aura-nlp/ci.uffs.cc?label=Build\u0026logo=github\u0026logoColor=white\u0026style=for-the-badge\" title=\"Status do build\"\u003e\n\u003c/p\u003e\n\n# Aura NLP\n\nMicroserviço para processamento de linguagem natural utilizado pela assistenve virtual [Aura](https://github.com/ccuffs/aura) para entendimento dos textos informados pelos usuários. A implementação é construída com base no pacote [nlp.js](https://github.com/axa-group/nlp.js).\n\n## 🚀 Começando\n\n### 1. Dependências\n\nPara executar o projeto, você precisa ter o seguinte instalado:\n\n- [Git](https://git-scm.com);\n- [NodeJS](https://nodejs.org/en/);\n- [NPM](https://www.npmjs.com/package/npm);\n\n### 2. Configuração\n\nFeito a instalação das dependências, é necessário obter uma cópia do projeto. A forma recomendada é clonar o repositório para a sua máquina.\n\nPara isso, rode:\n\n```bash\ngit clone --recurse-submodules https://github.com/ccuffs/aura-nlp \u0026\u0026 cd aura-nlp\n```\n\nIsso criará e trocará para a pasta `aura-nlp` com o código do projeto. Em seguinda, instale as dependências:\n\n```bash\nnpm install\n```\n\n### 3. Utilizacão\n\n#### 3.1 Rodando o projeto\n\nExistem várias formas de rodar o projeto, como a api web, treino, etc. Para saber todas as opções, rode:\n\n```bash\nnode aura.js -h\n```\n\nTodas as funcionalidades são baseadas no formato `node aura.js \u003ccomando\u003e`, onde `\u003ccomando\u003e` é o módulo que você deseja executar.\n\n\n#### 3.2 Utilização da API\n\n Para iniciar o servidor web (api REST), rode o seguinte;\n\n```bash\nnode aura.js serve\n```\n\nApós isso a aplicação estará rodando na porta 3000 e poderá ser acessada em [localhost:3000](http://localhost:3000).\n\n\u003e *DICA:* use `node aura.js serve -p 8080` para escolher a porta do servidor web.\n\nA API web, com todos os endpoints, estará acessivel em `/api`, por exemplo [localhost:3000/api](http://localhost:3000/api). Por padrão, dois endpoints da api estão disponíveis:\n\n- [localhost:3000/api/qna/](http://localhost:3000/api/qna) para perguntas e respostas;\n- [localhost:3000/api/domain](http://localhost:3000/api/domain) para informações de domínio específico.\n\nFaça um teste acessando [localhost:3000/api/qna/comida+favorita](http://localhost:3000/api/qna/comida+favorita).\n\nQuando o servidor web é iniciado, você pode informar quais engines (e modelos/urls) você deseja através do parâmetro `-e` (ou `--engine=`, cujo formato é `\u003cnome\u003e:\u003curl\u003e:/path/para/modelo.nlp, \u003cnome\u003e:\u003curl\u003e:/path/para/modelo.nlp, etc`). O exemplo abaixo inicia o servidor web com duas engines (`domain` e `qna`), nas urls `/api/domain-url` e `/api/qna-url`, informando onde os modelos dessas duas engines estão:\n\n```bash\nnode aura.js serve -p 3000 -e \"domain:domain-url:./data/models/domain.model,qna:qna-url:./data/models/qna.model\"\n```\n\n### 4. Baixando e treinando novos modelos\n\nO repositório vem com alguns modelos muito simples prontos para uso. O ideal é você treinar seus próprios modelos. Veja nas seções a seguir como treinar seus modelos.\n\n#### 4.1 Usando uma planilha no Google Spreadsheets como dataset\n\nA melhor forma de manter um dataset para outros contribuirem é utilizar uma planilha no [Google Spreadsheet](https://docs.google.com). Para tornar uma delas disponível para download, faça o seguinte:\n\n1. Acesse a planilha\n2. Escolha `File \u003e Publish to the web`\n3. Configure o tipo para `Tab-separated values (.tsv)\n4. Clique `Publish`\n5. Copie a URL resultante (será algo como `https://docs.google.com/spreadsheets/d/e/2PACX-1vS4GT7aqVyOHEGlSz-FPg1asFpq8ffoFwXFBoNiVQLR8uD6m2usl9t_bBwMm7VnXJoYvUFlV1HJRbJh/pub?output=tsv`).\n\nDepois de publicar a planilha como TSV, você pode baixar e utilizar ela como dataset. Para isso, na raiz desse repositório, rode o seguinte comando (assumindo que a URL da planilha é a mesma do passo anterior; atualize a URL se sua planilha for diferente):\n\n```bash\ncurl -L \"https://docs.google.com/spreadsheets/d/e/2PACX-1vS4GT7aqVyOHEGlSz-FPg1asFpq8ffoFwXFBoNiVQLR8uD6m2usl9t_bBwMm7VnXJoYvUFlV1HJRbJh/pub?gid=0\u0026single=true\u0026output=tsv\" \u003e ./data/train/dataset.tsv\n```  \n\nIsso criará o arquivo `./data/train/aura-domain.tsv` que pode ser utilizado para treinos.\n\n#### 4.3 Treinando um modelo\n\nPara treinar um novo modelo, você precisa especificar a engine e o local onde o modelo será escrito. A engine é o estilo de dados que serão processados. Atualmente existem duas engines disponíveis: `domain` (conhecimento de domínio específico, inclusive NER) e `qna` (perguntas e respostas).\n\nPara treinar um modelo para a engine `domain`, rode o seguinte:\n\n```bash\nnode aura.js train --type=\"domain\" --dataset=\"./data/train/aura-domain.tsv\" --output=\"./data/models/domain.model\"\n```\n\nPara treinar um modelo para a engine `qna`, rode o seguinte:\n\n```bash\nnode aura.js train --type=\"qna\" --dataset=\"./data/train/aura-qna.tsv\" --output=\"./data/models/qna.model\"\n```\n\n#### 4.4 Formato do dataset\n\nTodas as engines são treinadas a partir de um arquivo `.tsv` (tab-separed values). As seções a seguir explicam o formato de treinamento de cada engine.\n\n##### 4.4.1 Dataset `domain`\n\nPara a engine `domain`, o formato do arquivo é o seguinte:\n\n| type  |  category      |  nickname  | language  |          content            |\n|-------|----------------|------------|-----------|-----------------------------|\n|  ner  | hero           | spiderman  |    en     | Spiderman, Spider-man       |\n|  ner  | hero           | iron man\t  |    en     | Iron Man, Ironman, iron-man |\n|  ner  | hero           | thor       |    en     | Thor                        |\n|  ner  | food\t         | burger\t  |    en     | Burguer, Hamburguer         |\n|  doc  | sawhero\t     |            |    en     | I saw %hero% eating %food%  |\n|  doc  | wanteat\t     |            |    en     | I want to eat %food%        |\n    \nA coluna `type` informa o tipo da linha. Os tipos possiveis são `ner` (entidade nomeada) e `doc` (informação qualquer). Ambos os tipos tem uma coluna `category` que informa a categoria que aquela linha/entidade pertence, e uma coluna `language` que informa a linguagem.\n\nUma linha do tipo `ner` tem os seguintes atributos:\n- `nickname`: nome curto para a entidade em questão;\n- `content`: nomes reais da entidade, que são todas as variações possíveis do nome, separados por `,`.\n\nUma linha do tipo `doc` tem os seguintes atributos:\n- `nickname`: __(não possui, então deixar vazio)__.\n- `content`: frase que exemplifica o uso de alguma `ner`. Aqui você pode usar o nome de uma categoria de ner entre `%`, por exemplo, `%hero%` para se referir a todas as ners que sejam hero. A frase `I saw %hero% eating %food%` treinará o modelo para encontrar frases do tipo `I saw Thor eating Hamburguer` (`%hero%` é thor, `%food%` é burger).\n\n##### 4.4.1 Dataset `qna`\n\nPara a engine `qna`, o formato do arquivo é o seguinte:\n\n| question                |  answer                 |\n|-------------------------|-------------------------|\n| Fale sobre você         | Sou uma agente virtual  |\n| Porque você está aqui   | Porque é muito legal    |\n\nNão há tipos de colunas, apenas uma organização no formato `pergunta \\t resposta`. \n\n## 🤝 Contribua\n\nSua ajuda é muito bem-vinda, independente da forma! Confira o arquivo [CONTRIBUTING.md](CONTRIBUTING.md) para conhecer todas as formas de contribuir com o projeto. Por exemplo, [sugerir uma nova funcionalidade](https://github.com/ccuffs/aura-nlp/issues/new?assignees=\u0026labels=\u0026template=feature_request.md\u0026title=), [reportar um problema/bug](https://github.com/ccuffs/aura-nlp/issues/new?assignees=\u0026labels=bug\u0026template=bug_report.md\u0026title=), [enviar um pull request](https://github.com/ccuffs/hacktoberfest/blob/master/docs/tutorial-pull-request.md), ou simplemente utilizar o projeto e comentar sua experiência.\n\nVeja o arquivo [ROADMAP.md](ROADMAP.md) para ter uma ideia de como o projeto deve evoluir.\n\n\n## 🎫 Licença\n\nEsse projeto é licenciado nos termos da licença open-source [MIT](https://choosealicense.com/licenses/mit) e está disponível de graça.\n\n## 🧬 Changelog\n\nVeja todas as alterações desse projeto no arquivo [CHANGELOG.md](CHANGELOG.md).\n\n## 🧪 Projetos semelhates\n\nAbaixo está uma lista de links interessantes e projetos similares:\n\n* [Aura](https://github.com/ccuffs/aura)\n* [nlp.js](https://github.com/axa-group/nlp.js)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fccuffs%2Faura-nlp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fccuffs%2Faura-nlp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fccuffs%2Faura-nlp/lists"}