Freigeben über

Foundry Local CLI-Referenz

Von Bedeutung

  • Foundry Local CLI ist in der Vorschau verfügbar. Öffentliche Vorschauversionen bieten frühen Zugang zu Features, die aktuell bereitgestellt werden.
  • Features, Ansätze und Prozesse können sich vor der allgemeinen Verfügbarkeit (General Availability, GA) noch ändern oder eine eingeschränkte Funktionalität aufweisen.

Dieser Artikel enthält eine umfassende Referenz für die Befehlszeilenschnittstelle "Foundry Local" (CLI). Die CLI organisiert Befehle in logische Kategorien, um Modelle zu verwalten, den Dienst zu steuern und den lokalen Cache zu verwalten.

Voraussetzungen

  • Installieren Sie Foundry Local.
  • Ein lokales Terminal, in dem die foundry CLI verfügbar ist.
  • Stellen Sie sicher, dass Sie über Internet-access für erstmalige Downloads (Ausführungsanbieter und Modelle) verfügen.
  • Azure RBAC: Nicht anwendbar (wird lokal ausgeführt).
  • Wenn Sie über einen Intel NPU auf Windows verfügen, installieren Sie den Intel NPU-Treiber für eine optimale NPU-Beschleunigung.

Installieren von Foundry Local

Installieren Sie Foundry Local mithilfe des Paket-Managers für Ihr Betriebssystem.

  • Windows: Öffnen Sie ein Terminal, und führen Sie Folgendes aus:
    winget install Microsoft.FoundryLocal
  • macOS: Öffnen Sie ein Terminal, und führen Sie Folgendes aus: 
    brew tap microsoft/foundrylocal
brew install foundrylocal
    Alternativ können Sie das Installationsprogramm aus dem Repository Foundry Local GitHub herunterladen.

Überprüfen Sie die Installation:

foundry --version

Stellen Sie sicher, dass Sie über Administratorrechte zum Installieren von Software verfügen.

Tipp

Wenn nach der Installation ein Dienstverbindungsfehler angezeigt wird (z. B Request to local service failed. ), führen Sie aus foundry service restart.

Schnelle Überprüfung

Führen Sie diese Befehle aus, um zu bestätigen, dass die CLI installiert ist und der Dienst erreichbar ist.

  1. CLI-Hilfe anzeigen:

     foundry --help

    Dieser Befehl druckt Nutzungsinformationen und die Liste der verfügbaren Befehlsgruppen.

    Referenz: Übersicht

  2. Überprüfen Sie den Dienststatus:

     foundry service status

    Dieser Befehl gibt an, ob der lokale Foundry-Dienst ausgeführt wird und seinen lokalen Endpunkt enthält.

    Referenz: Dienstbefehle

Überblick

Verwenden Sie die integrierte Hilfe, um Befehle und Optionen zu erkunden.

Die CLI organisiert Befehle in drei Hauptkategorien:

  • Modell: Befehle zum Verwalten und Ausführen von KI-Modellen
  • Dienst: Befehle zum Steuern des lokalen Foundry-Diensts
  • Cache: Befehle zum Verwalten Ihres lokalen Modellspeichers

Modellbefehle

In der folgenden Tabelle sind die Befehle im Zusammenhang mit der Verwaltung und Ausführung von Modellen zusammengefasst:

Hinweis

Sie können das model Argument anhand des Alias oder der Modell-ID angeben. Verwenden eines Alias:

  • Wählt das beste Modell für Ihre verfügbare Hardware automatisch aus. Wenn Sie beispielsweise über eine Nvidia-GPU verfügen, wählt Foundry Local das beste GPU-Modell aus. Wenn Sie eine unterstützte NPU verfügbar haben, wählt Foundry Local das NPU-Modell aus.
  • Hiermit können Sie einen kürzeren Namen verwenden, ohne sich die Modell-ID merken zu müssen.

Wenn Sie ein bestimmtes Modell ausführen möchten, verwenden Sie die Modell-ID. Um beispielsweise qwen2.5-0.5b auf der CPU auszuführen – unabhängig von der verfügbaren Hardware – verwenden Sie: foundry model run qwen2.5-0.5b-instruct-generic-cpu.

Befehl Beschreibung
foundry model --help Zeigt alle verfügbaren modellbezogenen Befehle und deren Verwendung an.
foundry model run <model> Führt ein angegebenes Modell aus, lädt es herunter, wenn es nicht zwischengespeichert ist, und startet eine Interaktion.
foundry model list Listet alle verfügbaren Modelle für die lokale Verwendung auf. Bei der ersten Ausführung lädt sie Ausführungsanbieter (EPs) für Ihre Hardware herunter.
foundry model list --filter <key>=<value> Listet Modelle auf, die nach den angegebenen Kriterien gefiltert werden (Gerät, Aufgabe, Alias, Anbieter).
foundry model info <model> Zeigt detaillierte Informationen zu einem bestimmten Modell an.
foundry model info <model> --license Zeigt die Lizenzinformationen für ein bestimmtes Modell an.
foundry model download <model> Lädt ein Modell in den lokalen Cache herunter, ohne es auszuführen.
foundry model load <model> Lädt ein Modell in den Dienst.
foundry model unload <model> Entlädt ein Modell aus dem Dienst

Modelllistenbestellung

Wenn mehrere Modell-ID-Varianten für einen Alias verfügbar sind, zeigt die Modellliste die Modelle in der Prioritätsreihenfolge an. Das erste Modell in der Liste ist das Modell, das ausgeführt wird, wenn Sie das Modell nach alias angeben.

Filtern in der Modellliste

Der foundry model list Befehl unterstützt Filtermodelle mithilfe der --filter Option. Sie können Modelle anhand eines einzelnen Attributs mithilfe von Schlüsselwertpaaren filtern.

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

Mit diesem Befehl werden Modelle gedruckt, die mit dem Filterschlüssel und -wert übereinstimmen.

Referenz: Filterung der Modellliste

Hinweis

Wenn Sie foundry model list nach der Installation zum ersten Mal ausführen, lädt Foundry Local automatisch die relevanten Ausführungsanbieter (EPs) für die Hardwarekonfiguration Ihres Geräts herunter. Es wird eine Statusleiste angezeigt, die den Abschluss des Downloads anzeigt, bevor die Modellliste angezeigt wird.

Unterstützte Filterschlüssel:

gerät – Hardwaregerätetyp

Filtert Modelle nach dem Hardwaregerät, auf dem sie ausgeführt werden.

Mögliche Werte:

  • CPU - Zentrale Verarbeitungseinheitsmodelle
  • GPU - Grafikverarbeitungseinheitsmodelle
  • NPU - Neurale Verarbeitungseinheitsmodelle

Provider – Ausführungs-Provider

Filtert Modelle nach ihrem Ausführungsanbieter oder ihrer Laufzeit.

Mögliche Werte:

  • CPUExecutionProvider - CPU-basierte Ausführung
  • CUDAExecutionProvider - NVIDIA CUDA GPU-Ausführung
  • WebGpuExecutionProvider - WebGPU-Ausführung
  • QNNExecutionProvider - Neurale Netzwerkausführung von Qualcomm (NPU)
  • OpenVINOExecutionProvider - Intel OpenVINO-Ausführung
  • NvTensorRTRTXExecutionProvider - NVIDIA TensorRT-Ausführung
  • VitisAIExecutionProvider: AMD Vitis AI-Ausführung

task - Modellaufgabentyp

Filtert Modelle nach dem beabsichtigten Anwendungsfall oder der beabsichtigten Aufgabe.

Allgemeine Werte:

  • chat-completion: Konversationelle KI-Modelle
  • text-generation: Modelle der Textgenerierung

Alias – Modellalias

Filtert Modelle anhand ihres Aliasbezeichners. Unterstützt den Platzhalterabgleich mit dem Suffix *.

Beispielwerte:

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

Spezielle Filterfeatures

Negation-Unterstützung: Präfixen Sie jeden beliebigen Wert mit !, um übereinstimmende Modelle auszuschließen.

foundry model list --filter device=!GPU

Dieser Befehl schließt GPU-Modelle aus den Ergebnissen aus.

Referenz: Spezielle Filterfeatures

Platzhalterabgleich (nur Alias): Fügen Sie * an, um Präfixe beim Filtern nach Alias abzugleichen.

foundry model list --filter alias=qwen*

Dieser Befehl gibt Modelle zurück, deren Alias mit qwen beginnt.

Referenz: Spezielle Filterfeatures

Beispiele

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

In diesen Beispielen wird die Modellliste nach Geräte-, Aufgaben- und Ausführungsanbietern gefiltert.

Referenz: Filterung der Modellliste

Hinweis

  • Beim allen Vergleichen wird die Groß-/Kleinschreibung nicht beachtet.
  • Pro Befehl kann nur ein Filter verwendet werden.
  • Nicht erkannte Filterschlüssel führen zu einem Fehler.

Interaktives Ausführen eines Modells

Führen Sie ein Modell aus und interagieren Sie direkt im Terminal mit dem Modell:

foundry model run qwen2.5-0.5b

Foundry Local lädt das Modell bei der ersten Ausführung herunter und startet dann eine interaktive Sitzung. Geben Sie eine Eingabeaufforderung ein, um eine Antwort zu erhalten:

Why is the sky blue?

Screenshot der Ausgabe des Befehls

Tipp

Ersetzen Sie durch qwen2.5-0.5b einen beliebigen Modellalias aus dem Katalog. Führen Sie die Ausführung foundry model list aus, um verfügbare Modelle anzuzeigen. Foundry Local lädt die Variante herunter, die ihrer Hardware am besten entspricht , z. B. eine CUDA-Variante für NVIDIA GPUs oder eine NPU-Variante für Qualcomm NPUs.

Dienstbefehle

In der folgenden Tabelle sind die Befehle im Zusammenhang mit der Verwaltung und Ausführung des lokalen Foundry-Diensts zusammengefasst:

Befehl Beschreibung
foundry service --help Zeigt alle verfügbaren dienstbezogenen Befehle und deren Verwendung an.
foundry service start Startet den Dienst "Foundry Local".
foundry service stop Beendet den Foundry Local-Dienst
foundry service restart Startet den lokalen Foundry-Dienst neu.
foundry service status Zeigt den aktuellen Status des lokalen Foundry-Diensts an.
foundry service ps Listet alle Modelle auf, die zurzeit im lokalen Foundry-Dienst geladen wurden.
foundry service diag Zeigt die Protokolle des lokalen Foundry-Diensts an.
foundry service set <options> Legt die Konfiguration des lokalen Foundry-Diensts fest.

Cachebefehle

In der folgenden Tabelle sind die Befehle zum Verwalten des lokalen Caches zusammengefasst, in dem Modelle gespeichert sind:

Befehl Beschreibung
foundry cache --help Zeigt alle verfügbaren cachebezogenen Befehle und deren Verwendung an.
foundry cache location Zeigt das aktuelle Cacheverzeichnis an.
foundry cache list Listet alle Modelle auf, die im lokalen Cache gespeichert sind.
foundry cache cd <path> Ändert das Cacheverzeichnis in den angegebenen Pfad.
foundry cache remove <model> Entfernt ein Modell aus dem lokalen Cache.

Ausführungsanbieter

Ausführungsanbieter sind hardwarespezifische Beschleunigungsbibliotheken, die Modelle so effizient wie möglich auf Ihrem Gerät ausführen.

Integrierte Ausführungsanbieter

Foundry Local umfasst den CPU-Ausführungsanbieter, den WebGPU-Ausführungsanbieter und den CUDA-Ausführungsanbieter.

Der CPU-Ausführungsanbieter verwendet Microsoft Linear algebra Subroutines (MLAS) für die Ausführung auf einer beliebigen CPU und ist der CPU-Fallback für Foundry Local.

Der WebGPU-Ausführungsanbieter verwendet Dawn, die native Implementierung der webbasierten API, um jede GPU zu beschleunigen, und ist der GPU-Fallback für Foundry Local.

Der CUDA-Ausführungsanbieter verwendet NVIDIA CUDA für beschleunigung auf NVIDIA GPUs. Es erfordert eine NVIDIA GeForce RTX 30-Serie und höher mit mindestens empfohlener Treiberversion 32.0.15.5585 und CUDA Version 12.5. Es unterliegt den folgenden Lizenzbedingungen: Lizenzvertrag für NVIDIA Software Development Kits – EULA.

Plug-In-Ausführungsanbieter

Die in der folgenden Tabelle aufgeführten Ausführungsanbieter stehen je nach Geräte- und Treiberkompatibilität für den dynamischen Download und die Registrierung auf Windows zur Verfügung. Sie unterliegen den angegebenen Lizenzbedingungen.

Foundry Local lädt diese Ausführungsanbieter automatisch bei der ersten Ausführung herunter. Die Plugin-Ausführungsanbieter werden automatisch aktualisiert, wenn neue Versionen verfügbar sind.

Name (Anbieter) Anforderungen Lizenzbedingungen
NvTensorRTRTXExecutionProvider (NVIDIA) NVIDIA GeForce RTX 30XX und höhere Versionen mit mindestens empfohlener Treiberversion 32.0.15.5585 und CUDA, Version 12.5 Lizenzvertrag für NVIDIA Software Development Kits – EULA
OpenVINOExecutionProvider (Intel) CPU: Intel TigerLake (11. Generation) und spätere Versionen mit mindestens empfohlener Treiber 32.0.100.9565
GPU: Intel AlderLake (12. Generation) und höhere Versionen mit min. empfohlenem Treiber 32.0.101.1029
NPU: Intel ArrowLake (15. Generation) und späteren Versionen mit mindestens empfohlenem Treiber 32.0.100.4239		 Intel OBL Distribution Commercial Use License Agreement v2025.02.12
QNNExecutionProvider (Qualcomm) Snapdragon(R) X Elite - X1Exxxxx - Qualcomm(R) Hexagon(TM) NPU mit mindester Treiberversion 30.0.140.0 und höher
Snapdragon(R) X Plus - X1Pxxxxx - Qualcomm(R) Hexagon(TM) NPU mit mindester Treiberversion 30.0.140.0 und höher		 Um die QNN-Lizenz anzuzeigen, laden Sie das Neural Processing SDK von Qualcomm® herunter, extrahieren Sie die ZIP-Datei, und öffnen Sie die LICENSE.pdf Datei.
VitisAIExecutionProvider (AMD) Min: Adrenalin Version 25.6.3 mit NPU-Treiber 32.00.0203.280
Max: Adrenalin Edition 25.9.1 mit NPU Treiber 32.00.0203.297		 Keine zusätzliche Lizenz erforderlich

Verwenden von Open WebUI mit dem lokalen Server

Verbinden Sie Open WebUI mit Foundry Local für eine browserbasierte Chatschnittstelle, die vollständig auf Ihrem Gerät ausgeführt wird.

  1. Starten Sie ein Modell, und lassen Sie das Terminal geöffnet:

    foundry model run qwen2.5-0.5b

  2. Rufen Sie Ihre lokale Endpunkt-URL ab:

    foundry service status

    Kopieren Sie die Endpunkt-URL. Foundry Local weist bei jedem Start des Diensts einen dynamischen Port zu.

  3. Installieren und starten Sie Open WebUI, und öffnen http://localhost:8080 Sie sie dann in Ihrem Browser.

  4. Verbinden von Open WebUI mit Foundry Local:

    1. Wechseln Sie zu Einstellungen>für Administratoreinstellungen>Connections , und aktivieren Sie Direct Connections.
    2. Wechseln Sie zu "Einstellungen Connections>>Verwalten von Direkten Verbindungen", und wählen Sie "+.
    3. Legen Sie die URL auf http://localhost:PORT/v1 (ersetzen Sie PORT den Port aus Schritt 2) und die Authentifizierung auf "Keine" fest.
    4. Wählen Sie "Speichern" aus.

  5. Wählen Sie ein Modell aus der Dropdownliste aus, und beginnen Sie mit dem Chatten.

Tipp

Wenn keine Modelle angezeigt werden, führen Sie es in einem Terminal aus foundry model run <model> , und laden Sie Open WebUI neu. Wenn die Verbindung fehlschlägt, bestätigen Sie den Port mit foundry service status.

Upgrade Foundry Lokal

Führen Sie den Befehl für Ihr Betriebssystem aus, um foundry Local zu aktualisieren.

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

Foundry Local deinstallieren

Führen Sie den Befehl für Ihr Betriebssystem aus, um Foundry Local zu deinstallieren.

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

Problembehandlung

Dienstverbindungsprobleme

Wenn dieser Fehler angezeigt wird, wenn Sie einen Befehl wie 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'.

Starten Sie den Dienst neu:

foundry service restart

Dieser Befehl behebt Fälle, in denen der Dienst ausgeführt wird, aber aufgrund eines Portbindungsproblems nicht zugänglich ist.

Weitere Anleitungen zur Problembehandlung finden Sie unter Bewährte Methoden und Problembehandlung.

  • Last updated on