| --- |
| license: other |
| license_name: gemma-terms-of-use |
| license_link: https://ai.google.dev/gemma/terms |
| base_model: |
| - google/gemma-4-E2B-it |
| tags: |
| - code |
| - vision |
| - multimodal |
| - gemma4 |
| - software-engineering |
| - react-native |
| - android |
| - typescript |
| - python |
| - unsloth |
| language: |
| - pt |
| - en |
| pipeline_tag: image-text-to-text |
| --- |
| |
| # 🚀 SpaceCode-E2B (Versão Oficial V12 — Merged 16-bit) |
|
|
| **SpaceCode-E2B** é um modelo compacto e multimodal de alta precisão especializado em **Engenharia de Software, Desenvolvimento Mobile/Web (React Native, TypeScript, Python 3.12, Android) e Tutoria Acadêmica**, construído sobre a arquitetura **Google Gemma 4 E2B (`google/gemma-4-E2B-it`)** pela **SpaceGhost**. |
|
|
| > **Versão Oficial Atual:** `V12` (Release Tag: `v12`) |
| > **Formato de Distribuição:** Modelo completo fundido (*Merged 16-bit bfloat16 Safetensors*) |
| > **Modelo-Base:** `google/gemma-4-E2B-it` (Gemma4ForConditionalGeneration) |
| > **Adapter Homologado:** SpaceCode-E2B V12 Checkpoint 345 (`9e250264e93278b65c14d98e27c9631fe293734a04ed7e27140f417fb1396361`) |
| > **Status de Homologação:** ✅ **APROVADO E HOMOLOGADO PELO SOFTWARE ARCHITECT** |
|
|
| --- |
|
|
| ## 📌 1. Visão Geral e Arquitetura |
|
|
| O SpaceCode-E2B V12 unifica as capacidades multimodais de visão e raciocínio técnico do Gemma 4 E2B com especialização rigorosa em código fortemente tipado, padrões arquiteturais modernos, tutoria socrática e mitigação sistemática de alucinações técnicas. |
|
|
| - **Arquitetura Base:** `Gemma4ForConditionalGeneration` (2.3B parâmetros de linguagem + Vision Tower SigLIP). |
| - **Precisão Numérica dos Pesos:** Bfloat16 (16-bit) completo, sem quantização destrutiva na exportação merged. |
| - **Tamanho Total em Disco:** 9,54 GiB (10.242.069.243 bytes distribuídos em 3 shards Safetensors). |
| - **Janela de Contexto Suportada:** 1.536 tokens nominais certificados no treinamento (expansível até 16.384 tokens pelo mecanismo de atenção nativo do Gemma 4). |
|
|
| --- |
|
|
| ## 🛠️ 2. Informações do Treinamento e Fine-Tuning |
|
|
| - **Corpus de Treinamento:** V12 Sequence Gate (1.379 amostras ativas selecionadas com mascaramento estrito de prompt de sistema e labels pedagógicos). |
| - **Estratégia de Adaptação:** QLoRA SFT de alta fidelidade via Unsloth. |
| - Rank ($r$): 16 |
| - Alpha ($\alpha$): 16 |
| - Dropout: 0.05 |
| - Target Modules: Camadas de projeção de atenção e MLP do modelo de linguagem (`q_proj`, `k_proj`, `v_proj`, `o_proj`, `gate_proj`, `up_proj`, `down_proj`). |
| - **Duração do Treinamento:** Exatamente 1 época experimental (345 passos do otimizador AdamW, com gradiente acumulado em 4 micro-lotes e último passo normalizado estritamente por 3.0 amostras). |
| - **Curva de Taxa de Aprendizado:** Cosine schedule com 10 passos de warmup ($2 \times 10^{-4} \to 2 \times 10^{-5}$). |
| - **Progressão de Perda (Loss):** Redução de 1,0356 (Passo 1) para 0,3568 (Passo 345), correspondendo a -65,55% de otimização. |
|
|
| --- |
|
|
| ## 📊 3. Resultados da Avaliação Multimodal MMMU (TASK-0016) |
|
|
| Avaliação pareada e determinística (`temperature = 0.0`, `do_sample = False`) realizada sobre **100 questões oficiais do split de validação do benchmark MMMU (standard)**, distribuídas equitativamente entre 10 disciplinas acadêmicas (10 questões por disciplina): |
|
|
| | Disciplina Acadêmica | Grande Domínio | Gemma 4 E2B Original | SpaceCode-E2B V12 | Delta (p.p.) | Classificação | |
| | :--- | :--- | :---: | :---: | :---: | :--- | |
| | **Computer Science** | Tech & Engineering | 2/10 (20.0%) | **3/10 (30.0%)** | **+10.0%** | **SUPERIOR** | |
| | **Electronics** | Tech & Engineering | 0/10 (0.0%) | **3/10 (30.0%)** | **+30.0%** | **SUPERIOR** | |
| | **Mechanical Engineering** | Tech & Engineering | 0/10 (0.0%) | **1/10 (10.0%)** | **+10.0%** | **SUPERIOR** | |
| | **Math** | Science | 1/10 (10.0%) | **3/10 (30.0%)** | **+20.0%** | **SUPERIOR** | |
| | **Biology** | Science | 2/10 (20.0%) | **4/10 (40.0%)** | **+20.0%** | **SUPERIOR** | |
| | **Chemistry** | Science | 1/10 (10.0%) | **2/10 (20.0%)** | **+10.0%** | **SUPERIOR** | |
| | **Basic Medical Science** | Health & Medicine | 2/10 (20.0%) | **5/10 (50.0%)** | **+30.0%** | **SUPERIOR** | |
| | **Economics** | Business | 2/10 (20.0%) | **5/10 (50.0%)** | **+30.0%** | **SUPERIOR** | |
| | **Psychology** | Humanities & Social | 3/10 (30.0%) | 2/10 (20.0%) | -10.0% | Inferior | |
| | **Art Theory** | Art & Design | 7/10 (70.0%) | 5/10 (50.0%) | -20.0% | Inferior | |
| | **TOTAL GERAL (100 itens)** | **6 Áreas do Conhecimento** | **20/100 (20.0%)** | **33/100 (33.0%)** | **+13.0 p.p.** | **V12 SUPERIOR** | |
|
|
| > **Nota Metodológica Obrigatória:** A bateria acima constitui uma amostra experimental controlada de 100 questões do split de validação do MMMU padrão e **não equivale nem substitui a pontuação do benchmark completo ou do MMMU-Pro** (cujo valor oficial publicado pelo Google para o Gemma 4 E2B completo é de 44,2%). |
|
|
| ### Análise Estatística e Qualitativa: |
| - **Teste de Contingência McNemar:** $\chi^2 = 5,7600$ ($p = 0,0164$, ganho estatisticamente significativo com $p < 0,05$). |
| - **Redução Drástica de Evasão:** O modelo original gerou **52 respostas não interpretáveis (UNPARSED)** por esgotamento de tokens em dissertações reflexivas, enquanto o SpaceCode V12 reduziu esse número para apenas **14 UNPARSED** (-73,08% de respostas inválidas), respondendo de forma concisa e estruturada. |
|
|
| --- |
|
|
| ## 🧪 4. Resultados da Avaliação Funcional Independente (TASK-0015) |
|
|
| O SpaceCode-E2B V12 demonstrou conformidade integral nos testes formais pós-treinamento: |
| 1. **Engenharia de Software (Python 3.12 / Concorrência):** Geração idiomática com `asyncio.TaskGroup`, type hints completos e tratamento gracioso de cancelamento sob exceções. |
| 2. **Conhecimento Conceitual (Teorema CAP):** Síntese precisa dos trade-offs de consistência, disponibilidade e particionamento em bancos de dados distribuídos. |
| 3. **Tutoria Acadêmica (Escopo Léxico e Closure em JS):** Explicação didática clara estruturada em torno de um contador funcional sem jargões desnecessários. |
| 4. **Extração e Formatação Estrita:** Extração precisa de logs em formato JSON puro (`status_code`, `endpoint`, `horario`) sem ruído antes ou depois. |
| 5. **Anti-Alucinação Crítica (Sonda T04):** Recusa categórica e determinística a APIs inexistentes (rejeitando o hook fictício `useLifecycle()` no React Native e instruindo o usuário sobre métodos reais do ciclo de vida e `useEffect`). |
|
|
| --- |
|
|
| ## ⚠️ 5. Limitações Conhecidas |
|
|
| - **Execução em GPU de 8 GB de VRAM:** A viabilidade e a estabilidade de inferência em GPUs de consumo de 8 GB de VRAM **ainda não foi formalmente validada pela Arquitetura**. Embora a estimativa matemática aponte viabilidade sob quantização 4-bit, a homologação oficial para essa classe de hardware ocorrerá em etapa posterior. |
| - **Domínio Multimodal:** O modelo especializou predominantemente a geração de código, tutoria e interfaces móveis/web. Domínios visuais altamente abstratos (como Teoria da Arte pura) preservam as respostas herdadas da base ou podem apresentar variações estilísticas. |
|
|
| --- |
|
|
| ## 💻 6. Como Usar (Inferência com Hugging Face Transformers) |
|
|
| ### Instalação das Dependências: |
| ```bash |
| pip install -q transformers accelerate safetensors torch pillow torchvision |
| ``` |
|
|
| ### Exemplo em Python (Texto e Visão Multimodal): |
| ```python |
| import torch |
| from transformers import AutoProcessor, Gemma4ForConditionalGeneration |
| from PIL import Image |
| |
| MODEL_ID = "SpaceGhost/SpaceCode-E2B" |
| |
| # Carregar processador e modelo completo merged em bfloat16 |
| processor = AutoProcessor.from_pretrained(MODEL_ID) |
| model = Gemma4ForConditionalGeneration.from_pretrained( |
| MODEL_ID, |
| torch_dtype=torch.bfloat16, |
| device_map="auto" |
| ) |
| |
| # 1. Prompt de Código / Engenharia de Software: |
| prompt_code = [ |
| { |
| "role": "user", |
| "content": "Como implementar um hook customizado em React Native com TypeScript para gerenciar conexões WebSocket com reconexão automática e limpeza de memória?" |
| } |
| ] |
| |
| inputs = processor( |
| text=processor.apply_chat_template(prompt_code, tokenize=False, add_generation_prompt=True), |
| return_tensors="pt" |
| ).to("cuda") |
| |
| with torch.no_grad(): |
| outputs = model.generate(**inputs, max_new_tokens=400, do_sample=False) |
| |
| response = processor.tokenizer.decode(outputs[0][inputs.input_ids.shape[1]:], skip_special_tokens=True) |
| print(response) |
| |
| # 2. Prompt Multimodal (com Imagem de Interface UI): |
| # img = Image.open("tela_aplicativo.png").convert("RGB") |
| # msgs = [ |
| # { |
| # "role": "user", |
| # "content": [ |
| # {"type": "image"}, |
| # {"type": "text", "text": "Analise esta tela móvel e forneça os componentes React Native correspondentes."} |
| # ] |
| # } |
| # ] |
| # inp_multi = processor(text=processor.apply_chat_template(msgs, tokenize=False, add_generation_prompt=True), images=[img], return_tensors="pt").to("cuda") |
| # out_multi = model.generate(**inp_multi, max_new_tokens=300, do_sample=False) |
| # print(processor.tokenizer.decode(out_multi[0][inp_multi.input_ids.shape[1]:], skip_special_tokens=True)) |
| ``` |
|
|
| ### Execução Local com Ollama (GGUF): |
|
|
| O modelo conta com versões quantizadas oficiais GGUF disponibilizadas no diretório `gguf/`: |
| - `SpaceCode-E2B-V12-Q8_0.gguf` (4,61 GiB — Alta Precisão de Referência) |
| - `SpaceCode-E2B-V12-Q4_K_M.gguf` (3,18 GiB — Execução Otimizada para Recursos Limitados) |
|
|
| #### Como Criar e Rodar no Ollama: |
| ```bash |
| # 1. Baixar o arquivo Modelfile e o binário GGUF Q4_K_M |
| huggingface-cli download SpaceGhost/SpaceCode-E2B Modelfile --local-dir . |
| huggingface-cli download SpaceGhost/SpaceCode-E2B gguf/SpaceCode-E2B-V12-Q4_K_M.gguf --local-dir . |
| |
| # 2. Criar o modelo localmente no Ollama |
| ollama create spacecode-e2b -f Modelfile |
| |
| # 3. Executar o modelo no terminal |
| ollama run spacecode-e2b |
| ``` |
|
|
| > **Nota sobre Multimodalidade no Ollama:** O suporte a imagens em GGUF no ecossistema Ollama/llama.cpp para a arquitetura Gemma 4 depende da integração completa do projetor visual `mtmd/gemma4v`. Para inferência multimodal integral com visão ativa (texto + imagem), utilize a biblioteca oficial `transformers` com os pesos Safetensors bfloat16 conforme demonstrado acima. |
|
|
| --- |
|
|
| ## 📜 7. Histórico de Versões e Governança |
|
|
| | Versão | Tag da Release | Formato | Status | Destaques | |
| | :---: | :---: | :---: | :---: | :--- | |
| | **V12** | `v12` | **Merged 16-bit Safetensors** | **Atual Oficial** | Merge integral da base Gemma 4 E2B com LoRA V12. +13 p.p. no MMMU, 1.536 tokens, anti-alucinação T04. | |
| | **V11** | `v11` | Adapter LoRA (`specialization-task-0011`) | Homologado Baseline | Baseline imutável preservada (SHA-256: `cb58fbb0...`). | |
| | **V2** | `v2` | Merged 16-bit / GGUF | Histórico | Release inicial baseada na ementa Android/React Native (88% acurácia). | |
|
|
| --- |
|
|
| ## ⚖️ 8. Licença e Atribuições |
|
|
| Este modelo baseia-se no **Google Gemma 4 E2B** e é disponibilizado em estrita conformidade com os termos da [Gemma Terms of Use](https://ai.google.dev/gemma/terms). |
|
|
| *Gemma is a trademark of Google LLC.* |
| *Desenvolvido e mantido pela equipe de Engenharia de Machine Learning da **SpaceGhost**.* |
|
|
