Crea con CometAPITi serve una sola API per più modelli?Testa il flusso di lavoro in Playground, poi crea una chiave API quando modello e costo sono adatti al tuo caso d'uso.
Come distribuire Kimi K3.1 Pro in locale: requisiti hardware, configurazione di vLLM
Scopri come ospitare in proprio Kimi K3.1 Pro con vLLM, verificare i requisiti della GPU, scaricare i pesi, testare l’inferenza e confrontare la distribuzione locale con l’accesso via API.
Distribuisci Kimi K3.1 Pro su un server Linux con GPU, quindi collega un’applicazione locale al suo endpoint di inferenza. Questa guida utilizza un nodo NVIDIA B300 con otto GPU e vLLM. Ti serviranno accesso alla shell del server, driver compatibili e spazio per il checkpoint completo. Inizia completando una breve richiesta testuale prima di testare input più lunghi o workflow di agent.
Senza GPU adeguate, puoi eseguire l’applicazione in locale e collegarla all’API ufficiale Kimi o a un provider di terze parti come CometAPI.
Punti chiave
I 104 miliardi di parametri attivi del modello non rappresentano il suo requisito di archiviazione complessivo.
La compatibilità hardware include memoria GPU, interconnessioni, supporto alla quantizzazione e kernel d’inferenza.
Revisionato per chiarezza, attribuzione delle fonti e terminologia API aggiornata.
Risultati solidi ai benchmark rendono il modello meritevole di test, ma non garantiscono prestazioni equivalenti nella tua applicazione.
Un endpoint di inferenza funzionante non include automaticamente un browser, una sandbox di codice o un runtime di agente completo.
Confronta self-hosting e accesso via API in base al costo per task riuscito, inclusi retry e manutenzione.
Che cos’è Kimi K3.1 Pro?
Kimi K3.1 Pro è il modello multimodale a pesi aperti di Moonshot AI per programmazione, analisi di documenti e uso di strumenti. Le sue specifiche principali sono riportate di seguito, basate sulla scheda del modello ufficiale .
Specifica
Configurazione pubblicata
Architettura
MoE; 2,8T parametri totali, 104B attivi
Attenzione
93 livelli: 69 KDA + 24 Gated DSA
Esperti
896 instradati; 16 selezionati per token; 2 condivisi
Contesto
1.048.576 token
Input
Testo e immagini; encoder visivo MoonViT-V2
Quantizzazione
Pesi MXFP4 / attivazioni MXFP8; checkpoint a precisione mista
Motori consigliati
vLLM, SGLang, TokenSpeed
Il modello attiva 104 miliardi di parametri per token, ma la distribuzione richiede comunque il checkpoint completo da 2,8T parametri. Il motore di inferenza deve inoltre supportare i layer KDA e Gated DSA e la quantizzazione MXFP4.
Quale hardware serve per eseguire Kimi K3.1 Pro in locale?
La tabella seguente riassume le configurazioni vLLM rilevanti per questa guida. La procedura utilizza un nodo B300 con otto GPU; le distribuzioni su GB300 e AMD richiedono le rispettive configurazioni.
Hardware
Percorso documentato
Note di pianificazione
NVIDIA B300
Un nodo a otto GPU, TP8
Baseline per la procedura qui sotto
NVIDIA GB300
Otto GPU su due tray, TP8
Richiede configurazione multi-nodo e setup delle interconnessioni
AMD MI355X
Nodo a otto GPU con configurazione specifica
Usa il percorso ROCm/AITER; non riutilizzare le impostazioni NVIDIA
Singola GPU consumer 24–32 GB
Insufficiente per caricare il checkpoint completo
Non è un target pratico per questo tutorial
A titolo di scala, 2,8T parametri occuperebbero circa 5,6 TB in BF16, 2,8 TB a otto bit o 1,4 TB a quattro bit idealizzati. Si tratta di calcoli grezzi dello storage dei parametri, non delle dimensioni reali dei checkpoint o dei minimi di VRAM a runtime. La precisione mista e i metadati modificano la dimensione dei file; cache e allocazioni runtime aumentano il requisito di serving.
Riserva capacità NVMe per il download completo, file temporanei e una copia di rollback. Nei sistemi multi-nodo, valida la comunicazione prima di caricare il modello.
Come distribuire Kimi K3.1 Pro
Usa il self-hosting se disponi di hardware adeguato; altrimenti, inizia con un’API hosted. I passaggi sottostanti usano vLLM, con SGLang come alternativa alla fine di questa sezione. Confronta i costi di hosting dopo aver eseguito una richiesta funzionante.
Esegui i comandi di setup, download, avvio e verifica iniziale in una shell Bash sul server GPU. Se lavori da un laptop, collegati prima a quel server via SSH. Il client Python può poi essere eseguito su una delle due macchine seguendo le istruzioni di connessione sottostanti.
Questa procedura segue la ricetta di deployment ufficiale; non è stata testata in modo indipendente per questo articolo.
1. Verificare visibilità GPU, storage e connettività
Inizia con verifiche basilari dell’infrastruttura:
nvidia-smi
nvidia-smi topo -m
df -h
Conferma che tutte le GPU target siano visibili e che la directory del modello disponga di spazio sufficiente. Prevedi ulteriore spazio per cache di download, log e versioni future del checkpoint.
Per deployment multi-nodo, verifica la comunicazione tra i nodi prima di tentare l’avvio del modello.
Mantieni il primo traguardo circoscritto: carica il checkpoint e completa una breve richiesta testuale. Questo rende più semplice diagnosticare eventuali errori.
2. Preparare l’ambiente di serving
Usa un host Linux con otto GPU B300 per questo esempio a nodo singolo. In un ambiente CUDA compatibile con la ricetta pubblicata, crea un ambiente isolato e installa gli strumenti di serving:
Il requisito minimo di versione non garantisce la compatibilità con ogni driver o wheel. Se la ricetta hardware richiede un container o una build dedicata, usa quell’ambiente. Prima della produzione, blocca la versione che ha superato i test.
3. Scaricare il checkpoint completo
Installa la CLI di Hugging Face e scarica il repository del modello:
Mantieni i file di configurazione, tokenizer, processor e l’indice dei pesi insieme agli shard dei pesi. Copiare solo alcuni file dei tensori può lasciare il deployment incompleto.
Per deployment di produzione riproducibili, registra e blocca la revisione del repository che hai convalidato. Rivedi la licenza personalizzata del repository prima dell’uso commerciale.
Dopo aver preparato l’ambiente, usa il seguente comando di base. Avvia un parallelismo tensoriale a otto vie e limita la finestra di contesto iniziale a 32.768 token:
Il nome kimi-local è un alias esposto all’applicazione. Usa lo stesso nome nelle richieste successive.
L’impostazione a 32.768 token è un punto di partenza prudente per questa guida, non il contesto massimo supportato dal modello.
L’opzione --trust-remote-code consente di caricare codice personalizzato del repository. Associala a una revisione del checkpoint revisionata e bloccata.
Qui, 127.0.0.1 si riferisce alla macchina che esegue il client. I check con curl sottostanti sono eseguiti sul server GPU, dove raggiungono il suo processo di inferenza. Per usare il client Python dal laptop, apri un tunnel SSH in un terminale separato del laptop e mantienilo attivo:
ssh -N -L 8000:127.0.0.1:8000 user@gpu-server
Sostituisci user@gpu-server con il tuo login SSH e l’indirizzo del server. Con questo tunnel aperto, il client sul laptop può usare http://127.0.0.1:8000/v1. Se la porta 8000 è già occupata sul laptop, scegli una porta locale diversa e aggiorna l’URL del client.
5. Verificare l’endpoint locale
Verifica che il server esponga il modello:
curl http://127.0.0.1:8000/v1/models
Quindi invia una breve richiesta di completamento:
curl http://127.0.0.1:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "kimi-local",
"messages": [
{
"role": "user",
"content": "Spiega gli indici di database in tre frasi."
}
],
"reasoning_effort": "low",
"max_tokens": 2048
}'
Controlla la risposta e i log del server per:
Il nome del modello atteso.
Una risposta finale nel payload.
Un campo finish_reason che indichi se la generazione è completata o ha raggiunto il limite.
Errori di memoria GPU o operazioni non supportate.
Il ragionamento può consumare parte del budget di generazione. Se la richiesta raggiunge il limite prima di produrre una risposta finale, aumenta il budget e riprova prima di concludere che il server non funziona.
6. Collegare un’applicazione Python locale
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": "Scrivi una funzione Python che rimuova i nomi di file duplicati preservando l’ordine."}],
reasoning_effort="low",
max_tokens=2048,
)
print(response.choices[0].message.content)
print(response.choices[0].finish_reason)
EMPTY è un segnaposto per questo server in loopback senza autenticazione tramite API key. Usa la credenziale configurata per un endpoint autenticato. Convalida separatamente l’input di immagini e l’esecuzione degli strumenti prima di collegare un agent.
Alternativa SGLang
Per SGLang, usa il cookbook ufficiale specifico per l’hardware. Seleziona B300, Unified e Low-Latency (TP8) per l’assetto più vicino a questa procedura a nodo singolo. Controlla lo stato di verifica mostrato; una configurazione generata non è necessariamente una configurazione testata.
Sul server GPU, installa Docker e configura NVIDIA Container Toolkit, quindi crea un container con il checkpoint scaricato montato in /models/Kimi-K3.1-Pro. Arresta vLLM prima, in modo che i due motori non competano per le stesse GPU.
All’interno del container, incolla il comando di avvio completo prodotto dal cookbook per la configurazione selezionata. Sostituisci il percorso del modello con /models/Kimi-K3.1-Pro, imposta l’host del servizio su 0.0.0.0 e la porta su 30000, e preserva i flag specifici dell’hardware. Il container deve mettersi in ascolto sulla propria interfaccia di rete affinché il port forwarding di Docker funzioni; la porta lato host sopra resta vincolata al loopback. Attendi il messaggio di servizio pronto prima di testare.
In una seconda shell sul server GPU, elenca il modello servito, quindi invia una richiesta usando l’ID del modello restituito esattamente:
curl http://127.0.0.1:30000/v1/models
MODEL_ID="sostituisci-con-id-dalla-risposta-di-models"
curl http://127.0.0.1:30000/v1/chat/completions \
-H "Content-Type: application/json" \
-d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Spiega gli indici di database in tre frasi.\"}],\"reasoning_effort\":\"low\",\"max_tokens\":2048}"
Una risposta corretta dovrebbe contenere un risultato finale. Se l’avvio fallisce, ispeziona i log del container e conferma che la ricetta hardware selezionata e l’immagine corrispondano. Per l’accesso dal laptop, usa lo stesso schema di tunnel SSH con porta 30000. Consulta la guida all’installazione Docker di SGLang per i prerequisiti del container.
Come si comporta Kimi K3.1 Pro nei benchmark?
Usa i risultati ufficiali di valutazione sottostanti per scegliere i task del tuo test di deployment. Questi punteggi descrivono l’assetto di valutazione pubblicato; non misurano il server locale configurato in questa guida.
La tabella seguente mostra alcuni risultati selezionati e le loro posizioni nel set di confronto pubblicato nella scheda del modello.
Benchmark e risultati ufficiali
Punteggio modello
Posizione in quel confronto
Terminal-Bench 4.0
65,7
Secondo
SWE Marathon v1.1
51,7
Primo
Program Bench
31,5
Quarto
OfficeQA Pro v2
64,4
Primo tra i risultati riportati
Frontier Finance
58,6
Secondo
I risultati supportano il test del modello per task ingegneristici estesi e workflow documentali. Kimi K3.1 Pro guida questo confronto su SWE Marathon ma si colloca quarto su ProgramBench, rendendo entrambi utili candidati per test specifici dell’applicazione.
Queste posizioni sono calcolate all’interno della tabella di confronto ufficiale, non in una classifica globale live. Harness di valutazione, strumenti, budget di ragionamento e selezione dei campioni differiscono tra i benchmark.
Per una decisione di deployment, costruisci un piccolo set di valutazione a partire da lavoro reale: fix di repository, domande cross-document e task multi-step con strumenti. Misura qualità di completamento, correzioni umane e tempo trascorso. I punteggi pubblicati sono utili per una shortlist; i test sull’applicazione determinano se il deployment è vantaggioso.
Come ottimizzare l’inferenza locale di Kimi K3.1 Pro?
Controllare contesto e concorrenza
Una volta che le richieste brevi funzionano, testa separatamente documenti più lunghi, immagini, conversazioni multi-turn e chiamate a strumenti.
Monitora latenza del primo token, token di output al secondo e picco di memoria GPU alla tua lunghezza di contesto e concorrenza desiderate. Registra anche successo del task e costo per task riuscito, così che un output più rapido non nasconda più retry o correzioni umane.
Modifica una variabile principale alla volta. Aumentare contemporaneamente lunghezza del contesto, concorrenza e impostazioni di ottimizzazione rende difficile spiegare eventuali regressioni prestazionali.
Scegliere deliberatamente livello di ragionamento e cache
Usa low, high o max reasoning effort in base al task. Parti da low per i controlli dell’interfaccia, poi confronta high e max su task difficili usando sia qualità del completamento sia tempo trascorso. Un trace di ragionamento più lungo non è di per sé prova di un risultato migliore.
Per sessioni lunghe, valuta capacità della cache e riuso del prefisso prima di aggiungere decodifica speculativa o più concorrenza. Mantieni una baseline nota e modifica un’impostazione alla volta.
Perché le chiamate a strumenti possono fallire dopo il deployment?
La tua applicazione esegue le chiamate a strumenti, ritorna i loro risultati e prosegue la conversazione. Conserva l’intero messaggio dell’assistente, inclusi reasoning_content e tool_calls, e restituisci ciascun risultato dello strumento con il tool_call_id corrispondente.
Anche la gestione multi-turn è importante. Le linee guida d’uso del modello richiedono di mantenere l’intero messaggio dell’assistente, inclusi i campi di ragionamento e delle chiamate agli strumenti, invece di trattenere solo il testo finale.
Sintomo
Prime verifiche
Architettura del modello non riconosciuta
Versione runtime, codice personalizzato e config
Out of memory durante il caricamento
Capacità GPU, parallelismo e processi concorrenti
Le richieste brevi funzionano ma le lunghe falliscono
Limite di contesto, capacità cache e concorrenza
Le chiamate a strumenti non possono essere parse
Impostazioni del parser e schema degli strumenti
L’agent si ferma dopo aver richiesto uno strumento
Esecuzione applicativa e gestione del risultato dello strumento
Le risposte multi-turn diventano incoerenti
Campi del messaggio dell’assistente mancanti
Usa una richiesta minima riproducibile per isolare ogni errore. Una volta che funziona, reintroduci una alla volta le impostazioni aggiuntive dell’applicazione.
Meglio auto-ospitare o usare una API hosted?
Scegli il self-hosting quando ti servono controllo sui pesi, infrastruttura o ubicazione dei dati e puoi mantenere le GPU utilmente occupate. Per valutazioni iniziali o domanda variabile, confronta la Kimi API ufficiale e CometAPI usando gli stessi prompt e criteri di accettazione. Conferma accesso al modello, parametri supportati, quote e termini di gestione dei dati di ciascun servizio.
Fattore di costo o operativo
Self-hosted
Kimi API ufficiale / CometAPI
Costo di capacità
Acquisto o noleggio GPU, incluso tempo di idle
Uso API fatturato; verifica le tariffe correnti
Storage e networking
Storage del checkpoint, cache e costi di rete
Eventuali costi di storage e rete lato applicazione
Operations
Deployment, monitoraggio, upgrade e recovery
Integrazione, gestione quote e monitoraggio richieste
Retry
Includi il loro tempo GPU nei costi di compute
Includi i loro token o chiamate nei costi API
Revisione umana
Conta il tempo di correzione alla stessa tariffa
Conta il tempo di correzione alla stessa tariffa
Miglior fitting
Domanda stabile e controllo dell’infrastruttura
Valutazione e domanda variabile
Un confronto utile è:
Costo per task riuscito = (Compute GPU o costi API + storage e networking + operations + correzione umana) / task completati con successo.
Usa costi e conteggi dei task riusciti nello stesso periodo di misurazione. Includi tentativi falliti e retry nel totale compute o API una sola volta; non aggiungere un secondo addebito per il retry. Per un workflow ibrido, includi sia compute sia costi API. Conta i task completati unici, non i tentativi di richiesta.
Un server sottoutilizzato può rimanere costoso anche quando il throughput teorico è eccellente. Viceversa, un team con infrastruttura esistente, domanda stabile e requisiti rigorosi sui dati può trarre notevole valore dal self-hosting.
Usa prompt e criteri di accettazione identici quando confronti le modalità di deployment. Includi nella decisione latenza end-to-end e qualità dell’output.
Prova l’endpoint hosted senza caricare i pesi
Il quickstart dell’API ufficiale Kimi usa l’endpoint seguente. Imposta MOONSHOT_API_KEY nel tuo ambiente e conferma l’accesso al modello nel tuo account. Questa richiesta viene eseguita sull’infrastruttura del provider.
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": "Spiega gli indici di database in tre frasi."}],
reasoning_effort="low",
max_completion_tokens=2048,
)
print(response.choices[0].message.content)
Per la Kimi K3.1 Pro API in CometAPI, imposta COMETAPI_API_KEY nel tuo ambiente e conferma che il tuo account abbia accesso al modello richiesto. La richiesta viene eseguita in remoto:
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": "Spiega gli indici di database in tre frasi."}],
max_tokens=2048,
)
print(response.choices[0].message.content)
Confronta il risultato con il tuo endpoint locale usando gli stessi criteri di accettazione. Controlla il prezzo corrente della rotta e i parametri supportati prima di stimare i costi di produzione.
Conclusione
Il self-hosting di Kimi K3.1 Pro è praticabile con una configurazione GPU supportata e l’ambiente di inferenza corrispondente. Usa i passaggi di deployment sopra per stabilire un endpoint funzionante, quindi misura qualità del task, latenza e costo sul tuo carico di lavoro. Scegli un’API hosted se stai ancora validando l’applicazione o non disponi di hardware adeguato.
FAQ
Un normale laptop può eseguire il modello completo?
Un normale laptop non è un target pratico per i requisiti di capacità del checkpoint originale. Può agire come client collegato al tuo server di inferenza o a un’API hosted.
L’installazione dell’app desktop conta come deployment locale?
La posizione di installazione dell’applicazione non stabilisce dove avvenga l’inferenza. Il self-hosting richiede che i pesi del modello e il processo di inferenza vengano eseguiti in un’infrastruttura sotto il tuo controllo.
Perché il modello necessita così tanta memoria se solo 104B parametri sono attivi?
Token diversi possono selezionare esperti diversi. I parametri attivi descrivono la partecipazione al calcolo; la distribuzione deve comunque memorizzare e accedere all’intero set di pesi.
Posso abilitare subito l’intero contesto da un milione di token?
Aumenta gradualmente la lunghezza del contesto e misura l’uso di memoria GPU alla concorrenza target. Il modello supporta 1.048.576 token, ma la capacità di serving utilizzabile dipende da cache e impostazioni di parallelismo.
Il deployment locale riprodurrà i punteggi di benchmark pubblicati?
Non automaticamente. Quantizzazione, budget di ragionamento, strumenti, prompt e framework di valutazione possono influenzare i risultati. Valida la configurazione sui tuoi task.
Dovrei testare via API prima di acquistare hardware?
Se non hai stabilito che il modello soddisfi i requisiti di qualità, il test via API fornisce una baseline iniziale con meno lavoro infrastrutturale. I team con hardware adeguato e chiari requisiti di residenza dei dati possono passare direttamente a una valutazione controllata in self-hosting.
