Publica modelo QLoRA mesclado

README.md

@@ -1,257 +1,26 @@
-———
-
-  base_model: Qwen/Qwen2.5-0.5B-Instruct
-  base_model_relation: finetune
-  library_name: transformers
-  language:
-
-  - pt
-    pipeline_tag: text-generation
-    metrics:
-
-  - accuracy
-    tags:
-
-  - qwen
-  - lora
-  - merged
-  - sentiment-analysis
-  - text-classification
-  - portuguese
-  - json-output
-    license: apache-2.0
-
-  ———
-
-  # EscutIA LoRA
-
-  Modelo especializado em classificação de sentimentos em textos escritos em português.
-
-  O modelo recebe um texto e identifica o sentimento predominante entre três classes:
-
-  - negativo
-  - neutro
-  - positivo
-
-  A resposta é produzida como JSON, facilitando sua integração com APIs, pipelines de processamento de linguagem natural e sistemas baseados em agentes.
-
-  ## Visão geral
-
-   Propriedade               Valor
-  ━━━━━━━━━━━━━━━━━━━━━━━━  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   Modelo-base               Qwen/Qwen2.5-0.5B-Instruct
-  ────────────────────────  ──────────────────────────────────────────
-   Revisão do modelo-base    7ae557604adf67be50417f59c2c2f167def9a775
-  ────────────────────────  ──────────────────────────────────────────
-   Idioma principal          Português
-  ────────────────────────  ──────────────────────────────────────────
-   Técnica de ajuste         LoRA
-  ────────────────────────  ──────────────────────────────────────────
-   Tarefa                    Classificação de sentimentos
-  ────────────────────────  ──────────────────────────────────────────
-   Classes                   Negativo, neutro e positivo
-  ────────────────────────  ──────────────────────────────────────────
-   Formato de saída          JSON
-  ────────────────────────  ──────────────────────────────────────────
-   Estado dos pesos          LoRA mesclado ao modelo-base
-  ────────────────────────  ──────────────────────────────────────────
-   Biblioteca                Transformers
-  ────────────────────────  ──────────────────────────────────────────
-   Precisão dos pesos        FP16
-
-  Este repositório contém o modelo completo após o merge do adapter LoRA. Portanto, não é necessário instalar PEFT nem carregar um adapter separadamente para realizar inferência.
-
-  ## Resultados
-
-  O modelo foi avaliado em um conjunto congelado de 612 amostras, separado para avaliação do projeto.
-
-   Métrica                     Modelo-base    EscutIA LoRA
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━  ━━━━━━━━━━━━━  ━━━━━━━━━━━━━━
-   Acurácia de sentimento           40,20%          64,05%
-  ──────────────────────────  ─────────────  ──────────────
-   Respostas em JSON válido         81,54%         100,00%
-
-  O fine-tuning proporcionou um aumento de aproximadamente 23,85 pontos percentuais na acurácia em relação ao modelo-base.
-
-  Durante a etapa de validação do treinamento, foram observados:
-
-   Métrica       Resultado
-  ━━━━━━━━━━━━  ━━━━━━━━━━━
-   eval_loss        0,0846
-  ────────────  ───────────
-   train_loss       0,0902
-  ────────────  ───────────
-   Épocas                2
-
-  > Os resultados representam o conjunto de avaliação utilizado neste projeto e não garantem o mesmo desempenho em outros domínios, estilos de escrita ou distribuições de dados.
-
-  ## Uso recomendado
-
-  O modelo foi treinado para receber instruções no formato conversacional do Qwen. Para obter resultados consistentes, preserve o prompt e utilize geração determinística.
-
-  import json
-  from transformers import pipeline
-
-  MODEL_ID = "mdba/escutia-lora"
-
-  classificador = pipeline(
-      task="text-generation",
-      model=MODEL_ID,
-      device_map="auto",
-  )
-
-  texto = "Gostei muito do atendimento, foi excelente!"
-
-  mensagens = [
-      {
-          "role": "system",
-          "content": (
-              "Você é um roteador de sentimentos. "
-              "Responda somente com JSON válido no formato "
-              '{"sentimento":"negativo|neutro|positivo"}.'
-          ),
-      },
-      {
-          "role": "user",
-          "content": (
-              "Classifique o sentimento predominante do texto como negativo, "
-              "neutro ou positivo e responda somente com um JSON válido no "
-              'formato {"sentimento":"<rotulo>"}.\n\n'
-              f"Texto: {texto}"
-          ),
-      },
-  ]
-
-  resultado = classificador(
-      mensagens,
-      max_new_tokens=24,
-      do_sample=False,
-      return_full_text=False,
-  )[0]["generated_text"]
-
-  if isinstance(resultado, list):
-      resultado = resultado[-1]["content"]
-
-  sentimento = json.loads(resultado)
-  print(sentimento)
-
-  Saída esperada:
-
-  {
-    "sentimento": "positivo"
-  }
-
-  ## Carregamento manual
-
-  Também é possível carregar o modelo e o tokenizer diretamente com Transformers:
-
-  import torch
-  from transformers import AutoModelForCausalLM, AutoTokenizer
-
-  MODEL_ID = "mdba/escutia-lora"
-
-  tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)
-
-  model = AutoModelForCausalLM.from_pretrained(
-      MODEL_ID,
-      dtype=torch.float16,
-      device_map="auto",
-  )
-
-  ## Formato de resposta
-
-  Quando utilizado com o prompt recomendado, o modelo deve retornar apenas:
-
-  {"sentimento":"positivo"}
-
-  O campo sentimento deve conter um destes valores:
-
-   Valor       Interpretação
-  ━━━━━━━━━━  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   negativo    Predomínio de insatisfação, tristeza, raiva, rejeição ou crítica
-  ──────────  ──────────────────────────────────────────────────────────────────
-   neutro      Texto informativo, ambíguo ou sem polaridade predominante
-  ──────────  ──────────────────────────────────────────────────────────────────
-   positivo    Predomínio de satisfação, alegria, aprovação ou elogio
-
-  Mesmo com uma taxa de 100% de JSON válido no conjunto avaliado, aplicações em produção devem validar a estrutura e os valores retornados antes de consumi-los.
-
-  ## Treinamento
-
-  O ajuste foi realizado com Supervised Fine-Tuning e LoRA sobre o modelo Qwen/Qwen2.5-0.5B-Instruct.
-
-  ### Configuração principal
-
-   Parâmetro                                         Valor
-  ━━━━━━━━━━━━━━━━━━━━━━━  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   Épocas                                                2
-  ───────────────────────  ────────────────────────────────
-   Learning rate                                      1e-4
-  ───────────────────────  ────────────────────────────────
-   Batch por dispositivo                                 1
-  ───────────────────────  ────────────────────────────────
-   Gradient accumulation                                 8
-  ───────────────────────  ────────────────────────────────
-   Comprimento máximo                           256 tokens
-  ───────────────────────  ────────────────────────────────
-   LoRA rank                                             8
-  ───────────────────────  ────────────────────────────────
-   LoRA alpha                                           16
-  ───────────────────────  ────────────────────────────────
-   LoRA dropout                                       0,05
-  ─���─────────────────────  ────────────────────────────────
-   Módulos ajustados        q_proj, k_proj, v_proj, o_proj
-  ───────────────────────  ────────────────────────────────
-   Scheduler                                        Cosine
-  ───────────────────────  ────────────────────────────────
-   Otimizador                                        AdamW
-  ───────────────────────  ────────────────────────────────
-   Seed                                                 42
-
-  Após o treinamento, os pesos LoRA foram incorporados ao modelo-base e salvos em FP16.
-
-  ## Casos de uso
-
-  O modelo pode ser utilizado em:
-
-  - classificação de avaliações e comentários;
-  - análise de feedback de usuários;
-  - triagem de mensagens;
-  - monitoramento exploratório de sentimento;
-  - roteamento de solicitações por polaridade;
-  - experimentos educacionais com fine-tuning e LoRA.
-
-  ## Limitações
-
-  Este é um modelo experimental e possui limitações importantes:
-
-  - A acurácia observada foi de 64,05%; portanto, classificações incorretas ainda são esperadas.
-  - Ironia, sarcasmo, humor, negação complexa e mensagens ambíguas podem ser classificados incorretamente.
-  - Textos muito diferentes dos utilizados no treinamento podem apresentar desempenho inferior.
-  - O modelo classifica apenas o sentimento predominante e não identifica múltiplos sentimentos simultâneos.
-  - As classes disponíveis são limitadas a negativo, neutro e positivo.
-  - O modelo não fornece probabilidades calibradas nem uma medida confiável de confiança.
-  - Entradas muito longas podem perder informação relevante devido ao limite utilizado durante o treinamento.
-  - O modelo pode reproduzir vieses presentes no modelo-base ou nos dados de treinamento.
-
-  ## Uso responsável
-
-  Não utilize este modelo como único critério para decisões de alto impacto envolvendo pessoas, incluindo decisões médicas, financeiras, jurídicas, educacionais, trabalhistas ou de
-  moderação punitiva.
-
-  Em aplicações sensíveis, recomenda-se:
-
-  1. validar o desempenho com dados representativos do domínio;
-  2. manter revisão humana;
-  3. monitorar erros por classe e grupo;
-  4. registrar entradas, versões e resultados;
-  5. implementar tratamento para respostas inválidas ou inesperadas.
-
-  ## Sobre o projeto
-
-  O EscutIA é um projeto de estudo e experimentação com modelos de linguagem, fine-tuning eficiente e classificação estruturada de sentimentos em português.
-
-  Este modelo foi desenvolvido com finalidade educacional e experimental.
-
-  A parte mais importante dessa versão é que ela não tenta vender o modelo como mais preciso do que realmente é: apresenta os 64,05% de acurácia, compara com o modelo-base,
-  demonstra o prompt correto e explica claramente as limitações. Isso transmite bem mais profissionalismo do que apenas colocar um exemplo que funciona.
+---
+base_model: Qwen/Qwen2.5-1.5B-Instruct
+base_model_relation: finetune
+library_name: transformers
+language:
+- pt
+pipeline_tag: text-generation
+tags:
+- qlora
+- merged
+- sentiment-analysis
+- portuguese
+---
+
+# EscutIA QLoRA
+
+Modelo para classificação de sentimentos em português, treinado com QLoRA e mesclado ao modelo-base Qwen/Qwen2.5-1.5B-Instruct.
+
+Este repositório contém os pesos completos e pode ser carregado diretamente com transformers; não é necessário aplicar um adapter PEFT separado.
+
+Exemplo:
+
+    from transformers import AutoModelForCausalLM, AutoTokenizer
+    model_id = "mdba/escutia-qlora"
+    tokenizer = AutoTokenizer.from_pretrained(model_id)
+    model = AutoModelForCausalLM.from_pretrained(model_id, device_map="auto")