Справочник локального интерфейса командной строки для Foundry

Important

  • Локальный интерфейс командной строки Foundry доступен в предварительной версии. Общедоступные предварительные версии предоставляют ранний доступ к функциям, которые находятся в процессе активного развертывания.
  • Функции, подходы и процессы могут изменяться или иметь ограниченные возможности до общедоступной доступности.

В этой статье содержится исчерпывающая справка по интерфейсу командной строки Foundry Local (CLI). Интерфейс командной строки упорядочивает команды в логические категории, помогая управлять моделями, управлять службой и поддерживать локальный кэш.

Prerequisites

  • Установите Foundry Local.
  • Локальный терминал, в котором доступен ИНТЕРФЕЙС командной foundry строки.
  • Убедитесь, что у вас есть доступ к интернету для первого скачивания (поставщики выполнения и модели).
  • Azure RBAC: неприменимо (выполняется локально).
  • Если у вас есть NPU Intel на Windows, установите драйвер NPU Intel NPU для оптимального ускорения NPU.

Установка Foundry Local

Установите Foundry Local с помощью диспетчера пакетов для операционной системы.

  • Windows: откройте терминал и выполните следующую команду:
    winget install Microsoft.FoundryLocal
  • macOS: откройте терминал и выполните следующую команду: 
    brew tap microsoft/foundrylocal
brew install foundrylocal
    Кроме того, скачайте установщик из репозитория Foundry Local GitHub.

Проверьте установку:

foundry --version

Убедитесь, что у вас есть права администратора на установку программного обеспечения.

Tip

Если после установки появится ошибка подключения к службе (например, Request to local service failed), выполните команду foundry service restart.

Quick verification

Выполните эти команды, чтобы подтвердить, что интерфейс командной строки установлен и служба доступна.

  1. Отобразить справку по CLI:

     foundry --help

    Эта команда выводит сведения об использовании и список доступных групп команд.

    Reference: Overview

  2. Проверьте состояние службы:

     foundry service status

    Эта команда выводит, запущена ли локальная служба Foundry и включает ее локальную конечную точку.

    Справочник. Команды службы

Overview

Используйте встроенную справку для изучения команд и параметров.

Интерфейс командной строки упорядочивает команды в три основные категории:

  • Модель: команды для управления и запуска моделей ИИ
  • Служба: команды для управления локальной службой Foundry
  • Cache: команды для управления локальным хранилищем моделей

Model commands

В следующей таблице приведены команды, связанные с управлением и выполнением моделей:

Note

Аргумент можно указать по model или идентификатору модели. Использование псевдонима:

  • Выбирает лучшую модель для доступного оборудования автоматически. Например, если у вас есть gpu Nvidia, Foundry Local выбирает лучшую модель GPU. Если у вас есть поддерживаемый NPU, Foundry Local выбирает модель NPU.
  • Позволяет использовать более короткое имя без необходимости запоминать идентификатор модели.

Если вы хотите запустить определенную модель, используйте идентификатор модели. Например, чтобы запустить qwen2.5-0.5b на процессоре, независимо от наличия другого оборудования, используйте: foundry model run qwen2.5-0.5b-instruct-generic-cpu.

Command Description
foundry model --help Отображает все доступные команды, связанные с моделью, и их использование.
foundry model run <model> Запускает указанную модель, скачивает ее, если она не кэшируется и запускает взаимодействие.
foundry model list Выводит список всех доступных моделей для локального использования. При первом запуске он загружает поставщиков исполнения (EP) для вашего оборудования.
foundry model list --filter <key>=<value> Перечисляет модели, отфильтрованные указанными критериями (устройство, задача, псевдоним, поставщик).
foundry model info <model> Отображает подробные сведения о конкретной модели.
foundry model info <model> --license Отображает сведения о лицензии для конкретной модели.
foundry model download <model> Загружает модель в локальный кэш без его запуска.
foundry model load <model> Загружает модель в службу.
foundry model unload <model> Выгружает модель из службы.

Сортировка списка моделей

Если для псевдонима доступно несколько вариантов идентификаторов модели, список моделей отображает модели в порядке приоритета. Первая модель в списке — это модель, которая выполняется, когда вы указываете модель с помощью alias.

Фильтрация списка моделей

Команда foundry model list поддерживает фильтрацию моделей с помощью --filter параметра. Модели можно фильтровать на основе одного атрибута с помощью пар "ключ-значение".

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

Эта команда выводит модели, соответствующие ключу фильтра и значению.

Справочник. Фильтрация списка моделей

Note

При первом запуске foundry model list после установки Foundry Local автоматически скачивает соответствующие поставщики выполнения (EPS) для конфигурации оборудования компьютера. Отображается индикатор хода выполнения, указывающий завершение загрузки перед отображением списка моделей.

Поддерживаемые ключи фильтра:

устройство — тип аппаратного устройства

Фильтрует модели по аппаратному устройству, на которое они работают.

Possible values:

  • CPU — модели центрального процессора
  • GPU — модели единиц обработки графики
  • NPU — модели единиц нейронной обработки

provider — поставщик выполнения

Фильтрует модели по поставщику выполнения или среде выполнения.

Possible values:

  • CPUExecutionProvider — выполнение на базе ЦПУ
  • CUDAExecutionProvider — выполнение GPU NVIDIA CUDA
  • WebGpuExecutionProvider — выполнение WebGPU
  • QNNExecutionProvider - Выполнение нейронной сети Qualcomm (NPU)
  • OpenVINOExecutionProvider — Выполнение Intel OpenVINO
  • NvTensorRTRTXExecutionProvider — выполнение NVIDIA TensorRT
  • VitisAIExecutionProvider — выполнение ИИ AMD Vitis

задача — тип задачи модели

Фильтрует модели по их предполагаемому варианту использования или задаче.

Common values:

  • chat-completion: модели общения с искусственным интеллектом
  • text-generation: модели создания текста

псевдоним — псевдоним модели

Фильтрует модели по идентификатору псевдонима. Включает поддержку сопоставления символов-заместителей с суффиксом *.

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

Специальные функции фильтра

Поддержка отрицания: Добавьте префикс к любому значению !, чтобы исключить соответствующие модели.

foundry model list --filter device=!GPU

Эта команда исключает модели GPU из результатов.

Справочник. Специальные функции фильтра

Сопоставление подстановочных знаков (только псевдоним): Добавьте * для сопоставления префиксов при фильтрации по псевдониму.

foundry model list --filter alias=qwen*

Эта команда возвращает модели, псевдоним которых начинается с qwen.

Справочник. Специальные функции фильтра

Examples

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

Эти примеры фильтруют список моделей по устройству, задаче и поставщику выполнения.

Справочник. Фильтрация списка моделей

Note

  • Все сравнения не учитывают регистр.
  • Для каждой команды можно использовать только один фильтр.
  • Нераспознанные ключи фильтров приводят к ошибке.

Интерактивное выполнение модели

Запустите модель и взаимодействуйте с ней непосредственно в терминале:

foundry model run qwen2.5-0.5b

Foundry Local загружает модель при первом запуске, а затем запускает интерактивный сеанс. Введите запрос, чтобы получить ответ:

Why is the sky blue?

Снимок экрана: выходные данные команды Foundry Local Run.

Tip

Замените qwen2.5-0.5b любым псевдонимом модели из каталога. Запустите foundry model list для просмотра доступных моделей. Foundry Local скачивает вариант, который лучше всего соответствует вашему оборудованию, например вариант CUDA для GPU NVIDIA или NPU для NPU для NPUs Qualcomm.

Service commands

В следующей таблице приведены команды, связанные с управлением и запуском локальной службы Foundry:

Command Description
foundry service --help Отображает все доступные команды, связанные со службой, и их использование.
foundry service start Запускает локальную службу Foundry.
foundry service stop Останавливает локальную службу Foundry.
foundry service restart Перезапуск локальной службы Foundry.
foundry service status Отображает текущее состояние локальной службы Foundry.
foundry service ps Выводит список всех моделей, загруженных в локальную службу Foundry.
foundry service diag Отображает журналы локальной службы Foundry.
foundry service set <options> Задает конфигурацию локальной службы Foundry.

Cache commands

В следующей таблице приведены команды для управления локальным кэшем, в котором хранятся модели:

Command Description
foundry cache --help Отображает все доступные команды, связанные с кэшем, и их использование.
foundry cache location Отображает текущий каталог кэша.
foundry cache list Выводит список всех моделей, хранящихся в локальном кэше.
foundry cache cd <path> Изменяет каталог кэша на указанный путь.
foundry cache remove <model> Удаляет модель из локального кэша.

Execution providers

Поставщики выполнения — это аппаратно-специфичные библиотеки ускорения, которые выполняют модели как можно эффективнее на вашем устройстве.

Встроенные поставщики выполнения

Foundry Local включает исполнителя процессора, исполнителя WebGPU и исполнителя CUDA.

Поставщик выполнения ЦП использует Microsoft Линейная algebra Subroutines (MLAS) для запуска на любом ЦП и является резервным вариантом ЦП для Foundry Local.

Поставщик выполнения WebGPU использует Dawn, собственную реализацию веб-API для ускорения на любом GPU и является резервным вариантом GPU для Foundry Local.

Поставщик выполнения CUDA использует NVIDIA CUDA для ускорения на GPU NVIDIA. Для этого требуется серия NVIDIA GeForce RTX 30 и более поздних версий с минимальным рекомендуемым драйвером версии 32.0.15.5585 и CUDA версии 12.5. Это действует в соответствии с условиями следующего лицензионного соглашения: Лицензионное соглашение для комплектов средств разработки программного обеспечения NVIDIA — EULA.

Поставщики выполнения подключаемого модуля

Поставщики выполнения, перечисленные в следующей таблице, доступны для динамического скачивания и регистрации в Windows в зависимости от совместимости устройств и драйверов. Они подчиняются указанным условиям лицензии.

Foundry Local автоматически загружает эти поставщики выполнения при первом запуске. Провайдеры выполнения плагинов автоматически обновляются при появлении новых версий.

Name (Vendor) Requirements License terms
NvTensorRTRTXExecutionProvider (NVIDIA) NVIDIA GeForce RTX 30XX и более поздних версий с минимальным рекомендуемым драйвером версии 32.0.15.5585 и CUDA версии 12.5 Лицензионное соглашение для комплектов средств разработки программного обеспечения NVIDIA — EULA
OpenVINOExecutionProvider (Разведка) ЦП: Intel TigerLake (11-го поколения) и более поздних версий с минимальным рекомендуемым драйвером 32.0.100.9565
GPU: Intel AlderLake (12-го поколения) и более поздние версии с минимальным рекомендуемым драйвером 32.0.101.1029
NPU: Intel ArrowLake 15-го поколения и более поздние версии с минимальным рекомендуемым драйвером 32.0.100.4239		 Лицензионное соглашение о коммерческом использовании дистрибутива Intel OBL версии 2025.02.12
QNNExecutionProvider (Qualcomm) Snapdragon(R) X Elite - X1Exxxxx - Qualcomm(R) Hexagon(TM) NPU с минимальной версией драйвера 30.0.140.0 и более поздними версиями
Snapdragon(R) X Plus - X1Pxxxxx - Qualcomm(R) Hexagon(TM) NPU с минимальной версией драйвера 30.0.140.0 и выше		 Чтобы просмотреть лицензию QNN, скачайте пакет SDK для Нейронной обработки Qualcomm®, извлеките ZIP-файл и откройте файл LICENSE.pdf.
VitisAIExecutionProvider (AMD) Min: Adrenalin Edition 25.6.3 с драйвером NPU 32.00.0203.280
Max: Adrenalin Edition 25.9.1 с драйвером NPU 32.00.0203.297		 Дополнительная лицензия не требуется

Использование Open WebUI с локальным сервером

Подключите Open WebUI к Foundry Local для интерфейса чата на основе браузера, который работает полностью на устройстве.

  1. Запустите модель и оставьте терминал открытым:

    foundry model run qwen2.5-0.5b

  2. Получите URL-адрес локальной конечной точки:

    foundry service status

    Скопируйте URL-адрес конечной точки. Foundry Local назначает динамический порт при каждом запуске службы.

  3. Установите и запустите Open WebUI, а затем откройте http://localhost:8080 в браузере.

  4. Подключение Open WebUI к Foundry Local:

    1. Перейдите в раздел "Параметры>администратора>" подключения и включите прямые подключения.
    2. Перейдите к разделу "Параметры>">"Управление прямыми подключениями" и выберите +пункт .
    3. Задайте ДЛЯ URL-адресаhttp://localhost:PORT/v1 (замените PORT порт на шаге 2) и запустите проверку подлинности в значение None.
    4. Select Save.

  5. Выберите модель из раскрывающегося списка и запустите чат.

Tip

Если модели не отображаются, запустите foundry model run <model> в терминале и перезагрузите Open WebUI. Если подключение завершается ошибкой, подтвердите порт с foundry service statusпомощью .

Обновление платформы локального уровня

Выполните команду для операционной системы, чтобы обновить Foundry Local.

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

Удаление Foundry Local

Выполните команду для операционной системы, чтобы удалить Foundry Local.

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

Troubleshooting

Проблемы с подключением к службе

Если при выполнении команды 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'.

Перезапустите службу :

foundry service restart

Эта команда исправляет случаи, когда служба выполняется, но недоступна из-за проблемы привязки портов.

Дополнительные рекомендации по устранению неполадок см. в рекомендациях и устранении неполадок.

  • Last updated on