Foundry CLI Local - odniesienie

Ważna

• Lokalny interfejs wiersza polecenia usługi Foundry jest dostępny w wersji zapoznawczej. Publiczne wersje zapoznawcze udostępniają wczesny dostęp do funkcji, które są w trakcie aktywnego wdrażania.
• Funkcje, podejścia i procesy mogą ulec zmianie lub mieć ograniczone możliwości przed ogólną dostępnością.

Ten artykuł zawiera kompleksowe informacje dotyczące lokalnego interfejsu wiersza polecenia (CLI, Foundry Local). Interfejs wiersza polecenia organizuje polecenia w kategorie logiczne, aby ułatwić zarządzanie modelami, kontrolowanie serwera lokalnego i konserwowanie lokalnej pamięci podręcznej.

Wymagania wstępne

• Zainstaluj lokalnie program Foundry.
• Lokalny terminal, w którym foundry jest dostępny interfejs wiersza polecenia.
• Upewnij się, że masz dostęp do Internetu, aby pobrać po raz pierwszy (dostawców wykonania i modele).
• Azure kontroli dostępu opartej na rolach: nie dotyczy (działa lokalnie).
• Jeśli masz procesor NPU firmy Intel na Windows, zainstaluj sterownik Intel NPU aby uzyskać optymalne przyspieszenie NPU.

Instalowanie lokalnego rozwiązania Foundry

Zainstaluj program Foundry Local przy użyciu menedżera pakietów lub instalatora dla systemu operacyjnego.

• Windows: Otwórz terminal i uruchom polecenie:

  winget install Microsoft.FoundryLocal
  

• MacOS Apple Silicon: Otwórz terminal i uruchom polecenie:

  brew tap microsoft/foundrylocal
  brew install foundrylocal
  

  Alternatywnie pobierz bieżący system macOS .pkg lub .zip z zasobów lokalnego interfejsu wiersza polecenia usługi Foundry. Jeśli pobierzesz plik .pkg, otwórz go za pomocą Instalatora systemu macOS.

Zweryfikuj instalację:

foundry --version

Upewnij się, że masz uprawnienia administratora do instalowania oprogramowania.

Wskazówka

Jeśli po instalacji zostanie wyświetlony błąd połączenia serwera (na przykład Request to local service failed), uruchom polecenie foundry server restart.

Szybka weryfikacja

Uruchom te polecenia, aby potwierdzić, że interfejs wiersza polecenia jest zainstalowany, a serwer lokalny jest osiągalny.

1. Pokaż pomoc CLI (interfejsu wiersza polecenia):

   foundry --help
   

   To polecenie wyświetla informacje o użyciu i listę dostępnych grup poleceń.

   Dokumentacja: Omówienie

2. Sprawdź stan serwera:

   foundry server status
   

   To polecenie wyświetla, czy demon lokalny foundry jest uruchomiony i zawiera jego lokalny punkt końcowy.

   Dokumentacja: Polecenia serwera

Przegląd

Skorzystaj z wbudowanej pomocy, aby zapoznać się z poleceniami i opcjami.

Interfejs wiersza polecenia organizuje polecenia w następujących grupach:

• Model: model, cache
• Uruchamianie: run, , chat, completetranscribe
• Serwer: server
• Konfiguracja: config
• Pomoc: status, report

Poniższa tabela zawiera podsumowanie poleceń najwyższego poziomu:

Command	Opis
foundry model	Odnajduje, sprawdza, pobiera, ładuje i zwalnia lokalne modele.
foundry chat <model>	Uruchamia interaktywną sesję czatu lokalnego.
foundry complete <model> <prompt>	Generuje jedno bezstanowe uzupełnianie tekstu.
foundry run <model>	Uruchamia model z automatycznym routingiem do czatu lub transkrypcji.
foundry server	Uruchamia, zatrzymuje, uruchamia, uruchamia ponownie, sprawdza i rozwiązuje problemy z lokalnym demonem foundry.
foundry cache	Sprawdza pobrane wpisy pamięci podręcznej modelu i zarządza nimi.
foundry config	Wyświetla i edytuje trwałe ustawienia interfejsu wiersza polecenia usługi Foundry.
foundry status	Przedstawia diagnostykę systemu, serwera, modelu i łączności.
foundry report	Otwiera wstępnie wypełniony GitHub problem z diagnostyką.
foundry transcribe	Uruchamia interakcyjną sesję transkrypcji mowy lokalnej lub transkrybuje plik.

Polecenia modelu

Poniższa tabela zawiera podsumowanie poleceń związanych z zarządzaniem i uruchamianiem modeli:

Note

Możesz określić argument przy użyciu model lub identyfikatora modelu. Używanie aliasu:

• Wybiera najlepszy model dla dostępnego sprzętu automatycznie. Jeśli na przykład masz dostępny procesor GPU firmy Nvidia, narzędzie Foundry Local wybiera najlepszy model procesora GPU. Jeśli masz dostępną obsługiwaną jednostkę NPU, funkcja Foundry Local wybiera model NPU.
• Umożliwia użycie krótszej nazwy bez konieczności zapamiętania identyfikatora modelu.

Jeśli chcesz uruchomić określony model, użyj identyfikatora modelu. Aby na przykład uruchomić qwen2.5-0.5b procesor cpu, niezależnie od dostępnego sprzętu, użyj polecenia foundry run qwen2.5-0.5b-instruct-generic-cpu.

Command	Opis
foundry model --help	Wyświetla wszystkie dostępne polecenia związane z modelem i ich użycie.
foundry model list	Wyświetla listę wszystkich dostępnych modeli do użytku lokalnego. Przy pierwszym uruchomieniu pobiera dostawców uruchamiania (EP) dla sprzętu.
foundry model info <model>	Wyświetla szczegółowe informacje o określonym modelu.
foundry model download <model>	Pobiera model do lokalnej pamięci podręcznej bez jego uruchamiania.
foundry model load <model>	Ładuje model do lokalnego demona.
foundry model unload <model>	Zwalnia model z lokalnego demona.

Porządkowanie listy modeli

Jeśli dla aliasu jest dostępnych wiele wariantów identyfikatorów modelu, lista modeli jest wyświetlana w kolejności priorytetów. Pierwszy model na liście to model uruchamiany podczas określania modelu za pomocą polecenia alias.

Filtrowanie listy modeli

Użyj jawnych opcji, foundry model list aby zawęzić lub rozwinąć wyniki.

Note

Podczas pierwszego uruchomienia foundry model list po instalacji, program Foundry Local automatycznie pobiera odpowiednich dostawców zasobów wykonawczych (EPs) dla konfiguracji sprzętowej maszyny. Zostanie wyświetlony pasek postępu wskazujący ukończenie pobierania przed wyświetleniem listy modeli.

Opcja	Opis
--device <kind>	Filtruje modele według rodzaju urządzenia: cpu, gpulub npu.
--type <task>	Filtruje modele według zadania: chat, speechlub embedding.
--search <query>	Filtruje modele według zapytania wyszukiwania.
--cached	Filtruje listę do buforowanych modeli.
--loaded	Filtruje listę do załadowanych modeli.
--variants	Zawiera warianty modelu na liście.
--limit <n>	Ogranicza liczbę wierszy w danych wyjściowych.
-v, --verbose	Zawiera kolumny License(Licencja), Display Name (Nazwa wyświetlana) i Model ID (Identyfikator modelu).

Przykłady

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

Te przykłady filtrują lub rozszerzają listę modeli przy użyciu obsługiwanych opcji.

Dokumentacja: Filtrowanie listy modeli

Interakcyjne uruchamianie modelu

Uruchamianie modelu i interakcja z nim bezpośrednio w terminalu:

foundry chat qwen2.5-0.5b

Usługa Foundry Local pobiera model przy pierwszym uruchomieniu, a następnie uruchamia sesję interaktywną. Wprowadź monit, aby uzyskać odpowiedź:

Why is the sky blue?

Wskazówka

Zastąp qwen2.5-0.5b ciąg dowolnym aliasem modelu z wykazu. Uruchom polecenie , foundry model list aby wyświetlić dostępne modele. Foundry Local pobiera wariant najlepiej pasujący do sprzętu — na przykład wariant CUDA dla procesorów GPU NVIDIA lub wariant NPU dla procesorów NPU Qualcomm.

Polecenia serwera

Poniższa tabela zawiera podsumowanie poleceń związanych z zarządzaniem i uruchamianiem serwera lokalnego usługi Foundry:

Command	Opis
foundry server --help	Wyświetla wszystkie dostępne polecenia związane z serwerem i ich użycie.
foundry server start	Uruchamia lokalny demon foundry i usługę lokalną zgodną z protokołem OpenAI.
foundry server start --port <port>	Uruchamia usługę lokalną na określonym porcie TCP. Służy 0 do portu przypisanego przez system operacyjny.
foundry server start --idle-timeout <minutes>	Zatrzymuje demona po określonej liczbie nieaktywnych minut. Użyj polecenia 0 , aby zachować działanie demona.
foundry server stop	Zatrzymuje demona lokalnego programu Foundry.
foundry server restart	Uruchamia ponownie demona lokalnego i lokalnego demona Foundry.
foundry server restart --port <port> --idle-timeout 0	Uruchamia ponownie usługę lokalną na określonym porcie TCP i utrzymuje demona uruchomionego.
foundry server status	Wyświetla stan demona, adresy URL usługi lokalnej, identyfikator procesu, czas pracy i lokalizację dziennika.
foundry server logs	Wyświetla dzienniki demona lokalnego programu Foundry i zestawu SDK.

Opcje dzienników serwera

Użyj tych opcji w programie foundry server logs:

Opcja	Opis
-n, --lines <n>	Pokazuje określoną liczbę ostatnich wierszy dziennika. Wartość domyślna to 50.
-f, --follow	Przesyła strumieniowo nowe wiersze dziennika podczas dołączania.

Serwer lokalny o stałym porcie

Aby uruchomić usługę lokalną na stałym porcie i zachować działanie demona, użyj polecenia z poleceniem --port--idle-timeout 0:

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

Jeśli demon jest już uruchomiony i musisz zastosować nowy port, uruchom go ponownie przy użyciu tych samych opcji:

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

Aby zweryfikować lokalny adres URL punktu końcowego, uruchom polecenie:

foundry server status

Komendy pamięci podręcznej

Poniższa tabela zawiera podsumowanie poleceń zarządzania lokalną pamięcią podręczną, w której są przechowywane modele:

Command	Opis
foundry cache --help	Pokazuje wszystkie dostępne komendy związane z pamięcią podręczną oraz ich użycie.
foundry cache location	Pokazuje bieżący katalog pamięci podręcznej.
foundry cache list	Wyświetla listę wszystkich modeli przechowywanych w lokalnej pamięci podręcznej.
foundry cache cd <path>	Zmienia katalog pamięci podręcznej na określoną ścieżkę.
foundry cache remove [<model>]	Usuwa buforowany model. <model>Jeśli pominięto polecenie , polecenie usuwa wszystkie buforowane modele po potwierdzeniu.

Użyj foundry cache remove <model> --force polecenia , aby usunąć buforowany model bez potwierdzenia.

Dostawcy realizacji

Dostawcy akceleracji to biblioteki przyspieszania specyficzne dla sprzętu, które uruchamiają modele tak wydajnie, jak to możliwe na Twoim urządzeniu.

Dostawcy wbudowanych usług wykonawczych

Foundry Local obejmuje moduł wykonawczy CPU, moduł wykonawczy WebGPU i moduł wykonawczy CUDA.

Dostawca wykonywania procesora CPU używa Microsoft Liniowa algebra subroutines (MLAS) do uruchamiania na dowolnym procesorze CPU i jest rezerwą procesora CPU dla lokalnego rozwiązania Foundry.

Dostawca wykonywania WebGPU używa Dawn, natywnej implementacji webowego interfejsu API, do przyspieszania na dowolnym GPU i jest zapasową opcją dla GPU w Foundry Local.

Dostawca wykonywania CUDA używa NVIDIA CUDA do przyspieszania obliczeń na procesorach GPU firmy NVIDIA. Wymaga to serii NVIDIA GeForce RTX 30 i nowszych z minimalną zalecaną wersją sterownika 32.0.15.5585 i CUDA w wersji 12.5. Podlega ona następującym postanowieniom licencyjnym: Umowa licencyjna dla zestawów NVIDIA Software Development Kit — EULA.

Dostawcy wykonywania wtyczek

Dostawcy wykonywania wymienioni w poniższej tabeli są dostępni do dynamicznego pobierania i rejestracji w Windows, w zależności od zgodności urządzeń i sterowników. Podlegają one określonym postanowieniom licencyjnym.

Usługa Foundry Local automatycznie pobiera tych dostawców wykonywania podczas pierwszego uruchomienia. Dostawcy wykonywania wtyczki są automatycznie aktualizowani, gdy są dostępne nowe wersje.

Nazwa (dostawca)	Wymagania	Warunki licencji
NvTensorRTRTXExecutionProvider (NVIDIA)	NVIDIA GeForce RTX 30XX i nowsze wersje z minimalną zalecaną wersją sterownika 32.0.15.5585 i CUDA w wersji 12.5	Umowa licencyjna dotycząca zestawów NVIDIA Software Development Kit — EULA
OpenVINOExecutionProvider (Intel)	Procesor CPU: Intel TigerLake (11. generacja) i nowsze wersje z minimalnym zalecanym sterownikiem 32.0.100.9565 Procesor GPU: Intel AlderLake (12. generacja) i nowsze wersje z minimalnym zalecanym sterownikiem 32.0.101.1029 NPU: Intel ArrowLake (15th Gen) i nowsze wersje z minimalnym zalecanym sterownikiem 32.0.100.4239	Umowa licencyjna na komercyjne wykorzystanie Intel OBL Distribution v2025.02.12
QNNExecutionProvider (Qualcomm)	Snapdragon(R) X Elite - X1Exxxxx - Qualcomm(R) Hexagon(TM) NPU z minimalną wersją sterownika 30.0.140.0 i nowszymi wersjami Snapdragon(R) X Plus - X1Pxxxxx - Qualcomm(R) Hexagon(TM) NPU z minimalną wersją sterownika 30.0.140.0 i nowszymi wersjami	Aby wyświetlić licencję QNN, pobierz zestaw SDK przetwarzania neuronowego Qualcomm®, wyodrębnij plik ZIP i otwórz plik LICENSE.pdf.
VitisAIExecutionProvider (AMD)	Min: Adrenalin Edition 25.6.3 ze sterownikiem NPU 32.00.0203.280 Max: Adrenalin Edition 25.9.1 ze sterownikiem NPU 32.00.0203.297	Brak wymaganej dodatkowej licencji

Używanie interfejsu Open WebUI z serwerem lokalnym

Połącz program Open WebUI z aplikacją Foundry Local w celu uzyskania interfejsu czatu opartego na przeglądarce, który działa w całości na urządzeniu.

1. Uruchom model i pozostaw otwarty terminal:

   foundry run qwen2.5-0.5b
   

2. Pobierz lokalny adres URL punktu końcowego:

   foundry server status
   

   Skopiuj adres URL punktu końcowego. Program Foundry Local przypisuje port dynamiczny przy każdym uruchomieniu serwera.

3. Zainstaluj i uruchom program Open WebUI, a następnie otwórz http://localhost:8080 go w przeglądarce.

4. Połącz program Open WebUI z usługą Foundry Local:

   1. Przejdź do pozycji Ustawienia>Połączenia ustawień> administratora i włącz połączenia bezpośrednie.
   2. Przejdź do pozycji Połączenia> ustawień >Zarządzaj połączeniami bezpośrednimi i wybierz pozycję +.
   3. Ustaw wartość Url na http://localhost:PORT/v1 (zastąp PORT portem z kroku 2) i Uwierzytelnianie na Wartość Brak.
   4. Wybierz opcję Zapisz.

5. Wybierz model z listy rozwijanej i rozpocznij rozmowę.

Wskazówka

Jeśli nie są wyświetlane żadne modele, uruchom polecenie foundry run <model> w terminalu i załaduj ponownie interfejs Open WebUI. Jeśli połączenie nie powiedzie się, potwierdź port za pomocą foundry server statuspolecenia .

Uaktualnij Foundry Local

Uruchom polecenie dla systemu operacyjnego, aby uaktualnić program Foundry Local.

• Windows:

  winget upgrade --id Microsoft.FoundryLocal
  

• macOS Apple Silicon: jeśli uaktualniasz program Foundry Local 0.8.x, zatrzymaj starą usługę przed uaktualnieniem:

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

  Jeśli korzystasz już z bieżącego interfejsu wiersza polecenia w wersji zapoznawczej, uruchom polecenie:

  brew update
  brew upgrade microsoft/foundrylocal/foundrylocal
  

Odinstaluj Foundry Local

Aby odinstalować program Foundry Local w Windows, uruchom polecenie:

winget uninstall Microsoft.FoundryLocal

Troubleshooting

Problemy z połączeniem serwera

Jeśli ten błąd zostanie wyświetlony podczas uruchamiania polecenia takiego jak 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'.

Uruchom ponownie serwer:

foundry server restart

To polecenie naprawia przypadki, w których serwer działa, ale nie jest dostępny z powodu problemu z powiązaniem portów.

Aby uzyskać więcej wskazówek dotyczących rozwiązywania problemów, zobacz Najlepsze rozwiązania i rozwiązywanie problemów.