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

Important

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

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

Необходимые условия

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

Установка Foundry Local

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

  • Windows: откройте терминал и выполните следующую команду:

    winget install Microsoft.FoundryLocal

  • macOS Apple Silicon: откройте терминал и запустите:

    brew tap microsoft/foundrylocal
brew install foundrylocal

    Кроме того, скачайте текущий macOS .pkg или .zip из ресурсов выпуска Local CLI Foundry. Если скачать файл .pkg, откройте его с помощью установщика macOS.

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

foundry --version

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

Tip

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

Быстрая проверка

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

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

    foundry --help

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

    Справочник. Обзор

  2. Проверьте состояние сервера:

    foundry server status

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

    Справочник. Команды сервера

Обзор

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

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

  • Модель: model, cache
  • Запуск: run, , chatcompletetranscribe
  • Сервер: server
  • Настройка: config
  • Справка: status, report

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

Command Description
foundry model Обнаруживает, проверяет, загружает, загружает и выгружает локальные модели.
foundry chat <model> Запускает интерактивный сеанс локального чата.
foundry complete <model> <prompt> Создает одно завершение текста без отслеживания состояния.
foundry run <model> Запускает модель с автоматической маршрутизацией в чат или транскрибирование.
foundry server Запускает, останавливает, перезапускает, проверяет и устраняет неполадки локальной управляющей программы Foundry.
foundry cache Проверяет и управляет скачанными записями кэша моделей.
foundry config Просмотры и изменение параметров постоянного интерфейса командной строки Foundry.
foundry status Отображает системную, серверную, модель и диагностику подключения.
foundry report Открывает предварительно заполненную GitHub проблему с диагностикой.
foundry transcribe Запускает интерактивный сеанс транскрибирования речи или расшифровывает файл.

Команды модели

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

Note

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

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

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

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

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

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

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

Используйте явные параметры для foundry model list сужения или расширения результатов.

Note

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

Вариант Description
--device <kind> Фильтрует модели по типу устройства: cpu, gpuили npu.
--type <task> Фильтрует модели по задачам: chat, speechили embedding.
--search <query> Фильтрует модели по запросу поиска.
--cached Фильтрует список для кэшированных моделей.
--loaded Фильтрует список для загруженных моделей.
--variants Включает варианты модели в список.
--limit <n> Ограничивает количество строк в выходных данных.
-v, --verbose Включает столбцы лицензий, отображаемого имени и идентификатора модели.

Примеры

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

Эти примеры фильтруют или развертывают список моделей с помощью поддерживаемых параметров.

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

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

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

foundry chat qwen2.5-0.5b

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

Why is the sky blue?

Tip

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

Команды сервера.

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

Command Description
foundry server --help Отображает все доступные команды, связанные с сервером, и их использование.
foundry server start Запускает локальную управляющей программу Foundry и локальную службу, совместимую с OpenAI.
foundry server start --port <port> Запускает локальную службу на указанном TCP-порту. Используется 0 для порта, назначаемого ОС.
foundry server start --idle-timeout <minutes> Останавливает управляющая программа после указанного числа неактивных минут. Используется 0 для поддержания работы управляющей программы.
foundry server stop Останавливает управляющая программа Foundry Local.
foundry server restart Перезапуск управляющей программы Foundry Local и локальной службы.
foundry server restart --port <port> --idle-timeout 0 Перезапускает локальную службу на указанном TCP-порту и сохраняет управляющую программу.
foundry server status Отображает состояние управляющей программы, URL-адреса локальной службы, идентификатор процесса, время ожидания и расположение журнала.
foundry server logs Отображает журналы управляющей программы Foundry Local и SDK.

Параметры журналов сервера

Используйте следующие параметры со foundry server logsследующими параметрами:

Вариант Description
-n, --lines <n> Показывает указанное число последних строк журнала. Значение по умолчанию — 50.
-f, --follow Потоковая передача новых строк журнала по мере их добавления.

Локальный сервер с фиксированным портом

Чтобы запустить локальную службу на фиксированном порту и сохранить управляющую программу, используйте --port следующую команду:--idle-timeout 0

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

Если управляющая программа уже запущена и необходимо применить новый порт, перезапустите его с теми же параметрами:

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

Чтобы проверить URL-адрес локальной конечной точки, выполните следующую команду:

foundry server status

Команды кэша

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

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

Используется foundry cache remove <model> --force для удаления кэшированных моделей без подтверждения.

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

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

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

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 автоматически загружает эти поставщики выполнения при первом запуске. Провайдеры выполнения плагинов автоматически обновляются при появлении новых версий.

Имя (поставщик) Требования Условия лицензии
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 run qwen2.5-0.5b

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

    foundry server 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. Нажмите Сохранить.

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

Tip

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

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

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

  • Windows:

    winget upgrade --id Microsoft.FoundryLocal

  • macOS Apple Silicon: если вы обновляете из Foundry Local 0.8.x, остановите старую службу перед обновлением:

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

    Если вы уже находитесь в текущей предварительной версии CLI, выполните следующую команду:

    brew update
brew upgrade microsoft/foundrylocal/foundrylocal

Удаление Foundry Local

Чтобы удалить Foundry Local в Windows, выполните следующую команду:

winget uninstall Microsoft.FoundryLocal

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

Перезапустите сервер:

foundry server restart

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

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

  • Last updated on