iMiranda/kuro-small-gguf

Kuro-Small — Qwen2.5-3B GGUF (Q4_K_M)

Kuro-Small é a variante leve do Kuro, otimizada para rodar em máquinas com ~7.5 GB de RAM total em terminal puro (TTY), sem GPU dedicada. É o modelo Qwen/Qwen2.5-3B-Instruct (3.0 B parâmetros, Apache 2.0) quantizado para GGUF Q4_K_M (~1.8 GiB), com a persona "Kuro" aplicada via system prompt — sem fine-tuning de pesos.

RSS estimado em runtime: ~2.5 GiB com ctx=4096 (CPU-only). Cabe em ~7.5 GB total com Chrome/Discord/Codium abertos.

Créditos

Repack de Qwen/Qwen2.5-3B-Instruct (Apache 2.0). Nenhum peso treinado do zero — apenas quantizado para GGUF e empacotado com um system prompt. O mérito do modelo base é inteiramente da Alibaba / Qwen team.

• Modelo base: https://huggingface.co/Qwen/Qwen2.5-3B-Instruct
• Licença base: Apache 2.0
• Quantização: llama.cpp (llama-quantize) — MIT

Diferença vs. Kuro (3.8B)

	Kuro (Phi-3.5-mini)	Kuro-Small (Qwen2.5-3B)
Params	3.8 B	3.0 B
GGUF size	2.3 GiB	~1.8 GiB
RSS em runtime	~4.7 GiB	~2.5 GiB (ctx 4096)
Contexto recomendado	4096	4096–8192
RAM mínima	10–11 GiB livre	~3–4 GiB livre
Capacidade técnica	alta	média-alta
Recusa de unsafe	confirmada	confirmada
Tools (agente)	não	sim (Qwen2.5)
Licença	MIT	Apache 2.0

Kuro-Small é a escolha certa quando RAM é o bottleneck (máquinas de ~8 GB). A versão 3B é significativamente mais capaz que a antiga 1.5B (código completo, raciocínio multi-passo, menos "não sei" desnecessário).

Como funciona a persona "Kuro"

A persona não está nos pesos — está num system prompt aplicado em runtime. O .gguf aqui é o Qwen2.5-3B padrão; o estilo "Kuro" vem de injetar o prompt abaixo (system_prompt.md no repositório).

Especificações técnicas

Campo	Valor
Modelo base	Qwen/Qwen2.5-3B-Instruct
Parâmetros	3.0 B
Arquitetura	Qwen2.5 (decoder-only, GQA)
Quantização	Q4_K_M (4-bit primary + 6-bit K/V)
Arquivo	kuro-small-Q4_K_M.gguf (~1.8 GiB)
Context length	até 32768 (Modelfile: 8192)
Vocab	151k (BPE)
Runtime testado	llama.cpp (llama-cli) CPU-only
Chat template	Jinja2 embedded no GGUF (Qwen ChatML)

Como usar

Via Ollama (recomendado — config pronta)

Baixe os 3 arquivos diretamente (sem git clone — o repo é GGUF/LFS e clone via git exige git-lfs/xet, que não são necessários):

mkdir kuro-small && cd kuro-small
curl -fLO https://huggingface.co/iMiranda/kuro-small-gguf/resolve/main/kuro-small-Q4_K_M.gguf
curl -fLO https://huggingface.co/iMiranda/kuro-small-gguf/resolve/main/Modelfile.kuro-small
curl -fLO https://huggingface.co/iMiranda/kuro-small-gguf/resolve/main/system_prompt.md

# Cria o modelo com persona + contexto 8192 + params já configurados
ollama create kuro-small -f Modelfile.kuro-small

# Testa
ollama run kuro-small "Quem é você?"

# Como agente (Claude Code / OpenCode — suporta tools)
ollama launch claude      # selecione kuro-small

O .gguf tem ~1.8 GiB. Alternativa sem terminal: baixe cada arquivo pelo botão "Download file" na página do repo.

RAM apertada? Reduza o contexto editando o Modelfile antes do ollama create: PARAMETER num_ctx 4096 (KV cache de Qwen 3B em ctx 4096 ≈ 0.6 GiB). Para agentes com prompts grandes, num_ctx 16384 se houver RAM.

Via llama.cpp (CLI direto)

# One-shot
llama-cli \
    -m kuro-small-Q4_K_M.gguf \
    --threads 8 \
    -c 4096 \
    --temp 0.6 --top-p 0.92 --repeat-penalty 1.05 \
    --jinja \
    --system-prompt "$(cat system_prompt.md)" \
    --single-turn \
    -p "Escreva uma função Python que retorne únicos de uma lista." \
    -n 512 --no-display-prompt

# Modo interativo (chat multi-turno)
llama-cli \
    -m kuro-small-Q4_K_M.gguf \
    --threads 8 -c 4096 \
    --temp 0.6 --top-p 0.92 --repeat-penalty 1.05 \
    --jinja \
    --system-prompt "$(cat system_prompt.md)" \
    -cnv --color on -mli

--jinja é obrigatório: sem ele o Qwen gera respostas truncadas em tarefas de código.

Via LM Studio / Jan

Compatível com qualquer ferramenta que consuma GGUF. Configure o system prompt (system_prompt.md) manualmente na ferramenta — o .gguf só carrega o chat template, não o prompt.

Performance conhecida

Medido em runtime real (i7-1355U, CPU-only, 16 GiB de RAM do dev).

Ambiente	Valor
CPU	Intel i7-1355U (10 cores, 12 threads)
GPU	Nenhuma usada (CPU-only)
Prompt processing	~40–50 tok/s
Generation	~6–11 tok/s
Context length	4096 (testado)

Na máquina alvo do usuário (i5-1035G1, 8 threads, 7.5 GiB RAM, CPU-only), a geração é similar (~5–10 tok/s). Em hardware mais rápido, números sobem proporcionalmente.

Limitações conhecidas

• Capacidade técnica: 3B resolve snippets, scripts e raciocínio multi-passo curto. Para código multi-arquivo complexo ou cadeias longas de raciocínio, o Kuro 3.8B é superior (mas exige 10–11 GiB livres).
• Aritmética multi-passo: oscila em contas longas se o prompt não pedir raciocínio explícito; com "raciocine passo a passo" acerta.
• Context length: GGUF suporta até 32768, mas em CPU com ~7.5 GB de RAM total, num_ctx 4096–8192 é o teto seguro.
• Versus Kuro 3.8B: use o Kuro principal quando a RAM permitir; use Kuro-Small quando a RAM for o bottleneck. Kuro-Small tem tools (agente); Kuro 3.8B não.

Licença

Este repack segue a mesma licença do modelo base: Apache 2.0.

• Modelo base Qwen/Qwen2.5-3B-Instruct: Apache 2.0
• llama.cpp (usado para quantizar): MIT
• Este repositório de empacotamento: Apache 2.0

Nenhum peso treinado do zero. Todos os créditos do modelo pertencem à Alibaba / Qwen team.