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 lokalen Server 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 oder Installers für Ihr Betriebssystem.

  • Windows: Öffnen Sie ein Terminal, und führen Sie Folgendes aus:

    winget install Microsoft.FoundryLocal

  • macOS Apple Silicon: Laden Sie die aktuellen macOS .pkg oder .zip aus den Veröffentlichungsressourcen der Lokalen CLI herunter. Homebrew wird für die aktuelle CLI-Vorschau nicht unterstützt. Wenn Sie das .pkgProgramm herunterladen, öffnen Sie es mit macOS Installer.

Überprüfen Sie die Installation:

foundry --version

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

Tip

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

Schnelle Überprüfung

Führen Sie diese Befehle aus, um zu bestätigen, dass die CLI installiert ist und der lokale Server 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 Serverstatus:

    foundry server status

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

    Referenz: Serverbefehle

Übersicht

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

Die CLI organisiert Befehle in den folgenden Gruppen:

  • Modell: model, cache
  • Run: run, chat, , completetranscribe
  • Server: server
  • Setup: config
  • Hilfe: status, report

In der folgenden Tabelle sind die Befehle der obersten Ebene zusammengefasst:

Command Beschreibung
foundry model Ermittelt, überprüft, lädt, lädt und entlädt lokale Modelle.
foundry chat <model> Startet eine interaktive lokale Chatsitzung.
foundry complete <model> <prompt> Generiert einen zustandslosen Textabschluss.
foundry run <model> Führt ein Modell mit automatischem Routing zu Chat oder Transkription aus.
foundry server Startet, stoppt, startet, startet, prüft und problembehandlungen den lokalen Foundry-Daemon.
foundry cache Überprüft und verwaltet heruntergeladene Modellcacheeinträge.
foundry config Ansichten und Bearbeiten persistenter Gießerei CLI-Einstellungen.
foundry status Zeigt die System-, Server-, Modell- und Konnektivitätsdiagnose an.
foundry report Öffnet ein vorab ausgefülltes GitHub Problem mit der Diagnose.
foundry transcribe Startet eine interaktive lokale Sprachtranskriptionssitzung oder transkribiert eine Datei.

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 die qwen2.5-0.5b CPU auszuführen, verwenden Sie foundry run qwen2.5-0.5b-instruct-generic-cpuunabhängig von der verfügbaren Hardware die CPU.

Command Beschreibung
foundry model --help Zeigt alle verfügbaren modellbezogenen Befehle und deren Verwendung an.
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 info <model> Zeigt detaillierte Informationen zu einem bestimmten 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 lokalen Daemon.
foundry model unload <model> Entlädt ein Modell aus dem lokalen Daemon.

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

Verwenden Sie die expliziten Optionen, foundry model list um die Ergebnisse einzugrenzen oder zu erweitern.

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.

Auswahl Beschreibung
--device <kind> Filtert Modelle nach Gerätetyp: cpu, , gpuoder npu.
--type <task> Filtert Modelle nach Aufgabe: chat, , speechoder embedding.
--search <query> Filtert Modelle nach einer Suchabfrage.
--cached Filtert die Liste auf zwischengespeicherte Modelle.
--loaded Filtert die Liste nach geladenen Modellen.
--variants Enthält Modellvarianten in der Liste.
--limit <n> Schränkt die Anzahl der Zeilen in der Ausgabe ein.
-v, --verbose Enthält Spalten "Lizenz", "Anzeigename" und "Modell-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

In diesen Beispielen wird die Modellliste mithilfe der unterstützten Optionen gefiltert oder erweitert.

Referenz: Filterung der Modellliste

Interaktives Ausführen eines Modells

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

foundry chat 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?

Tip

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.

Serverbefehle

In der folgenden Tabelle sind die Befehle zum Verwalten und Ausführen des lokalen Foundry-Servers zusammengefasst:

Command Beschreibung
foundry server --help Zeigt alle verfügbaren serverbezogenen Befehle und deren Verwendung an.
foundry server start Startet den Foundry Local Daemon und den openAI-kompatiblen lokalen Dienst.
foundry server start --port <port> Startet den lokalen Dienst für den angegebenen TCP-Port. Wird 0 für einen vom Betriebssystem zugewiesenen Port verwendet.
foundry server start --idle-timeout <minutes> Beendet den Daemon nach der angegebenen Anzahl inaktiver Minuten. Wird verwendet 0 , um die Ausführung des Daemons beizubehalten.
foundry server stop Beendet den lokalen Daemon "Foundry".
foundry server restart Startet den Foundry Local Daemon und den lokalen Dienst neu.
foundry server restart --port <port> --idle-timeout 0 Startet den lokalen Dienst auf dem angegebenen TCP-Port neu und führt den Daemon aus.
foundry server status Zeigt den Daemonstatus, lokale Dienst-URLs, Prozess-ID, Betriebszeit und Protokollspeicherort an.
foundry server logs Zeigt die Protokolle "Foundry Local daemon" und "SDK" an.

Serverprotokolloptionen

Verwenden Sie diese Optionen mit foundry server logs:

Auswahl Beschreibung
-n, --lines <n> Zeigt die angegebene Anzahl der zuletzt verwendeten Protokollzeilen an. Der Standardwert lautet 50.
-f, --follow Streamt neue Protokollzeilen, während sie angefügt werden.

Lokaler Server mit fester Port

Um den lokalen Dienst auf einem festen Port zu starten und den Daemon weiterhin auszuführen, verwenden Sie Folgendes --port--idle-timeout 0:

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

Wenn der Daemon bereits ausgeführt wird und Sie einen neuen Port anwenden müssen, starten Sie ihn mit den gleichen Optionen neu:

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

Führen Sie Folgendes aus, um die url des lokalen Endpunkts zu überprüfen:

foundry server status

Cachebefehle

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

Command 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 zwischengespeichertes Modell. Wenn Sie weglassen <model>, entfernt der Befehl alle zwischengespeicherten Modelle nach der Bestätigung.

Verwenden Sie diese Option foundry cache remove <model> --force , um ein zwischengespeichertes Modell ohne Bestätigung zu entfernen.

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 Lizenzvertrag 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 run qwen2.5-0.5b

  2. Rufen Sie Ihre lokale Endpunkt-URL ab:

    foundry server status

    Kopieren Sie die Endpunkt-URL. Foundry Local weist bei jedem Start des Servers 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.

Tip

Wenn keine Modelle angezeigt werden, führen Sie es in einem Terminal aus foundry run <model> , und laden Sie Open WebUI neu. Wenn die Verbindung fehlschlägt, bestätigen Sie den Port mit foundry server 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 Apple Silicon: Laden Sie das neuere macOS .pkg oder .zip aus den Foundry Local CLI-Releaseressourcen herunter, und installieren Sie das neuere Paket.

Foundry Local deinstallieren

Um Foundry Local auf Windows zu deinstallieren, führen Sie Folgendes aus:

winget uninstall Microsoft.FoundryLocal

Troubleshooting

Serververbindungsprobleme

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 server status with 'foundry server status'.

Starten Sie den Server neu:

foundry server restart

Dieser Befehl behebt Fälle, in denen der Server 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