Principali problemi Ollama con Kimi
Principali problemi Ollama con Kimi
Guida pratica per sviluppatori e ingegneri informatici
Kimi K2 di Moonshot AI è oggi uno dei modelli open-weight più performanti per il lavoro agentico: coding, tool use, ragionamento a lungo orizzonte. Integrato con Ollama, offre una pipeline comoda per chi vuole usare modelli di grandi dimensioni senza rinunciare alla propria infrastruttura. Ma chi ha già provato a collegare Kimi a Claude Code o ad altri agenti sa bene che la strada non è sempre liscia.
In questo articolo raccogliamo i principali problemi segnalati dalla community di sviluppatori, su GitHub Issues e forum tecnici, e per ciascuno forniamo una soluzione pratica. Se stai cercando di far funzionare Kimi con Claude Code, Hermes o qualsiasi altro agente AI basato su Ollama, sei nel posto giusto.
Indice dei contenuti – Principali problemi Ollama con Kimi
1. Cos’è Kimi K2 e perché usarlo con Ollama
2. Problema 1: Errore 403: il modello richiede un abbonamento
3. Problema 2: Tag deprecati: kimi-k2:1t-cloud e kimi-k2-thinking
4. Problema 3: Tool calling rotto: le chiamate agli strumenti escono come testo grezzo
5. Problema 4: Context window rilevata erroneamente (32K invece di 256K)
6. Problema 5: Claude Code produce un solo token per risposta
7. Problema 6: Limite di 30 immagini per conversazione (analisi multimodale)
8. Problema 7: Configurare Claude Code con Kimi via Ollama manualmente
9. Best practice: pro e contro di Ollama con Kimi
10. Conclusioni e formazione professionale
1. Cos’è Kimi K2 e perché usarlo con Ollama
Cominciamo la nostra guida sui Principali problemi Ollama con Kimi. Kimi K2 è un modello open-weight sviluppato da Moonshot AI, con architettura Mixture-of-Experts (MoE): 1 trilione di parametri totali, 32 miliardi attivi per ogni forward pass. È stato addestrato su 15,5 trilioni di token con un ottimizzatore proprietario chiamato MuonClip. Il risultato è un modello progettato esplicitamente per l’uso agentico: coding a lungo orizzonte, tool calling, pianificazione multi-step.
Su SWE-Bench Verified raggiunge il 65,8% in modalità standard, superando modelli come DeepSeek-V3 e GPT-4.1 su task di ingegneria del software. Dalla versione K2-Instruct (settembre 2025) dispone di una finestra di contesto da 256K token.
Il problema pratico è uno: le sue dimensioni (oltre 247 GB anche alla quantizzazione 1,8-bit) rendono impossibile l’esecuzione locale su qualsiasi laptop o workstation consumer. Ollama risolve questo con il tag :cloud — il modello gira sui server di Ollama, ma l’interfaccia CLI e API rimane identica al flusso locale. Una soluzione elegante, ma con alcune insidie che analizziamo di seguito.
2. Problema 1: Errore 403: il modello richiede un abbonamento
Sintomi
Molti sviluppatori si sono trovati di fronte a questo errore senza preavviso:
Error: 403 Forbidden: this model requires a subscription, upgrade for access: https://ollama.com/upgrade
Il problema è segnalato in modo ricorrente su GitHub Issues di Ollama (issue #15741, aprile 2026). L’utente è regolarmente autenticato, l’utilizzo settimanale è ben al di sotto del limite, eppure Kimi restituisce 403 mentre altri modelli cloud (es. Gemma) funzionano normalmente.
Causa
Kimi K2 (dalla versione K2.5 in poi) è classificato come modello di livello superiore nella gerarchia di Ollama Cloud. Il piano gratuito copre solo modelli di livello 1 e 2; Kimi rientra in una fascia che richiede il piano Pro o superiore. La transizione non è sempre comunicata chiaramente nella documentazione.
Un ulteriore problema documentato: quando un modello a pagamento restituisce un 403, in alcune configurazioni il cooldown si propaga all’intera connessione Ollama Cloud, bloccando temporaneamente anche i modelli gratuiti.
Soluzione
- Verificare il piano attivo su ollama.com/settings e accertarsi di avere il piano Pro ($20/mese) o Max per usare Kimi K2.5 / K2.6 / K2.7.
- Se si è sul piano gratuito, usare modelli di livello inferiore (Gemma, Qwen3.6-27B) per i task non critici e riservare Kimi ai workflow agentic più impegnativi.
- In ambienti di test, separare i modelli a pagamento da quelli gratuiti in richieste distinte per evitare il cooldown globale della connessione.
- Alternativa: usare la Kimi API ufficiale di Moonshot AI direttamente, con le proprie chiavi, per avere pieno controllo su quota e fatturazione.
3. Problema 2: Tag deprecati: kimi-k2:1t-cloud e kimi-k2-thinking
Sintomi
Script, Modelfile e configurazioni di agenti che facevano riferimento ai tag kimi-k2:1t-cloud o kimi-k2-thinking smettono di funzionare. Il modello non risponde o restituisce un errore di modello non trovato.
Causa
Il 16 giugno 2026 Ollama ha ritirato ufficialmente entrambi i tag. Il modello aggiornato è kimi-k2.6:cloud (1,04 trilioni di parametri, 256K contesto, multimodale). Dal 2026 è disponibile anche kimi-k2.7-code:cloud, ottimizzato per il coding con un consumo di token di pensiero ridotto del 30% rispetto a K2.6.
Soluzione
Aggiornare tutti i riferimenti negli script e nei Modelfile. Esempio pratico:
# PRIMA (deprecato dopo il 16/06/2026) ollama run kimi-k2:1t-cloud # DOPO (versione attuale) ollama run kimi-k2.6:cloud # Per task di coding agentico ollama run kimi-k2.7-code:cloud
Per Claude Code, aggiornare il flag –model:
ANTHROPIC_AUTH_TOKEN=ollama \ ANTHROPIC_BASE_URL=http://localhost:11434 \ ANTHROPIC_API_KEY=”” \ claude –model kimi-k2.7-code:cloud
ℹ️ Consiglio: nei team, centralizzare il nome del modello in una variabile d’ambiente (MODEL=kimi-k2.6:cloud) e referenziarla in tutti gli script. In questo modo un aggiornamento richiede una sola modifica.
4. Problema 3: Tool calling rotto: le chiamate escono come testo grezzo – Principali problemi Ollama con Kimi
Sintomi
Quando si usa Kimi K2.5 (versione locale) con strumenti definiti via API, il modello emette i tool call come testo ASCII invece di restituire oggetti strutturati nel campo message.tool_calls. L’agente non riesce a parsare le chiamate e il workflow si interrompe.
Causa
Come documentato nell’issue #14360 di Ollama (febbraio 2026), il chat template ufficiale di Kimi K2.5 su Ollama manca del blocco {{ .ToolCalls }}, necessario al parser di Ollama per riconoscere e strutturare le chiamate agli strumenti. Il modello usa token nativi propri (<|tool_calls_section_begin|>, <|tool_call_begin|>, ecc.) che non vengono intercettati.
Soluzione: Modelfile personalizzato
Creare un Modelfile che sovrascrive il template con una versione corretta:
FROM kimi-k2.5:latest TEMPLATE “”” {{- if .Tools }}<|im_system|>tool_declare<|im_middle|>{{ .Tools }}<|im_end|> {{- end }} {{- range $i, $_ := .Messages }} {{- $last := eq (len (slice $.Messages $i)) 1 }} {{- if eq .Role “system” }}<|im_system|>system<|im_middle|>{{ .Content }}<|im_end|> {{- else if eq .Role “user” }}<|im_user|>user<|im_middle|>{{ .Content }}<|im_end|> {{- else if eq .Role “assistant” }}<|im_assistant|>assistant<|im_middle|> {{- if .ToolCalls }}{{ .ToolCalls }}{{- end }} {{ .Content }} {{- if not $last }}<|im_end|>{{- end }} {{- end }} {{- end }} “””
Poi costruire e avviare il modello personalizzato:
ollama create kimi-k2.5-tools -f ./Modelfile ollama run kimi-k2.5-tools
Per le versioni cloud (K2.6, K2.7) il problema non si presenta: i modelli cloud di Ollama usano il template corretto lato server.
5. Problema 4: Context window rilevata erroneamente (32K invece di 256K)
Sintomi
Agenti come Hermes rifiutano kimi-k2.6:cloud con l’errore:
ValueError: Model kimi-k2.6 has a context window of 32,768 tokens, below the minimum 64,000 required by Hermes Agent.
Eppure l’API Ollama Cloud riporta correttamente 262.144 token (256K). Il bug è documentato nell’issue #23949 di NousResearch/hermes-agent (maggio 2026).
Causa
La funzione detect_local_server_type() di Hermes non riesce a identificare https://ollama.com/v1 come provider ‘ollama’ (perché è un endpoint remoto, non localhost). Di conseguenza, la query_ollama_num_ctx() non viene chiamata e si usa un fallback hardcoded di 32.768 token.
Soluzione
Aggiungere la context window manualmente nel file config.yaml dell’agente:
# config.yaml model: name: kimi-k2.6:cloud context_length: 262144 # forzare 256K
Per agenti che usano variabili d’ambiente o flag CLI, specificare il parametro num_ctx:
# Esempio con curl diretto a Ollama curl http://localhost:11434/api/chat \ -d ‘{ “model”: “kimi-k2.6:cloud”, “options”: { “num_ctx”: 131072 }, “messages”: [{“role”: “user”, “content”: “ciao”}] }’
ℹ️ Attenzione: per l’inferenza locale con llama.cpp, aumentare il contesto ha un costo diretto in VRAM. Con il modello cloud, il limite reale è 256K ma la latenza aumenta con prompt molto lunghi.
6. Problema 5: Claude Code produce un solo token per risposta
Sintomi
Quando si usa ollama launch claude con un modello Kimi (o altri modelli), l’agente restituisce solo un token per ogni risposta — di fatto la generazione si blocca subito. Il problema colpisce tutti i casi d’uso agentic basati su ollama launch.
Causa e soluzione
Si tratta di un bug introdotto in una versione intermedia di Ollama, corretto nel changelog ufficiale del progetto (GitHub releases, maggio 2026): “Fixed issue where ollama launch claude and other coding agent or assistant use cases would only output one token.”
La soluzione è aggiornare Ollama all’ultima versione disponibile:
# macOS / Linux curl -fsSL https://ollama.com/install.sh | sh # Verificare la versione ollama –version
Se si usa Docker, aggiornare l’immagine:
docker pull ollama/ollama:latest docker restart ollama
ℹ️ Best practice: nei CI/CD pipeline che usano Ollama, specificare sempre una versione minima e aggiungere un check automatico della versione all’avvio del container.
7. Problema 6: Limite di 30 immagini per conversazione (analisi multimodale)
Sintomi
Chi usa Kimi K2.6 per task di analisi di immagini (es. immagini satellitari, screenshot di UI) si scontra con il limite imposto da Moonshot AI: massimo 30 immagini per conversazione. Il superamento del limite restituisce un errore, segnalato nell’issue #16167 di Ollama (maggio 2026).
Causa
Il limite è imposto a livello di infrastruttura Moonshot AI, non da Ollama. Il routing cloud di Ollama trasparisce le richieste verso i server Moonshot, che applicano la restrizione indipendentemente dalla finestra di contesto disponibile (262K token).
Soluzioni
- Ridurre la risoluzione delle immagini con Pillow prima di inviarle, per minimizzare il peso in token di ciascuna immagine e restare nel limite.
- Strutturare il workflow in sessioni multiple, suddividendo l’analisi in batch da meno di 30 immagini.
- Per uso professionale intensivo, usare direttamente l’API Moonshot AI con le proprie chiavi e un piano che supporti limiti superiori.
- Alternativa: valutare modelli multimodali locali (es. Gemma4 su GPU locale) per i task con molte immagini, riservando Kimi ai task testuali o di coding.
# Esempio: riduzione risoluzione con Pillow (Python) from PIL import Image import io, base64 def compress_image(path, max_size=(1024, 1024)): img = Image.open(path) img.thumbnail(max_size, Image.LANCZOS) buf = io.BytesIO() img.save(buf, format=’JPEG’, quality=80) return base64.b64encode(buf.getvalue()).decode()
8. Problema 7: Configurare Claude Code con Kimi via Ollama manualmente
Anche senza errori specifici, la configurazione manuale di Claude Code con Kimi tramite Ollama richiede attenzione. La documentazione ufficiale di Ollama (docs.ollama.com/integrations/claude-code) indica il metodo rapido con ollama launch claude, ma in molti ambienti (CI, container, server headless) è necessario il setup manuale.
Setup rapido (comando unico)
ollama launch claude –model kimi-k2.6:cloud
Setup manuale (ambienti headless o CI)
Passo 1 — Installare Claude Code:
# macOS / Linux curl -fsSL https://claude.ai/install.sh | bash # Windows (PowerShell) irm https://claude.ai/install.ps1 | iex
Passo 2 — Impostare le variabili d’ambiente:
export ANTHROPIC_AUTH_TOKEN=ollama export ANTHROPIC_API_KEY="" export ANTHROPIC_BASE_URL=http://localhost:11434
Passo 3 — Avviare Claude Code con il modello Kimi:
claude --model kimi-k2.7-code:cloud
Oppure tutto in una riga:
ANTHROPIC_AUTH_TOKEN=ollama \ ANTHROPIC_BASE_URL=http://localhost:11434 \ ANTHROPIC_API_KEY="" \ claude --model kimi-k2.7-code:cloud
Passo 4 — Per repository di grandi dimensioni, aumentare il contesto. Claude Code lo gestisce internamente, ma è buona pratica verificare che Ollama non applichi un limite inferiore:
# Nel file di configurazione dell’agente o come opzione –context-length 131072
Attenzione: Per ambienti Docker o Kubernetes, aggiungere le variabili d’ambiente nel manifest di deployment. Evitare di hardcodare ANTHROPIC_API_KEY; usare secrets manager o variabili CI/CD.
9. Best practice: pro e contro di Ollama con Kimi – Principali problemi Ollama con Kimi
Vantaggi (Pro)
- Interfaccia unificata: lo stesso CLI e API OpenAI-compatibile funziona sia per modelli locali che cloud — zero refactoring del codice.
- Nessun download di pesi: con il tag :cloud, il modello gira su infrastruttura Ollama senza occupare centinaia di GB di disco.
- Integrazione nativa con agenti AI: Claude Code, Hermes, OpenClaw, Codex supportano Kimi via ollama launch con un solo comando.
- Privacy by design: le richieste non vengono registrate né usate per il training, secondo la politica zero-data-retention di Ollama con i provider cloud.
- Performance elevate per coding agentico: Kimi K2.6/K2.7 è tra i migliori modelli open-weight per SWE-Bench e task di ingegneria del software nel 2026.
Svantaggi e rischi (Contro)
- Dipendenza dalla connessione internet: i modelli cloud richiedono connessione stabile. Nessuna opzione offline reale per Kimi tramite Ollama.
- Costo del piano Pro: il piano gratuito non copre Kimi K2.5+ — per uso professionale serve il piano a pagamento.
- Limiti di concorrenza: il piano gratuito consente un solo modello cloud attivo alla volta, critico per workflow multi-agente.
- Deprecazione dei tag: Moonshot AI aggiorna frequentemente la serie K2; ogni aggiornamento richiede revisione di script e configurazioni.
- Inferenza locale impossibile per Kimi 1T: senza hardware da data center (oltre 247 GB RAM+VRAM), il modello completo non può girare in locale.
- Bug non ancora risolti: alcuni problemi di context detection e tool calling persistono in versioni intermedie e richiedono workaround manuali.
Raccomandazioni operative
- Centralizzare il nome del modello in una variabile d’ambiente e usare sempre la versione più recente del tag cloud.
- Aggiornare Ollama prima di aprire qualsiasi issue: molti bug già corretti vengono segnalati su versioni obsolete.
- Per pipeline CI/CD, preferire il setup manuale con variabili d’ambiente rispetto a ollama launch (più stabile in ambienti headless).
- Monitorare ollama.com/settings per i limiti di utilizzo aggiornati, che cambiano periodicamente.
10. Conclusioni e formazione professionale
Ollama con Kimi K2 rappresenta oggi una delle soluzioni più interessanti per chi vuole sfruttare modelli frontier open-weight in workflow di sviluppo software agentico. I problemi esistono — autenticazione, deprecazione dei tag, tool calling, context window, bug di output, ma per ciascuno esiste una soluzione praticabile, spesso già documentata nel repository ufficiale.
Il mercato dell’intelligenza artificiale applicata allo sviluppo software è in continua, accelerata evoluzione. In soli dodici mesi, Moonshot AI ha rilasciato K2, K2-Instruct, K2.5, K2.6 e K2.7, ognuno con architettura migliorata e nuove funzionalità. Questo ritmo non rallenterà. L’unico modo per un team di sviluppo di rimanere competitivo, e di sfruttare davvero questi strumenti senza perdere tempo su bug già risolti, è la formazione continua e strutturata.
Conoscere i modelli LLM, la loro architettura, le API e le best practice di integrazione non è più un vantaggio opzionale: è un prerequisito per chi vuole lavorare con agenti AI in produzione.
Innovaformazione propone due percorsi specifici per sviluppatori e team aziendali:
• Corso Sviluppo Applicazioni LLM : per padroneggiare l’integrazione di modelli linguistici come Kimi, Claude e GPT in applicazioni reali, con focus su API, agenti AI e pipeline di produzione.
• Corso Claude Code per Sviluppatori: per usare Claude Code in modo professionale, configurarlo con modelli alternativi come Kimi, e integrarlo nei processi di sviluppo aziendali.
Fondimpresa e formazione finanziata
Le aziende aderenti a Fondimpresa possono accedere a finanziamenti per la formazione professionale dei propri dipendenti. I corsi di Innovaformazione sono strutturati per essere erogati anche in modalità finanziata tramite Fondi Interprofessionali. Contattaci per verificare l’accesso al finanziamento e ottenere un piano formativo personalizzato per il tuo team.
Contatti
Per informazioni sui corsi, preventivi personalizzati e accesso a Fondimpresa:
- Email: info@innovaformazione.net
- Tel.: 347 101 2275 — Dario Carrassi
- Sito: innovaformazione.net
Articoli correlati
Claude Code con Arduino
Novità .Net 11
Backdoor nei modelli AI open-weight
Opportunità di lavoro Bari
Spieghiamo il Weight space programming
