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

Důležité

  • 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 místní server a udržovat místní mezipaměť.

Předpoklady

  • 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ů nebo instalačního programu pro váš operační systém.

  • Windows: Otevřete terminál a spusťte:

    winget install Microsoft.FoundryLocal

  • macOS Apple Silicon: Otevřete terminál a spusťte:

    brew tap microsoft/foundrylocal
brew install foundrylocal

    Případně si můžete stáhnout aktuální macOS .pkg nebo .zip z prostředků vydané verze Foundry Local CLI. Pokud si soubor stáhnete, otevřete ho pomocí instalačního .pkgprogramu pro macOS.

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í k serveru (například Request to local service failed), spusťte foundry server restart.

Rychlé ověření

Spuštěním těchto příkazů potvrďte, že je rozhraní příkazového řádku nainstalované a místní server 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ů.

    Referenční informace: Přehled

  2. Zkontrolujte stav serveru:

    foundry server status

    Tento příkaz vytiskne, jestli je spuštěný místní démon Foundry a obsahuje jeho místní koncový bod.

    Referenční informace: Příkazy serveru

Přehled

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

Rozhraní příkazového řádku uspořádá příkazy do následujících skupin:

  • Model: model, cache
  • Spustit: run, chat, complete, transcribe
  • Server: server
  • Nastavení: config
  • Nápověda: status, report

Následující tabulka shrnuje příkazy nejvyšší úrovně:

Command Description
foundry model Zjišťuje, kontroluje, stahuje, načítá a odčítá místní modely.
foundry chat <model> Spustí interaktivní místní chatovací relaci.
foundry complete <model> <prompt> Vygeneruje jedno bezstavové dokončování textu.
foundry run <model> Spustí model s automatickým směrováním do chatu nebo přepisu.
foundry server Spustí, zastaví, restartuje, zkontroluje a vyřeší místní démon Foundry.
foundry cache Kontroluje a spravuje stažené položky mezipaměti modelu.
foundry config Zobrazení a úpravy trvalých nastavení rozhraní příkazového řádku Foundry
foundry status Zobrazuje diagnostiku systému, serveru, modelu a připojení.
foundry report Otevře předem vyplněný GitHub problém s diagnostikou.
foundry transcribe Spustí interaktivní relaci místního přepisu řeči nebo přepisuje soubor.

Příkazy modelu

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 chcete například spustit qwen2.5-0.5b procesor bez ohledu na dostupný hardware, použijte foundry 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 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 info <model> Zobrazí podrobné informace o konkrétním modelu.
foundry model download <model> Stáhne model do místní mezipaměti, aniž by ho spustil.
foundry model load <model> Načte model do místního démona.
foundry model unload <model> Uvolní model z místního démona.

Ř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ů

Pomocí explicitních možností foundry model list můžete výsledky zúžit nebo rozbalit.

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ů.

Možnost Description
--device <kind> Filtruje modely podle typu zařízení: cpu, gpunebo npu.
--type <task> Filtruje modely podle úkolu: chat, speechnebo embedding.
--search <query> Filtruje modely podle vyhledávacího dotazu.
--cached Filtruje seznam na modely uložené v mezipaměti.
--loaded Filtruje seznam na načtené modely.
--variants Zahrnuje varianty modelu v seznamu.
--limit <n> Omezí počet řádků ve výstupu.
-v, --verbose Zahrnuje sloupce Licence, Zobrazovaný název a ID modelu.

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

Tyto příklady filtrují nebo rozbalují seznam modelů pomocí podporovaných možností.

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

Interaktivní spuštění modelu

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

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

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.

Příkazy serveru

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

Command Description
foundry server --help Zobrazí všechny dostupné příkazy související se serverem a jejich použití.
foundry server start Spustí Místní démon Foundry a místní službu kompatibilní s OpenAI.
foundry server start --port <port> Spustí místní službu na zadaném portu TCP. Slouží 0 pro port přiřazený operačním systémem.
foundry server start --idle-timeout <minutes> Zastaví démona po zadaném počtu neaktivních minut. Slouží 0 k udržování procesu démona spuštěného.
foundry server stop Zastaví místní démon Foundry.
foundry server restart Restartuje místní démon Foundry a místní službu.
foundry server restart --port <port> --idle-timeout 0 Restartuje místní službu na zadaném portu TCP a udržuje proces démon spuštěný.
foundry server status Zobrazí stav démona, adresy URL místní služby, ID procesu, dobu provozu a umístění protokolu.
foundry server logs Zobrazí protokoly místního démona Foundry a sady SDK.

Možnosti protokolů serveru

Použijte tyto možnosti s foundry server logs:

Možnost Description
-n, --lines <n> Zobrazuje zadaný počet posledních řádků protokolu. Výchozí hodnota je 50.
-f, --follow Streamuje nové řádky protokolu při jejich připojení.

Místní server s pevným portem

Pokud chcete spustit místní službu na pevném portu a ponechat proces démon spuštěný, použijte:--port--idle-timeout 0

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

Pokud už proces démon běží a potřebujete použít nový port, restartujte ho se stejnými možnostmi:

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

Pokud chcete ověřit adresu URL místního koncového bodu, spusťte:

foundry server status

Příkazy mezipaměti

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 uložený v mezipaměti. Pokud vynecháte <model>, příkaz po potvrzení odebere všechny modely uložené v mezipaměti.

Slouží foundry cache remove <model> --force k odebrání modelu v mezipaměti bez potvrzení.

Zprostředkovatelé spouštění

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.

Název (dodavatel) Požadavky Licenční podmínky
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 run qwen2.5-0.5b

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

    foundry server status

    Zkopírujte adresu URL koncového bodu. Foundry Local při každém spuštění serveru 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. Vyberte Uložit.

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

Tip

Pokud se nezobrazí žádné modely, spusťte foundry run <model> v terminálu a znovu načtěte Open WebUI. Pokud se připojení nezdaří, potvrďte port pomocí foundry server 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 Apple Silicon: Pokud upgradujete z Foundry Local 0.8.x, před upgradem zastavte starou službu:

    foundry service stop
brew update
brew upgrade microsoft/foundrylocal/foundrylocal

    Pokud už používáte aktuální rozhraní příkazového řádku preview, spusťte následující příkaz:

    brew update
brew upgrade microsoft/foundrylocal/foundrylocal

Odinstalujte Foundry Local

Pokud chcete odinstalovat Foundry Local v Windows, spusťte:

winget uninstall Microsoft.FoundryLocal

Troubleshooting

Problémy s připojením k serveru

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

Restartujte server:

foundry server restart

Tento příkaz opravuje případy, kdy se server 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