Referentie voor Foundry Local CLI

Belangrijk

  • Foundry Local CLI is beschikbaar in preview. Openbare preview-versies bieden vroege access aan functies die actief zijn geïmplementeerd.
  • Functies, benaderingen en processen kunnen worden gewijzigd of beperkte mogelijkheden hebben, voordat algemene beschikbaarheid (GA) wordt uitgevoerd.

Dit artikel bevat een uitgebreide naslaginformatie over de opdrachtregelinterface (CLI) van Foundry. De CLI organiseert opdrachten in logische categorieën om u te helpen bij het beheren van modellen, het beheren van de lokale server en het onderhouden van uw lokale cache.

Vereiste voorwaarden

  • Installeer Foundry Local.
  • Een lokale terminal waar de foundry CLI beschikbaar is.
  • Zorg ervoor dat u internettoegang hebt voor de eerste keer downloaden (uitvoeringsproviders en modellen).
  • Azure RBAC: Niet van toepassing (lokaal uitgevoerd).
  • Als u een Intel NPU op Windows hebt, installeert u het Intel NPU-stuurprogramma voor optimale NPU-versnelling.

Foundry Local installeren

Installeer Foundry Local met behulp van pakketbeheer voor uw besturingssysteem.

  • Windows: Open een terminal en voer het volgende uit:
    winget install Microsoft.FoundryLocal
  • macOS: Open een terminal en voer het volgende uit: 
    brew tap microsoft/foundrylocal
brew install foundrylocal
    U kunt ook het installatieprogramma downloaden uit de foundry-samples GitHub opslagplaats.

Controleer de installatie:

foundry --version

Zorg ervoor dat u beheerdersrechten hebt om software te installeren.

Tip

Als er een serviceverbindingsfout wordt weergegeven na de installatie (bijvoorbeeld Request to local service failed), voert u de opdracht uit foundry server restart.

Snelle verificatie

Voer deze opdrachten uit om te bevestigen dat de CLI is geïnstalleerd en de service bereikbaar is.

  1. CLI-help bekijken:

     foundry --help

    Met deze opdracht worden gebruiksgegevens en de lijst met beschikbare opdrachtgroepen afgedrukt.

    Naslaginformatie: Overzicht

  2. Controleer de serverstatus:

foundry-serverstatus '''

Met deze opdracht wordt afgedrukt of de Foundry Local-daemon wordt uitgevoerd en het lokale eindpunt bevat.

Naslaginformatie: Serveropdrachten

Overzicht

Gebruik de ingebouwde Help om opdrachten en opties te verkennen.

De CLI organiseert opdrachten in de volgende groepen:

  • Model: model, cache
  • Uitvoeren: run, chat, completetranscribe
  • Server: server
  • Installatie: config
  • Help: status, report

De volgende tabel bevat een overzicht van de opdrachten op het hoogste niveau:

Command Description
foundry model Detecteert, inspecteert, downloadt, laadt en laadt lokale modellen.
foundry chat <model> Start een interactieve lokale chatsessie.
foundry complete <model> <prompt> Hiermee wordt één staatloze tekst voltooid.
foundry run <model> Voert een model uit met automatische routering naar chat of transcriptie.
foundry server Start, stopt, start opnieuw, inspecteert en lost de lokale Foundry-daemon op.
foundry cache Hiermee worden gedownloade modelcachevermeldingen gecontroleerd en beheerd.
foundry config Weergaven en bewerkingen van permanente Foundry CLI-instellingen.
foundry status Geeft systeem-, service-, model- en connectiviteitsdiagnose weer.
foundry report Hiermee opent u een vooraf ingevuld GitHub probleem met diagnostische gegevens.
foundry transcribe Start een interactieve lokale spraaktranscriptiesessie of transcribeert een bestand.

Modelopdrachten

De volgende tabel bevat een overzicht van de opdrachten met betrekking tot het beheren en uitvoeren van modellen:

Note

U kunt het argument opgeven op basis van de modelalias of model-id. Een alias gebruiken:

  • Hiermee selecteert u automatisch het beste model voor uw beschikbare hardware. Als u bijvoorbeeld een Nvidia GPU hebt, selecteert Foundry Local het beste GPU-model. Als er een ondersteunde NPU beschikbaar is, selecteert Foundry Local het NPU-model.
  • Hiermee kunt u een kortere naam gebruiken zonder dat u de model-id hoeft te onthouden.

Als u een specifiek model wilt uitvoeren, gebruikt u de model-id. Als u bijvoorbeeld de qwen2.5-0.5b CPU wilt uitvoeren, ongeacht uw beschikbare hardware, gebruikt foundry run qwen2.5-0.5b-instruct-generic-cpuu .

Command Description
foundry model --help Geeft alle beschikbare modelgerelateerde opdrachten en het bijbehorende gebruik weer.
foundry model list Geeft een lijst weer van alle beschikbare modellen voor lokaal gebruik. Bij de eerste uitvoering worden uitvoeringsproviders (EPs) voor uw hardware gedownload.
foundry model info <model> Geeft gedetailleerde informatie weer over een specifiek model.
foundry model download <model> Hiermee downloadt u een model naar de lokale cache zonder het uit te voeren.
foundry model load <model> Laadt een model in de service.
foundry model unload <model> Hiermee wordt een model uit de service verwijderd.

Volgorde van modellijst

Wanneer er meerdere model-id-varianten beschikbaar zijn voor een alias, worden in de lijst met modellen de modellen in prioriteitsvolgorde weergegeven. Het eerste model in de lijst is het model dat wordt uitgevoerd wanneer u het model opgeeft door alias.

Filteren van modellijst

Gebruik de expliciete opties om foundry model list de resultaten te beperken of uit te vouwen.

Note

Wanneer u voor het eerst na de installatie uitvoert foundry model list , downloadt Foundry Local automatisch de relevante uitvoeringsproviders (EPs) voor de hardwareconfiguratie van uw computer. U ziet een voortgangsbalk die aangeeft dat de download is voltooid voordat de modellijst wordt weergegeven.

Optie Description
--device <device> Filtert modellen op apparaat.
--type <type> Filtert modellen op type.
--search <query> Filtert modellen op een zoekquery.
--cached Hiermee filtert u de lijst naar modellen in de cache.
--loaded Hiermee filtert u de lijst op geladen modellen.
--variants Bevat modelvarianten in de lijst.

Voorbeelden

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

In deze voorbeelden wordt de modellijst gefilterd of uitgebreid met behulp van de ondersteunde opties.

Referentie: Modellijsten filteren

Een model interactief uitvoeren

Voer een model uit en communiceer er rechtstreeks mee in de terminal:

foundry chat qwen2.5-0.5b

Foundry Local downloadt het model bij de eerste uitvoering en start vervolgens een interactieve sessie. Voer een prompt in om een antwoord te krijgen:

Why is the sky blue?

Tip

Vervang qwen2.5-0.5b door een modelalias uit de catalogus. Uitvoeren foundry model list om beschikbare modellen weer te geven. Foundry Local downloadt de variant die het beste overeenkomt met uw hardware, bijvoorbeeld een CUDA-variant voor NVIDIA GPU's of een NPU-variant voor Azure NPUs.

Serveropdrachten

De volgende tabel bevat een overzicht van de opdrachten die betrekking hebben op het beheren en uitvoeren van de Foundry Local-service:

Command Description
foundry server --help Geeft alle beschikbare servergerelateerde opdrachten en het bijbehorende gebruik weer.
foundry server start Hiermee start u de lokale daemon van Foundry en openAI-compatibele lokale service.
foundry server start --port <port> Hiermee start u de lokale service op de opgegeven TCP-poort. Gebruiken 0 voor een poort die is toegewezen aan het besturingssysteem.
foundry server start --idle-timeout <minutes> Stopt de daemon na het opgegeven aantal inactieve minuten. Gebruik 0 deze om de daemon actief te houden.
foundry server stop Stopt de Lokale daemon van Foundry.
foundry server restart Start de Foundry Local-daemon en de lokale service opnieuw.
foundry server restart --port <port> --idle-timeout 0 Start de lokale service opnieuw op de opgegeven TCP-poort en houdt de daemon actief.
foundry server status Geeft de daemonstatus, url's van de lokale service, proces-id, uptime en logboeklocatie weer.
foundry server logs Hiermee worden de lokale daemon- en SDK-logboeken van Foundry weergegeven.

Lokale server met vaste poort

Als u de lokale service op een vaste poort wilt starten en de daemon actief wilt houden, gebruikt u het volgende --port--idle-timeout 0:

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

Als de daemon al wordt uitgevoerd en u een nieuwe poort wilt toepassen, start u deze opnieuw met dezelfde opties:

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

Voer de volgende opdracht uit om de URL van het lokale eindpunt te controleren:

foundry server status

Cacheopdrachten

De volgende tabel bevat een overzicht van de opdrachten voor het beheren van de lokale cache waarin modellen worden opgeslagen:

Command Description
foundry cache --help Toont alle beschikbare opdrachten die betrekking hebben op de cache en het bijbehorende gebruik.
foundry cache location Toont de huidige cachemap.
foundry cache list Geeft een lijst weer van alle modellen die zijn opgeslagen in de lokale cache.
foundry cache cd <path> Wijzigt de cachemap naar het opgegeven pad.
foundry cache remove <model> Hiermee verwijdert u een model uit de lokale cache.

Uitvoeringsproviders

Uitvoeringsproviders zijn hardwarespecifieke versnellingsbibliotheken die modellen zo efficiënt mogelijk op uw apparaat uitvoeren.

Ingebouwde uitvoeringsproviders

Foundry Local bevat de CPU-uitvoeringsprovider, de WebGPU-uitvoeringsprovider en de CUDA-uitvoeringsprovider.

De CPU-uitvoeringsprovider maakt gebruik van Microsoft Linear Algebra Subroutines (MLAS) om te worden uitgevoerd op elke CPU en is de CPU-terugval voor Foundry Local.

De WebGPU-uitvoeringsprovider maakt gebruik van Dawn, de systeemeigen implementatie van de web-API, voor versnelling op elke GPU en is de GPU-terugval voor Foundry Local.

De CUDA-uitvoeringsprovider gebruikt NVIDIA CUDA voor versnelling op NVIDIA GPU's. Het vereist een NVIDIA GeForce RTX 30-serie en hoger met minimaal aanbevolen stuurprogrammaversie 32.0.15.5585 en CUDA versie 12.5. Het is onderhevig aan de volgende licentievoorwaarden: Licentieovereenkomst voor NVIDIA Software Development Kits- EULA.

Providers voor het uitvoeren van invoegtoepassingen

De uitvoeringsproviders die in de volgende tabel worden vermeld, zijn beschikbaar voor dynamische download en registratie op Windows, afhankelijk van de compatibiliteit van apparaten en stuurprogramma's. Ze zijn onderworpen aan de opgegeven licentievoorwaarden.

Foundry Local downloadt deze uitvoeringsproviders automatisch bij de eerste uitvoering. De uitvoeringsproviders van de plug-in worden automatisch bijgewerkt wanneer er nieuwe versies beschikbaar zijn.

Naam (leverancier) Requirements Licentievoorwaarden
NvTensorRTRTXExecutionProvider (NVIDIA) NVIDIA GeForce RTX 30XX en latere versies met minimaal aanbevolen stuurprogrammaversie 32.0.15.5585 en CUDA versie 12.5 Gebruiksrechtovereenkomst voor NVIDIA Software Development Kits - GEBRUIKSRECHTOVEREENKOMST
OpenVINOExecutionProvider (Inlichtingen) CPU: Intel TigerLake (11e generatie) en latere versies met minimaal aanbevolen stuurprogramma 32.0.100.9565
GPU: Intel AlderLake (12e generatie) en latere versies met minimaal aanbevolen stuurprogramma 32.0.101.1029
NPU: Intel ArrowLake (15e generatie) en latere versies met minimaal aanbevolen stuurprogramma 32.0.100.4239		 Gebruiksrechtovereenkomst voor Intel OBL-distributie v2025.02.12
QNNExecutionProvider (Servicem) Snapdragon(R) X Elite - X1Exxxxx - Qualcomm(R) Hexagon(TM) NPU met minimale stuurprogrammaversie 30.0.140.0 of nieuwer
Snapdragon(R) X Plus - X1Pxxxxx - Qualcomm(R) Hexagon(TM) NPU met minimale driver-versie 30.0.140.0 en latere versies		 Als u de QNN-licentie wilt bekijken, downloadt u de Qualcomm® Neural Processing SDK, pakt u het ZIP-bestand uit en opent u de LICENSE.pdf.
VitisAIExecutionProvider (AMD) Min: Adrenalin Edition 25.6.3 met NPU-stuurprogramma 32.00.0203.280
Max: Adrenalin Edition 25.9.1 met NPU-stuurprogramma 32.00.0203.297		 Er is geen extra licentie vereist

Open WebUI gebruiken met de lokale server

Verbind Open WebUI met Foundry Local voor een browsergebaseerde chatinterface die volledig op uw apparaat wordt uitgevoerd.

  1. Start een model en laat de terminal open:

foundry run qwen2.5-0.5b


1. Get your local endpoint URL:

```bash
foundry server status

Kopieer de eindpunt-URL. Foundry Local wijst telkens wanneer de service wordt gestart een dynamische poort toe.

  1. Installeer en start Open WebUI en open http://localhost:8080 vervolgens in uw browser.

  2. Open WebUI verbinden met Foundry Local:

    1. Ga naar>Instellingenbeheerdersverbindingen> en schakel directe verbindingen in.
    2. Ga naar Instellingenverbindingen>>Directe verbindingen beheren en selecteer +.
    3. Stel de URL in op http://localhost:PORT/v1 (vervang door PORT de poort uit stap 2) en verificatie op Geen.
    4. Kies Opslaan.

  3. Selecteer een model in de vervolgkeuzelijst en begin te chatten.

Tip

Als er geen modellen worden weergegeven, voert u deze uit foundry run <model> in een terminal en laadt u Open WebUI opnieuw. Als de verbinding mislukt, bevestigt u de poort met foundry server status.

Lokaal upgraden van Foundry

Voer de opdracht voor uw besturingssysteem uit om Foundry Local te upgraden.

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

Foundry Lokaal verwijderen

Voer de opdracht voor uw besturingssysteem uit om Foundry Local te verwijderen.

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

Troubleshooting

Problemen met de serviceverbinding

Als u deze fout ziet wanneer u een opdracht uitvoert, zoals 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 server status'.

Start de service opnieuw:

foundry server restart

Met deze opdracht worden gevallen opgelost waarin de server wordt uitgevoerd, maar niet toegankelijk is vanwege een poortbindingsprobleem.

Zie Best practices en probleemoplossing voor meer richtlijnen voor probleemoplossing.

  • Last updated on