llama.cpp ヴァルカン for AMD

<b>High-Performance LLM / VLM Inference & Autonomous Agentic Ecosystem with Native AMD Vulkan Acceleration, Instella-MoE & LLM-jp-4 Support</b>

<p align="center">
  <a href="#-versão-em-português-pt-br">🇧🇷 <b>Português (PT-BR)</b></a> &nbsp;|&nbsp;
  <a href="#-日本語版-jp">🇯🇵 <b>日本語 (JP)</b></a>
</p>

[](https://opensource.org/licenses/MIT)
[](https://en.cppreference.com/)
[](#-arquitetura-e-aceleração-amd-vulkan)
[](#-suporte-ao-amd-instella-moe--gated-mla)
[](https://svelte.dev/)
[](#-principais-capacidades-do-fork)
[](#-1-centro-de-controle-agêntico-agent-control-center)

</div>

---

# 🇧🇷 Versão em Português (PT-BR)

## 📖 Visão Geral

**llama.cpp_ Vullkan** é um fork avançado, desbloqueado e de altíssimo desempenho do ecossistema `llama.cpp`, projetado com suporte nativo de primeira classe para aceleração de hardware **AMD Vulkan (RADV)** em CPUs e GPUs AMD (da linha Ryzen 5 até Ryzen 9, APUs integradas e placas dedicadas Radeon), com suporte completo para as arquiteturas de ponta da comunidade open-source, incluindo a família **AMD Instella-MoE** (Gated MLA + FarSkip-Collective) e a família **LLM-jp-4** (Unigram Byte-Fallback Tokenizer com OpenAI Harmony Channels).

O projeto une o poder da computação vetorial Vulkan com:
- **Suporte Nativo a AMD Instella-MoE** com Gated MLA (`attn_gate`), FarSkip residual dataflow e conversor HF $\rightarrow$ GGUF integrado;
- **Suporte Completo a LLM-jp-4 (8B & 32B-A3B Thinking/Instruct)** com correção de prefixo de espaço (`lstrip`) em tokenizadores Unigram e parser PEG tolerante a canais Harmony/GPT-OSS;
- **Motor Agêntico Autônomo Multi-Turn** com 6 perfis integrados (incluindo *Polyglot & Localization*);
- **Sistema de Referência Multilíngue de 55 Línguas (`languages_ref`)** para injeção de diretrizes linguísticas e alinhamento de sentenças na memória do LLM;
- **Suporte Nativo a FIM (Fill-in-the-Middle)** para geração e autocompletar código em IDEs;
- **Aceleração MMVQ (Matriz-Vetor Quantizado)** nativa para arquiteturas AMD;
- **Zero-Copy Host Memory** automático para APUs com arquitetura de memória unificada (UMA);
- **Web UI Moderna (SvelteKit + Vite)** com o tema **Cyberpunk Lava Neon** e efeitos dinâmicos de fogo durante o processamento.

---

## ⚡ Suporte ao AMD Instella-MoE & Gated MLA

Este fork implementa suporte completo e nativo de ponta a ponta para a arquitetura **Instella-MoE** (`amd/Instella-MoE-16B-A3B-Think`, `Base`, `SFT`, etc.):

1. **Gated Multi-Head Latent Attention (Gated MLA)**:
   - Suporte ao tensor de gating de atenção (`model.layers.{i}.self_attn.gate_proj.weight` $\rightarrow$ `blk.{i}.attn_gate.weight`).
   - Avaliação e aplicação da ativação $\sigma(\text{gate}) \odot \text{attn\_output}$ antes da projeção de saída `wo` em operações de atenção latente absorvida e MHA.
2. **FarSkip-Collective Residual Dataflow**:
   - Implementação do fluxo residual desacoplado que propaga `residual_no_routed` ($\text{resíduo} + \text{atenção} + \text{especialistas compartilhados}$) diretamente para a atenção da camada seguinte, reservando a agregação dos *routed experts* para o bloco MLP, espelhando a arquitetura de treinamento da AMD.
3. **Conversão HF $\rightarrow$ GGUF Nativa**:
   - Mapeamento direto de `InstellaMoEForCausalLM` no conversor [`convert_hf_to_gguf.py`](convert_hf_to_gguf.py), exportando tensores em precisões `f16`, `bf16` ou quantizações sem necessidade de scripts externos.

---

## 🎌 Suporte Nativo a LLM-jp-4 (Unigram Tokenizer & Harmony Channels)

Este fork incorpora as correções e aprimoramentos necessários para a execução nativa de toda a família de modelos **LLM-jp-4** (incluindo `llm-jp-4-8b-thinking`, `llm-jp-4-32b-a3b-thinking-gguf` e variantes `Instruct`):

1. **Correção de Remoção de Espaço em Tokens Especiais (`lstrip` / `add_space_prefix`)**:
   - Os modelos LLM-jp-4 utilizam o tokenizador Unigram byte-fallback (`add_space_prefix = true`). No `llama.cpp` upstream original, palavras emitidas imediatamente após tokens de controle/especiais (como `<|channel|>`, `<|start|>`, `<|message|>`) recebiam um espaço inicial indevido na detokenização e no streaming (`tools/server/server-context.cpp`).
   - Implementamos a sincronização com o fork oficial `llm-jp/llama.cpp`, propagando `remove_space` e `lstrip` após tokens de controle (`LLAMA_TOKEN_ATTR_CONTROL | LLAMA_TOKEN_ATTR_USER_DEFINED`), garantindo decodificação 100% idêntica ao tokenizador Hugging Face de referência.
2. **Gramática PEG Robusta para Canais GPT-OSS / Harmony**:
   - A gramática de parsing nativo (`common_chat_params_init_gpt_oss` em `common/chat.cpp`) foi aprimorada para aceitar delimitadores com espaços opcionais (`opt_space`). Isso elimina completamente falhas de validação de formato (`unparsed peg-native output`), impedindo que a Web UI trave ou aborte o streaming durante turnos de raciocínio (*analysis/thinking*) ou de resposta final (*final*).

---

## 🎮 Arquitetura e Aceleração AMD Vulkan

O **llama.cpp_ Vullkan** foi projetado para extrair 100% do poder do hardware AMD via Vulkan sem a necessidade de scripts de contorno ou parâmetros hardcoded:

1. **Eliminação Nativa de Fallbacks de Software (`llvmpipe`)**:
   - O subsistema de inicialização de dispositivos filtra e seleciona diretamente GPUs físicas de hardware (`eDiscreteGpu` e `eIntegratedGpu`), descartando emuladores de CPU.
2. **Zero-Copy Host Memory em APUs (UMA)**:
   - Identificação dinâmica de arquitetura integrada em processadores Ryzen (5, 7, 9). Tensores são alocados diretamente na memória do host sem overhead de cópias redundantes.
3. **Kernels MMVQ Acelerados**:
   - Ativação nativa de kernels quantizados otimizados para as Compute Units AMD (`VK_VENDOR_ID_AMD`).
4. **Proteção Dinâmica de Alocação (SysMem Fallback)**:
   - Alocação elástica para contextos extensos (ex: 32k - 128k tokens) prevenindo quebras por falta de VRAM dedicada.
5. **Afinidade Inteligente de Threads Zen**:
   - Detecção automática de núcleos físicos no Linux para eliminar contenção de threads SMT em álgebra linear.

---

## ✨ Principais Capacidades do Fork

### 🤖 1. Centro de Controle Agêntico (*Agent Control Center*)
- **Painel Dedicado na Barra Lateral (`#/agents`)**: Interface intuitiva para configurar e alternar entre agentes autônomos.
- **6 Perfis Agênticos Nativos**:
  - 💻 **Code Architect**: Engenheiro full-stack para inspeção de código, refatoração e testes.
  - ⚡ **DevOps & SysOps**: Diagnóstico de sistema operacional, automação shell e monitoramento de hardware.
  - 🔍 **Deep Research**: Pesquisa técnica, síntese de documentações e consultas estruturadas.
  - 📊 **Math & Data Analyst**: Resolução algébrica e cálculo simbólico exato via sandbox **Nerdamer**.
  - 🌐 **Polyglot & Localization**: Especialista em tradução paralela, terminologia e localização ancorada no corpus de 55 línguas.
  - 🤖 **Universal Agent**: Acesso unificado a todas as ferramentas do ecossistema simultaneamente.
- **Execução Autônoma Contínua**: Loop multi-turno desbloqueado para execução fluida sem interrupções manuais de permissão.

---

### 💻 2. Motor de Infilling e FIM (Fill-in-the-Middle) Nativo
- **Compatibilidade Total com OpenAI `/v1/completions`**:
  - Processa o parâmetro `suffix` diretamente no núcleo C++, integrando-se instantaneamente a extensões de IDEs como **Continue.dev**, **Cursor**, **Tabby**, **VS Code** e **Neovim**.
- **Endpoint Especializado `POST /infill`**:
  - Suporte ao padrão **Repo-Level Context** (`<FIM_REP>`, `<FIM_SEP>`, `<FIM_PRE>`, `<FIM_SUF>`, `<FIM_MID>`) para sugestões contextuais de código em múltiplos arquivos.

---

### 🛠️ 3. Matriz de Ferramentas Nativas & Protocolo MCP
Conjunto completo de ferramentas de sistema prontas para uso:

| Ferramenta | Identificador | Camada | Descrição |
| :--- | :--- | :--- | :--- |
| **Language Reference** | `languages_ref` | Backend C++ | Acesso ao corpus de 55 línguas, alinhamento paralelo de frases, busca de termos e injeção na memória de contexto do LLM. |
| **Read File** | `read_file` | Backend C++ | Leitura de arquivos locais com paginação e offset de bytes. |
| **Write File** | `write_file` | Backend C++ | Criação e persistência de arquivos no disco. |
| **Edit File** | `edit_file` | Backend C++ | Substituição cirúrgica de trechos com verificação de integridade. |
| **File Glob Search** | `file_glob_search` | Backend C++ | Varredura recursiva de diretórios com padrões glob. |
| **Grep Search** | `grep_search` | Backend C++ | Busca de texto literal ou regex em múltiplos arquivos. |
| **Exec Shell** | `exec_shell_command` | Backend C++ | Execução de comandos no shell bash com streaming SSE. |
| **Get Datetime** | `get_datetime` | Backend C++ | Consulta precisa de data, hora e fuso horário. |
| **Get Runtime Info** | `get_info` | Backend C++ | Diagnóstico de SO, arquitetura, CPU e commit Git. |
| **Run JavaScript** | `run_javascript` | Frontend Browser | Sandbox Web Worker isolado com motor simbólico Nerdamer. |
| **MCP Connectors** | `mcp:*` | Backend / Proxy | Conexão com servidores MCP (Exa, GitHub, HF Hub, SQL, etc.). |

---

### 🌐 4. Sistema de Referência Multilíngue (55 Línguas & `languages_ref`)
Este fork integra uma base paralela completa de 55 idiomas em [`tools/languages_ref/`](tools/languages_ref/) para que o modelo consulte termos exatos, padrões gramaticais e frases de referência durante a geração:

- **Ações da Tool (`languages_ref`)**:
  - `action: "get"`: Carrega frases de referência do idioma selecionado diretamente na memória de contexto (`reference_context`).
  - `action: "list"`: Lista todas as 55 línguas suportadas com seus nomes nativos e status de disponibilidade.
  - `action: "search"`: Busca termos específicos em qualquer língua do corpus.
  - `action: "align"`: Alinha traduções paralelas entre língua de origem (`source_language`) e destino (`language`) com base em IDs idênticos.
- **Integração no Frontend Vite**:
  - Comando de barra rápida `/lang <código>` (ex: `/lang pt-BR`, `/lang ja`, `/lang de`).
  - Renderização dedicada de cards com badges de idioma, alinhamentos bilíngues e botões de cópia rápida.
  - Disponibilidade garantida em qualquer porta ou rota via endpoints relativos (`./tools`).

---

### 🔥 5. Identidade Visual Vullkan (Cyberpunk Lava Neon)
- **Logo Vetorial Vullkan**: Emblema geométrico vulcânico incandescente integrado nos formatos `.svg` e PWA.
- **Efeitos de Lava durante Processamento**:
  - Shimmer fluido estilo magma líquido nas caixas de raciocínio (*Reasoning...*);
  - Borda com pulso térmico (`magma-pulse`) durante a geração de tokens;
  - Barras de progresso e spinners iluminados com halo de fogo neon;
  - Tema escuro de alto contraste otimizado para longas sessões de desenvolvimento.