Compartilhar via

Introdução ao Foundry Local

Importante

  • A Fábrica Local está disponível na versão prévia. As visualizações públicas fornecem acesso antecipado a recursos que estão em implantação ativa.
  • Os recursos, abordagens e processos podem mudar ou ter seus recursos limitados antes da GA (disponibilidade geral).

Este guia mostra como configurar o Foundry Local para executar modelos de IA em seu dispositivo.

Pré-requisitos

Seu sistema deve atender aos seguintes requisitos para executar o Foundry Local:

  • Sistema operacional: Windows 10 (x64), Windows 11 (x64/ARM), Windows Server 2025, macOS.
  • Hardware: mínimo de 8 GB de RAM e 3 GB de espaço livre em disco. 16 GB de RAM recomendados e 15 GB de espaço livre em disco.
  • Rede: conexão com a Internet para baixar modelos e provedores de execução. Depois de baixar um modelo, você pode executar modelos armazenados em cache offline.
  • Aceleração (opcional): GPU NVIDIA (série 2000 ou mais recente), GPU AMD (série 6000 ou mais recente), AMD NPU, Intel iGPU, Intel NPU (32 GB ou mais de memória), Qualcomm Snapdragon X Elite (8 GB ou mais de memória), Qualcomm NPU ou silício apple.

Para instalar o Foundry Local usando os comandos neste início rápido:

  • No Windows, verifique se winget está disponível.
  • No macOS, instale o Homebrew se você usar a opção brew .

Observação

Há suporte para novas NPUs somente em sistemas que executam o Windows 24H2 ou posterior. Se você usar uma NPU intel no Windows, instale o driver de NPU Intel para habilitar a aceleração de NPU no Foundry Local.

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, 'Falha na solicitação ao serviço local'), execute foundry service restart.

Início Rápido

Comece rapidamente com o Foundry Local:

Opção 1: Configuração rápida da CLI

  1. Instale Foundry Local.

    • Windows: Abra um terminal e execute o seguinte comando. 
      winget install Microsoft.FoundryLocal
    • macOS: Abra um terminal e execute o seguinte comando. 
      brew tap microsoft/foundrylocal
brew install foundrylocal
      Como alternativa, você pode baixar o instalador no repositório Local do GitHub do Foundry.

    Referência: Documentação local do Foundry

  2. Verifique a instalação. Executar:

    foundry --version

    Você deve ver o número de versão instalado.

    Referência: Referência da CLI local do Foundry

  3. Execute seu primeiro modelo. Abra um terminal e execute este comando:

    foundry model run qwen2.5-0.5b

    O Foundry Local baixa o modelo, que pode levar alguns minutos, dependendo da velocidade da Internet, e o executa. Depois que o modelo for iniciado, interaja com ele usando a CLI (interface de linha de comando). Por exemplo, você pode perguntar:

    Why is the sky blue?

    Você verá uma resposta do modelo no terminal: captura de tela da saída do comando de execução Local do Foundry.

Referência: Referência da CLI local do Foundry

Opção 2: Baixar projetos iniciais

Para aprendizado prático e aplicado, baixe um dos projetos iniciais que demonstram cenários do mundo real.

Cada projeto inclui:

  • Instruções de configuração passo a passo
  • Código-fonte completo
  • Exemplos de configuração
  • Práticas recomendadas

Dica

Esses projetos initores se alinham a cenários nos guias de instruções e fornecem valor prático imediato.

Dica

Substitua qwen2.5-0.5b por qualquer nome de modelo do catálogo (execute foundry model list para exibir os modelos disponíveis). O Foundry Local baixa a variante que melhor corresponde à configuração de hardware e software do sistema. Por exemplo, se você tiver uma GPU NVIDIA, o Foundry Local baixará a versão cuda. Se você tiver uma NPU Qualcomm, o Foundry Local baixará a variante da NPU. Se você não tiver GPU ou NPU, o Foundry Local baixará a versão da CPU.

Ao executar foundry model list a primeira vez, você verá uma barra de progresso de download enquanto o Foundry Local baixa os provedores de execução para seu hardware.

Referência: Referência da CLI local do Foundry

Explorar comandos

A CLI do Foundry organiza comandos nessas categorias principais:

  • Modelo: comandos para gerenciar e executar modelos.
  • Serviço: comandos para gerenciar o serviço Local da Foundry.
  • Cache: comandos para gerenciar o cache de modelo local (modelos baixados em disco local).

Para exibir todos os comandos, use:

foundry --help

foundry model --help

foundry --help

foundry service --help

Exibir comandos de cache :

foundry cache --help

Referência: Referência da CLI local do Foundry

Opcional: executar o modelo gpt oss 20B mais recente

Rode o gpt-oss-20b modelo:

foundry model run gpt-oss-20b

Importante

Se o modelo não estiver disponível para seu dispositivo, execute um modelo menor (por exemplo, qwen2.5-0.5b).

Para a variante CUDA, normalmente você precisa de uma GPU NVIDIA com 16 GB de VRAM ou mais.

O Foundry Local versão 0.6.87 ou posterior adiciona suporte para esse modelo. Verifique sua versão com:

foundry --version

Referência: Referência da CLI local do Foundry

Dica

Para obter detalhes sobre todos os comandos da CLI, consulte a referência da CLI local do Foundry.

Atualizar Local do Foundry

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

  • Windows: Em um terminal, execute: 
    winget upgrade --id Microsoft.FoundryLocal
  • macOS: em um terminal, execute: 
    brew upgrade foundrylocal

Desinstalar o Foundry Local

Para desinstalar o Foundry Local, execute o comando do sistema operacional:

  • Windows: Abra um terminal e execute: 
    winget uninstall Microsoft.FoundryLocal
  • macOS: abra um terminal e execute: 
    brew rm foundrylocal
brew untap microsoft/foundrylocal
brew cleanup --scrub

Resolução de problemas

Problemas de conexão de serviço

Se você vir esse erro ao executar foundry model list ou um comando semelhante:

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'.

Execute este comando para reiniciar 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.

Referência: Práticas recomendadas e solução de problemas

Conteúdo relacionado

  • Last updated on