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 servidor local 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 de GitHub de amostras de fundiário.

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 server 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 servidor:

status do servidor de pesquisa '''

Esse comando imprime se o daemon Local da Foundry está em execução e inclui seu ponto de extremidade local.

Referência: comandos do servidor

Visão geral

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

A CLI organiza comandos nos seguintes grupos:

  • Modelo: model, cache
  • Executar: run, , chat, completetranscribe
  • Servidor: server
  • Configuração: config
  • Ajuda: status, report

A tabela a seguir resume os comandos de nível superior:

Command Description
foundry model Descobre, inspeciona, baixa, carrega e descarrega modelos locais.
foundry chat <model> Inicia uma sessão interativa de chat local.
foundry complete <model> <prompt> Gera uma conclusão de texto sem estado.
foundry run <model> Executa um modelo com roteamento automático para chat ou transcrição.
foundry server Inicia, para, reinicia, inspeciona e soluciona problemas do daemon local da Foundry.
foundry cache Inspeciona e gerencia entradas de cache de modelo baixadas.
foundry config Exibe e edita configurações persistentes da CLI do Foundry.
foundry status Mostra o diagnóstico de sistema, serviço, modelo e conectividade.
foundry report Abre um problema de GitHub pré-preenchido com o diagnóstico.
foundry transcribe Inicia uma sessão interativa de transcrição de fala local ou transcreve um arquivo.

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 a qwen2.5-0.5b CPU em diante, independentemente do hardware disponível, use foundry run qwen2.5-0.5b-instruct-generic-cpu.

Command Description
foundry model --help Exibe todos os comandos relacionados ao modelo disponíveis e seu uso.
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 info <model> Exibe informações detalhadas sobre 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

Use as opções explícitas para foundry model list restringir ou expandir os resultados.

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.

Opção Description
--device <device> Filtra modelos por dispositivo.
--type <type> Filtra modelos por tipo.
--search <query> Filtra modelos por uma consulta de pesquisa.
--cached Filtra a lista para modelos armazenados em cache.
--loaded Filtra a lista para modelos carregados.
--variants Inclui variantes de modelo na lista.

Exemplos

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

Esses exemplos filtram ou expandem a lista de modelos usando as opções com suporte.

Referência: Filtragem de lista de modelos

Executar um modelo interativamente

Execute um modelo e interaja com ele diretamente no terminal:

foundry chat 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?

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 servidor

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

Command Description
foundry server --help Exibe todos os comandos disponíveis relacionados ao servidor e seu uso.
foundry server start Inicia o daemon Local do Foundry e o serviço local compatível com OpenAI.
foundry server start --port <port> Inicia o serviço local na porta TCP especificada. Use 0 para uma porta atribuída pelo sistema operacional.
foundry server start --idle-timeout <minutes> Interrompe o daemon após o número especificado de minutos inativos. Use 0 para manter o daemon em execução.
foundry server stop Interrompe o daemon Local da Foundry.
foundry server restart Reinicia o daemon Local da Foundry e o serviço local.
foundry server restart --port <port> --idle-timeout 0 Reinicia o serviço local na porta TCP especificada e mantém o daemon em execução.
foundry server status Exibe o estado do daemon, as URLs de serviço local, a ID do processo, o tempo de atividade e o local do log.
foundry server logs Exibe os logs do daemon local do Foundry e do SDK.

Servidor local de porta fixa

Para iniciar o serviço local em uma porta fixa e manter o daemon em execução, use --port com --idle-timeout 0:

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

Se o daemon já estiver em execução e você precisar aplicar uma nova porta, reinicie-a com as mesmas opções:

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

Para verificar a URL do ponto de extremidade local, execute:

foundry server status

Comandos de cache

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

Command Description
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) Requisitos 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 run qwen2.5-0.5b


1. Get your local endpoint URL:

```bash
foundry server status

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

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

  2. Conecte o Open WebUI ao Foundry Local:

    1. Vá para Configurações> deConexões de> 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. Selecione Salvar.

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

Dica

Se nenhum modelo aparecer, execute foundry run <model> em um terminal e recarregue o Open WebUI. Se a conexão falhar, confirme a porta com foundry server 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 server status'.

Reinicie o serviço :

foundry server restart

Esse comando corrige casos em que o servidor é 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