Referens för lokal CLI i Foundry

Important

  • Foundry Local CLI är tillgängligt som förhandsversion. Offentliga förhandsversioner ger tidiga access till funktioner som är i aktiv distribution.
  • Funktioner, metoder och processer kan ändra eller ha begränsade funktioner, före allmän tillgänglighet (GA).

Den här artikeln innehåller en omfattande referens för kommandoradsgränssnittet foundry Local (CLI). CLI organiserar kommandon i logiska kategorier som hjälper dig att hantera modeller, kontrollera tjänsten och underhålla din lokala cache.

Prerequisites

  • Installera Foundry Local.
  • En lokal terminal där foundry CLI är tillgängligt.
  • Se till att du har internetåtkomst vid första nedladdningarna (exekveringsleverantörer och modeller).
  • Azure RBAC: Inte tillämpligt (körs lokalt).
  • Om du har en Intel NPU på Windows installerar du Intel NPU-drivrutinen för optimal NPU-acceleration.

Installera Foundry Local

Installera Foundry Local med hjälp av pakethanteraren för operativsystemet.

  • Windows: Öppna en terminal och kör:
    winget install Microsoft.FoundryLocal
  • macOS: Öppna en terminal och kör: 
    brew tap microsoft/foundrylocal
brew install foundrylocal
    Du kan också ladda ned installationsprogrammet från lagringsplatsen Foundry Local GitHub.

Kontrollera installationen:

foundry --version

Kontrollera att du har administratörsbehörighet för att installera programvara.

Tip

Om du ser ett tjänstanslutningsfel efter installationen (till exempel Request to local service failed), kör foundry service restartdu .

Quick verification

Kör dessa kommandon för att bekräfta att CLI är installerat och att tjänsten kan nås.

  1. Visa CLI-hjälp:

     foundry --help

    Det här kommandot skriver ut användningsinformation och listan över tillgängliga kommandogrupper.

    Reference: Overview

  2. Kontrollera tjänststatusen:

     foundry service status

    Det här kommandot skriver ut om den lokala Foundry-tjänsten körs och innehåller dess lokala slutpunkt.

    Referens: Tjänstkommandon

Overview

Använd den inbyggda hjälpen för att utforska kommandon och alternativ.

CLI organiserar kommandon i tre huvudkategorier:

  • Modell: Kommandon för att hantera och köra AI-modeller
  • Tjänst: Kommandon för att styra den lokala foundry-tjänsten
  • Cache: Kommandon för att hantera din lokala modellagring

Model commands

I följande tabell sammanfattas kommandona som rör hantering och körning av modeller:

Note

Argumentet kan anges efter model dess alias eller modell-ID. Använda ett alias:

  • Väljer den bästa modellen för den tillgängliga maskinvaran automatiskt. Om du till exempel har en Nvidia GPU tillgänglig väljer Foundry Local den bästa GPU-modellen. Om du har en NPU som stöds väljer Foundry Local NPU-modellen.
  • Gör att du kan använda ett kortare namn utan att behöva komma ihåg modell-ID:t.

Om du vill köra en specifik modell använder du modell-ID:t. Om du till exempel vill köra processorn qwen2.5-0.5b – oavsett vilken maskinvara du har – använder du: foundry model run qwen2.5-0.5b-instruct-generic-cpu.

Command Description
foundry model --help Visar alla tillgängliga modellrelaterade kommandon och deras användning.
foundry model run <model> Kör en angiven modell, laddar ned den om den inte cachelagras och startar en interaktion.
foundry model list Visar en lista över alla tillgängliga modeller för lokal användning. Vid första körningen laddar den ned executionsproviders (EPs) för din maskinvara.
foundry model list --filter <key>=<value> Visar modeller som filtrerats efter de angivna kriterierna (enhet, uppgift, alias, provider).
foundry model info <model> Visar detaljerad information om en specifik modell.
foundry model info <model> --license Visar licensinformationen för en specifik modell.
foundry model download <model> Laddar ned en modell till den lokala cachen utan att köra den.
foundry model load <model> Läser in en modell i tjänsten.
foundry model unload <model> Tar bort en modell från tjänsten.

Ordning av modellista

När flera modell-ID-varianter är tillgängliga för ett alias visar modelllistan modellerna i prioritetsordning. Den första modellen i listan är den modell som körs när du anger modellen med alias.

Filtrering av modelllista

Kommandot foundry model list stöder filtreringsmodeller med hjälp av alternativet --filter . Du kan filtrera modeller baserat på ett enda attribut med hjälp av nyckel/värde-par.

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

Det här kommandot skriver ut modeller som matchar filternyckeln och värdet.

Referens: Filtrering för modellista

Note

När du kör foundry model list för första gången efter installationen laddar Foundry Local automatiskt ned relevanta exekveringsleverantörer (EPs) för datorns hårdvarukonfiguration. Du ser en förloppsindikator som anger att nedladdningen har slutförts innan modelllistan visas.

Filternycklar som stöds:

device – Typ av maskinvaruenhet

Filtrerar modeller efter den maskinvaruenhet som de körs på.

Possible values:

  • CPU – Modeller för central bearbetningsenhet
  • GPU – Enhetsmodeller för grafikbearbetning
  • NPU – Modeller av neuralbehandlingsenheter

provider – körningsprovider

Filtrerar modeller efter deras exekveringsmiljö eller runtime.

Possible values:

  • CPUExecutionProvider – CPU-baserad körning
  • CUDAExecutionProvider – NVIDIA CUDA GPU-körning
  • WebGpuExecutionProvider – WebGPU-körning
  • QNNExecutionProvider - Qualcomm neurala nätverksutförande (NPU)
  • OpenVINOExecutionProvider – Intel OpenVINO-körning
  • NvTensorRTRTXExecutionProvider – NVIDIA TensorRT-körning
  • VitisAIExecutionProvider – AMD Vitis AI-körning

task – Modell Uppgiftstyp

Filtrerar modeller efter avsett användningsfall eller uppgift.

Common values:

  • chat-completion: Ai-modeller för konversationer
  • text-generation: Modeller för textgenerering

Alias – Modellalias

Filtrerar modeller efter aliasidentifierare. Stöder jokerteckenmatchning med *-suffixet.

Sample values:

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

Särskilda filterfunktioner

Negation Support: Prefix valfritt värde med ! för att undanta matchande modeller.

foundry model list --filter device=!GPU

Det här kommandot undantar GPU-modeller från resultaten.

Referens: Särskilda filterfunktioner

Matchning av jokertecken (endast alias):* Lägg till för att matcha prefix vid filtrering efter alias.

foundry model list --filter alias=qwen*

Det här kommandot returnerar modeller vars alias börjar med qwen.

Referens: Särskilda filterfunktioner

Examples

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

De här exemplen filtrerar modelllistan efter enhet, uppgift och körningsprovider.

Referens: Filtrering för modellista

Note

  • Alla jämförelser är skiftlägesokänsliga.
  • Endast ett filter kan användas per kommando.
  • Okända filternycklar resulterar i ett fel.

Köra en modell interaktivt

Kör en modell och interagera med den direkt i terminalen:

foundry model run qwen2.5-0.5b

Foundry Local laddar ned modellen vid första körningen och startar sedan en interaktiv session. Ange en uppmaning om att få ett svar:

Why is the sky blue?

Skärmbild av utdata från kommandot Foundry Local run.

Tip

Ersätt qwen2.5-0.5b med alla modellalias från katalogen. Kör foundry model list för att visa tillgängliga modeller. Foundry Local hämtar den variant som bäst matchar din maskinvara – till exempel en CUDA-variant för NVIDIA GPU:er eller en NPU-variant för Qualcomm NPU:er.

Service commands

I följande tabell sammanfattas kommandona som rör hantering och körning av den lokala foundry-tjänsten:

Command Description
foundry service --help Visar alla tillgängliga tjänstrelaterade kommandon och deras användning.
foundry service start Startar den lokala fabrikstjänsten.
foundry service stop Stänger Foundry Local-tjänsten.
foundry service restart Startar om Foundry-tjänsten lokalt.
foundry service status Visar aktuell status för Foundry Local-tjänsten.
foundry service ps Lista över alla modeller som för närvarande har laddats in i Foundry Local-tjänsten.
foundry service diag Visar loggarna för Foundry Local-tjänsten.
foundry service set <options> Ställer in konfigurationen för Foundry Local-tjänsten.

Cache commands

I följande tabell sammanfattas kommandona för att hantera den lokala cachen där modeller lagras:

Command Description
foundry cache --help Visar alla tillgängliga cacherelaterade kommandon och deras användning.
foundry cache location Visar den aktuella cachekatalogen.
foundry cache list Visar en lista över alla modeller som lagras i den lokala cachen.
foundry cache cd <path> Ändrar cachekatalogen till den angivna sökvägen.
foundry cache remove <model> Tar bort en modell från den lokala cachen.

Execution providers

Körningstjänster är maskinvaruspecifika accelerationsbibliotek som kör modeller så effektivt som möjligt på din enhet.

Inbyggda exekveringsleverantörer

Foundry Local innehåller processorkörningsprovidern, WebGPU-körningsprovidern och CUDA-körningsprovidern.

Processorkörningsprovidern använder Microsoft Linear Algebra Subroutines (MLAS) för att köra på valfri CPU och är CPU-återställning för Foundry Local.

WebGPU-körningsprovidern använder Dawn, den interna implementeringen av det webbaserade API:et, för acceleration på alla GPU:er och är GPU-återställning för Foundry Local.

CUDA-körningsprovidern använder NVIDIA CUDA för acceleration på NVIDIA GPU:er. Det kräver en NVIDIA GeForce RTX 30-serie och senare med en lägsta rekommenderad drivrutinsversion 32.0.15.5585 och CUDA version 12.5. Det omfattas av följande licensvillkor: Licensavtal för NVIDIA Software Development Kits – EULA.

Utförandetjänst för plugin-program

Körningsprovidrar som anges i följande tabell är tillgängliga för dynamisk nedladdning och registrering på Windows, beroende på enhets- och drivrutinskompatibilitet. De omfattas av de licensvillkor som anges.

Foundry Local laddar automatiskt ned dessa exekveringsleverantörer vid första körningen. Leverantörerna för pluginutförande uppdateras automatiskt när nya versioner är tillgängliga.

Name (Vendor) Requirements License terms
NvTensorRTRTXExecutionProvider (NVIDIA) NVIDIA GeForce RTX 30XX och senare versioner med lägsta rekommenderade drivrutinsversion 32.0.15.5585 och CUDA version 12.5 Licensavtal för NVIDIA Software Development Kits – EULA
OpenVINOExecutionProvider (Intel) CPU: Intel TigerLake (11:e generationen) och senare versioner med min rekommenderad drivrutin 32.0.100.9565
GPU: Intel AlderLake (12:e generationen) och senare versioner med min rekommenderad drivrutin 32.0.101.1029
NPU: Intel ArrowLake (15:e generationen) och senare versioner med min rekommenderad drivrutin 32.0.100.4239		 Licensavtal för kommersiell användning med Intel OBL-distribution v2025.02.12
QNNExecutionProvider (Qualcomm) Snapdragon(R) X Elite – X1Exxxxx – Qualcomm(R) Hexagon(TM) NPU med lägsta drivrutinsversion 30.0.140.0 och senare versioner
Snapdragon(R) X Plus – X1Pxxxxx – Qualcomm(R) Hexagon(TM) NPU med lägsta drivrutinsversion 30.0.140.0 och senare versioner		 Om du vill visa QNN-licensen laddar du ned Qualcomm® Neural Processing SDK, extraherar ZIP och öppnar filen LICENSE.pdf.
VitisAIExecutionProvider (AMD) Min: Adrenalin Edition 25.6.3 med NPU-drivrutin 32.00.0203.280
Max: Adrenalin Edition 25.9.1 med drivrutin för NPU 32.00.0203.297		 Ingen ytterligare licens krävs

Använda Open WebUI med den lokala servern

Anslut Open WebUI till Foundry Local för ett webbläsarbaserat chattgränssnitt som körs helt på enheten.

  1. Starta en modell och lämna terminalen öppen:

    foundry model run qwen2.5-0.5b

  2. Hämta din lokala slutpunkts-URL:

    foundry service status

    Kopiera slutpunkts-URL:en. Foundry Local tilldelar en dynamisk port varje gång tjänsten startas.

  3. Installera och starta Open WebUI och öppna http://localhost:8080 sedan i webbläsaren.

  4. Anslut Open WebUI till Foundry Local:

    1. Gå till Inställningar>Administratörsinställningar>Anslutningar och aktivera direktanslutningar.
    2. Gå till Inställningar>Anslutningar>Hantera direktanslutningar och välj +.
    3. Ange URL tillhttp://localhost:PORT/v1 (ersätt PORT med porten från steg 2) och Auth till Ingen.
    4. Select Save.

  5. Välj en modell i listrutan och börja chatta.

Tip

Om inga modeller visas kör du foundry model run <model> i en terminal och läser in Open WebUI igen. Om anslutningen misslyckas bekräftar du porten med foundry service status.

Uppgradera Foundry Local

Kör kommandot för operativsystemet för att uppgradera Foundry Local.

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

Avinstallera Foundry Local

Kör kommandot för operativsystemet för att avinstallera Foundry Local.

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

Troubleshooting

Problem med tjänstanslutning

Om du ser det här felet när du kör ett kommando som 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'.

Starta om tjänsten:

foundry service restart

Det här kommandot åtgärdar fall där tjänsten körs men inte är tillgänglig på grund av ett portbindningsproblem.

Mer felsökningsvägledning finns i Metodtips och felsökning.

  • Last updated on