Guia para executar o Kimi K3 localmente

• O Kimi K3, da Moonshot AI, é um modelo de pesos abertos com 2,8T de parâmetros totais e 104B ativos, visão nativa e contexto de 1 milhão de tokens; a Unsloth fornece quantizações GGUF para execução local
• A inferência em precisão completa exige 1,56 TB, mas o Dynamic 1-bit UD-IQ1_S registra cerca de 78,9% de acurácia Top-1 em 594 GB, enquanto o UD-Q2_K_XL de 2 bits, com 861,3 GB, registra cerca de 90%
• O Kimi K3 é um modelo thinking-only, que mantém rastros de raciocínio, não oferece modo Instant; permite escolher "low", "high"", "max" via reasoning_effort e processa até 1.048.576 tokens
• O Unsloth Studio automatiza offloading para RAM e detecção de múltiplas GPUs; para executar o llama.cpp com recursos de visão é necessário o fork da Unsloth para o Kimi K3
• A execução recomendada de UD-IQ1_S requer no mínimo 610 GB de RAM e, em geral, é preciso garantir RAM+VRAM equivalente ao tamanho do arquivo quantizado; se não houver memória suficiente, o offloading para disco deixa tudo muito mais lento

---

Características do modelo e requisitos para execução local

• O Kimi K3, da Moonshot AI, é um modelo de pesos abertos com 2,8T de parâmetros voltado a programação, agentes, contexto longo e chat, ativando 104B de parâmetros durante a inferência
• Suporta visão nativa e janela de contexto de 1 milhão de tokens, usando MXFP4 nos pesos MoE
• A inferência em precisão completa requer 1,56 TB de armazenamento
• Kimi-K3-GGUF pode ser executado no Unsloth Studio ou no llama.cpp
• Também pode rodar em uma NVIDIA DGX Station ou em um Mac Studio conectado a um dispositivo com 128 GB de RAM
• Os requisitos de hardware são calculados como a soma de RAM e VRAM, ou memória unificada, com configurações na faixa de 610 GB a 1,6 TB

Implementação GGUF

• A implementação é baseada no PR do llama.cpp, e o fork da Unsloth adiciona suporte a visão e correções de bugs
• A torre de visão é semelhante à do Kimi K2.5, mas com as seguintes diferenças
  • Usa RMSNorm e não tem bias
  • O QKV fundido não é quadrado, com qkv width != n_embd
  • Aplica normalização após o projector
• Em batches grandes, o orçamento n_tokens * 40 falhava, então foi aumentado para n_tokens * 160
• O template de chat do Kimi foi convertido para o formato Jinja
• Como a configuração padrão de treinamento ativa preserved thinking, os rastros de raciocínio são mantidos em vez de removidos

Métodos de quantização e qualidade

• UD-Q8_K_XL segue exatamente a configuração de MXFP4 nos pesos MoE e BF16 nos demais pesos, portanto corresponde a uma quantização sem perdas
• UD-Q4_K_XL armazena alguns tensores residuais, exceto tensores de normalização etc., em Q8_0; é próximo da precisão completa e tem tamanho de 1,51 TB
• O UD-Q8_K_XL sem perdas tem 1,56 TB, 50 GB maior que o UD-Q4_K_XL
• Os principais resultados de quantização são os seguintes
  • UD-IQ1_S: 594,0 GB, perplexity 2,5789, acurácia Top-1 78,875±0,107%
  • UD-IQ1_M: 648,9 GB, perplexity 2,3639, acurácia Top-1 81,219±0,103%
  • UD-IQ2_XXS: 711,1 GB, perplexity 2,1266, acurácia Top-1 84,127±0,096%
  • UD-Q2_K_XL: 861,3 GB, perplexity 1,7359, acurácia Top-1 90,390±0,077%
  • UD-Q4_K_XL: 1.510 GB, perplexity 1,4579
  • UD-Q8_K_XL: 1.560 GB, perplexity 1,4581
• A geração de imatrix e a calibração da quantização usam o UD-Q8_K_XL sem perdas de 1,56 TB
• O Dynamic 1-bit é 62% menor que a versão sem perdas e alcança cerca de 79% de acurácia Top-1
• O UD-Q2_K_XL de 2 bits é 45% menor e registra cerca de 90% de acurácia
• O tamanho em 1 bit é 553,2 GiB, e ainda está sendo investigado se é possível reduzir para menos de 512 GiB sem degradar o modelo

• Comparação com quantizações da comunidade

  • O IQ1_M comunitário de 618,9 GB é maior que o UD-IQ1_S de 594 GB, mas a perplexity sobe para 54,56, ficando 21 vezes pior
  • O IQ2_XXS comunitário registrou perplexity 96 em 725 GB, enquanto a versão da Unsloth registrou 2,12 em 711 GB, uma diferença de cerca de 45 vezes
  • A quantização dinâmica e a calibração adequada determinam conjuntamente o tamanho do arquivo e a qualidade

Configuração de inferência e desempenho

• O Kimi K3 é um modelo thinking-only, com preserve_thinking sempre ativado e nível padrão de raciocínio em max
• O modo Instant não é suportado, e é possível especificar "low", "high", "max" no campo de requisição reasoning_effort
• O comprimento de contexto é de até 1.048.576 tokens, e a Unsloth permite alternar entre os três níveis de raciocínio
• As configurações de inferência incluem temperature=1.0, top_p=0.95 ou top_p=1.0
• Quando o modelo cabe na memória, é possível obter no B200 cerca de 20 tokens/s na geração e throughput acima de 120 tokens/s
• Considerando o equilíbrio entre tamanho e qualidade, recomenda-se o UD-IQ1_S de 594 GB
• A soma de RAM e VRAM deve ser semelhante ao tamanho do arquivo quantizado; mesmo com memória insuficiente a execução é possível, mas fica muito mais lenta por causa do offloading para disco

Executando no Unsloth Studio

• O Unsloth Studio é uma interface web open source para IA local, com suporte a macOS, Windows e Linux
• Permite buscar, baixar e executar modelos GGUF e safetensors, oferecendo inferência CPU+GPU baseada em llama.cpp
• Detecta automaticamente offloading para RAM e configurações com múltiplas GPUs
• Os comandos de instalação e execução são os seguintes

# macOS, Linux, WSL
curl -fsSL https://unsloth.ai/install.sh | sh


# Windows PowerShell
irm https://unsloth.ai/install.ps1 | iex

unsloth studio

• Após executar, abra no navegador http://127.0.0.1:8888 ou o endereço exibido; na primeira execução, crie uma senha para proteção da conta
• Também há suporte à execução via HTTPS por meio de um túnel gratuito da Cloudflare

unsloth studio --secure

• No Model hub, pesquise por Kimi K3, baixe a quantização desejada e execute
• Os parâmetros de inferência são configurados automaticamente, mas é possível alterar manualmente o nível de raciocínio, o comprimento de contexto, o template de chat etc.
• As configurações detalhadas podem ser consultadas no guia de inferência do Unsloth Studio

Executando no llama.cpp

• Para inferência local rápida, incluindo CPU, use o llama.cpp
• Para ativar a visão do Kimi K3, é preciso compilar o fork específico da Unsloth, não a versão genérica

git clone https://github.com/unslothai/llama.cpp
cd llama.cpp
git fetch origin pull/48/head:kimi-k3-fullsize-vision
git checkout kimi-k3-fullsize-vision
cd ..
cmake llama.cpp -B llama.cpp/build \
    -DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON
cmake --build llama.cpp/build --config Release -j --clean-first \
    --target llama-cli llama-mtmd-cli llama-server llama-gguf-split
cp llama.cpp/build/bin/llama-* llama.cpp

• Se não houver GPU, ou se for usar apenas inferência por CPU, altere para -DGGML_CUDA=OFF
• Dispositivos Apple Mac e Metal também usam -DGGML_CUDA=OFF, e o suporte a Metal é ativado por padrão
• É possível fazer o llama.cpp baixar e executar o modelo diretamente, mas o download pode ser muito lento

export LLAMA_CACHE="unsloth/Kimi-K3-GGUF"
./llama.cpp/llama-cli \
    -hf unsloth/Kimi-K3-GGUF:UD-IQ1_S \
    --temp 1.0 \
    --top-p 0.95

• Para download manual, instale huggingface_hub e use hf download; se houver problemas, consulte depuração do Hugging Face Hub XET

hf download unsloth/Kimi-K3-GGUF \
    --local-dir unsloth/Kimi-K3-GGUF \
    --include "*mmproj-BF16*" \
    --include "*UD-IQ1_S*"

• Se precisar da versão sem perdas, altere o padrão de download para *UD-Q8_K_XL*
• É possível executar em modo de conversa especificando o arquivo local e o projector de visão

./llama.cpp/llama-cli \
    --model unsloth/Kimi-K3-GGUF/UD-IQ1_S/Kimi-K3-UD-IQ1_S-00001-of-00014.gguf \
    --mmproj unsloth/Kimi-K3-GGUF/mmproj-BF16.gguf \
    --temp 1.0 \
    --top-p 0.95

• Além de consultas de texto, também há suporte a entrada de imagens usando mmproj-BF16.gguf

Escopo dos benchmarks

• A avaliação inclui raciocínio e conhecimento, programação, agentes e visão
• Os benchmarks usados são GPQA Diamond, HLE-Full, DeepSWE, Terminal-Bench 2.1, BrowseComp, GDPval-AA v2, OSWorld 2.0, MMMU-Pro e MathVision
• Nos resultados do DeepSWE, o Kimi K3 demonstra desempenho eficiente

[plumpmath]

Depois de rodar aqui, achei boooom demais~ agora só falta o tangjjamyeon & dakkang