Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
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 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
foundryriga 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 o il programma di installazione per il sistema operativo.
Windows: aprire un terminale ed eseguire:
winget install Microsoft.FoundryLocalmacOS Apple Silicon: aprire un terminale ed eseguire:
brew tap microsoft/foundrylocal brew install foundrylocalIn alternativa, scaricare l'attuale macOS
.pkgo.zipdagli asset della versione dell'interfaccia della riga di comando locale di Foundry. Se si scarica ,.pkgaprirlo con il programma di installazione macOS.
Verificare l'installazione:
foundry --version
Assicurarsi di disporre dei diritti di amministratore per installare il software.
Tip
Se viene visualizzato un errore di connessione al server dopo l'installazione ( ad esempio , Request to local service failed), eseguire foundry server restart.
Verifica rapida
Eseguire questi comandi per verificare che l'interfaccia della riga di comando sia installata e che il server locale sia raggiungibile.
Mostra aiuto CLI
foundry --helpQuesto comando stampa informazioni sull'utilizzo e l'elenco dei gruppi di comandi disponibili.
Informazioni di riferimento: Panoramica
Controllare lo stato del server:
foundry server statusQuesto 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:
| Comando | Descrizione |
|---|---|
foundry model |
Individua, controlla, scarica, carica e scarica modelli locali. |
foundry chat <model> |
Avvia una sessione di chat locale interattiva. |
foundry complete <model> <prompt> |
Genera un completamento del testo senza stato. |
foundry run <model> |
Esegue un modello con routing automatico alla chat o alla trascrizione. |
foundry server |
Avvia, arresta, riavvia, controlla e risolve i problemi del daemon Foundry locale. |
foundry cache |
Controlla e gestisce le voci della cache dei modelli scaricate. |
foundry config |
Visualizza e modifica le impostazioni dell'interfaccia della riga di comando di Foundry persistenti. |
foundry status |
Mostra la diagnostica di sistema, server, modello e connettività. |
foundry report |
Apre un problema di GitHub precompilato con la diagnostica. |
foundry transcribe |
Avvia una sessione interattiva di trascrizione vocale locale o trascrive un file. |
Comandi del modello
La tabella seguente riepiloga i comandi correlati alla gestione e all'esecuzione dei modelli:
Note
È 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 in CPU, indipendentemente dall'hardware qwen2.5-0.5b disponibile, usare foundry 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 list |
Elenca tutti i modelli disponibili per l'uso locale. Alla prima esecuzione, scarica i provider di esecuzione (EP) per l'hardware. |
foundry model info <model> |
Visualizza informazioni dettagliate su un modello specifico. |
foundry model download <model> |
Scarica un modello nella cache locale senza eseguirlo. |
foundry model load <model> |
Carica un modello nel daemon locale. |
foundry model unload <model> |
Scarica un modello dal daemon locale. |
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
Usare le opzioni esplicite per foundry model list restringere o espandere i risultati.
Note
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.
| Opzione | Descrizione |
|---|---|
--device <kind> |
Filtra i modelli in base al tipo di dispositivo: cpu, gpuo npu. |
--type <task> |
Filtra i modelli per attività: chat, speecho embedding. |
--search <query> |
Filtra i modelli in base a una query di ricerca. |
--cached |
Filtra l'elenco per memorizzare nella cache i modelli. |
--loaded |
Filtra l'elenco per caricare i modelli. |
--variants |
Include varianti di modello nell'elenco. |
--limit <n> |
Limita il numero di righe nell'output. |
-v, --verbose |
Include le colonne License, Display Name e Model ID. |
Examples
foundry model list --device gpu
foundry model list --type chat
foundry model list --search qwen
foundry model list --cached
foundry model list --loaded
foundry model list --variants
foundry model list --limit 20
foundry model list --verbose
Questi esempi filtrano o espandono l'elenco di modelli usando le opzioni supportate.
Riferimento: Filtro elenco modelli
Eseguire un modello in modo interattivo
Eseguire un modello e interagire con esso direttamente nel terminale:
foundry chat 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?
Tip
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 per il server
La tabella seguente riepiloga i comandi correlati alla gestione e all'esecuzione del server locale Foundry:
| Comando | Descrizione |
|---|---|
foundry server --help |
Visualizza tutti i comandi correlati al server disponibili e il relativo utilizzo. |
foundry server start |
Avvia il daemon locale Foundry e il servizio locale compatibile con OpenAI. |
foundry server start --port <port> |
Avvia il servizio locale sulla porta TCP specificata. Usare 0 per una porta assegnata dal sistema operativo. |
foundry server start --idle-timeout <minutes> |
Arresta il daemon dopo il numero specificato di minuti inattivi. Usare 0 per mantenere il daemon in esecuzione. |
foundry server stop |
Arresta il daemon locale foundry. |
foundry server restart |
Riavvia il daemon locale foundry e il servizio locale. |
foundry server restart --port <port> --idle-timeout 0 |
Riavvia il servizio locale sulla porta TCP specificata e mantiene il daemon in esecuzione. |
foundry server status |
Visualizza lo stato del daemon, gli URL del servizio locale, l'ID processo, il tempo di attività e il percorso del log. |
foundry server logs |
Visualizza il daemon locale foundry e i log sdk. |
Opzioni dei log del server
Usare queste opzioni con foundry server logs:
| Opzione | Descrizione |
|---|---|
-n, --lines <n> |
Mostra il numero specificato di righe di log recenti. Il valore predefinito è 50. |
-f, --follow |
Trasmette le nuove righe di log man mano che vengono accodate. |
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:
| 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 memorizzato nella cache. Se si omette <model>, il comando rimuove tutti i modelli memorizzati nella cache dopo la conferma. |
Usare foundry cache remove <model> --force per rimuovere un modello memorizzato nella cache senza confermare.
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 (Informazioni) |
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.
Avviare un modello e lasciare aperto il terminale:
foundry run qwen2.5-0.5bOttenere l'URL dell'endpoint locale:
foundry server statusCopiare l'URL dell'endpoint. Foundry Local assegna una porta dinamica ogni volta che il server viene avviato.
Installare e avviare Open WebUI ,quindi aprire
http://localhost:8080nel browser.Connettere Open WebUI to Foundry Local :Connect Open WebUI to Foundry Local:Connect Open WebUI to Foundry Local:
- Passare a Impostazioni>Impostazioni Impostazioni Connessioni> amministratore e abilitare Connessioni dirette.
- Passare a Impostazioni>Connessioni>gestisci connessioni dirette e selezionare +.
- Impostare URL su
http://localhost:PORT/v1(sostituirePORTcon la porta del passaggio 2) e Autenticazione su Nessuno. - Seleziona Salva.
Selezionare un modello dall'elenco a discesa e avviare la chat.
Tip
Se non vengono visualizzati modelli, eseguire foundry run <model> in un terminale e ricaricare Open WebUI. Se la connessione non riesce, confermare la porta con foundry server status.
Aggiornare Foundry Local
Eseguire il comando per il sistema operativo per aggiornare Foundry Local.
Windows:
winget upgrade --id Microsoft.FoundryLocalmacOS Apple Silicon: se si esegue l'aggiornamento da Foundry Local 0.8.x, arrestare il servizio precedente prima dell'aggiornamento:
foundry service stop brew update brew upgrade microsoft/foundrylocal/foundrylocalSe si è già nell'interfaccia della riga di comando di anteprima corrente, eseguire:
brew update brew upgrade microsoft/foundrylocal/foundrylocal
Disinstallare Foundry Local
Per disinstallare Foundry Local in Windows, eseguire:
winget uninstall Microsoft.FoundryLocal
Risoluzione dei problemi
Problemi di connessione al server
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 server status with 'foundry server status'.
Riavviare il server:
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.