Referência da CLI local do Foundry

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 o Foundry Local. Para obter as etapas de instalação, consulte Introdução ao Foundry Local.
• Use um terminal local em que a foundry CLI esteja disponível.
• Verifique se você tem acesso à Internet para downloads pela primeira vez (provedores de execução e modelos).
• RBAC do Azure: não aplicável (é executado localmente).
• Se você tiver uma NPU Intel no Windows, instale o driver de NPU Intel para uma aceleração de NPU ideal.

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 de modelos local

Comandos de modelo

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

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

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

Comandos de serviço

A tabela a seguir resume os comandos relacionados ao gerenciamento e à execuçã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:

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 as MLAS (Sub-rotinas de Álgebra Linear da Microsoft) para operar em qualquer CPU e serve como recurso de reserva de CPU para o Foundry Local.

O provedor de execução do WebGPU usa o Dawn, a implementação nativa da API baseada na Web, para aceleração em qualquer GPU e serve como alternativa de GPU para o 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 no 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.