Referência do Foundry CLI Local

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

Pré-requisitos

• Instale o Foundry Local. Para os passos de configuração, consulte Começar com o Foundry Local.
• Use um terminal local onde o foundry CLI esteja disponível.
• Certifique-se de que tem acesso à internet para downloads iniciais (fornecedores de execução e modelos).
• Azure RBAC: Não aplicável (corre localmente).
• Se tiveres uma NPU Intel no Windows, instala o driver Intel NPU para uma aceleração NPU ótima.

Verificação rápida

Execute estes comandos para confirmar que a CLI está instalada e que o serviço está acessível.

1. Mostrar ajuda do CLI:

    foundry --help
   

   Este comando imprime informações de utilização e a lista de grupos de comandos disponíveis.

   Referência: Visão Geral

2. Verifique o estado do serviço:

    foundry service status
   

   Este comando imprime se o serviço Foundry Local está a correr e inclui o seu endpoint local.

   Referência: Comandos de serviço

Visão geral

Use a ajuda incorporada 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 do modelo local

Comandos de modelo

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

Ordenação da lista de modelos

Quando estão disponíveis múltiplas variantes de ID de modelo para um alias, a lista de modelos mostra os modelos por ordem de prioridade. O primeiro modelo da lista é o modelo que executa quando se especifica o modelo por alias.

Filtragem de lista de modelos

O foundry model list comando suporta filtragem de modelos usando a --filter opção. Pode filtrar modelos com base num único atributo usando pares-chave-valor.

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

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

Referência: Filtragem por lista de modelos

Teclas de filtro suportadas:

device - Tipo de dispositivo de hardware

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

Valores possíveis:

• CPU - Modelos de unidades de processamento central
• GPU - Modelos de unidades de processamento gráfico
• NPU - Modelos de unidades de processamento neural

provedor - Provedor de execução

Filtra os modelos pelo seu fornecedor de execução ou pelo tempo de execução.

Valores possíveis:

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

task - Tipo de tarefa do modelo

Filtra os modelos pelo seu caso de uso ou tarefa pretendidos.

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. Suporta correspondência curinga com o sufixo *.

Valores de amostra:

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

Características especiais do filtro

Suporte de negação: Prefira qualquer valor com ! para excluir modelos correspondentes.

foundry model list --filter device=!GPU

Este comando exclui modelos de GPU dos resultados.

Referência: Características especiais do filtro

Coincidência (apenas para alias): Acrescentar * para coincidir com prefixos ao usar filtros por alias.

foundry model list --filter alias=qwen*

Este comando devolve modelos cujo alias começa por qwen.

Referência: Características especiais do filtro

Examples

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

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

Referência: Filtragem por lista de modelos

Comandos de serviço

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

Comandos de cache

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

Fornecedores de execução

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

Fornecedores de execução incorporados

O Foundry Local inclui o fornecedor de execução da CPU, o fornecedor de execução WebGPU e o fornecedor de execução CUDA.

O fornecedor de execução da CPU utiliza as Microsoft Linear Algebra Subroutines (MLAS) para correr em qualquer CPU e é a alternativa da CPU para o Foundry Local.

O fornecedor de execução WebGPU utiliza Dawn, a implementação nativa da API baseada na web, para aceleração em qualquer GPU e é a alternativa de GPU para Foundry Local.

O fornecedor de execução CUDA utiliza o NVIDIA CUDA para aceleração em GPUs NVIDIA. Requer uma NVIDIA GeForce RTX série 30 e posteriores, com um driver mínimo recomendado versão 32.0.15.5585 e CUDA versão 12.5. Está sujeito aos seguintes termos de licença: Contrato de Licença para Kits de Desenvolvimento de Software NVIDIA—EULA.

Fornecedores de execução de plugins

Os fornecedores de execução listados na tabela seguinte estão disponíveis para download dinâmico e registo no Windows, dependendo da compatibilidade do dispositivo e do driver. Estão sujeitos aos termos da licença especificados.

O Foundry Local descarrega automaticamente estes fornecedores de execução na primeira execução. Os fornecedores de execução de plugins atualizam-se automaticamente quando há novas versões disponíveis.