Compartilhar via

Referência da CLI local do Foundry

Importante

  • A CLI local do Foundry está disponível na versão prévia. Versões de visualização pública fornecem acesso antecipado aos recursos que estão em desenvolvimento ativo.
  • Os recursos, abordagens e processos podem mudar ou ter seus recursos limitados antes da GA (disponibilidade geral).

Este artigo fornece uma referência abrangente para a CLI (interface de linha de comando) local do Foundry. A CLI organiza comandos em categorias lógicas para ajudá-lo a gerenciar modelos, controlar o serviço e manter o cache local.

Pré-requisitos

  • Instale Foundry Local.
  • Um terminal local onde a foundry CLI está disponível.
  • Verifique se você tem acesso à Internet para downloads pela primeira vez (provedores de execução e modelos).
  • Azure RBAC: não aplicável (é executado localmente).
  • Se você tiver uma NPU Intel no Windows, instale o driver Intel NPU para uma aceleração de NPU ideal.

Instalar o Foundry Local

Instale o Foundry Local usando o gerenciador de pacotes para seu sistema operacional.

  • Windows: abra um terminal e execute:
    winget install Microsoft.FoundryLocal
  • macOS: abra um terminal e execute: 
    brew tap microsoft/foundrylocal
brew install foundrylocal
    Como alternativa, baixe o instalador do repositório Foundry Local GitHub.

Verifique a instalação:

foundry --version

Verifique se você tem direitos de administrador para instalar o software.

Dica

Se você vir um erro de conexão de serviço após a instalação (por exemplo, Request to local service failed), execute foundry service restart.

Verificação rápida

Execute esses comandos para confirmar se a CLI está instalada e se o serviço pode ser acessado.

  1. Mostrar ajuda do CLI

     foundry --help

    Esse comando imprime informações de uso e a lista de grupos de comandos disponíveis.

    Referência: Visão geral

  2. Verifique o status do serviço:

     foundry service status

    Esse comando imprime se o serviço Local da Foundry está em execução e inclui seu endpoint local.

    Referência: Comandos de serviço

Visão geral

Use a ajuda interna para explorar comandos e opções.

A CLI organiza comandos em três categorias principais:

  • Modelo: comandos para gerenciar e executar modelos de IA
  • Serviço: Comandos para controlar o serviço Foundry Local
  • Cache: comandos para gerenciar o armazenamento local de modelos

Comandos de modelo

A tabela a seguir resume os comandos relacionados ao gerenciamento e à execução de modelos:

Observação

Você pode especificar o model argumento por seu alias ou ID de modelo. Usando um alias:

  • Seleciona o melhor modelo para seu hardware disponível automaticamente. Por exemplo, se você tiver uma GPU Nvidia disponível, o Foundry Local selecionará o melhor modelo de GPU. Se você tiver uma NPU com suporte disponível, o Foundry Local selecionará o modelo de NPU.
  • Permite que você use um nome mais curto sem precisar se lembrar da ID do modelo.

Se você quiser executar um modelo específico, use a ID do modelo. Por exemplo, para executar o qwen2.5-0.5b na CPU, independentemente do hardware disponível, use: foundry model run qwen2.5-0.5b-instruct-generic-cpu.

Command Descrição
foundry model --help Exibe todos os comandos relacionados ao modelo disponíveis e seu uso.
foundry model run <model> Executa um modelo especificado, baixa-o se não estiver armazenado em cache e inicia uma interação.
foundry model list Lista todos os modelos disponíveis para uso local. Na primeira execução, ele baixa provedores de execução (EPs) para o seu hardware.
foundry model list --filter <key>=<value> Lista modelos filtrados pelos critérios especificados (dispositivo, tarefa, alias, provedor).
foundry model info <model> Exibe informações detalhadas sobre um modelo específico.
foundry model info <model> --license Exibe as informações de licença de um modelo específico.
foundry model download <model> Baixa um modelo para o cache local sem executá-lo.
foundry model load <model> Carrega um modelo no serviço.
foundry model unload <model> Descarrega um modelo do serviço.

Ordenação de lista de modelos

Quando várias variantes de ID de modelo estão disponíveis para um alias, a lista de modelos mostra os modelos em ordem de prioridade. O primeiro modelo na lista é o modelo que é executado quando você especifica o modelo por alias.

Filtragem de lista de modelos

O foundry model list comando dá suporte à filtragem de modelos usando a opção --filter . Você pode filtrar modelos com base em um único atributo usando pares chave-valor.

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

Esse comando imprime modelos que correspondem à chave de filtro e ao valor.

Referência: Filtragem de lista de modelos

Observação

Quando você executa foundry model list pela primeira vez após a instalação, o Foundry Local baixa automaticamente os EPs (provedores de execução) relevantes para a configuração de hardware do computador. Você verá uma barra de progresso indicando a conclusão do download antes da exibição da lista de modelos.

Chaves de filtro com suporte:

dispositivo – Tipo de Dispositivo de Hardware

Filtra modelos pelo dispositivo de hardware em que eles são executados.

Valores possíveis:

  • CPU – Modelos de unidade de processamento central
  • GPU – Modelos de unidade de processamento gráfico
  • NPU – Modelos de unidade de processamento neural

provedor – Provedor de Execução

Filtra os modelos por seu provedor de execução ou runtime.

Valores possíveis:

  • CPUExecutionProvider – Execução baseada em CPU
  • CUDAExecutionProvider – Execução da GPU NVIDIA CUDA
  • WebGpuExecutionProvider – Execução do WebGPU
  • QNNExecutionProvider - Execução de rede neural (NPU) da Qualcomm
  • OpenVINOExecutionProvider – Execução do Intel OpenVINO
  • NvTensorRTRTXExecutionProvider – Execução do NVIDIA TensorRT
  • VitisAIExecutionProvider - Execução de IA do AMD Vitis

tarefa – Tipo de Tarefa do Modelo

Filtra os modelos por sua tarefa ou caso de uso pretendido.

Valores comuns:

  • chat-completion: modelos de IA conversacional
  • text-generation: modelos de geração de texto

alias – Alias de modelo

Filtra modelos por seu identificador de alias. Oferece suporte à correspondência curinga com o sufixo *.

Valores de exemplo:

  • phi4-cpu
  • qwen2.5-coder-0.5b-instruct-generic-cpu
  • deepseek-r1-distill-qwen-1.5b-generic-cpu
  • phi-4-mini-instruct-generic-cpu

Recursos de filtro especiais

Suporte à negação: Prefixe qualquer valor com ! para excluir modelos correspondentes.

foundry model list --filter device=!GPU

Esse comando exclui os modelos de GPU dos resultados.

Referência: Recursos de filtro especiais

Correspondência curinga (somente alias): Acrescente * para corresponder aos prefixos ao filtrar por alias.

foundry model list --filter alias=qwen*

Este comando retorna modelos cujo alias começa com qwen.

Referência: Recursos de filtro especiais

Exemplos

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

Esses exemplos filtram a lista de modelos por dispositivo, tarefa e provedor de execução.

Referência: Filtragem de lista de modelos

Observação

  • Todas as comparações não diferenciam maiúsculas de minúsculas.
  • Somente um filtro pode ser usado por comando.
  • Chaves de filtro não reconhecidas resultam em um erro.

Executar um modelo interativamente

Execute um modelo e interaja com ele diretamente no terminal:

foundry model run qwen2.5-0.5b

O Foundry Local baixa o modelo na primeira execução e inicia uma sessão interativa. Insira um prompt para obter uma resposta:

Why is the sky blue?

Captura de tela da saída do comando de execução Local do Foundry.

Dica

Substitua qwen2.5-0.5b por qualquer alias de modelo do catálogo. Execute foundry model list para exibir os modelos disponíveis. O Foundry Local baixa a variante que melhor corresponde ao hardware , por exemplo, uma variante CUDA para GPUs NVIDIA ou uma variante de NPU para NPUs do Qualcomm.

Comandos de serviço

A tabela a seguir resume os comandos relacionados ao gerenciamento e à execução do serviço Local do Foundry:

Command Descrição
foundry service --help Exibe todos os comandos relacionados ao serviço disponíveis e seu uso.
foundry service start Inicia o serviço Foundry Local.
foundry service stop Interrompe o serviço local de Fábrica.
foundry service restart Reinicia o serviço local de Fábrica.
foundry service status Exibe o status atual do serviço Foundry Local.
foundry service ps Lista todos os modelos atualmente carregados no serviço Local da Foundry.
foundry service diag Exibe os logs do serviço Local da Foundry.
foundry service set <options> Define a configuração do serviço Local do Foundry.

Comandos de cache

A tabela a seguir resume os comandos para gerenciar o cache local onde os modelos são armazenados:

Command Descrição
foundry cache --help Mostra todos os comandos relacionados ao cache disponíveis e seu uso.
foundry cache location Mostra o diretório de cache atual.
foundry cache list Lista todos os modelos armazenados no cache local.
foundry cache cd <path> Altera o diretório de cache para o caminho especificado.
foundry cache remove <model> Remove um modelo do cache local.

Provedores de execução

Os provedores de execução são bibliotecas de aceleração específicas de hardware que executam modelos da maneira mais eficiente possível em seu dispositivo.

Provedores de execução internos

Foundry Local inclui o provedor de execução de CPU, o provedor de execução WebGPU, e o provedor de execução CUDA.

O provedor de execução de CPU usa Microsoft MLAS (Sub-rotinas de Álgebra Linear) para ser executado em qualquer CPU e é o fallback da CPU para Foundry Local.

O provedor de execução WebGPU usa a Dawn, a implementação nativa da API baseada na Web, para aceleração em qualquer GPU e é o fallback da GPU no Foundry Local.

O provedor de execução cuda usa o NVIDIA CUDA para aceleração em GPUs NVIDIA. Ele requer uma série NVIDIA GeForce RTX 30 e posterior com um driver mínimo recomendado versão 32.0.15.5585 e CUDA versão 12.5. Ele está sujeito aos seguintes termos de licença: Contrato de Licença para Kits de Desenvolvimento de Software NVIDIA — EULA.

Provedores de execução de plug-in

Os provedores de execução listados na tabela a seguir estão disponíveis para download dinâmico e registro em Windows, dependendo da compatibilidade do dispositivo e do driver. Eles estão sujeitos aos termos de licença especificados.

O Foundry Local baixa automaticamente esses provedores de execução na primeira execução. Os provedores de execução do plug-in são atualizados automaticamente quando novas versões estão disponíveis.

Nome (Fornecedor) Requirements Termos de licença
NvTensorRTRTXExecutionProvider (NVIDIA) NVIDIA GeForce RTX 30XX e versões posteriores com o driver mínimo recomendado versão 32.0.15.5585 e CUDA versão 12.5 Contrato de licença para kits de desenvolvimento de software NVIDIA — EULA
OpenVINOExecutionProvider (Intel) CPU: Intel TigerLake (11ª Geração) e versões posteriores com o driver mínimo recomendado 32.0.100.9565
GPU: Intel AlderLake (12ª Geração) e versões posteriores com o driver mínimo recomendado 32.0.101.1029
NPU: Intel ArrowLake (15ª Geração) e versões posteriores com o driver mínimo recomendado 32.0.100.4239		 Contrato de Licença de Uso Comercial de Distribuição Intel OBL v2025.02.12
QNNExecutionProvider (Qualcomm) Snapdragon(R) X Elite - X1Exxxxx - NPU do Qualcomm(R) Hexagon(TM) com versão mínima do driver 30.0.140.0 e versões posteriores
Snapdragon(R) X Plus - X1Pxxxxxx - NPU do Qualcomm(R) Hexagon(TM) com versão mínima do driver 30.0.140.0 e versões posteriores		 Para exibir a Licença QNN, baixe o SDK de Processamento Neural da Qualcomm®, extraia o ZIP e abra o arquivo LICENSE.pdf.
VitisAIExecutionProvider (AMD) Min: Adrenalin Edition 25.6.3 com driver de NPU 32.00.0203.280
Max: Adrenalin Edition 25.9.1 com o driver de NPU 32.00.0203.297		 Nenhuma licença adicional necessária

Usar o Open WebUI com o servidor local

Conecte o Open WebUI ao Foundry Local para uma interface de chat baseada em navegador que é executada inteiramente em seu dispositivo.

  1. Inicie um modelo e deixe o terminal aberto:

    foundry model run qwen2.5-0.5b

  2. Obtenha a URL do ponto de extremidade local:

    foundry service status

    Copie a URL do ponto de extremidade. O Foundry Local atribui uma porta dinâmica sempre que o serviço é iniciado.

  3. Instale e inicie o Open WebUI e abra http://localhost:8080 no navegador.

  4. Conecte o Open WebUI ao Foundry Local:

    1. Vá para Configurações> deConexões deConfigurações> de Administrador e habilite Conexões Diretas.
    2. Vá para AsConexões>de Configurações>Gerenciar Conexões Diretas e selecione +.
    3. Defina a URL como http://localhost:PORT/v1 (substitua PORT pela porta da etapa 2) e Autenticação como Nenhuma.
    4. Clique em Salvar.

  5. Selecione um modelo na lista suspensa e comece a conversar.

Dica

Se nenhum modelo aparecer, execute foundry model run <model> em um terminal e recarregue o Open WebUI. Se a conexão falhar, confirme a porta com foundry service status.

Atualizar Local do Foundry

Execute o comando do sistema operacional para atualizar o Foundry Local.

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

Desinstalar o Foundry Local

Execute o comando do sistema operacional para desinstalar o Foundry Local.

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

Solução de problemas

Problemas de conexão de serviço

Se você vir esse erro ao executar um comando como 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'.

Reinicie o serviço :

foundry service restart

Esse comando corrige casos em que o serviço é executado, mas não é acessível devido a um problema de associação de porta.

Para obter mais diretrizes de solução de problemas, consulte As práticas recomendadas e a solução de problemas.

  • Last updated on