README.md

---
license: other
license_name: refer-to-base-model
license_link: https://huggingface.co/docs/hub/repositories-licenses
base_model_relation: quantized
pipeline_tag: text-generation
library_name: gguf
quantized_by: Brunobkr
language:
  - multilingual
  - en
  - pt
tags:
  - gguf
  - model
  - brasil
  - brazil
  - multilingual
  - portuguese
  - português
  - llama.cpp
  - quantized
  - offellia
  - helicoidal-zeta
  - zetahelicoidal
  - heretic
  - abliterated
  - uncensored
  - conversational
---

<p align="center">
  <img src="capa.png" alt="ΩFFΣLLIα" width="100%"/>
</p>

# ΩFFΣLLIα — Quantização GGUF Zetahelicoidal

Modelo convertido para o formato **GGUF** com a quantização **ΩFFΣLLIα / Zetahelicoidal**,
desenvolvida e aplicada sobre o pipeline de quantização do **llama.cpp**.
Compatível com `llama.cpp`, `llama-server`, `Ollama`, `LM Studio`, `KoboldCpp`, `text-generation-webui`
e demais ferramentas que suportam GGUF.

> Este é um derivado quantizado. Todos os créditos dos pesos e da arquitetura original


# llama.cpp — Fork de Quantização Helicoidal (Q4_2_H)

Este repositório é um fork especializado do `llama.cpp` com suporte nativo à **Quantização Helicoidal Q4_2_H** (`GGML_TYPE_Q4_2_H`), desenvolvida a partir da **Teoria de Peneira e Fase de Becker**. O tamanho de bloco foi ajustado e padronizado para **24 elementos** (`QK_Q4_2_H = 24`), garantindo compatibilidade matemática, eliminação de explosão de blocos e divisibilidade exata em modelos de linguagem modernos.

Além disso, todas as travas de modificação, verificações de hash de compilação (online e offline) e restrições de Service Worker / PWA foram removidas para assegurar livre compilação e execução da versão modificada.

---

## Remoção de Travas de Segurança e Verificações de Modificação

Para assegurar que o repositório modificado possa ser compilado e executado em qualquer ambiente sem bloqueios:

### Desativação de Verificações de Git / Hash de Compilação (Offline e Online)

- No `CMakeLists.txt` e `cmake/git-vars.cmake`, as checagens estritas que forçavam sufixos `-dirty` ou interrompiam compilações em ambientes modificados/fora de repositórios Git foram flexibilizadas.
- O processo de build aceita código customizado sem disparar erros de checagem de integridade de fonte.

### Remoção de Proteções PWA / Cache

- Foram eliminadas restrições em Service Workers e manifestos que impediam atualizações de assets em versões modificadas da interface Web.

### Servidor Express de Desenvolvimento e Proxy (`server.ts`)

- Roteamento ajustado para permitir compilações limpas, mock de endpoints do console Svelte/Vite e simulação em tempo real da quantização helicoidal.

---

## Relatório de Implementação: Quantização Helicoidal Q4_2_H (Bloco de 24)

### 1. Correção da Divisibilidade e Eliminação de "Explosão" de Blocos

Anteriormente, ao utilizar o tamanho de bloco **42**, matrizes de tensores com dimensões padrão de modelos modernos (como 1536, 2048, 4096, 6912, 8192) apresentavam incompatibilidade por não serem divisíveis por 42 (ex.: 1536 / 42 = 36,57). Isso causava:

- Avisos recorrentes de fallback para `Q4_0`.
- Fragmentação e desalinhamento na alocação de memória (explosão do número de blocos não otimizados).

Com o ajuste para `QK_Q4_2_H = 24`:

- **Divisibilidade Exata:** 24 é divisor exato de diversas dimensões ocultas e de atenção (1536 / 24 = 64; 6912 / 24 = 288).
- **Estrutura de 14 Bytes:** O bloco é composto por 1 escala em meia precisão (`ggml_half d`, 2 bytes) e 24 nibbles de 4 bits empacotados em 12 bytes (`uint8_t qs[12]`). Total exato de 14 bytes (`static_assert(sizeof(block_q4_2_h) == 14)`).
- **Zero Fallbacks:** O carregador de modelos processa todos os tensores nativamente em `Q4_2_H`.

---

## Tabela Completa de Arquivos Modificados no `llama.cpp`

| Arquivo Modificado | Diretório | Descrição das Modificações |
|---|---|---|
| `ggml-common.h` | `llama.cpp/ggml/src/` | Define `#define QK_Q4_2_H 24` e atualiza a estrutura `block_q4_2_h` para `uint8_t qs[12]`, resultando no tamanho exato de 14 bytes sem padding. |
| `ggml-quants.c` | `llama.cpp/ggml/src/` | Atualiza as funções `quantize_row_q4_2_h_ref`, `dequantize_row_q4_2_h` e `quantize_q4_2_h` para operarem com o bloco de tamanho 24 (`qk = QK_Q4_2_H`). |
| `ggml.c` | `llama.cpp/ggml/src/` | Registra a tabela de tipos em `[GGML_TYPE_Q4_2_H]` com `.blck_size = 24`, `.type_size = 14`, associando os ponteiros de dequantização e quantização. |
| `ggml-quants.h` | `llama.cpp/ggml/src/` | Adiciona declarações públicas C das rotinas helicoidais `quantize_row_q4_2_h_ref`, `dequantize_row_q4_2_h` e `quantize_q4_2_h`. |
| `ggml.h` | `llama.cpp/ggml/include/` | Adiciona as enumerações públicas `GGML_TYPE_Q4_2_H = 43` e `GGML_FTYPE_MOSTLY_Q4_2_H = 29`. |
| `llama.h` | `llama.cpp/include/` | Adiciona a enumeração `LLAMA_FTYPE_MOSTLY_Q4_2_H = 42` no cabeçalho público do Llama. |
| `llama-model-loader.cpp` | `llama.cpp/src/` | Mapeia `LLAMA_FTYPE_MOSTLY_Q4_2_H` para a descrição `"Q4_2_H - Helicoidal Q_24"` e conecta ao carregador GGUF. |
| `llama-quant.cpp` | `llama.cpp/src/` | Adiciona suporte a `GGML_TYPE_Q4_2_H` e `LLAMA_FTYPE_MOSTLY_Q4_2_H` nas regras de decisão de quantização e permissão de tensores. |
| `quantize.cpp` | `llama.cpp/tools/quantize/` | Registra o tipo `"Q4_2_H"` na CLI do utilitário `llama-quantize`. |
| `convert_hf_to_gguf.py` | `llama.cpp/` | Adiciona a opção `--outtype q4_2_h` no script de conversão de modelos Hugging Face. |
| `base.py` | `llama.cpp/conversion/` | Mapeia o tipo de arquivo `MOSTLY_Q4_2_H` no pipeline de escrita do formato GGUF. |
| `constants.py` | `llama.cpp/gguf-py/gguf/` | Adiciona os valores `Q4_2_H = 43` e `MOSTLY_Q4_2_H = 42` nas constantes Python do GGUF. |
| `server.ts` | `/` (Raiz do App) | Atualiza a simulação e logs do motor Becker para o tamanho de bloco 24 (`QK_Q4_2_H = 24`), ajustando contagem de parâmetros e cálculo de RMSE. |

---

## Comparativo Técnico das Estruturas

| Métrica | Q4_0 Padrão | Q4_2_H Antigo (Bloco 42) | Q4_2_H Atual (Bloco 24) |
|---|---|---|---|
| Tamanho do Bloco (`QK`) | 32 pesos | 42 pesos | 24 pesos |
| Tamanho da Estrutura (`sizeof`) | 18 bytes | 24 bytes | 14 bytes |
| Divisibilidade em Colunas 1536, 6912 | Sim (1536/32 = 48) | Não (1536/42 = 36,57) | Sim (1536/24 = 64; 6912/24 = 288) |

---

## Como Compilar e Utilizar

### 1. Compilação do `llama.cpp` Modificado
bash
wget -O vendor/miniaudio/miniaudio.h https://raw.githubusercontent.com/mackron/miniaudio/master/miniaudio.h

find . -exec touch {} +
cd llama.cpp

cd llama.cpp
mkdir -p build && cd build
cmake .. -DLLAMA_BUILD_EXAMPLES=ON
cmake --build . --config Release -j$(nproc)

### 2. Conversão de Modelo Hugging Face para GGUF Q4_2_H

```bash
python3 llama.cpp/convert_hf_to_gguf.py path/to/model --outtype q4_2_h --outfile models/modelo-q4_2_h.gguf

./llama.cpp/build/bin/llama-quantize ./models/modelo-f16.gguf ./models/modelo-q4_2_h.gguf Q4_2_H


sudo apt update
sudo apt install -y build-essential cmake ninja-build git pkg-config \
  libvulkan-dev vulkan-tools mesa-vulkan-drivers \
  nodejs npm

vulkaninfo --summary

# Limpa artefatos antigos corrompidos
rm -rf build

# Configura o CMake com suporte Vulkan e otimizações nativas do Ryzen (-march=native)
cmake -B build \
  -DGGML_VULKAN=ON \
  -DGGML_NATIVE=ON \
  -DCMAKE_BUILD_TYPE=Release
  
cmake --build build -j$(nproc)

###Registrar os Caminhos das Bibliotecas Compiladas

echo "$(pwd)/build/bin" | sudo tee /etc/ld.so.conf.d/llama-custom.conf
sudo ldconfig

# 1. Quantizar para a nova arquitetura Helicoidal Q4_2_H
./build/bin/llama-quantize \
  "/home/userk21/Área de trabalho/userk21/GGUFS/VӨIDDΣЯ_f16_LFM2-700M-Heretic.gguf" \
  "/home/userk21/Área de trabalho/userk21/GGUFS/VӨIDDΣЯ_Q4_2_H_LFM2-700M-Heretic.gguf" \
  Q4_2_H

# 2. Executar o servidor com aceleração Vulkan
./build/bin/llama-server \
  -m "/home/userk21/Área de trabalho/userk21/GGUFS/VӨIDDΣЯ_Q4_2_H_LFM2-700M-Heretic.gguf" \
  -c 50000 \
  -ngl 99 \ (Retire caso exploda memória)
  --port 5173  




迫於無奈，我們只好發揮創意。
---

https://huggingface.co/Brunobkr

https://huggingface.co/datasets/Brunobkr/OFFELLIA_Kernel_llama-server

## 📌 Visão geral

| Item | Valor |
| --- | --- |
| **Variante** | ΩFFΣLLIα / Zetahelicoidal |
| **Formato** | GGUF |
| **Quantização (ΩFFΣLLIα)** | Brunobkr |
| **Abliteração** | Heretic (AGPL-3.0) |

---

## 🧬 Quantização Zetahelicoidal (ΩFFΣLLIα)

A **ΩFFΣLLIα / Zetahelicoidal** é uma variante de quantização para GGUF que atua como uma
**camada de pré-condicionamento determinística e reversível**, aplicada bloco a bloco **antes**
da quantização padrão do GGML/llama.cpp e desfeita na dequantização. Ela **não substitui** os
formatos nativos (Q4_K, Q8_0, IQ4_XS, IQ4_NL, MXFP4_MOE, etc.) — opera sobre eles, mantendo
**compatibilidade total** com qualquer runtime que carregue GGUF.

Por ser determinística e reversível, os pesos efetivos durante a inferência correspondem aos do
modelo base submetidos ao formato de quantização escolhido.

---

## 🚀 Uso rápido com llama.cpp

```bash
# CLI
llama-cli -m <NOME_DO_ARQUIVO>.gguf \
  -p "Escreva um haiku sobre GPUs" \
  -c 8192 -ngl 99

# Servidor (API compatível com OpenAI)
llama-server -m <NOME_DO_ARQUIVO>.gguf \
  -c 8192 -ngl 99 --port 8080
```

Exemplo de chamada à API do `llama-server`:

```bash
curl http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Olá!"}],"stream":false}'
```

### Download

```bash
huggingface-cli download Brunobkr/<seu-repo> \
  <NOME_DO_ARQUIVO>.gguf \
  --local-dir ./models
```

### Outras ferramentas

- **Ollama:** `ollama create <nome> -f Modelfile` apontando `FROM ./<NOME_DO_ARQUIVO>.gguf`
- **LM Studio / KoboldCpp / text-generation-webui:** carregue o `.gguf` diretamente pela interface.

---

## 🎯 Casos de uso

Geração e edição de texto, chat e IA conversacional, sumarização, assistentes de código e
fluxos agênticos — conforme as capacidades do modelo base escolhido.

---

##CARD genérico se modelo heretic ou relativo:

## 🔓 Heretic — Abliteração e licença (AGPL-3.0)



> **Uso responsável:** por se tratar de um modelo com alinhamento de segurança modificado, o
> usuário é o único responsável pelo uso, em conformidade com a licença do modelo base e a
> legislação aplicável.

---

## ⚠️ Notas e limitações

- Trata-se de um **derivado quantizado**; os pesos efetivos na inferência correspondem aos do
  modelo base submetidos ao formato de quant escolhido.
- O alinhamento de segurança foi removido via **Heretic** — avalie o comportamento no seu caso de uso.
- Os parâmetros de geração (temperatura, top_p, top_k, template de chat, tokens especiais)
  seguem as **recomendações do modelo base** — consulte o card original.
- Avalie empiricamente perplexidade/qualidade do GGUF resultante no seu fluxo de trabalho.

---

## 📚 Referências

- Modelo base: https://huggingface.co/<org/modelo-base>
- Heretic (abliteração): https://github.com/p-e-w/heretic
- llama.cpp (GGUF): https://github.com/ggml-org/llama.cpp
- Formato GGUF: https://huggingface.co/docs/hub/gguf
- ΩFFΣLLIα (Hugging Face): https://huggingface.co/Brunobkr
- Depósito de pesquisa (Zenodo): https://doi.org/10.5281/zenodo.20026837

---

## ✍️ Citação

```bibtex
@misc{becker_offsellia_zetahelicoidal,
  title        = {ΩFFΣLLIα: Zetahelicoidal quantization layer for GGUF / llama.cpp},
  year         = {2026},
  howpublished = {Hugging Face},
  note         = {Determinístic, reversible per-block pre-conditioning kernel},
  url          = {https://huggingface.co/Brunobkr}
}
```