Construa com CometAPIPrecisa de uma API para vários modelos?Teste o fluxo no Playground e depois crie uma chave da API quando o modelo e o custo atenderem ao seu caso de uso.
Como implantar o Kimi K3.1 Pro localmente: requisitos de hardware, configuração do vLLM
Aprenda a hospedar por conta própria o Kimi K3.1 Pro com o vLLM, a verificar os requisitos de GPU, a baixar os pesos, a testar a inferência e a comparar a implantação local com o acesso via API.
Deon GoodwinEquipe de pesquisa de modelos e API de IA
Implemente o Kimi K3.1 Pro em um servidor Linux com GPU e, em seguida, conecte um aplicativo local ao endpoint de inferência. Este passo a passo usa um nó NVIDIA B300 com oito GPUs e vLLM. Você precisará de acesso ao shell do servidor, drivers compatíveis e armazenamento para o checkpoint completo. Comece concluindo uma solicitação curta de texto antes de testar entradas mais longas ou fluxos de trabalho de agentes.
Sem GPUs adequadas, você pode executar seu aplicativo localmente e conectá-lo à API oficial do Kimi ou a um provedor de terceiros como a CometAPI.
Principais pontos
Os 104B de parâmetros ativos do modelo não representam sua exigência total de armazenamento.
A compatibilidade de hardware inclui memória de GPU, interconexões, suporte a quantização e kernels de inferência.
Revisado para maior clareza, atribuição de fontes e terminologia de API atual.
Resultados fortes em benchmarks tornam o modelo digno de teste, mas não garantem desempenho equivalente no seu aplicativo.
Um endpoint de inferência funcional não inclui automaticamente um navegador, sandbox de código ou um runtime de agente completo.
Compare autohospedagem e acesso via API pelo custo por tarefa bem-sucedida, incluindo retentativas e manutenção.
O que é Kimi K3.1 Pro?
Kimi K3.1 Pro é o modelo multimodal de pesos abertos da Moonshot AI para programação, análise de documentos e uso de ferramentas. Suas principais especificações estão abaixo, com base no model card oficial.
Especificação
Configuração publicada
Arquitetura
MoE; 2,8T de parâmetros totais, 104B ativos
Atenção
93 camadas: 69 KDA + 24 Gated DSA
Experts
896 roteados; 16 selecionados por token; 2 compartilhados
Contexto
1.048.576 tokens
Entradas
Texto e imagens; codificador de visão MoonViT-V2
Quantização
Pesos MXFP4 / ativações MXFP8; checkpoint de precisão mista
Motores recomendados
vLLM, SGLang, TokenSpeed
O modelo ativa 104B parâmetros por token, mas a implantação ainda exige o checkpoint completo de 2,8T de parâmetros. O mecanismo de inferência também deve suportar suas camadas KDA e Gated DSA e a quantização MXFP4.
Que hardware você precisa para executar o Kimi K3.1 Pro localmente?
A tabela abaixo resume as configurações do vLLM relevantes para este guia. O passo a passo usa um nó B300 com oito GPUs; implantações em GB300 e AMD exigem suas configurações correspondentes.
Hardware
Rota documentada
Observações de planejamento
NVIDIA B300
Um nó com oito GPUs, TP8
Referência básica para o passo a passo abaixo
NVIDIA GB300
Oito GPUs em dois trays, TP8
Requer configuração multinó e setup de interconexão
AMD MI355X
Nó com oito GPUs e configuração específica AMD
Use o caminho ROCm/AITER; não reutilize as configurações da NVIDIA
GPU de consumo única 24–32 GB
Insuficiente para carregar o checkpoint completo diretamente
Não é um alvo prático para este tutorial
A título de escala, 2,8T parâmetros ocupariam aproximadamente 5,6 TB em BF16, 2,8 TB em oito bits ou 1,4 TB em quatro bits idealizados. Esses são cálculos de armazenamento bruto de parâmetros, não tamanhos reais de checkpoint ou mínimos de VRAM em tempo de execução. Precisão mista e metadados alteram o tamanho do arquivo; cache e alocações em runtime aumentam a exigência de serving.
Reserve capacidade NVMe para o download completo, arquivos temporários e uma cópia para rollback. Em sistemas multinó, valide a comunicação antes de carregar o modelo.
Como implantar o Kimi K3.1 Pro
Use autohospedagem se você tiver hardware adequado; caso contrário, comece com uma API hospedada. As etapas abaixo usam vLLM, com SGLang como alternativa ao final desta seção. Compare os custos de hospedagem após ter uma solicitação funcional.
Execute os comandos de setup, download, inicialização e verificação inicial em um shell Bash no servidor com GPU. Se estiver trabalhando a partir de um laptop, conecte-se a esse servidor primeiro via SSH. O cliente Python pode, posteriormente, ser executado em qualquer uma das máquinas usando as instruções de conexão abaixo.
Este passo a passo segue a receita oficial de implantação; ele não foi testado de forma independente para este artigo.
1. Verifique a visibilidade da GPU, armazenamento e conectividade
Comece com verificações básicas de infraestrutura:
nvidia-smi
nvidia-smi topo -m
df -h
Confirme que todas as GPUs de destino estão visíveis e que o diretório do modelo tem espaço suficiente. Reserve armazenamento adicional para caches de download, logs e versões futuras do checkpoint.
Para implantações multinó, verifique a comunicação entre os nós antes de tentar iniciar o modelo.
Mantenha estreito o primeiro marco: carregue o checkpoint e conclua uma solicitação curta de texto. Isso facilita o diagnóstico de falhas.
2. Prepare o ambiente de serving
Use um host Linux com oito GPUs B300 para este exemplo de nó único. Em um ambiente CUDA compatível com a receita publicada, crie um ambiente isolado e instale as ferramentas de serving:
O limite mínimo de versão não garante compatibilidade com todos os drivers ou wheels. Se a receita de hardware exigir um contêiner ou build dedicado, use esse ambiente. Faça pin da versão que foi testada com sucesso antes de produção.
3. Baixe o checkpoint completo
Instale a CLI do Hugging Face e baixe o repositório do modelo:
Mantenha os arquivos de configuração, tokenizer, processor e o índice de pesos junto aos shards de peso. Copiar apenas alguns arquivos de tensores pode deixar a implantação incompleta.
Para implantações reprodutíveis em produção, registre e fixe a revisão do repositório que você validou. Revise a licença personalizada do repositório antes de uso comercial.
Após preparar o ambiente, use o comando base abaixo. Ele inicia paralelismo tensorial de oito vias e limita a janela de contexto inicial a 32.768 tokens:
O nome kimi-local é um alias voltado ao aplicativo. Use o mesmo nome nas solicitações subsequentes.
A configuração de 32.768 tokens é um ponto de partida conservador para este passo a passo, não o contexto máximo suportado pelo modelo.
A opção --trust-remote-code permite carregar código personalizado do repositório. Emparelhe-a com uma revisão do checkpoint revisada e fixada.
Aqui, 127.0.0.1 se refere à máquina que executa o cliente. As verificações com curl abaixo são executadas no servidor com GPU, onde alcançam seu processo de inferência. Para usar o cliente Python a partir do seu laptop, abra um túnel SSH em um terminal separado no laptop e mantenha-o em execução:
ssh -N -L 8000:127.0.0.1:8000 user@gpu-server
Substitua user@gpu-server pelo seu login e endereço do servidor. Com esse túnel aberto, o cliente do laptop pode usar http://127.0.0.1:8000/v1. Se a porta 8000 já estiver ocupada no laptop, escolha outra porta local e atualize a URL do cliente.
5. Verifique o endpoint local
Confira se o servidor expõe o modelo:
curl http://127.0.0.1:8000/v1/models
Em seguida, envie uma solicitação curta de completion:
Um finish_reason indicando se a geração foi concluída ou atingiu seu limite.
Erros de memória de GPU ou de operação não suportada.
O raciocínio pode consumir parte do orçamento de geração. Se a solicitação atingir seu limite antes de produzir uma resposta final, aumente o orçamento e tente novamente antes de concluir que o servidor está com problemas.
6. Conecte um aplicativo Python local
python -m pip install openai
from openai import OpenAI
client = OpenAI(
base_url="http://127.0.0.1:8000/v1",
api_key="EMPTY",
timeout=300.0,
max_retries=1,
)
response = client.chat.completions.create(
model="kimi-local",
messages=[{"role": "user", "content": "Write a Python function that removes duplicate filenames while preserving order."}],
reasoning_effort="low",
max_tokens=2048,
)
print(response.choices[0].message.content)
print(response.choices[0].finish_reason)
EMPTY é um placeholder para este servidor de loopback sem autenticação por API key. Use sua credencial configurada para um endpoint autenticado. Valide a entrada de imagem e a execução de ferramentas separadamente antes de conectar um agente.
Alternativa SGLang
Para SGLang, use o cookbook oficial específico de hardware. Selecione B300, Unified e Low-Latency (TP8) para a correspondência mais próxima deste passo a passo de nó único. Verifique o status de verificação exibido; uma configuração gerada não é necessariamente uma configuração testada.
No servidor com GPU, instale Docker e configure o NVIDIA Container Toolkit, depois crie um contêiner com o checkpoint baixado montado em /models/Kimi-K3.1-Pro. Pare o vLLM primeiro, para que ambos os engines não disputem as mesmas GPUs.
Dentro do contêiner, cole o comando completo de inicialização produzido pelo cookbook para a configuração selecionada. Substitua o caminho do modelo por /models/Kimi-K3.1-Pro, defina o host do serviço como 0.0.0.0 e a porta como 30000, e preserve os flags específicos de hardware. O contêiner deve escutar em sua interface de rede para que o redirecionamento de porta do Docker funcione; a porta no host acima permanece vinculada ao loopback. Aguarde a mensagem de serviço pronto antes de testar.
Em um segundo shell no servidor com GPU, liste o modelo servido e, em seguida, envie uma solicitação usando o ID de modelo exato retornado:
curl http://127.0.0.1:30000/v1/models
MODEL_ID="replace-with-id-from-models-response"
curl http://127.0.0.1:30000/v1/chat/completions \
-H "Content-Type: application/json" \
-d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Explain database indexes in three sentences.\"}],\"reasoning_effort\":\"low\",\"max_tokens\":2048}"
Uma resposta bem-sucedida deve conter uma resposta final. Se a inicialização falhar, inspecione os logs do contêiner e confirme que a receita de hardware selecionada e a imagem correspondem. Para acesso via laptop, use o mesmo padrão de túnel SSH com a porta 30000. Consulte o guia de instalação do Docker do SGLang para os pré-requisitos do contêiner.
Como o Kimi K3.1 Pro se sai nos benchmarks?
Use os resultados oficiais de avaliação abaixo para escolher tarefas para seu teste de implantação. Essas pontuações descrevem o setup de avaliação publicado; elas não medem o servidor local configurado neste guia.
A tabela a seguir mostra resultados selecionados e suas posições no conjunto de comparação publicado no model card.
Benchmark e resultados oficiais
Pontuação do modelo
Posição dentro dessa comparação
Terminal-Bench 4.0
65,7
Segundo
SWE Marathon v1.1
51,7
Primeiro
Program Bench
31,5
Quarto
OfficeQA Pro v2
64,4
Primeiro entre os resultados reportados
Frontier Finance
58,6
Segundo
Os resultados justificam testar o modelo para tarefas de engenharia prolongadas e fluxos de trabalho com documentos. O Kimi K3.1 Pro lidera essa comparação no SWE Marathon, mas fica em quarto no ProgramBench, tornando ambos candidatos úteis para testes específicos do aplicativo.
Essas posições são calculadas dentro da tabela de comparação oficial, não em um ranking global ao vivo. Harnesses de avaliação, ferramentas, orçamentos de raciocínio e seleção de amostras diferem entre os benchmarks.
Para uma decisão de implantação, construa um pequeno conjunto de avaliação a partir do trabalho real: correções de repositório, perguntas entre documentos e tarefas de múltiplas etapas com ferramentas. Meça a qualidade de conclusão, correções humanas e tempo decorrido. Pontuações publicadas são úteis para shortlist; testes no aplicativo determinam se a implantação vale a pena.
Como otimizar a inferência local do Kimi K3.1 Pro?
Controle o contexto e a concorrência
Quando solicitações curtas funcionarem, teste separadamente documentos longos, imagens, conversas multi-turno e chamadas de ferramentas.
Acompanhe latência do primeiro token, tokens por segundo de saída e pico de memória da GPU no comprimento de contexto e concorrência pretendidos. Registre também sucesso de tarefa e custo por tarefa bem-sucedida, para que uma saída mais rápida não oculte mais retentativas ou correções humanas.
Altere uma variável principal por vez. Aumentar simultaneamente o comprimento de contexto, a concorrência e as configurações de otimização torna difícil explicar regressões de desempenho.
Escolha deliberadamente o esforço de raciocínio e as configurações de cache
Use esforço de raciocínio baixo, alto ou máximo conforme a tarefa. Comece com baixo para verificações de interface e compare alto e máximo em tarefas difíceis usando tanto a qualidade da conclusão quanto o tempo decorrido. Um traço de raciocínio mais longo não é, por si só, evidência de um resultado melhor.
Para sessões longas, avalie a capacidade do cache e o reuso de prefixo antes de adicionar decodificação especulativa ou mais concorrência. Mantenha uma base conhecida como boa e altere uma configuração por vez.
Por que as chamadas de ferramentas do Kimi K3.1 Pro podem falhar após a implantação?
Seu aplicativo executa chamadas de ferramentas, retorna seus resultados e continua a conversa. Preserve a mensagem completa do assistente — incluindo reasoning_content e tool_calls — e retorne cada resultado de ferramenta com seu tool_call_id correspondente.
O tratamento multi-turno também é importante. A orientação de uso do modelo exige preservar a mensagem completa do assistente, incluindo campos de raciocínio e de chamada de ferramentas, em vez de manter apenas o texto final.
Sintoma
Primeiras verificações
Arquitetura de modelo não reconhecida
Versão do runtime, código personalizado e configuração
Falta de memória ao carregar
Capacidade da GPU, paralelismo e processos concorrentes
Solicitações curtas funcionam, longas falham
Limite de contexto, capacidade de cache e concorrência
Chamadas de ferramentas não podem ser analisadas
Configurações do parser e esquema da ferramenta
O agente para após solicitar uma ferramenta
Execução do aplicativo e tratamento do resultado da ferramenta
Respostas multi-turno tornam-se inconsistentes
Campos da mensagem do assistente ausentes
Use uma solicitação mínima reprodutível para isolar cada falha. Quando funcionar, reintroduza as configurações adicionais do aplicativo uma a uma.
Você deve hospedar por conta própria ou usar uma API hospedada?
Escolha autohospedagem quando precisar de controle sobre pesos, infraestrutura ou localização dos dados e puder manter as GPUs utilmente ocupadas. Para avaliação inicial ou demanda variável, compare a API oficial do Kimi e a CometAPI usando os mesmos prompts e critérios de aceitação. Confirme o acesso ao modelo de cada serviço, parâmetros suportados, cotas e termos de tratamento de dados.
Fator de custo ou operação
Autohospedado
API oficial do Kimi / CometAPI
Custo de capacidade
Compra ou aluguel de GPU, incluindo tempo ocioso
Uso de API faturado; verifique as tarifas atuais de cada provedor
Armazenamento e rede
Armazenamento do checkpoint, cache e custos de rede
Quaisquer custos de armazenamento e rede do lado do aplicativo
Operações
Implantação, monitoramento, upgrades e recuperação
Integração, gestão de cotas e monitoramento de solicitações
Retentativas
Inclua o tempo de GPU no custo de computação
Inclua os tokens ou chamadas no custo da API
Revisão humana
Conte o tempo de correção usando a mesma taxa
Conte o tempo de correção usando a mesma taxa
Melhor ajuste
Demanda estável e controle de infraestrutura
Avaliação e demanda variável
Uma comparação útil é:
Custo por tarefa bem-sucedida = (computação de GPU ou cobranças de API + armazenamento e rede + operações + correção humana) / tarefas concluídas com sucesso.
Use custos e contagens de tarefas bem-sucedidas do mesmo período de medição. Inclua tentativas com falha e retentativas no total de computação ou API uma vez; não adicione uma segunda cobrança pela retentativa. Para um fluxo híbrido, inclua tanto computação quanto cobranças de API. Conte tarefas concluídas únicas, não tentativas de solicitação.
Um servidor subutilizado pode continuar caro mesmo quando seu throughput teórico é excelente. Por outro lado, uma equipe com infraestrutura existente, demanda estável e requisitos rígidos de dados pode obter valor substancial com autohospedagem.
Use prompts e critérios de aceitação idênticos ao comparar rotas de implantação. Inclua latência de ponta a ponta e qualidade de saída na decisão.
Teste o endpoint hospedado sem carregar pesos
O quickstart da API oficial do Kimi usa o endpoint abaixo. Defina MOONSHOT_API_KEY no seu ambiente e confirme o acesso ao modelo na sua conta. Esta solicitação é executada na infraestrutura do provedor.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["MOONSHOT_API_KEY"],
base_url="https://api.moonshot.ai/v1",
)
response = client.chat.completions.create(
model="kimi-k3.1-pro",
messages=[{"role": "user", "content": "Explain database indexes in three sentences."}],
reasoning_effort="low",
max_completion_tokens=2048,
)
print(response.choices[0].message.content)
Para a API do Kimi K3.1 Pro na CometAPI, defina COMETAPI_API_KEY no seu ambiente e confirme que sua conta tem acesso ao modelo solicitado. A solicitação roda remotamente:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["COMETAPI_API_KEY"],
base_url="https://api.cometapi.com/v1",
)
response = client.chat.completions.create(
model="kimi-k3.1-pro",
messages=[{"role": "user", "content": "Explain database indexes in three sentences."}],
max_tokens=2048,
)
print(response.choices[0].message.content)
Compare o resultado com seu endpoint local usando os mesmos critérios de aceitação. Verifique o preço atual da rota e os parâmetros suportados antes de estimar custos de produção.
Conclusão
Autohospedar o Kimi K3.1 Pro é viável com uma configuração de GPU suportada e o ambiente de inferência correspondente. Use as etapas de implantação acima para estabelecer um endpoint funcional e, em seguida, meça qualidade de tarefa, latência e custo no seu próprio workload. Escolha uma API hospedada se você ainda estiver validando o aplicativo ou não tiver hardware adequado.
FAQ
Um laptop comum consegue executar o modelo completo?
Um laptop comum não é um alvo prático para os requisitos de capacidade do checkpoint original. Ele pode atuar como cliente conectado ao seu próprio servidor de inferência ou a uma API hospedada.
Instalar o aplicativo desktop conta como implantação local?
A localização da instalação do aplicativo não determina onde a inferência ocorre. Autohospedagem exige que os pesos do modelo e o processo de inferência sejam executados em infraestrutura sob seu controle.
Por que o modelo precisa de tanta memória se apenas 104B parâmetros estão ativos?
Tokens diferentes podem selecionar experts diferentes. Parâmetros ativos descrevem participação no cálculo; a implantação ainda precisa armazenar e acessar o conjunto completo de pesos.
Posso habilitar imediatamente o contexto completo de um milhão de tokens?
Aumente gradualmente o comprimento de contexto e meça o uso de memória da GPU na concorrência desejada. O modelo suporta 1.048.576 tokens, mas a capacidade de serving utilizável depende do seu cache e das configurações de paralelismo.
A implantação local reproduzirá as pontuações de benchmark publicadas?
Não automaticamente. Quantização, orçamentos de raciocínio, ferramentas, prompts e frameworks de avaliação podem afetar os resultados. Valide a configuração em suas próprias tarefas.
Devo testar via API antes de comprar hardware?
Se você não estabeleceu que o modelo atende às suas exigências de qualidade, testar via API fornece uma linha de base inicial com menos trabalho de infraestrutura. Equipes com hardware adequado e requisitos claros de residência de dados podem seguir diretamente para uma avaliação controlada de autohospedagem.
