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.
Installare DeepSeek Harness in locale: setup e configurazione delle API
Di seguito una guida pratica per:
- predisporre un “harness” locale (orchestratore) per DeepSeek
- configurare una chiave API
- rivedere i requisiti d’installazione
- chiarire la differenza tra orchestrazione locale e inferenza locale
Requisiti di installazione (minimi e consigliati)
- Sistema operativo: Linux/macOS oppure Windows via WSL2
- Strumenti di base: Git, curl, Python 3.9–3.12, pip/venv
- Facoltativo (Node.js): v18+ se preferisci SDK JavaScript/TypeScript
- Per inferenza locale su GPU:
- GPU NVIDIA con driver recenti (es. 535+), CUDA 12.x, cuDNN installato
- VRAM: 8–24 GB a seconda del modello/quantizzazione
- Spazio disco: 10–30+ GB per pesi del modello
- Per inferenza locale su CPU: possibile ma molto più lenta; raccomandata solo per test
Configurazione della chiave API (inferenza via cloud)
1) Ottieni una chiave API dal tuo provider DeepSeek.
2) Esporta la chiave come variabile d’ambiente:
- macOS/Linux: export DEEPSEEK_API_KEY="la_tua_chiave"
- Windows PowerShell: setx DEEPSEEK_API_KEY "la_tua_chiave" (poi riapri la shell)
3) Test rapido via curl:
curl https://api.deepseek.com/v1/chat/completions \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-chat",
"messages": [{"role":"user","content":"Ciao!"}]
}'
- Sostituisci "deepseek-chat" con il modello specifico disponibile nel tuo account se diverso.
4) Test rapido in Python (client compatibile OpenAI):
from openai import OpenAI
import os
client = OpenAI(base_url="https://api.deepseek.com/v1", api_key=os.environ["DEEPSEEK_API_KEY"])
resp = client.chat.completions.create(
model="deepseek-chat",
messages=[{"role":"user","content":"Saluta in una riga"}]
)
print(resp.choices[0].message.content)
Set up di un harness locale (orchestrazione) con router OpenAI-compatibile
- Obiettivo: esporre in locale un endpoint /v1 compatibile OpenAI che instrada le richieste al backend DeepSeek (cloud). Esempio con LiteLLM.
1) Crea un ambiente Python:
python -m venv .venv
source .venv/bin/activate (su Windows: .venv\Scripts\Activate.ps1)
2) Installa LiteLLM:
pip install litellm
3) Crea un file di configurazione litellm.config.yaml (usa variabile d’ambiente per la chiave):
model_list:
- model_name: deepseek-chat
litellm_params:
provider: openai
model: deepseek-chat
api_base: https://api.deepseek.com/v1
api_key: ${DEEPSEEK_API_KEY}
4) Avvia il router locale:
litellm --config litellm.config.yaml --port 4000
- Ora hai un endpoint locale OpenAI-compatibile: http://localhost:4000/v1
5) Prova dal tuo client puntando al router locale:
from openai import OpenAI
client = OpenAI(base_url="http://localhost:4000/v1", api_key="dummy")
resp = client.chat.completions.create(
model="deepseek-chat",
messages=[{"role":"user","content":"Dimmi una curiosità in 1 frase"}]
)
Nota: l’api_key “dummy” serve solo per il client; LiteLLM usa DEEPSEEK_API_KEY per autenticarsi verso DeepSeek.
Inferenza locale (senza cloud) con server OpenAI-compatibile
- Obiettivo: eseguire un modello DeepSeek open-source localmente e servire un endpoint /v1.
- Esempio con vLLM e un modello disponibile su Hugging Face (ad es. deepseek-ai/deepseek-coder-6.7b-instruct):
1) Installa vLLM:
pip install vllm
2) (Se necessario) configura il token Hugging Face: export HUGGINGFACE_TOKEN="..."
3) Avvia il server OpenAI-compatibile di vLLM:
python -m vllm.entrypoints.openai.api_server --model deepseek-ai/deepseek-coder-6.7b-instruct --host 0.0.0.0 --port 8000
- L’endpoint locale sarà: http://localhost:8000/v1
4) Test locale:
from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="dummy")
resp = client.chat.completions.create(
model="deepseek-ai/deepseek-coder-6.7b-instruct",
messages=[{"role":"user","content":"Spiega in 1 frase cosa fai"}]
)
- Per GPU: vLLM userà la tua GPU se disponibile. Per CPU-only le prestazioni saranno limitate.
- In alternativa a vLLM, puoi usare llama.cpp (GGUF) o altri runtime; l’importante è esporre un endpoint OpenAI-compatibile per riusare gli stessi client.
Comprendere orchestrazione locale vs inferenza locale
- Orchestrazione locale (inferenza remota):
- Cosa significa: esegui in locale un router/agent che gestisce prompt, strumenti, memoria, logging, ma delega l’inferenza al cloud (DeepSeek API).
- Pro:
- Requisiti hardware minimi
- Accesso a modelli aggiornati e potenti
- Deploy rapido, manutenzione ridotta
- Contro:
- Dipendenza dalla rete e latenza
- Costi a consumo
- Considerazioni su privacy/compliance (dati verso cloud)
- Inferenza locale (modello in locale):
- Cosa significa: i pesi del modello risiedono sulla tua macchina; il calcolo è sul tuo hardware.
- Pro:
- Dati che non escono dall’ambiente locale
- Possibile funzionamento offline
- Costi ricorrenti ridotti (dopo setup)
- Contro:
- Requisiti hardware e complessità operative
- Aggiornamenti e ottimizzazioni a tuo carico
- Qualità e velocità legate al modello/quantizzazione che puoi permetterti
Pattern consigliati
- Solo orchestrazione locale: usa un router locale che punta a DeepSeek API. È il modo più semplice per iniziare.
- Solo inferenza locale: usa vLLM/llama.cpp per servire il modello; utile per privacy/offline.
- Ibrido (fallback): prova prima l’inferenza locale; in caso di errore o richiesta “pesante”, reindirizza al cloud. Puoi implementarlo nel router (es. LiteLLM) o lato applicazione.
Troubleshooting rapido
- 401/403: verifica DEEPSEEK_API_KEY e che l’endpoint api_base sia corretto.
- Timeout/SSL: controlla proxy/firewall; prova con curl per isolare il problema.
- GPU non rilevata: verifica driver NVIDIA, versione CUDA/cudnn e compatibilità con vLLM.
- Out-of-memory: usa modelli più piccoli o quantizzati; riduci max_tokens; attiva tensor parallelism se disponibile.
Sicurezza e buone pratiche
- Non hardcodare la chiave API nel codice; usa variabili d’ambiente o un vault.
- Non committare file .env; aggiungili a .gitignore.
- Logga in modo sicuro; evita di salvare payload sensibili in chiaro.
Con questi passi disponi sia di un harness di orchestrazione locale verso DeepSeek (cloud), sia di un percorso per l’inferenza locale. Se indichi il tuo sistema operativo e quale modello/SDK vuoi usare (Python/JS), posso fornirti comandi specifici e file pronti all’uso.
TLDR DeepSeek Harness (dsh) è il runtime open source per agenti di DeepSeek AI, rilasciato in anteprima per sviluppatori intorno al 13 agosto 2026 sotto licenza MIT. Segue il principio “Modello + Harness = Agente”, con ogni funzionalità (modelli, strumenti, sessioni, sandbox, loop, UI) implementata come plugin Cordis intercambiabili.
Il modo più rapido per eseguirlo in locale è npx @deepseek-ai/dsh web (richiede Node.js ^22.19 o ≥24), che avvia una Web UI su http://127.0.0.1:3080. Fornisci una chiave API DeepSeek (o compatibile con OpenAI) e un workspace. Sono disponibili anche build da sorgente, app desktop, Docker, SDK Python e integrazioni con Ollama. Per accesso multi‑modello di livello production, affidabilità e controllo dei costi mentre usi l’harness, instrada le richieste tramite l’endpoint unificato compatibile con OpenAI di CometAPI.
Revisionato per chiarezza, attribuzione delle fonti e terminologia API aggiornata.
Usa questo riepilogo per una risposta rapida, poi leggi la guida per contesto, esempi e dettagli di implementazione.
Punti chiave
DeepSeek Harness non è un modello: è il runtime/orchestratore locale che consente ai modelli di agire su file, shell, strumenti e sessioni.
One‑liner ufficiale: npx @deepseek-ai/dsh web → apre la Web UI locale sulla porta 3080.
Requisito Node.js rigoroso: ^22.19.0 o ≥24.x.
Supporta i modelli ufficiali DeepSeek (deepseek-v4-flash, deepseek-v4-pro), gateway personalizzati compatibili con OpenAI e modelli locali tramite plugin/Ollama.
Architettura completamente basata su plugin (kernel Cordis); modalità: Standard, Minimal, Code e Creator.
Adozione rapida: da decine di migliaia a ben oltre 100k stelle su GitHub nei giorni successivi al lancio.
Consigliato agli utenti avanzati: abbinalo a CometAPI (https://www.cometapi.com/) come provider personalizzato per accedere a 500+ modelli, risparmi del 20–40% e una singola chiave API.
Usa sempre un workspace isolato; l’agente può modificare file ed eseguire comandi.
Stato di anteprima per sviluppatori: sono attesi breaking change—blocca le versioni per esperimenti simil‑produzione.
Che cos’è DeepSeek Harness e perché conta nel 2026
DeepSeek Harness (dsh) è un runtime open source per agenti sviluppato da DeepSeek AI. Rilasciato sotto licenza MIT in anteprima per sviluppatori, enfatizza la componibilità: ogni capacità—adattatori di modelli, strumenti, skill, sessioni, sandbox, storage, loop dell’agente, scheduling e UI—esiste come plugin Cordis che può essere montato, smontato, sostituito o ricomposto via configurazione. In pratica non esiste un core privilegiato che richieda patch.
Principi progettuali chiave:
Agente = Modello + Harness.
Flussi di eventi tracciabili con supporto a ripresa, fork, ricerca e replay.
Più modalità di runtime (toolset completo standard, modalità code/orchestrazione, modalità minimal per benchmark, modalità creator/sperimentali).
Web UI local‑first per uso interattivo più opzioni headless e SDK per l’automazione.
Pagine guida all’installazione e mirror della community ribadiscono gli stessi comandi di base.
Nota terminologica importante: “distribuzione locale” può significare due cose diverse. Il DeepSeek Harness discusso in questa guida gira in locale sul tuo computer, ma il progetto standard deepseek-harness si connette a DeepSeek V4-Pro o V4-Flash tramite API. Ciò significa che l’harness, la configurazione, le sessioni, la validazione e la logica client possono essere locali, mentre l’inferenza del modello è normalmente effettuata dall’API di DeepSeek. Se ti serve inferenza realmente offline con i pesi del modello sulla tua GPU, si tratta di un’architettura di distribuzione diversa.
Prerequisiti e requisiti di sistema
Prima di installare, verifica quanto segue:
Sistemi operativi: Windows 10+, macOS 10.15+, Linux mainstream (x64 o arm64). L’SDK Python ha vincoli aggiuntivi (Linux x64/arm64 o macOS 14+ arm64).
Node.js: richiesto per il percorso principale della Web UI. Intervallo target ^22.19.0 || ≥24.0.0. Verifica con node --version. Le versioni intermedie con numero dispari fuori da questo intervallo non sono supportate.
Gestori pacchetti: npm/npx (inclusi con Node). Le build da sorgente richiedono pnpm (installa con npm install -g pnpm).
Git: richiesto per il clone dei sorgenti.
Python (opzionale): 3.10+ per l’SDK Python ufficiale.
Chiave API / endpoint: una chiave API DeepSeek da platform.deepseek.com, o qualsiasi endpoint compatibile con OpenAI + chiave + nome modello.
Hardware: nessuna GPU necessaria per l’harness stesso—l’inferenza del modello avviene in remoto (o tramite un provider locale da te configurato). Le risorse di un normale laptop sono sufficienti per Web UI e orchestrazione.
Rete: necessaria al primo avvio per scaricare i pacchetti; in seguito la UI può operare con le sole chiamate API del modello.
Workspace: prepara una directory isolata. L’agente può leggere, scrivere ed eseguire comandi all’interno del workspace configurato—non puntarlo mai a dati di produzione o personali senza tutele.
Fonti per i requisiti: README ufficiale e più guide d’installazione indipendenti pubblicate poco dopo il lancio.
Metodo 1: One‑liner ufficiale con npx (consigliato per la maggior parte degli utenti)
Questo è il percorso più rapido e promosso ufficialmente.
Assicurati che Node.js soddisfi il requisito di versione.
Apri un terminale ed esegui:
Bash
npx @deepseek-ai/dsh web
Il pacchetto viene scaricato (o usa la cache), avvia il profilo Web UI e stampa l’indirizzo in ascolto—per impostazione predefinita http://127.0.0.1:3080.
Apri quell’URL nel browser. Accetta l’avviso di anteprima per sviluppatori se mostrato.
Al primo utilizzo, configura un provider di modelli (Settings → Models) incollando la tua chiave API e selezionando un modello come deepseek-v4-flash o deepseek-v4-pro.
Scegli o crea una directory di workspace.
Inizia a eseguire task.
Per usare una porta diversa:
Bash
npx @deepseek-ai/dsh web --port 8080
Platform-specific one-liners disponibili sui siti della community (PowerShell su Windows con winget, Homebrew su macOS, NodeSource su Debian/Ubuntu, ecc.) che verificano anche la presenza di Node.
Pro: Nessuna installazione permanente oltre alla cache npm; preleva sempre una versione recente pubblicata; onboarding più semplice. Contro: Dipende dalla rete per il pacchetto iniziale; meno comodo per ispezione profonda dei sorgenti o build custom.
Metodo 2: Installazione ed esecuzione dai sorgenti
Usalo quando vuoi leggere i plugin Cordis, fissare un commit, sviluppare preset personalizzati o contribuire.
Bash
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web
Compare la stessa Web UI sulla porta predefinita. Le build in anteprima per sviluppatori possono rompersi tra i commit, quindi trattalo come un percorso sperimentale.
Metodo 3: Applicazioni desktop (senza setup Node)
Wrapper desktop della community e di terze parti impacchettano il runtime così che gli utenti evitino di installare Node/pnpm:
Client leggeri basati su Tauri che avviano un runtime Node integrato e sincronizzano all’avvio l’ultima versione upstream dell’harness. Girano su 127.0.0.1:3080, mantengono i dati in locale e registrano i comandi dsh.
Packaging basato su Electron con dipendenze fissate.
Scarica gli installer dalle rispettive pagine GitHub Releases (cerca “deepseek-harness-desktop”). Al primo avvio scaricano i componenti core (alcune centinaia di MB). Comodi per non‑sviluppatori ma non sono prodotti ufficiali DeepSeek—verifica repository e checksum SHA.
Metodo 4: Distribuzione Docker / container
Esistono immagini Docker e file compose della community per eseguire la Web UI in un container, spesso con terminazione HTTPS via nginx e supporto per gateway arbitrari compatibili con OpenAI. Flusso tipico:
Bash
git clone <docker-repo>
cd <docker-repo>
cp .env.example .env # set API key / public host
docker compose up -d --build
Utile per accesso in LAN, server o ambienti in cui non si vuole Node sull’host. Alcune configurazioni supportano un settings.yaml personalizzato per provider non‑DeepSeek.
Metodo 5: SDK Python per uso programmatico / headless
Per agenti non presidiati o integrazione in pipeline Python:
Quindi esegui gli esempi inclusi o usa la classe DeepSeekHarness nel tuo codice, puntando a un workspace e a una directory di sessione isolati. L’SDK incorpora il proprio runtime e non richiede Node.js di sistema.
Metodo 6: Integrazione con Ollama
Ollama fornisce un launcher pratico:
Bash
ollama launch dsh
# or with a specific model
ollama launch dsh --model deepseek-v4-flash:cloud
Ollama può installare il pacchetto se necessario e memorizza separatamente le impostazioni di avvio. La ricerca web e il supporto agli strumenti dipendono dal modello scelto e dall’accesso cloud di Ollama.
Configurazione di modelli e provider (incluso CometAPI)
All’interno della Web UI vai su Settings → Models.
Per DeepSeek ufficiale: incolla la chiave da platform.deepseek.com. I modelli tipici sono deepseek-v4-flash e deepseek-v4-pro.
Per provider catalogo (Anthropic, OpenAI, ecc.): usa il flusso “Add provider”.
Per endpoint personalizzati / self‑hosted / aggregator: scegli “Add a custom provider.” Fornisci un Provider ID permanente, base URL, protocollo (di solito openai-completions), riferimento o valore della chiave API per l’ambiente e almeno un ID modello.
Raccomandazione CometAPI (fortemente suggerita per molti workflow simil‑produzione) CometAPI è una piattaforma unificata di infrastruttura AI che espone 500+ modelli (incluse varianti DeepSeek, GPT, Claude, Gemini, Grok e molti altri) tramite un singolo endpoint compatibile con OpenAI: https://api.cometapi.com/v1.
Vantaggi se usato con DeepSeek Harness:
Una sola chiave API invece di gestire più credenziali di provider.
Prezzi competitivi (riportati risparmi del 20–40% rispetto alle tariffe dirette di molti vendor).
Alta disponibilità (target SLA 99,9%), bassa latenza mediana e billing pay‑as‑you‑go.
Cambio modello semplice per test A/B o ottimizzazione dei costi senza modificare la configurazione dell’harness oltre all’ID del modello.
Compatibilità drop‑in: i pattern degli SDK OpenAI esistenti funzionano dopo aver cambiato solo base_url e chiave.
Nel modulo del provider personalizzato dell’harness:
Base URL: https://api.cometapi.com/v1
Protocol: openai-completions (o l’opzione equivalente supportata)
API key: la tua chiave CometAPI
Model ID: qualsiasi stringa di modello supportata dal catalogo di CometAPI
Questa combinazione mantiene il potente runtime agente locale offrendo al contempo accesso multi‑vendor flessibile ed economico. I nuovi utenti di solito ricevono crediti di prova gratuiti. Documentazione: https://apidoc.cometapi.com/.
Le chiavi sono memorizzate in sola scrittura (ad es., sotto $DSH_HOME/.credentials.yaml); la UI mostra solo descrittori oscurati.
Risoluzione dei problemi di DeepSeek Harness
DEEPSEEK_API_KEY non trovato
Verifica:
echo $DEEPSEEK_API_KEY
Su Windows:
echo $env:DEEPSEEK_API_KEY
Se vuoto, riconfiguralo.
Errore 400 reasoning_content
Di solito indica una gestione errata del lifecycle di reasoning.
Verifica che la tua applicazione preservi le informazioni di reasoning dell’assistente rilevanti tra richieste multi‑turn di thinking/tool‑call.
Questo è uno dei problemi principali che l’harness è progettato specificamente per gestire.
Errore di lunghezza del contesto
Verifica:
input tokens + max_tokens
Il limite massimo documentato è:
1,048,576 tokens
Riduci il contesto in input o la dimensione di completion richiesta.
Le chiamate agli strumenti diventano non valide durante lo streaming
Non dare per scontato che i chunk di stream arrivino nell’ordine degli strumenti.
Aggrega i delta delle tool‑call per tool_call.index, come raccomandato dal contratto dell’harness.
Le richieste sono inaspettatamente costose
Verifica:
modalità di thinking
lunghezza dell’output
tasso di hit della cache
stabilità del prefisso del prompt
scelta del modello
prezzi API correnti
Un miglioramento semplice è spesso spostare i task di routine da Pro a Flash.
Confronto tra metodi di installazione e distribuzione
Metodo
Facilità d’uso
Node richiesto
Ideale per
Persistenza / Controllo
Porta / Accesso tipici
Note
One‑liner npx
Massima
Sì
Prove rapide, la maggior parte
Effimero (solo cache)
3080 (configurabile)
Raccomandato ufficiale
Sorgente (pnpm)
Media
Sì
Sviluppo, plugin, pinning
Pieno controllo dei sorgenti
3080
Richiede pnpm + build
Desktop (Tauri/Electron)
Alta
No (bundled)
Utenti non tecnici
Profili locali & auto‑update
3080 (interno)
Pacchetti community
Docker
Media
No (container)
Server, LAN, HTTPS
Volumi del container
Personalizzata / 443
Immagini community
SDK Python
Media
No (bundled)
Headless, automazione, pipeline
Sessioni programmatiche
N/A (nessuna UI)
SDK ufficiale
Avvio con Ollama
Alta
Opzionale
Esperimenti con modelli locali
Impostazioni di Ollama
3080
Integrazione con Ollama
Dati sintetizzati da documentazione ufficiale e guide post‑lancio (agosto 2026).
Conclusione e prossimi passi
DeepSeek Harness porta un runtime per agenti dal design pulito e completamente basato su plugin sulle macchine locali con quasi zero attrito grazie al one‑liner npx. Combinato con un routing modelli flessibile—soprattutto tramite una piattaforma unificata come CometAPI—ottieni sia la potenza dei moderni workflow agentici per il coding sia un controllo pratico su costi, scelta del modello e località dei dati.
Inizia oggi con:
npx @deepseek-ai/dsh web
Configura una chiave DeepSeek o CometAPI, puntalo a un workspace sicuro ed esplora la modalità Standard. Poi sperimenta con la modalità Minimal per benchmark, provider personalizzati per ottimizzare i costi o l’SDK Python per l’automazione.
Per le istruzioni ufficiali più recenti preferisci sempre il repository GitHub e doc. Per affidabilità multi‑modello e vantaggi di prezzo mentre esegui l’harness, esplora CometAPI e la sua documentazione su https://apidoc.cometapi.com/.