Como implantar o Kimi K3 localmente?

TL;DR

Kimi K3 tem pesos abertos, mas não é em escala de estação de trabalho: servir o modelo nativo exige GPUs de classe data center e memória distribuída. Use vLLM para o caminho de produção mais direto, ou SGLang quando topologia, paralelismo de especialistas e controle de cache importarem. Compilações GGUF da comunidade reduzem o limite de hardware, mas ainda exigem cerca de 500 GB a bem mais de 1 TB de memória endereçável e trocam velocidade ou qualidade por viabilidade. Para PCs e Macs comuns, teste primeiro via uma API hospedada e faça self-host apenas quando privacidade, utilização sustentada ou controle da infraestrutura justificarem o custo.

What Is Kimi K3?

Kimi K3 é o modelo multimodal nativo de pesos abertos, carro-chefe da Moonshot AI para codificação de longo horizonte, trabalho de conhecimento agentivo, raciocínio e compreensão visual.

A Moonshot o descreve como o primeiro modelo aberto de classe 3T do mundo. Sua arquitetura combina Kimi Delta Attention e Attention Residuals com um design MoE esparso que seleciona apenas um subconjunto de especialistas para cada token.

A escala é incomum mesmo pelos padrões de modelos de fronteira. Em vez de ativar todos os 2,8T parâmetros para cada token, o K3 seleciona 16 de 896 especialistas roteados, além de especialistas compartilhados. Isso reduz substancialmente o cálculo por token, embora todos os pesos do modelo ainda precisem estar disponíveis em algum lugar no sistema de inferência.

O K3 também aplica treinamento ciente de quantização desde a etapa de SFT, em vez de tratar o serviço em baixa precisão apenas como um passo de compressão pós-treinamento.

Sua arquitetura é, portanto, otimizada para serviço em escala muito grande — mas “cálculo esparso” não deve ser confundido com “pegada de memória pequena”. Apenas parte da rede computa cada token, mas o conjunto completo de especialistas ainda precisa ser acessível.

How Does Kimi K3 Perform?

O conjunto oficial de benchmarks Kimi K3 da Moonshot posiciona o modelo próximo aos principais modelos proprietários de fronteira, especialmente em engenharia de software de longo horizonte e cargas de trabalho agentivas.

A seleção a seguir cobre raciocínio, codificação, agentes e visão. Quanto maior, melhor para todas as pontuações apresentadas.

As pontuações oficiais colocam o Kimi K3 perto de GPT-5.6 Sol, Claude Fable 5 e Claude Opus 4.8 em tarefas de raciocínio, codificação, agentes e visão. Trate esses resultados informados pelo provedor como contexto de capacidade e não como um ranking universal; a análise detalhada de benchmarks é tratada separadamente. Para este guia, o ponto operacional é que o self-hosting oferece capacidade de classe de fronteira e controle de infraestrutura, mas não um atalho de baixo custo no desktop.

Can You Actually Run Kimi K3 Locally?

Sim, mas existem duas definições muito diferentes de “local”.

Servidor local / data center privado: realista.

Desktop ou laptop normal: tecnicamente experimentável com compilações agressivamente quantizadas da comunidade, mas geralmente impraticável para uso interativo.

A receita atual do vLLM para Kimi K3 define uma linha de base muito alta:

• NVIDIA: pelo menos 8× GB300
• AMD ROCm: pelo menos 8× MI355X ou MI350X
• Driver NVIDIA: R580+ para a imagem CUDA 13 atual do K3
• Infraestrutura multi-nó recomendada para tráfego de produção real

O guia de dia 0 do vLLM original também demonstrou um caminho de início rápido com 8 GPUs B300 ou 8 GPUs MI355X. Para uma nova implantação de produção, siga a receita mais recente, pois ela reflete a pilha de serviço após as otimizações do dia do lançamento.

Este é o ponto-chave: o K3 tem pesos abertos, mas não é um modelo aberto em escala de consumidor.

Official Weights vs Community GGUF Quantizations

Há outra maneira de reduzir o limite de hardware: quantização pela comunidade.

O repositório Unsloth K3 atual fornece várias variantes GGUF que podem ser executadas por software compatível com llama.cpp.

Comparação consolidada. As cifras de memória endereçável são estimativas de planejamento (tamanho do download mais cerca de 10–15% de margem de execução), não garantias; configurações de contexto, cache, visão e offload podem exigir mais.

Essa distinção também explica por que alguns artigos iniciais de implantação local citam 594 GB: 594 GB agora correspondem à compilação comunitária UD-IQ1_S GGUF, não a uma descrição útil do checkpoint nativo completo atual.

Um modelo de 466–649 GB é dramaticamente menor do que a pegada de implantação original, mas ainda é enorme para padrões de workstation. Você também deve reservar memória para estado de runtime, contexto, caches, o projetor de visão, processos do sistema operacional e outros overheads.

Capacidade de disco não é o mesmo que memória de inferência. Ter um SSD de 1 TB não significa que um modelo de 600 GB será executado rapidamente em uma máquina com 64 GB de RAM. O offload para SSD pode tornar experimentos extremos possíveis, mas a geração de tokens pode ficar dolorosamente lenta.

How to Deploy Kimi K3 with vLLM

Para self-hosting sério, vLLM é o ponto de partida mais direto.

A Moonshot atualmente lista o vLLM como um dos mecanismos de inferência recomendados para K3, e o vLLM fornece suporte específico ao modelo para KDA, MoE MXFP4, parsing de raciocínio, chamadas de ferramenta, cache de prefixo e implantação distribuída.

Check the prerequisites

Para implantação de produção com NVIDIA, a receita testada atual usa o container vllm/vllm-openai:kimi-k3.

Verifique as GPUs:

nvidia-smi

Confirme o Docker:

docker --version

Confirme se o NVIDIA Container Toolkit consegue ver os aceleradores:

docker run --rm --gpus all nvidia/cuda:13.0.0-base-ubuntu24.04 nvidia-smi

Se o último comando não conseguir ver todas as GPUs, corrija o runtime de GPU do host/container antes de baixar um modelo de vários terabytes.

Set your Hugging Face token

Se for necessária autenticação para o repositório do modelo, armazene o token em uma variável de ambiente em vez de fixá-lo em scripts.

export HF_TOKEN="YOUR_HUGGING_FACE_TOKEN"

Pull the K3 vLLM container

docker pull vllm/vllm-openai:kimi-k3

A receita atual especifica uma compilação CUDA 13 e driver NVIDIA R580 ou mais recente.

Launch Kimi K3

Modelo inicial TP8 do Blackwell (receita vLLM atualizada em 2026-09-10): use como base e depois regenere ou faça benchmark do perfil para seu hardware e tráfego exatos.

docker run --rm \
  --gpus all \
  --ipc=host \
  -p 8000:8000 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -e HF_TOKEN="$HF_TOKEN" \
  -e VLLM_USE_V2_MODEL_RUNNER=1 \
  vllm/vllm-openai:kimi-k3 \
  --model moonshotai/Kimi-K3 \
  --tensor-parallel-size 8 \
  --gpu-memory-utilization 0.95 \
  --kv-cache-dtype fp8 \
  --attention-backend TOKENSPEED_MLA \
  --attention-config '{"use_prefill_query_quantization":true,"mla_prefill_backend":"TOKENSPEED_MLA"}' \
  --prefix-match-unit 128 \
  --enable-prefix-caching \
  --max-model-len 131072 \
  --enable-auto-tool-choice \
  --tool-call-parser kimi_k3 \
  --reasoning-parser kimi_k3

A receita atual requer a imagem CUDA 13 do K3 e um driver NVIDIA R580 ou mais recente. O cache KV em FP8 deve ser pareado com um backend de prefill/decode MLA compatível; faça benchmark de alternativas antes de mudar a configuração de atenção.

Fonte: Receita do vLLM para Kimi K3. Isso substitui o comando do dia 0 anterior, em vez de apresentá-lo como a receita de produção atual.

Para uma primeira validação, considere limitar o comprimento máximo do modelo em vez de alocar imediatamente em torno da capacidade completa de 1.048.576 tokens. A receita atual do vLLM recomenda explicitamente ajustar max-model-len para a carga de trabalho.

Por exemplo:

--max-model-len 131072

Isso não muda o limite de contexto arquitetural do K3. Simplesmente dá ao mecanismo de serviço um envelope operacional mais administrável para seus testes iniciais.

Test the local endpoint

O vLLM expõe uma API compatível com OpenAI na porta 8000.

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "moonshotai/Kimi-K3",
    "messages": [
      {
        "role": "user",
        "content": "Explain the difference between tensor parallelism and expert parallelism."
      }
    ],
    "max_tokens": 512
  }' 

Ou use o SDK Python da OpenAI:

python

from openai import OpenAI

 client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="EMPTY",
    timeout=3600,
 )

response = client.chat.completions.create(
    model="moonshotai/Kimi-K3",
    messages=[
        {
            "role": "user",
            "content": "Write a Python function that validates a JSON schema.",
        }
    ],
    max_tokens=1024,
 )

print(response.choices[0].message.content)

A receita oficial do vLLM usa o mesmo padrão compatível com OpenAI em localhost, facilitando alternar um aplicativo entre inferência local e hospedada.

How to Deploy Kimi K3 with SGLang

SGLang é a outra rota principal de implantação oficialmente recomendada pela Moonshot.

Ele é particularmente relevante quando você deseja controle mais profundo sobre serviço distribuído, paralelismo de especialistas, kernels específicos de hardware ou topologia de produção complexa.

Use o Cookbook dedicado do Kimi K3 no SGLang e selecione uma topologia específica de hardware. A seguir está o perfil verificado de nó único 8×B300 Unified/Balanced do cookbook; foi medido com SGLang v0.5.18 no commit 71de97b2.

Instale uma build compatível com K3:

pip install --upgrade pip
pip install uv
uv pip install --prerelease=allow sglang

Inicie o perfil verificado B300 TP8/DCP8:

sglang serve \
  --trust-remote-code \
  --model-path moonshotai/Kimi-K3 \
  --tp-size 8 \
  --dcp-size 8 \
  --mem-fraction-static 0.85 \
  --mamba-full-memory-ratio <value-from-official-calculator> \
  --reasoning-parser kimi_k3 \
  --tool-call-parser kimi_k3 \
  --host 0.0.0.0 \
  --port 30000

--mamba-full-memory-ratio depende da carga: calcule a partir do comprimento médio de entrada mais saída no cookbook oficial. Não copie esta topologia B300 para H100/H200, GB200/GB300, AMD ou implantações multi-nó; esses perfis usam layouts TP/PP/DCP/EP diferentes.

Teste o servidor:

curl http://localhost:30000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "moonshotai/Kimi-K3",
    "messages": [{"role": "user", "content": "Give me a five-step debugging plan for a distributed Python application."}]
  }'

Para uma implantação real, valide capacidade, qualidade de saída e recuperação de falhas na versão exata do SGLang, topologia, comprimento de contexto e mix de tráfego que você pretende executar.

vLLM vs SGLang vs llama.cpp

Escolher um mecanismo de inferência depende principalmente do seu hardware e do propósito da implantação.

Se você possui um servidor com 8 GPUs classe Blackwell/MI35x, comece com vLLM.

Se você está projetando um cluster de inferência distribuída especializado e quer mais controles de serving de baixo nível, avalie também o SGLang.assistant_message

Se seu objetivo é simplesmente “Quero provar que o K3 pode executar no hardware que possuo”, GGUF com llama.cpp é bem mais acessível — desde que sua máquina tenha uma quantidade realmente excepcional de memória.

How to Run a Quantized Kimi K3 with llama.cpp or Ollama

O repositório GGUF do Kimi K3 na comunidade agora fornece variantes compatíveis com llama.cpp.

Essa rota reduz dramaticamente a barreira de entrada em comparação com uma implantação nativa de pesos em data center, mas “dramaticamente” é relativo: mesmo as menores compilações têm centenas de gigabytes.

Install llama.cpp on macOS or Linux

O model card GGUF atual fornece:

curl -LsSf https://llama.app/install.sh | sh

No Windows:

winget install llama.cpp

Start an OpenAI-compatible server

O repositório atualmente documenta UD-Q4_K_XL como exemplo:

llama serve \
  -hf unsloth/Kimi-K3-GGUF:UD-Q4_K_XL

Você também pode executar o CLI diretamente:

llama cli \
  -hf unsloth/Kimi-K3-GGUF:UD-Q4_K_XL

Esses comandos vêm diretamente do model card GGUF atual do Kimi K3.

No entanto, UD-Q4_K_XL tem cerca de 1,51 TB, portanto não é a variante com que a maioria dos usuários de workstation começaria. Se sua prioridade é reduzir requisitos de memória em vez de preservar o máximo de qualidade, investigue primeiro as variantes menores de 1-bit e 2-bit.

Por exemplo:

llama serve \
  -hf unsloth/Kimi-K3-GGUF:UD-IQ1_M

O diretório UD-IQ1_M atual tem aproximadamente 649 GB.

Um modelo de 649 GB ainda não é um modelo para laptop normal. Idealmente, o estado do modelo acessado com frequência deve residir em memória rápida. Offload pesado para SSD pode tornar um experimento extremo tecnicamente possível sem torná-lo útil para trabalho interativo.

Run the Same GGUF Build with Ollama

Ollama é uma camada de conveniência para a mesma rota de implantação GGUF, não um quarto método independente de self-hosting.

O repositório GGUF do K3 também expõe uma rota via Ollama.

Por exemplo:

bash

ollama run hf.co/unsloth/Kimi-K3-GGUF:UD-Q4_K_XL

O Ollama simplifica o gerenciamento do modelo e a experiência da API, mas não remove os requisitos de memória do K3.

Trocar o lançador de llama.cpp para Ollama não transforma uma quantização de várias centenas de gigabytes em um modelo de 24 GB de GPU. Os dados subjacentes do modelo ainda precisam ser armazenados e acessados.

Por essa razão, o Ollama deve ser visto como um wrapper de runtime conveniente, não como uma solução para hardware.

Which Kimi K3 Quantization Should You Choose?

Para experimentos, a escolha é principalmente um trade-off entre tamanho do modelo e fidelidade.

Important Kimi K3 Serving Behavior

Há um detalhe de implementação específico do K3 que é fácil de negligenciar.

O K3 usa histórico de pensamento preservado. A Moonshot diz que conversas multi-turn e fluxos de chamadas de ferramenta devem enviar de volta ao modelo a mensagem completa anterior do assistente, incluindo reasoning_content e tool_calls, e não apenas o conteúdo visível.

Um padrão de aplicação simplificado se parece com isto:

messages = [
    {
        "role": "user",
        "content": "Inspect this project and propose a migration plan.",
    }
 ]

first = client.chat.completions.create(
    model="moonshotai/Kimi-K3",
    messages=messages,
    max_tokens=2048,
 )

assistant_message = first.choices[0].message

 # Preserve the whole message object, not just assistant_message.content.
 messages.append(
    assistant_message.model_dump(exclude_none=True)
 )

messages.append(
    {
        "role": "user",
        "content": "Now identify the riskiest part of that plan.",
    }
 )

second = client.chat.completions.create(
    model="moonshotai/Kimi-K3",
    messages=messages,
    max_tokens=2048,
 )

Isso se torna especialmente importante para agentes de codificação, loops de ferramentas e sessões autônomas de longa duração.

O K3 também mantém o raciocínio habilitado e suporta esforço de raciocínio baixo, alto e máximo. Quando sua camada de serviço expuser esses parâmetros, trate o esforço de raciocínio como mais um controle de latência/qualidade, em vez de sempre maximizá-lo para cada requisição.

How to Optimize a Local Kimi K3 Deployment

Não aloque imediatamente o contexto completo de 1M

O K3 suporta 1.048.576 tokens, mas capacidade máxima do modelo e configuração sensata do servidor são coisas diferentes.

Para desenvolvimento, comece com algo como:

--max-model-len 131072

Depois aumente o contexto apenas após medir memória disponível, tempo até o primeiro token, throughput e concorrência esperada.

Habilite cache de prefixo

Agentes de codificação frequentemente reutilizam instruções de repositório, esquemas de ferramentas, prompts de sistema e prefixos longos.

Com vLLM:

--enable-prefix-caching

A arquitetura de atenção híbrida do K3 exigiu tratamento especial para cache de prefixo, e o vLLM implementou suporte específico ao modelo para isso.

Use os parsers do K3

Para cargas de trabalho agentivas, inclua:

--tool-call-parser kimi_k3 \
--reasoning-parser kimi_k3

Isso mantém chamadas de ferramenta e a saída de raciocínio alinhadas com o formato de serviço do K3.

Mantenha o armazenamento rápido

Um modelo nessa escala impõe pressão incomum sobre o armazenamento local durante o primeiro download, carregamento de checkpoint, atualizações e recuperação.

Armazenamento NVMe é preferível a discos lentos montados em rede. Se várias máquinas compartilham arquivos de modelo, a topologia do cache de modelos e a largura de banda de rede tornam-se parte da arquitetura de inferência e não meros detalhes de implantação.

Monitore mais do que a utilização da GPU

Acompanhe:

• Utilização de HBM/VRAM
• RAM da CPU
• taxa de acerto do cache
• tempo até o primeiro token
• tokens decodificados por segundo
• profundidade da fila de requisições
• comunicação entre GPUs
• largura de banda entre nós
• falhas ao parsear chamadas de ferramenta
• tempo de carregamento do modelo

Na escala do K3, uma aparente figura saudável de utilização da GPU não informa se a topologia de serviço está eficiente.

Local Kimi K3 vs Hosted Kimi K3

O self-hosting dá às equipes máximo controle sobre o caminho dos dados, runtime e pesos do modelo, ao mesmo tempo em que as torna responsáveis por capacidade de GPU, escalonamento, upgrades, monitoramento e recuperação. O acesso hospedado remove a maior parte do trabalho de infraestrutura e geralmente é a rota mais rápida para avaliação ou demanda variável.

Para a análise completa de hardware e ponto de equilíbrio, leia Kimi K3 Self-Hosting vs API. Para preços por token, cache e comparações com K2.7, use o guia de preços do Kimi K3. Assim, este artigo mantém a comparação breve e se concentra em comandos de implantação, configuração e solução de problemas.

Common Kimi K3 Local Deployment Problems

O modelo não cabe na memória da GPU

Esta é a falha mais previsível.

Não calcule a memória a partir dos 104B parâmetros ativados. Essa cifra descreve o cálculo por token, não a quantidade de pesos de especialistas que o sistema de serviço precisa disponibilizar.

Use uma topologia distribuída suportada, uma quantização GGUF menor ou um serviço hospedado.

Erros de CUDA ou de driver NVIDIA

A imagem atual do vLLM para K3 é baseada em CUDA 13 e requer driver de host R580+.

Se o host ainda estiver em uma pilha R575/CUDA 12.9, atualize ou siga o caminho de compilação a partir do código-fonte descrito pelo vLLM, em vez de presumir que o container corrigirá incompatibilidades de driver do host.

A primeira requisição é extremamente lenta

Verifique se o checkpoint ainda está carregando, compilando kernels, aquecendo caches ou puxando arquivos.

Com ativos de classe multi-terabyte, “processo do servidor iniciado” e “modelo pronto para tráfego de produção” não são estados equivalentes.

Chamadas de ferramenta falham intermitentemente

A receita atual do vLLM observa que o K3 pode ocasionalmente produzir uma forma de chamada de ferramenta que seu parser não espera. Sistemas de produção devem, portanto, validar esquemas de chamadas de ferramenta e implementar retentativas, em vez de confiar cegamente em toda chamada gerada.

Conversas longas ficam menos estáveis

Garanta que você está retornando a mensagem completa do assistente — incluindo informações de raciocínio e de ferramentas — para os turnos subsequentes do K3.

Descartar campos ocultos de estado de raciocínio pode quebrar o padrão de histórico de pensamento preservado que o K3 foi treinado para usar.

So, What Is the Best Way to Deploy Kimi K3 Locally?

Para a maioria das organizações com hardware adequado, vLLM é o melhor primeiro caminho de implantação. Ele tem suporte dedicado ao K3, uma API compatível com OpenAI, parsers específicos do modelo, cache de prefixo, suporte a decodificação especulativa e receitas para hardware atual.

Escolha SGLang quando engenharia de inferência distribuída e controle de serving de baixo nível forem mais importantes do que o caminho de configuração mais curto.

Escolha llama.cpp mais uma quantização GGUF da comunidade apenas quando seu objetivo for experimentação em workstation/servidor e você entender que mesmo as versões de 1-bit ainda têm centenas de gigabytes.

Para uma workstation de desenvolvedor convencional, a conclusão mais prática é diferente: não compre centenas de gigabytes de RAM apenas para forçar o K3 em um desktop. Teste o Kimi K3 via CometAPI primeiro, quantifique o benefício nas suas próprias tarefas e parta para self-hosting apenas quando privacidade, utilização sustentada ou controle de infraestrutura tornarem a economia justificável.

FAQ

O Kimi K3 pode rodar em uma única GPU de consumidor?

Não de forma realista. O modelo está muito além da capacidade de VRAM de GPUs de consumidor. Quantizações GGUF de baixa precisão feitas pela comunidade reduzem bastante a pegada, mas as menores variantes atuais ainda têm centenas de gigabytes.

Posso rodar o Kimi K3 em um Mac?

Execução experimental em CPU/Apple Silicon com GGUF e offload de armazenamento é possível em princípio, mas desempenho interativo e capacidade de memória são os fatores limitantes. Um MacBook típico não deve ser tratado como uma plataforma prática de serviço do K3.

O Kimi K3 é compatível com Ollama?

Compilações GGUF da comunidade podem ser iniciadas via Ollama. O runtime simplifica a configuração, mas não muda o requisito de memória subjacente.

vLLM ou SGLang é melhor para o Kimi K3?

vLLM é o padrão mais fácil para uma nova implantação de produção. SGLang é atraente para equipes que constroem topologias de serviço distribuído sofisticadas. Ambos estão entre os mecanismos de inferência para K3 recomendados pela Moonshot.

Quanto de contexto o Kimi K3 suporta?

A especificação oficial do modelo suporta 1.048.576 tokens. Um servidor local não precisa expor toda a janela de contexto; definir um max-model-len menor pode ser mais prático para implantação inicial e maior concorrência.

O Kimi K3 é open source?

Uma descrição mais precisa é pesos abertos. A Moonshot lançou os pesos do modelo sob a Licença Kimi K3. Revise essa licença diretamente antes de redistribuição comercial ou outro uso em que os termos importem.

Qual é a forma mais fácil de usar o Kimi K3 sem GPUs locais?

Uma API hospedada é a rota mais simples. Kimi K3 está disponível via CometAPI com uma interface de chat-completions compatível com OpenAI, então o código da aplicação pode permanecer próximo ao que você usaria contra um servidor local vLLM ou SGLang.