Partilhar via

Introdução ao Foundry Local

Important

  • O Foundry Local está disponível em pré-visualização. As versões de visualização pública fornecem acesso antecipado aos recursos que estão em implantação ativa.
  • Recursos, abordagens e processos podem mudar ou ter recursos limitados, antes da Disponibilidade Geral (GA).

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

Prerequisites

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. Recomendado 16 GB de RAM e 15 GB de espaço livre em disco.
  • Rede: Ligação à Internet para modelos de download e fornecedores de execução. Depois de descarregares um modelo, podes executar modelos 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 Apple Silicon.

Para instalar o Foundry Local usando os comandos deste quickstart:

  • No Windows, certifica-te de que winget está disponível.
  • No macOS, instala o Homebrew se usares essa brew opção.

Observação

Novas NPUs são suportadas apenas em sistemas que executam o Windows 24H2 ou posterior. Se você usar uma NPU Intel no Windows, instale o driver Intel NPU para ativar a aceleração NPU no Foundry Local.

Certifique-se de que tem direitos de administrador para instalar o software.

Tip

Se vir um erro de ligação de serviço após a instalação (por exemplo, 'Falha no pedido ao serviço local'), execute foundry service restart.

Início Rápido

Comece rapidamente com a 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 do repositório GitHub local do Foundry.

    Referência: Documentação Local da Foundry

  2. Verifica a instalação. Executar:

    foundry --version

    Deverá ver o número da versão instalada.

    Referência: Referência do CLI Local do Foundry

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

    foundry model run qwen2.5-0.5b

    O Foundry Local baixa o modelo, o que pode levar alguns minutos, dependendo da velocidade da sua internet, e o executa. Depois que o modelo for iniciado, interaja com ele usando a interface de linha de comando (CLI). 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 Foundry Local run.

Referência: Referência do CLI Local do Foundry

Opção 2: Download de projetos iniciais

Para aprendizagem prática e interativa, descarregue um dos projetos de iniciação que exemplificam cenários reais:

Cada projeto inclui:

  • Instruções de configuração passo a passo
  • Código fonte completo
  • Exemplos de configuração
  • Melhores práticas

Tip

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

Tip

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 transfere a variante que melhor corresponde à configuração de hardware e software do seu 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 baixa a variante NPU. Se você não tiver GPU ou NPU, o Foundry Local baixará a versão da CPU.

Ao executar foundry model list pela 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 do CLI Local do Foundry

Explorar comandos

A CLI do Foundry organiza os comandos nas seguintes categorias principais:

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

Para visualizar todos os comandos, use:

foundry --help


```bash
foundry model --help

Fundição -- Ajuda

foundry service --help

Exibir comandos de cache :

foundry cache --help

Referência: Referência do CLI Local do Foundry

Opcional: Executar o modelo mais recente do GPT OSS 20B

Executa o gpt-oss-20b modelo:

foundry model run gpt-oss-20b

Important

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

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

A versão Foundry Local 0.6.87 ou posterior adiciona suporte para este modelo. Verifique a sua versão com:

foundry --version

Referência: Referência do CLI Local do Foundry

Tip

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

Atualizar Fundição Local

Execute o comando para o seu SO 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 para o seu 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

Solução de problemas

Problemas de ligação ao serviço

Se vir este erro quando 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

Este comando corrige casos em que o serviço corre mas não é acessível devido a um problema de ligação de portas.

Referência: Boas práticas e resolução de problemas

Conteúdo relacionado

  • Last updated on