--- language: - pt license: apache-2.0 tags: - spiritism - kardec - espiritismo - allan-kardec - religion - portuguese - brazilian - fine-tuned - qlora - llama-3.1 - spirituality - riv-ai - espírita - unsloth - GGUF - llama.cpp datasets: - ia-espirita/riv-ai-v2-dataset base_model: meta-llama/Meta-Llama-3.1-8B-Instruct pipeline_tag: text-generation model-index: - name: riv-ai-v2 results: [] --- # 🔼 RIV AI v2 — Modelo de IA Espírita Open Source

> **🆕 VersĂŁo 2.0 — atualização significativa.** Esta Ă© a evolução do [RIV AI v1](https://huggingface.co/ia-espirita/riv-ai), agora baseada em **Llama 3.1** e treinada com a obra de **Allan Kardec praticamente completa**: as 5 obras da Codificação + obras complementares + Revistas EspĂ­ritas (1858–1869). Dataset **4× maior** que a v1. **RIV AI** (homenagem a Hippolyte LĂ©on Denizard **Riv**ail — Allan Kardec) Ă© um modelo de linguagem open-source treinado na **Doutrina EspĂ­rita**, conforme codificada e desenvolvida por **Allan Kardec**. A v2 foi fine-tunada via **QLoRA** sobre o **Llama 3.1 8B Instruct** com um dataset expandido de **4.896 pares de pergunta/resposta** extraĂ­dos da obra integral de Kardec. O objetivo Ă© oferecer um assistente que responda sobre a Doutrina com **fidelidade doutrinĂĄria** e **citação de fontes**, servindo como ferramenta de estudo, divulgação e replicação cientĂ­fica. > *"O Espiritismo Ă© uma ciĂȘncia que trata da natureza, origem e destino dos EspĂ­ritos, bem como de suas relaçÔes com o mundo corporal."* > — Allan Kardec, *O Livro dos EspĂ­ritos*, Introdução. --- ## 🆕 O que mudou da v1 para a v2 | | **v1** | **v2** | |---|---|---| | **Modelo base** | Llama 3.0 8B Instruct | **Llama 3.1 8B Instruct** | | **Pares no dataset** | ~1.200 | **4.896** (4× maior) | | **Cobertura doutrinĂĄria** | 5 obras da Codificação | **Codificação + Complementares + Revistas EspĂ­ritas** | | **Épocas** | 3 | 2 (compensa o dataset maior, evita overfit) | | **Total de steps** | ~450 | 1.224 | | **Loss final** | 0,64 | **0,74** (esperado e desejado — ver explicação abaixo) | | **RepositĂłrio** | `ia-espirita/riv-ai` | `ia-espirita/riv-ai-v2` | ### Por que a loss da v2 Ă© maior — e por que isso Ă© positivo A loss absoluta da v2 (0,74) Ă© numericamente maior que a v1 (0,64), mas isso **nĂŁo significa pior qualidade**. Pelo contrĂĄrio: - **Dataset 4× maior** = maior diversidade lexical e temĂĄtica → o modelo generaliza em vez de memorizar - **2 Ă©pocas vs 3** = redução intencional de exposição repetida → menos overfitting literal - **Cobertura ampliada** = mais conceitos novos sendo aprendidos → loss converge mais alto, mas a representação Ă© mais rica Em resumo: a v1 ficou mais "decorada" no escopo restrito da Codificação. A v2 estĂĄ mais "compreendendo" um corpus muito maior. Para uso real (RAG + geração), a v2 entrega respostas mais robustas e com contextualização mais ampla. --- ## 📩 Arquivos disponĂ­veis | Arquivo | Formato | Tamanho | Uso | |---------|---------|---------|-----| | `meta-llama-3.1-8b-instruct.Q4_K_M.gguf` | GGUF 4-bit | ~4,9 GB | Ollama, LM Studio, llama.cpp | | `adapter_model.safetensors` | LoRA adapter | ~168 MB | Transformers + PEFT (Python) | | Modelo merged 16-bit | Safetensors (4 shards) | ~16 GB | vLLM, deploy server | --- ## 🎯 Para que serve? Este modelo foi criado para responder perguntas sobre a Doutrina EspĂ­rita com: - **PrecisĂŁo doutrinĂĄria** — fundamentado na obra integral de Allan Kardec - **Citação de fontes** — toda resposta referencia livro, questĂŁo e/ou capĂ­tulo - **Tom acolhedor e didĂĄtico** — como um amigo estudioso explicando Kardec - **Analogias modernas** — traduz conceitos espĂ­ritas para linguagem contemporĂąnea quando apropriado - **PortuguĂȘs brasileiro** — treinado nativamente em PT-BR ### Exemplos de perguntas que o modelo responde: | Pergunta | Fonte da resposta | |----------|-------------------| | O que Ă© Deus? | *O Livro dos EspĂ­ritos*, questĂŁo 1 | | Animais tĂȘm espĂ­rito? | *O Livro dos EspĂ­ritos*, questĂ”es 597-602 | | O que acontece quando morremos? | *O Livro dos EspĂ­ritos*, questĂ”es 149-165 | | O que Ă© mediunidade? | *O Livro dos MĂ©diuns*, cap. 14 | | O que Ă© o perispĂ­rito? | *O Livro dos EspĂ­ritos*, questĂ”es 93-95 | | Como surgiu o Espiritismo? | *Revista EspĂ­rita*, 1858 / *O Que É o Espiritismo* | | O que Ă© o Espiritismo em poucas palavras? | *O Que É o Espiritismo*, "Resumo da Doutrina" | | Como conduzir uma sessĂŁo mediĂșnica? | *InstruçÔes PrĂĄticas sobre as ManifestaçÔes EspĂ­ritas* (1858) | | Existe cĂ©u e inferno? | *O CĂ©u e o Inferno*, Parte Primeira | | Como fazer o Evangelho no Lar? | *O Evangelho Segundo o Espiritismo*, cap. 28 | | CiĂȘncia e Espiritismo se contradizem? | *A GĂȘnese*, cap. 1 | --- ## đŸ’» Como usar ### Com Ollama (mais fĂĄcil) ```bash ollama run iaespirita/riv-ai-v2 ``` Modelo disponĂ­vel em: [ollama.com/iaespirita/riv-ai-v2](https://ollama.com/iaespirita/riv-ai-v2) ### Com LM Studio 1. Baixe o arquivo `meta-llama-3.1-8b-instruct.Q4_K_M.gguf` deste repositĂłrio 2. Abra o LM Studio e importe o arquivo 3. Configure o system prompt: > *VocĂȘ Ă© RIV AI, um assistente especializado em Doutrina EspĂ­rita. Responda de forma objetiva, didĂĄtica e precisa, sempre citando a fonte (obra, questĂŁo ou capĂ­tulo) ao final. Use portuguĂȘs brasileiro.* 4. Comece a conversar ### Com llama.cpp ```bash llama-cli -hf ia-espirita/riv-ai-v2 --jinja ``` ### Com Transformers (Python) ```python from transformers import AutoTokenizer, AutoModelForCausalLM model_name = "ia-espirita/riv-ai-v2" tokenizer = AutoTokenizer.from_pretrained(model_name) model = AutoModelForCausalLM.from_pretrained(model_name) messages = [ {"role": "system", "content": "VocĂȘ Ă© RIV AI, um assistente especializado em Doutrina EspĂ­rita. Responda de forma objetiva, didĂĄtica e precisa, sempre citando a fonte (obra, questĂŁo ou capĂ­tulo) ao final. Use portuguĂȘs brasileiro."}, {"role": "user", "content": "O que acontece quando morremos?"} ] input_ids = tokenizer.apply_chat_template(messages, return_tensors="pt") output = model.generate(input_ids, max_new_tokens=512, temperature=0.7) print(tokenizer.decode(output[0], skip_special_tokens=True)) ``` ### Com vLLM (servidor OpenAI-compatible) ```bash python -m vllm.entrypoints.openai.api_server \ --model ia-espirita/riv-ai-v2 \ --port 8000 ``` --- ## 📚 Fontes do treinamento O dataset v2 foi construĂ­do a partir da **obra integral de Allan Kardec em domĂ­nio pĂșblico**, organizada em trĂȘs blocos: ### Bloco 1 — Codificação EspĂ­rita (5 obras canĂŽnicas) | Obra | Ano | Estrutura | Tema central | |------|-----|-----------|--------------| | **O Livro dos EspĂ­ritos** | 1857 | 1.019 questĂ”es em 4 partes | Deus, espĂ­ritos, leis morais, vida futura | | **O Livro dos MĂ©diuns** | 1861 | 32 capĂ­tulos, 370 itens | Mediunidade, manifestaçÔes e comunicação | | **O Evangelho Segundo o Espiritismo** | 1864 | 28 capĂ­tulos | Moral de Jesus Ă  luz do Espiritismo | | **O CĂ©u e o Inferno** | 1865 | 2 partes (doutrina + relatos) | Justiça divina, penas e recompensas futuras | | **A GĂȘnese** | 1868 | 18 capĂ­tulos | CiĂȘncia e Espiritismo: criação, milagres, profecias | ### Bloco 2 — Obras complementares de Kardec | Obra | Ano | Estrutura | Tema central | |------|-----|-----------|--------------| | **InstruçÔes PrĂĄticas sobre as ManifestaçÔes EspĂ­ritas** | 1858 | Manual prĂĄtico | Primeira obra de Kardec sobre o tema. Como conduzir reuniĂ”es mediĂșnicas, glossĂĄrio inicial | | **O Que É o Espiritismo** | 1859 | OpĂșsculo em 3 capĂ­tulos | Introdução em formato de diĂĄlogo: explica a Doutrina para iniciantes e cĂ©ticos | ### Bloco 3 — Revistas EspĂ­ritas | Obra | Ano | Estrutura | Tema central | |------|-----|-----------|--------------| | **Revista EspĂ­rita — Jornal de Estudos PsicolĂłgicos** | 1858–1869 | 12 volumes anuais | PeriĂłdico mensal editado por Kardec. Artigos, comunicaçÔes mediĂșnicas, debates, comentĂĄrios doutrinĂĄrios, casos prĂĄticos | **Todas as obras sĂŁo de domĂ­nio pĂșblico** (Allan Kardec faleceu em 1869; obras publicadas entre 1857–1869). --- ## 🔧 Detalhes tĂ©cnicos do treinamento | ParĂąmetro | Valor | |-----------|-------| | **Modelo base** | `meta-llama/Meta-Llama-3.1-8B-Instruct` | | **MĂ©todo** | QLoRA (4-bit quantization) | | **Framework** | Unsloth 2026.4.8 (2× faster) | | **Dataset** | 4.896 pares Q&A no formato ShareGPT | | **Idioma** | PortuguĂȘs Brasileiro | | **Hardware** | NVIDIA Tesla T4 (Google Colab) | | **PrecisĂŁo** | fp16 (T4 nĂŁo suporta bf16) | | **Épocas** | 2 | | **Total steps** | 1.224 | | **Batch size efetivo** | 8 (2 per device × 4 gradient accumulation × 1 GPU) | | **Learning rate** | 2e-4 | | **LR scheduler** | linear | | **Warmup steps** | 10 | | **Weight decay** | 0,01 | | **Optimizer** | AdamW 8-bit | | **LoRA rank (r)** | 16 | | **LoRA alpha** | 32 | | **LoRA dropout** | 0 | | **LoRA target modules** | q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj | | **Trainable parameters** | 41.943.040 / 8.072.204.288 (**0,52%**) | | **Max seq length** | 2048 | | **Random seed** | 3407 | | **Gradient checkpointing** | Unsloth optimized | | **Tempo de treino** | ~1h50min em T4 | | **GGUF quantization** | Q4_K_M (~4,9 GB) | ### Curva de loss (amostragem a cada 20 steps) ``` Step 20 → 1,669 (warmup) Step 100 → 1,010 Step 200 → 1,003 Step 300 → 0,969 Step 400 → 0,957 Step 500 → 0,958 Step 600 → 0,938 (fim da Ă©poca 1) Step 620 → 0,856 (inĂ­cio da Ă©poca 2 — drop natural) Step 700 → 0,762 Step 800 → 0,755 Step 900 → 0,741 Step 1000 → 0,731 Step 1100 → 0,741 Step 1180 → 0,742 (convergĂȘncia) ``` A curva mostra duas fases distintas: **descida acentuada no warmup → estabilização ao redor de 0,95 na primeira Ă©poca → segundo drop quando inicia a segunda Ă©poca → convergĂȘncia estĂĄvel em ~0,74**. --- ## 📊 Dataset O dataset estĂĄ publicado em [`ia-espirita/riv-ai-v2-dataset`](https://huggingface.co/datasets/ia-espirita/riv-ai-v2-dataset). ### Distribuição por bloco | Bloco | Pares aproximados | |-------|-------------------| | Codificação EspĂ­rita (5 obras) | ~1.200 | | Obras complementares (InstruçÔes PrĂĄticas + O Que É o Espiritismo) | ~600 | | Revistas EspĂ­ritas (12 volumes) | ~3.000 | | Temas modernos / sintĂ©ticos / existenciais | ~100 | | **Total** | **4.896** | ### Formato ```json { "conversations": [ {"from": "human", "value": "Animais tĂȘm alma segundo a Doutrina EspĂ­rita?"}, {"from": "gpt", "value": "Sim, os animais possuem um princĂ­pio inteligente que sobrevive Ă  morte do corpo fĂ­sico. Esse princĂ­pio evolui progressivamente atravĂ©s dos reinos da natureza...\n\n📖 Fonte: O Livro dos EspĂ­ritos, questĂ”es 597-602."} ] } ``` --- ## 🔼 Por que "RIV"? **RIV** Ă© uma homenagem a **Riv**ail — o verdadeiro nome de Allan Kardec. Hippolyte LĂ©on Denizard Rivail (1804-1869) foi o pedagogo francĂȘs que codificou a Doutrina EspĂ­rita. Ele adotou o pseudĂŽnimo "Allan Kardec" para separar seu trabalho acadĂȘmico da obra espĂ­rita. O nome RIV AI conecta a tradição kardecista com a era da inteligĂȘncia artificial — o passado e o futuro do conhecimento espĂ­rita. --- ## ⚠ LimitaçÔes e uso responsĂĄvel - Este modelo Ă© uma **ferramenta de estudo**, nĂŁo substitui a leitura das obras originais de Allan Kardec. - **CitaçÔes especĂ­ficas (questĂ”es, capĂ­tulos, itens) podem conter imprecisĂ”es.** O modelo aprende a estrutura e o conceito doutrinĂĄrio, mas pode ocasionalmente gerar numeraçÔes incorretas. **Sempre verifique a citação na obra original.** - NĂŁo Ă© um mĂ©dium e nĂŁo recebe mensagens de espĂ­ritos. - NĂŁo faz previsĂ”es do futuro nem prescreve tratamentos mĂ©dicos. - Para questĂ”es de mediunidade prĂĄtica, sempre procure um centro espĂ­rita presencialmente. - Para temas sensĂ­veis como suicĂ­dio, o modelo orienta o contato com o **CVV (188)**. - O dataset desta v2 cobre a obra de **Allan Kardec**. Para conteĂșdo da sĂ©rie AndrĂ© Luiz (psicografia de Chico Xavier), use o modelo companheiro [`ia-espirita/andre-luiz-ai`](https://huggingface.co/ia-espirita/andre-luiz-ai). Obras de Emmanuel, Divaldo Franco e outros autores mediĂșnicos poderĂŁo ser incluĂ­das em versĂ”es futuras. --- ## đŸ—ș Roadmap - [x] **v1.0** — Codificação EspĂ­rita (5 obras de Allan Kardec) - [x] **v2.0** — Codificação + InstruçÔes PrĂĄticas + O Que É o Espiritismo + Revistas EspĂ­ritas (este modelo) - [ ] **v3.0** — Obras de Emmanuel, Divaldo Franco e ESDE - [ ] **v4.0** — VersĂŁo em Espanhol (es) - [ ] **v5.0** — VersĂŁo em InglĂȘs (en) --- ## 🌐 Projeto IA.Espirita O RIV AI v2 Ă© a versĂŁo open-source do projeto IA.Espirita — Doutrina EspĂ­rita na Era da InteligĂȘncia Artificial. O **RIV IA** ([iaespirita.com](https://iaespirita.com)) usa uma arquitetura mais robusta (modelo base maior com reasoning + RAG estrito sobre o mesmo corpus), enquanto este modelo Ă© publicado como artefato de pesquisa, replicação e deploy offline. | Plataforma | Link | |------------|------| | 🌐 Site | [iaespirita.com](https://iaespirita.com) | | đŸ€– RIV IA (chatbot) | [Converse agora](https://iaespirita.com) | | ▶ YouTube | [@ia.espirita](https://youtube.com/@ia.espirita) | | đŸŽ” TikTok | [@ia.esprita](https://tiktok.com/@ia.esprita) | | 📾 Instagram | [@ia.espirita](https://instagram.com/ia.espirita) | | 🎧 Spotify | [IA.Espirita Podcast](https://open.spotify.com/show/4Xf22wuDUlJUnMx2hjWV7A) | | 🐩 X/Twitter | [@IAEspiritaBR](https://x.com/IAEspiritaBR) | | 📧 E-mail | [contato@iaespirita.com.br](mailto:contato@iaespirita.com.br) | --- ## 📜 Licença O modelo Ă© distribuĂ­do sob licença **Apache 2.0**. As obras de Allan Kardec utilizadas no treinamento sĂŁo de **domĂ­nio pĂșblico** (publicadas entre 1857-1869). --- ## 🙏 Citação ```bibtex @misc{iaespirita2026rivaiv2, title={RIV AI v2: Modelo de IA EspĂ­rita Open Source baseado na obra integral de Allan Kardec}, author={IA.Espirita}, year={2026}, url={https://huggingface.co/ia-espirita/riv-ai-v2}, note={Fine-tuned on Llama 3.1 8B Instruct with QLoRA using Allan Kardec's complete works (Codification + Practical Instructions + What is Spiritism + Revue Spirite 1858-1869)} } ``` --- ## đŸ€ ContribuiçÔes ContribuiçÔes sĂŁo bem-vindas. Se vocĂȘ Ă© estudioso da Doutrina EspĂ­rita e/ou desenvolvedor: - 📝 Revise e expanda o dataset com novas perguntas e respostas - đŸ§Ș Teste o modelo e reporte erros doutrinĂĄrios (especialmente citaçÔes imprecisas) - 🌍 Ajude a traduzir o dataset para espanhol e inglĂȘs - 📚 Contribua com dados de obras mediĂșnicas para as prĂłximas versĂ”es Abra uma issue ou pull request neste repositĂłrio. ---


"Nascer, morrer, renascer ainda e progredir sem cessar, tal Ă© a Lei."
— Allan Kardec, epitĂĄfio em seu tĂșmulo no cemitĂ©rio PĂšre-Lachaise, Paris.