Riferimento CLI Locale di Foundry

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 facilitare la gestione dei modelli, il controllo del server locale 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 foundry-samples GitHub.

Verificare l'installazione:

foundry --version

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

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 server:

stato del server foundry '''

Questo comando stampa se il daemon locale foundry è in esecuzione e include l'endpoint locale.

Riferimento: Comandi del server

Informazioni generali

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

L'interfaccia della riga di comando organizza i comandi nei gruppi seguenti:

• Modello: model, cache
• Eseguire: run, chat, completetranscribe
• Server: server
• Configurazione: config
• Guida: status, report

La tabella seguente riepiloga i comandi di primo livello:

Comandi del modello

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

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

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

Examples

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

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?

Comandi per il server

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

Server locale a porta fissa

Per avviare il servizio locale su una porta fissa e mantenere in esecuzione il daemon, usare --port con --idle-timeout 0:

foundry server start --port 39839 --idle-timeout 0

Se il daemon è già in esecuzione ed è necessario applicare una nuova porta, riavviarlo con le stesse opzioni:

foundry server restart --port 39839 --idle-timeout 0

Per verificare l'URL dell'endpoint locale, eseguire:

foundry server status

Comandi della cache

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

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.

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:

stato del server foundry

Copy the endpoint URL. Foundry Local assigns a dynamic port each time the service starts.

1. Install and launch [Open WebUI](https://github.com/open-webui/open-webui), then open `http://localhost:8080` in your browser.

1. Connect Open WebUI to Foundry Local:

1. Go to **Settings** > **Admin Settings** > **Connections** and enable **Direct Connections**.
1. Go to **Settings** > **Connections** > **Manage Direct Connections** and select **+**.
1. Set **URL** to `http://localhost:PORT/v1` (replace `PORT` with the port from step 2) and **Auth** to **None**.
1. Select **Save**.

1. Select a model from the dropdown and start chatting.

> [!TIP]
> If no models appear, run `foundry model run <model>` in a terminal and reload Open WebUI. If the connection fails, confirm the port with `foundry server status`.

## Upgrade Foundry Local

Run the command for your operating system to upgrade Foundry Local.

- **Windows**:
```bash
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 server status'.

Riavviare il servizio:

foundry server restart

Questo comando risolve i casi in cui il server 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.