Skip to content

README.md

Latest commit

 

History

History
260 lines (198 loc) · 10.2 KB

README.md

File metadata and controls

260 lines (198 loc) · 10.2 KB
Raw

Portuguese OpenIE

English version

Biblioteca Python unificada para Extração Aberta de Informação (OpenIE) em português. Ela oferece a mesma API para duas linhas de pesquisa desenvolvidas no doutorado de Bruno Souza Cabral:

  • PortNOIE, o extrator neural clássico por rotulagem de sequência, indicado para extrações estritamente presentes no texto;
  • modelos generativos Qwen3OIE, PortugueseT5Oie e Llama-PortOIE3, publicados no Hugging Face, incluindo OpenIE abstrativa.

O resultado sempre é normalizado para triplas ARG0, V, ARG1, independentemente do modelo escolhido.

Instalação

A release suporta Python 3.10–3.13.

Para os modelos do Hugging Face:

pip install "portuguese-openie[transformers]"

O Llama-PortOIE3 é publicado somente em GGUF e usa um extra separado:

pip install "portuguese-openie[gguf]"

Para o PortNOIE, incluindo o backend PyTorch e o downloader do checkpoint histórico:

pip install "portuguese-openie[portnoie]"

Para instalar todos os backends de uma vez:

pip install "portuguese-openie[all]"

Durante o desenvolvimento local:

git clone https://github.com/FORMAS/Portuguese-OpenIE.git
cd Portuguese-OpenIE
python -m venv .venv
# Linux/macOS: source .venv/bin/activate
# Windows: .venv\Scripts\activate
python -m pip install -e ".[transformers,dev]"

Não é necessário informar diretório de modelo. Os modelos neurais, o GGUF e o checkpoint histórico do PortNOIE são resolvidos pelo enum e baixados do Hugging Face na primeira extração. Nenhum wheel inclui pesos. Todos reutilizam cache nas chamadas seguintes. Cada modelo remoto é fixado por padrão na revisão auditada registrada na biblioteca, evitando que uma alteração futura em main mude silenciosamente os resultados.

Uso rápido

from portuguese_openie import Model, PortugueseOpenIE

extractor = PortugueseOpenIE(Model.QWEN3_OIE_0_6B)
triples = extractor.extract("A UFBA está localizada em Salvador.")

for triple in triples:
    print(triple.to_dict())

Saída normalizada:

{"ARG0": "A UFBA", "V": "está localizada em", "ARG1": "Salvador"}

Para manter o texto bruto gerado e os metadados:

result = extractor.extract_with_metadata(
    "A UFBA está localizada em Salvador."
)
print(result.raw_output)
print(result.to_dict())

Linha de comando

portuguese-openie --model qwen3-oie-0.6b \
  "A Universidade Federal da Bahia fica em Salvador."

Também é possível usar entrada padrão:

echo "A UFBA fica em Salvador." | portuguese-openie --model portuguese-t5-oie-abstractive

Para ver todos os aliases:

portuguese-openie --list-models

Após uma primeira execução online, use --local-files-only para trabalhar offline. --cache-dir escolhe o cache e --revision permite uma revisão explicitamente diferente da versão auditada; nenhum desses argumentos é obrigatório.

Modelos disponíveis

Alias Tipo Tamanho Quando usar
qwen3-oie-0.6b abstrativo 0,6B menor modelo e ponto de partida recomendado
qwen3-oie-4b abstrativo 4B melhor perfect match entre os modelos ajustados
qwen3-oie-8b abstrativo 8B melhor F1 lexical reportado na tese
portuguese-t5-oie-abstractive abstrativo 770M alternativa menor, validada ponta a ponta no snapshot público
portuguese-t5-oie experimental 770M tarefa e prompt exatos ainda sem proveniência recuperada
llama-port-oie3 extrativo GGUF 8B linha generativa Llama 3/PortOIE via llama.cpp
portnoie extrativo PyTorch spans do texto; migração moderna experimental do modelo de 2022

Detalhes, métricas e identificadores exatos estão no guia de modelos. Veja também o mapa dos projetos, que separa PortNOIE 2022, GenPtOIE, PTOIE/TransAlign e os datasets.

Os identificadores públicos são Model.QWEN3_OIE_0_6B, Model.QWEN3_OIE_4B, Model.QWEN3_OIE_8B, Model.PORTUGUESE_T5_OIE_ABSTRACTIVE, Model.PORTUGUESE_T5_OIE, Model.LLAMA_PORT_OIE3 e Model.PORTNOIE. Os aliases em string continuam aceitos para compatibilidade. O registro também expõe spec.status: validated indica um teste ponta a ponta do artefato, research indica evidência experimental documentada e experimental indica que ainda há lacunas de proveniência ou equivalência. A CLI mostra esse estado com --list-models.

Usando o PortNOIE

O PortNOIE fica em um pacote separado por ter implementação e dependências próprias. O backend padrão reconstrói o grafo em PyTorch atual; texto bruto também usa o modelo linguístico pt_core_news_lg:

pip install "portnoie[modern]"

Na primeira extração, a biblioteca baixa o checkpoint histórico de cerca de 75 MB de bratao/PortNOIE, na revisão fixada e verificada por hashes. Para texto bruto, também instala pt_core_news_lg==3.8.0 se ausente: a wheel oficial tem 568.207.147 bytes. A instalação usa pip ou uv no Python em execução, com URL e SHA-256 fixados. Chamadas seguintes reutilizam o checkpoint em cache e o pipeline carregado.

from portuguese_openie import Model, PortugueseOpenIE

extractor = PortugueseOpenIE(Model.PORTNOIE)
print([triple.to_dict() for triple in extractor.extract(
    "Maria escreveu um livro."
)])
# [{'ARG0': 'Maria', 'V': 'escreveu', 'ARG1': 'um livro'}]

Veja o guia do PortNOIE para cache, checkpoint local e requisitos.

O checkpoint histórico de referência publicado com o código original (LSTM 1×384 + Flair, 74,8 MB) é distribuído pelo Hugging Face, não pelo wheel. O novo backend evita AllenNLP e os dois downloads Flair externos, mas permanece marcado como experimental até ser comparado numericamente com o pipeline legado. O melhor experimento BERTimbau Large da tese é um artefato local diferente, de aproximadamente 1,38 GB, e não é apresentado como se fosse o mesmo arquivo.

Escolha entre OpenIE extrativa e abstrativa

Extrativa preserva a proveniência: os argumentos e a relação são trechos da frase. É adequada para auditoria, destaque no texto e aplicações que exigem rastreabilidade.

Abstrativa pode resolver referências, normalizar relações e explicitar fatos implícitos. É mais apropriada para consolidar conhecimento, mas o texto gerado deve ser validado em aplicações sensíveis.

Hardware

  • qwen3-oie-0.6b e os modelos T5 são as opções mais acessíveis.
  • Os modelos 4B/8B normalmente exigem GPU ou quantização/offload.
  • llama-port-oie3 baixa llama3_finetune.gguf (8,54 GB) e pode executar em CPU; configure n_gpu_layers para offload em GPU quando suportado.
  • device_map="auto" e dtype="auto" são usados por padrão.
  • Entradas Transformers são truncadas em 2.048 tokens por padrão, em linha com o comprimento usado no ajuste Qwen; altere com max_input_tokens se necessário.
  • Para execução offline, faça uma primeira execução online para preencher o cache e depois use local_files_only=True.
extractor = PortugueseOpenIE(
    Model.QWEN3_OIE_0_6B,
    local_files_only=True,
)

Desenvolvimento e testes

python -m pip install -e ".[dev]"
ruff check .
pytest

Os testes unitários não baixam pesos. A validação ponta a ponta de cada modelo é separada porque os artefatos variam de aproximadamente 0,6B a 8B parâmetros. Os testes reais do Qwen3OIE-0.6B e do PortugueseT5OieAbstractive, com revisões e checksums fixados, estão documentados em docs/VALIDATION.md. Mantenedores podem seguir o guia de release para publicar no PyPI e no GitHub sem tokens persistentes.

Limitações

  • OpenIE não garante factualidade; modelos generativos podem alucinar.
  • A avaliação da tese usa corpora majoritariamente enciclopédicos e jornalísticos.
  • O PortNOIE produz relações binárias e não cobre todas as sobreposições ou relações n-árias.
  • O tempo e a memória dependem do modelo e do hardware.
  • Os três repositórios Qwen têm licença Apache-2.0. Os repositórios T5 e Llama-PortOIE3 não declaram licença própria; confirme a licença antes de redistribuir pesos.
  • Os estados de treino publicados para os modelos T5 parecem parciais, portanto a proveniência de treino ainda exige confirmação. Isso não invalida o teste E2E do snapshot PortugueseT5OieAbstractive, marcado validated; PortugueseT5Oie continua experimental, e os demais artefatos T5 não têm alias OpenIE nesta versão.
  • O extra [all] inclui llama-cpp-python; em plataformas sem wheel binário compatível, a instalação pode exigir CMake e um compilador C/C++.

Citação

Use o arquivo CITATION.cff. Como referência principal da linha PortNOIE, cite também o artigo:

Cabral, Bruno; Souza, Marlo; Claro, Daniela Barreiro. “PortNOIE: A Neural Framework for Open Information Extraction for the Portuguese Language.” PROPOR, 2022.

E, para o conjunto completo de modelos e dados:

Cabral, Bruno Souza. “Evolving Open Information Extraction for Portuguese employing Language Models.” Tese de Doutorado, Universidade Federal da Bahia, 2025.

Licença

O código desta biblioteca usa a licença Apache-2.0. Pesos e datasets são artefatos separados e mantêm as licenças indicadas em seus respectivos cartões ou repositórios. Consulte o NOTICE antes de redistribuir.