Referenční informace k místnímu rozhraní příkazového řádku Foundry

Important

  • Místní rozhraní příkazového řádku Foundry je k dispozici ve verzi Preview. Verze Public Preview poskytují dřívější access funkcím, které jsou v aktivním nasazení.
  • Funkce, přístupy a procesy se můžou před obecnou dostupností měnit nebo mít omezené možnosti.

Tento článek obsahuje komplexní referenční informace pro rozhraní příkazového řádku Foundry Local (CLI). Rozhraní příkazového řádku uspořádá příkazy do logických kategorií, které vám pomůžou spravovat modely, řídit službu a udržovat místní mezipaměť.

Prerequisites

  • Nainstalujte Foundry Local.
  • Místní terminál, kde je rozhraní příkazového foundry řádku k dispozici.
  • Ujistěte se, že máte přístup k internetu při prvním stahování (poskytovatelé služeb a modely).
  • Azure RBAC: Nejde použít (spouští se místně).
  • Pokud máte na Windows intel NPU, nainstalujte ovladač Intel NPU pro optimální akceleraci NPU.

Nainstalujte Foundry Local

Nainstalujte Foundry Local pomocí správce balíčků pro váš operační systém.

  • Windows: Otevřete terminál a spusťte:
    winget install Microsoft.FoundryLocal
  • macOS: Otevřete terminál a spusťte: 
    brew tap microsoft/foundrylocal
brew install foundrylocal
    Případně si stáhněte instalační program z úložiště Foundry Local GitHub.

Ověřte tuto instalaci:

foundry --version

Ujistěte se, že máte práva správce k instalaci softwaru.

Tip

Pokud se po instalaci zobrazí chyba připojení služby (například Request to local service failed), spusťte foundry service restart.

Quick verification

Spuštěním těchto příkazů potvrďte, že je rozhraní příkazového řádku nainstalované a služba je dostupná.

  1. Zobrazit nápovědu k rozhraní příkazového řádku:

     foundry --help

    Tento příkaz vytiskne informace o využití a seznam dostupných skupin příkazů.

    Reference: Overview

  2. Zkontrolujte stav služby:

     foundry service status

    Tento příkaz vypíše, zda je spuštěna služba Foundry Local a vypíše její místní koncový bod.

    Referenční informace: Příkazy služby

Overview

Pomocí integrované nápovědy můžete prozkoumat příkazy a možnosti.

Rozhraní CLI uspořádává příkazy do tří hlavních kategorií:

  • Model: Příkazy pro správu a spouštění modelů AI
  • Služba: Příkazy pro řízení místní služby Foundry
  • Cache: Příkazy pro správu místního modelu storage

Model commands

Následující tabulka shrnuje příkazy související se správou a spouštěním modelů:

Note

Pomocí model můžete argument zadat podle jeho aliasu nebo ID modelu. Použití aliasu:

  • Vybere nejlepší model pro váš dostupný hardware automaticky. Pokud máte například k dispozici Nvidia GPU, Foundry Local vybere nejlepší model GPU. Pokud máte k dispozici podporovanou NPU, Foundry Local vybere model NPU.
  • Umožňuje použít kratší název, aniž byste si museli pamatovat ID modelu.

Pokud chcete spustit konkrétní model, použijte ID modelu. Pokud například chcete spustit qwen2.5-0.5b na procesoru, bez ohledu na dostupný hardware, použijte: foundry model run qwen2.5-0.5b-instruct-generic-cpu.

Command Description
foundry model --help Zobrazí všechny dostupné příkazy související s modelem a jejich použití.
foundry model run <model> Spustí zadaný model, stáhne ho, pokud není uložený v mezipaměti, a spustí interakci.
foundry model list Zobrazí seznam všech dostupných modelů pro místní použití. Při prvním spuštění stáhne poskytovatele spouštění (EPs) pro váš hardware.
foundry model list --filter <key>=<value> Zobrazí seznam modelů filtrovaných podle zadaných kritérií (zařízení, úkol, alias, poskytovatel).
foundry model info <model> Zobrazí podrobné informace o konkrétním modelu.
foundry model info <model> --license Zobrazí informace o licenci pro konkrétní model.
foundry model download <model> Stáhne model do místní mezipaměti, aniž by ho spustil.
foundry model load <model> Načte model do služby.
foundry model unload <model> Odstraní model ze služby.

Řazení modelů v seznamu

Pokud je pro alias k dispozici více variant ID modelu, zobrazí se v seznamu modelů modely v pořadí priority. Prvním modelem v seznamu je model, který se spouští při zadávání modelu podle alias.

Filtrování seznamu modelů

Příkaz foundry model list podporuje filtrování modelů pomocí možnosti --filter. Modely můžete filtrovat na základě jednoho atributu pomocí párů klíč-hodnota.

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

Tento příkaz vytiskne modely, které odpovídají klíči filtru a hodnotě.

Referenční informace: Filtrování seznamu modelů

Note

Když po instalaci spustíte foundry model list poprvé, Foundry Local automaticky stáhne příslušné poskytovatele spouštění (EPs) pro konfiguraci hardwaru vašeho počítače. Zobrazí se indikátor průběhu označující dokončení stahování před zobrazením seznamu modelů.

Podporované klíče filtru:

zařízení – Typ hardwarového zařízení

Filtruje modely podle hardwarového zařízení, na kterých běží.

Possible values:

  • CPU - Modely jednotek centrálního zpracování
  • GPU - Modely grafických procesorů
  • NPU - Neurální zpracování modelů jednotek

provider – Zprostředkovatel spuštění

Filtruje modely podle poskytovatele spouštění nebo modulu runtime.

Possible values:

  • CPUExecutionProvider – Spuštění řízené procesorem
  • CUDAExecutionProvider – Spouštění GPU NVIDIA CUDA
  • WebGpuExecutionProvider – Provádění protokolu WebGPU
  • QNNExecutionProvider - Spuštění neurální sítě Qualcomm (NPU)
  • OpenVINOExecutionProvider - Spuštění Technologie Intel OpenVINO
  • NvTensorRTRTXExecutionProvider – Zpracování pomocí NVIDIA TensorRT
  • VitisAIExecutionProvider - AMD Vitis AI spouštění

task – typ úlohy modelu

Filtruje modely podle zamýšleného případu použití nebo úkolu.

Common values:

  • chat-completion: Konverzační modely AI
  • text-generation: Modely generování textu

alias – Modelový alias

Filtruje modely podle jejich identifikátoru aliasu. Podporuje porovnávání pomocí zástupných znaků s příponou *.

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

Speciální funkce filtru

Podpora negace: Předpona jakékoli hodnoty s vyloučením ! odpovídajících modelů.

foundry model list --filter device=!GPU

Tento příkaz z výsledků vyloučí modely GPU.

Referenční informace: Speciální funkce filtru

Porovnávání zástupných znaků (pouze alias): Při filtrování podle aliasu připojte * k předponám pro shodu.

foundry model list --filter alias=qwen*

Tento příkaz vrátí modely, jejichž alias začíná qwen.

Referenční informace: Speciální funkce filtru

Examples

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

Tyto příklady filtrují seznam modelů podle zařízení, úlohy a poskytovatele spouštění.

Referenční informace: Filtrování seznamu modelů

Note

  • Všechna porovnání nerozlišují malá a velká písmena.
  • Pro každý příkaz lze použít pouze jeden filtr.
  • Nerozpoznané klíče filtru způsobí chybu.

Interaktivní spuštění modelu

Spusťte model a interagujte s ním přímo v terminálu:

foundry model run qwen2.5-0.5b

Foundry Local stáhne model při prvním spuštění a pak spustí interaktivní relaci. Zadejte výzvu k získání odpovědi:

Why is the sky blue?

Snímek obrazovky s výstupem příkazu Foundry Local Run

Tip

Nahraďte qwen2.5-0.5b libovolným aliasem modelu z katalogu. Spuštěním foundry model list zobrazíte dostupné modely. Foundry Local stáhne variantu, která nejlépe odpovídá vašemu hardwaru – například varianta CUDA pro GRAFICKÉ procesory NVIDIA nebo varianta NPU pro NpU Typu NpU.

Service commands

Následující tabulka shrnuje příkazy související se správou a spuštěním místní služby Foundry:

Command Description
foundry service --help Zobrazí všechny dostupné příkazy související se službami a jejich použití.
foundry service start Spustí službu „Foundry Local“.
foundry service stop Zastaví službu Foundry Local.
foundry service restart Restartuje službu Foundry Local.
foundry service status Zobrazí aktuální stav místní služby Foundry.
foundry service ps Zobrazí seznam všech modelů aktuálně načtených ve službě Foundry Local.
foundry service diag Zobrazí protokoly místní služby Foundry.
foundry service set <options> Nastaví konfiguraci místní služby Foundry.

Cache commands

Následující tabulka shrnuje příkazy pro správu místní mezipaměti, ve které jsou uložené modely:

Command Description
foundry cache --help Zobrazí všechny dostupné příkazy související s mezipamětí a jejich použití.
foundry cache location Zobrazuje aktuální adresář mezipaměti.
foundry cache list Zobrazí seznam všech modelů uložených v místní mezipaměti.
foundry cache cd <path> Změní adresář mezipaměti na zadanou cestu.
foundry cache remove <model> Odebere model z místní mezipaměti.

Execution providers

Poskytovatelé spouštění jsou hardwarově specifické akcelerační knihovny, které na vašem zařízení spouštějí modely nejefektivnějším možným způsobem.

Předdefinované zprostředkovatelé spouštění

Foundry Local zahrnuje zprostředkovatele spouštění procesoru, poskytovatele spuštění WebGPU a poskytovatele provádění CUDA.

Poskytovatel spouštění procesoru používá Microsoft Lineární podprogramy Algebra (MLAS) ke spuštění na libovolném procesoru a je náhradním procesorem pro Foundry Local.

Zprostředkovatel spouštění WebGPU používá Dawn, nativní implementaci webového rozhraní API pro akceleraci libovolného GPU a je náhradním gpu pro Foundry Local.

Zprostředkovatel provádění CUDA používá NVIDIA CUDA pro akceleraci grafických procesorů NVIDIA. Vyžaduje řadu NVIDIA GeForce RTX 30 a novější s minimální doporučenou verzí ovladače 32.0.15.5585 a CUDA verze 12.5. Podléhá následujícím licenčním podmínkám: Licenční smlouva pro NVIDIA Software Development Kits – EULA.

Poskytovatelé spouštění modulů plug-in

Poskytovatelé spouštění uvedené v následující tabulce jsou k dispozici pro dynamické stahování a registraci v Windows v závislosti na kompatibilitě zařízení a ovladačů. Podléhají zadaným licenčním podmínkám.

Foundry Local automaticky stáhne tyto zprostředkovatele spouštění při prvním spuštění. Poskytovatelé spouštění modulů plug-in se automaticky aktualizují, když jsou k dispozici nové verze.

Name (Vendor) Requirements License terms
NvTensorRTRTXExecutionProvider (NVIDIA) NVIDIA GeForce RTX 30XX a novější verze s minimální doporučenou verzí ovladače 32.0.15.5585 a CUDA verze 12.5 Licenční smlouva pro sady NVIDIA Software Development Kits – EULA
OpenVINOExecutionProvider (Intel) PROCESOR: Intel TigerLake (11. generace) a novější verze s minimálním doporučeným ovladačem 32.0.100.9565
GPU: Intel AlderLake (12. generace) a novější verze s minimálním doporučeným ovladačem 32.0.101.1029
NPU: Intel ArrowLake (15. generace) a novější verze s minimálním doporučeným ovladačem 32.0.100.4239		 Licenční smlouva s komerčním využitím distribuce Intel OBL v2025.02.12
QNNExecutionProvider (Roku 2019) Snapdragon(R) X Elite - X1Exxxxx - Qualcomm(R) Hexagon(TM) NPU s minimální verzí ovladače 30.0.140.0 a novějšími verzemi
Snapdragon(R) X Plus - X1Pxxxxx - Qualcomm(R) Hexagon(TM) NPU s minimální verzí ovladače 30.0.140.0 a dalšími verzemi.		 Pokud chcete zobrazit licenci QNN, stáhněte si Qualcomm® Neural Processing SDK, extrahujte soubor ZIP a otevřete soubor LICENSE.pdf.
VitisAIExecutionProvider (AMD) Min: Adrenalin Edition 25.6.3 s ovladačem NPU 32.00.0203.280
Max: Adrenalin Edition 25.9.1 s ovladačem NPU 32.00.0203.297		 Nevyžaduje se žádná další licence.

Použití Open WebUI s místním serverem

Připojte Open WebUI k Foundry Local pro rozhraní chatu založeného na prohlížeči, které běží zcela na vašem zařízení.

  1. Spusťte model a nechte terminál otevřený:

    foundry model run qwen2.5-0.5b

  2. Získejte adresu URL místního koncového bodu:

    foundry service status

    Zkopírujte adresu URL koncového bodu. Foundry Local při každém spuštění služby přiřadí dynamický port.

  3. Nainstalujte a spusťte Open WebUI a otevřete ho http://localhost:8080 v prohlížeči.

  4. Připojit Open WebUI k Foundry Local:

    1. Přejděte na>Připojení> a povolte přímá připojení.
    2. Přejděte na Nastavení>Připojení>Spravovat přímá připojení a vyberte +.
    3. Nastavte adresu URL na http://localhost:PORT/v1 (nahraďte PORT portem z kroku 2) a ověřováním na Hodnotu None.
    4. Select Save.

  5. V rozevíracím seznamu vyberte model a začněte chatovat.

Tip

Pokud se nezobrazí žádné modely, spusťte foundry model run <model> v terminálu a znovu načtěte Open WebUI. Pokud se připojení nezdaří, potvrďte port pomocí foundry service status.

Upgrade systému Foundry na místní úrovni

Spuštěním příkazu pro váš operační systém upgradujte Foundry Local.

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

Odinstalujte Foundry Local

Spuštěním příkazu pro váš operační systém odinstalujte Foundry Local.

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

Troubleshooting

Problémy s připojením ke službě

Pokud se při spuštění příkazu zobrazí tato chyba, například 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'.

Zrestartujte službu:

foundry service restart

Tento příkaz opravuje případy, kdy se služba spouští, ale není přístupná kvůli problému s vazbou portu.

Další pokyny k řešení potíží najdete v tématu Osvědčené postupy a řešení potíží.

  • Last updated on