Update README.md

README.md

@@ -1,26 +1,257 @@
----
-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")
+———
+
+  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.