Condividi tramite

Riferimento CLI Locale di Foundry

Importante

  • L'interfaccia della riga di comando locale di Foundry è disponibile in anteprima. Le versioni di anteprima pubblica forniscono access iniziali alle funzionalità in fase di distribuzione attiva.
  • Funzionalità, approcci e processi possono subire variazioni o avere funzionalità limitate, prima della disponibilità generale (GA).

Questo articolo fornisce informazioni di riferimento complete per l'interfaccia della riga di comando locale di Foundry. L'interfaccia della riga di comando organizza i comandi in categorie logiche per semplificare la gestione dei modelli, il controllo del servizio e la gestione della cache locale.

Prerequisiti

  • Installare Foundry Local.
  • Terminale locale in cui è disponibile l'interfaccia della foundry riga di comando.
  • Assicurarsi di disporre dell'accesso a Internet per i download per la prima volta (provider di esecuzione e modelli).
  • Azure controllo degli accessi in base al ruolo: non applicabile (viene eseguito localmente).
  • Se si dispone di una NPU Intel in Windows, installare il driver Intel NPU per un'accelerazione NPU ottimale.

Installare Foundry Local

Installare Foundry Local usando la gestione pacchetti per il sistema operativo.

  • Windows: aprire un terminale ed eseguire:
    winget install Microsoft.FoundryLocal
  • macOS: aprire un terminale ed eseguire: 
    brew tap microsoft/foundrylocal
brew install foundrylocal
    In alternativa, scaricare il programma di installazione dal repository GitHub GitHub locale <>Foundry.

Verificare l'installazione:

foundry --version

Assicurarsi di disporre dei diritti di amministratore per installare il software.

Suggerimento

Se viene visualizzato un errore di connessione al servizio dopo l'installazione , ad esempio Request to local service failed, eseguire foundry service restart.

Verifica rapida

Eseguire questi comandi per verificare che l'interfaccia della riga di comando sia installata e che il servizio sia raggiungibile.

  1. Mostra aiuto CLI

     foundry --help

    Questo comando stampa informazioni sull'utilizzo e l'elenco dei gruppi di comandi disponibili.

    Informazioni di riferimento: Panoramica

  2. Controllare lo stato del servizio:

     foundry service status

    Questo comando stampa se il servizio locale Foundry è in esecuzione e include l'endpoint locale.

    Riferimento: Comandi del servizio

Informazioni generali

Usare la guida integrata per esplorare i comandi e le opzioni.

L'interfaccia della riga di comando organizza i comandi in tre categorie principali:

  • Modello: comandi per la gestione e l'esecuzione di modelli di intelligenza artificiale
  • Servizio: comandi per il controllo del servizio locale Foundry
  • Cache: comandi per la gestione dell'archiviazione locale del modello

Comandi del modello

La tabella seguente riepiloga i comandi correlati alla gestione e all'esecuzione dei modelli:

Annotazioni

È possibile specificare l'argomento modelutilizzando l'alias o l'ID modello. Uso di un alias:

  • Seleziona automaticamente il modello migliore per l'hardware disponibile. Ad esempio, se è disponibile una GPU Nvidia, Foundry Local seleziona il modello GPU migliore. Se è disponibile una NPU supportata, Foundry Local seleziona il modello NPU.
  • Consente di usare un nome più breve senza dover ricordare l'ID modello.

Se si vuole eseguire un modello specifico, usare l'ID modello. Ad esempio, per eseguire il qwen2.5-0.5b su CPU, indipendentemente dall'hardware disponibile, usare: foundry model run qwen2.5-0.5b-instruct-generic-cpu.

Comando Descrizione
foundry model --help Visualizza tutti i comandi relativi al modello disponibili e il relativo utilizzo.
foundry model run <model> Esegue un modello specificato, lo scarica se non è memorizzato nella cache e avvia un'interazione.
foundry model list Elenca tutti i modelli disponibili per l'uso locale. Alla prima esecuzione, scarica i provider di esecuzione (EP) per l'hardware.
foundry model list --filter <key>=<value> Elenca i modelli filtrati in base ai criteri specificati (dispositivo, attività, alias, provider).
foundry model info <model> Visualizza informazioni dettagliate su un modello specifico.
foundry model info <model> --license Visualizza le informazioni sulla licenza per un modello specifico.
foundry model download <model> Scarica un modello nella cache locale senza eseguirlo.
foundry model load <model> Carica un modello nel servizio.
foundry model unload <model> Scarica un modello dal servizio.

Ordinamento elenco modelli

Quando sono disponibili più varianti di ID modello per un alias, l'elenco dei modelli mostra i modelli in ordine di priorità. Il primo modello nell'elenco è il modello eseguito quando si specifica il modello per alias.

Filtraggio dell'elenco modelli

Il foundry model list comando supporta il filtro dei modelli usando l'opzione --filter . È possibile filtrare i modelli in base a un singolo attributo usando coppie chiave-valore.

foundry model list --filter <key>=<value>

Questo comando stampa i modelli che corrispondono alla chiave e al valore del filtro.

Riferimento: Filtro elenco modelli

Annotazioni

Quando si esegue foundry model list per la prima volta dopo l'installazione, Fonderia Locale scarica automaticamente i provider di esecuzione pertinenti per la configurazione hardware del computer. Viene visualizzata una barra di stato che indica il completamento del download prima che venga visualizzato l'elenco dei modelli.

Chiavi di filtro supportate:

device - Tipo di dispositivo hardware

Filtra i modelli in base al dispositivo hardware in cui vengono eseguiti.

Valori possibili:

  • CPU - Modelli di unità di elaborazione centrale
  • GPU - Modelli di unità di elaborazione grafica
  • NPU - Modelli di unità di elaborazione neurale

provider - Provider di esecuzione

Filtra i modelli in base al provider di esecuzione o al runtime.

Valori possibili:

  • CPUExecutionProvider - Esecuzione basata sulla CPU
  • CUDAExecutionProvider - Esecuzione GPU NVIDIA CUDA
  • WebGpuExecutionProvider - Esecuzione di WebGPU
  • QNNExecutionProvider - Esecuzione della rete neurale Qualcomm (NPU)
  • OpenVINOExecutionProvider - Esecuzione di Intel OpenVINO
  • NvTensorRTRTXExecutionProvider - Esecuzione di NVIDIA TensorRT
  • VitisAIExecutionProvider - Esecuzione dell'intelligenza artificiale AMD Vitis

task - Tipo di attività modello

Filtra i modelli in base al caso d'uso o all'attività desiderata.

Valori comuni:

  • chat-completion: modelli di intelligenza artificiale conversazionale
  • text-generation: modelli di generazione di testo

alias - Alias del modello

Filtra i modelli in base al relativo identificatore di alias. Supporta la corrispondenza dei caratteri jolly con il suffisso *.

Valori di esempio:

  • phi4-cpu
  • qwen2.5-coder-0.5b-instruct-generic-cpu
  • deepseek-r1-distill-qwen-1.5b-generic-cpu
  • phi-4-mini-instruct-generic-cpu

Funzionalità di filtro speciali

Supporto per la negazione: Anteporre qualsiasi valore a ! per escludere i modelli corrispondenti.

foundry model list --filter device=!GPU

Questo comando esclude i modelli GPU dai risultati.

Riferimento: Funzionalità di filtro speciali

Corrispondenza dei caratteri jolly (solo alias): aggiungere * per trovare le corrispondenze dei prefissi per il filtro in base all'alias.

foundry model list --filter alias=qwen*

Questo comando restituisce modelli il cui alias inizia con qwen.

Riferimento: Funzionalità di filtro speciali

Esempi

foundry model list --filter device=GPU
foundry model list --filter task=chat-completion
foundry model list --filter provider=CUDAExecutionProvider

Questi esempi filtrano l'elenco di modelli in base a dispositivo, attività e provider di esecuzione.

Riferimento: Filtro elenco modelli

Annotazioni

  • Tutti i confronti non fanno distinzione tra maiuscole e minuscole.
  • È possibile usare un solo filtro per ogni comando.
  • Le chiavi di filtro non riconosciute generano un errore.

Eseguire un modello in modo interattivo

Eseguire un modello e interagire con esso direttamente nel terminale:

foundry model run qwen2.5-0.5b

Foundry Local scarica il modello alla prima esecuzione, quindi avvia una sessione interattiva. Immettere un prompt per ottenere una risposta:

Why is the sky blue?

Screenshot dell'output dal comando Di esecuzione locale di Foundry.

Suggerimento

Sostituire qwen2.5-0.5b con qualsiasi alias del modello dal catalogo. Eseguire foundry model list per visualizzare i modelli disponibili. Foundry Local scarica la variante che meglio corrisponde all'hardware, ad esempio una variante CUDA per GPU NVIDIA o una variante di NPU per i CRITERI di rete Qualcomm.

Comandi del servizio

La tabella seguente riepiloga i comandi correlati alla gestione e all'esecuzione del servizio locale Foundry:

Comando Descrizione
foundry service --help Visualizza tutti i comandi correlati al servizio disponibili e il relativo utilizzo.
foundry service start Avvia il servizio Foundry Locale.
foundry service stop Arresta il servizio Foundry Local.
foundry service restart Riavvia il servizio Foundry Locale.
foundry service status Visualizza lo stato corrente del servizio locale Foundry.
foundry service ps Elenca tutti i modelli attualmente caricati nel servizio locale Foundry.
foundry service diag Visualizza i log del servizio locale Foundry.
foundry service set <options> Imposta la configurazione del servizio locale Foundry.

Comandi della cache

La tabella seguente riepiloga i comandi per la gestione della cache locale in cui vengono archiviati i modelli:

Comando Descrizione
foundry cache --help Mostra tutti i comandi correlati alla cache disponibili e il relativo utilizzo.
foundry cache location Mostra la directory della cache corrente.
foundry cache list Elenca tutti i modelli archiviati nella cache locale.
foundry cache cd <path> Modifica la directory della cache nel percorso specificato.
foundry cache remove <model> Rimuove un modello dalla cache locale.

Fornitori di esecuzione

I provider di esecuzione sono librerie di accelerazione specifiche dell'hardware che eseguono modelli nel modo più efficiente possibile nel dispositivo.

Provider di esecuzione predefiniti

Foundry Local include il provider di esecuzione della CPU, il provider di esecuzione WebGPU e il provider di esecuzione CUDA.

Il provider di esecuzione della CPU usa Microsoft Subroutine algebriche lineari (MLAS) per l'esecuzione su qualsiasi CPU ed è il fallback della CPU per Foundry Local.

Il provider di esecuzione WebGPU utilizza Dawn, l'implementazione nativa dell'API basata sul web, per l'accelerazione su qualsiasi GPU, ed è l'alternativa GPU per Foundry Local.

Il provider di esecuzione CUDA usa NVIDIA CUDA per l'accelerazione su GPU NVIDIA. Richiede una serie NVIDIA GeForce RTX 30 e successive con una versione minima consigliata del driver 32.0.15.5585 e CUDA versione 12.5. È soggetto alle seguenti condizioni di licenza: Contratto di licenza per i Kit di Sviluppo Software NVIDIA—EULA.

Provider di esecuzione plug-in

I provider di esecuzione elencati nella tabella seguente sono disponibili per il download dinamico e la registrazione in Windows, a seconda della compatibilità dei dispositivi e dei driver. Sono soggetti alle condizioni di licenza specificate.

Foundry Local scarica automaticamente questi provider di esecuzione al primo avvio. I provider di esecuzione del plug-in vengono aggiornati automaticamente quando sono disponibili nuove versioni.

Nome (fornitore) Requisiti Condizioni di licenza
NvTensorRTRTXExecutionProvider (NVIDIA) NVIDIA GeForce RTX 30XX e versioni successive con la versione minima consigliata del driver 32.0.15.5585 e CUDA versione 12.5 Accordo di Licenza con l'Utente Finale per NVIDIA Software Development Kits—EULA
OpenVINOExecutionProvider (Intel) CPU: Intel TigerLake (prima generazione) e versioni successive con il driver minimo consigliato 32.0.100.9565
GPU: Intel AlderLake (12a generazione) e versioni successive con il driver minimo consigliato 32.0.101.1029
NPU: Intel ArrowLake (15a generazione) e versioni successive con il driver minimo consigliato 32.0.100.4239		 Contratto di licenza intel OBL Distribution Commercial Use v2025.02.12
QNNExecutionProvider (Qualcomm) Snapdragon(R) X Elite - X1Exxxxx - Qualcomm(R) Hexagon(TM) NPU con una versione minima del driver 30.0.140.0 e versioni successive
Snapdragon(R) X Plus - X1Pxxxxx - Qualcomm(R) Hexagon(TM) NPU con versione minima del driver 30.0.140.0 e versioni successive		 Per visualizzare la licenza QNN, scaricare Qualcomm® Neural Processing SDK, estrarre il file ZIP e aprire il file LICENSE.pdf.
VitisAIExecutionProvider (AMD) Min: Adrenalin Edition 25.6.3 con driver NPU 32.00.0203.280
Max: Adrenalin Edition 25.9.1 con driver NPU 32.00.0203.297		 Nessuna licenza aggiuntiva richiesta

Usare Open WebUI con il server locale

Connettere Open WebUI to Foundry Local per un'interfaccia di chat basata su browser eseguita interamente nel dispositivo.

  1. Avviare un modello e lasciare aperto il terminale:

    foundry model run qwen2.5-0.5b

  2. Ottenere l'URL dell'endpoint locale:

    foundry service status

    Copiare l'URL dell'endpoint. Foundry Local assegna una porta dinamica ogni volta che il servizio viene avviato.

  3. Installare e avviare Open WebUI ,quindi aprire http://localhost:8080 nel browser.

  4. Connettere Open WebUI to Foundry Local :Connect Open WebUI to Foundry Local:Connect Open WebUI to Foundry Local:

    1. Passare a Impostazioni>Impostazioni Impostazioni Connessioni> amministratore e abilitare Connessioni dirette.
    2. Passare a Impostazioni>Connessioni>gestisci connessioni dirette e selezionare +.
    3. Impostare URL su http://localhost:PORT/v1 (sostituire PORT con la porta del passaggio 2) e Autenticazione su Nessuno.
    4. Seleziona Salva.

  5. Selezionare un modello dall'elenco a discesa e avviare la chat.

Suggerimento

Se non vengono visualizzati modelli, eseguire foundry model run <model> in un terminale e ricaricare Open WebUI. Se la connessione non riesce, confermare la porta con foundry service status.

Aggiornare Foundry Local

Eseguire il comando per il sistema operativo per aggiornare Foundry Local.

  • Windows:
    winget upgrade --id Microsoft.FoundryLocal
  • macOS:
    brew upgrade foundrylocal

Disinstallare Foundry Local

Eseguire il comando per il sistema operativo per disinstallare Foundry Local.

  • Windows:
    winget uninstall Microsoft.FoundryLocal
  • macOS:
    brew rm foundrylocal
brew untap microsoft/foundrylocal
brew cleanup --scrub

Risoluzione dei problemi

Problemi di connessione al servizio

Se viene visualizzato questo errore quando si esegue un comando come foundry model list:

Exception: Request to local service failed.
Uri: http://127.0.0.1:0/foundry/list

The requested address is not valid in its context. (127.0.0.1:0)

Please check service status with 'foundry service status'.

Riavviare il servizio:

foundry service restart

Questo comando risolve i casi in cui il servizio viene eseguito ma non è accessibile a causa di un problema di associazione di porte.

Per altre indicazioni sulla risoluzione dei problemi, vedere Procedure consigliate e risoluzione dei problemi.

  • Last updated on