Foundation Models a partir do Python: a CLI fm

Por um ano, o modelo de linguagem grande on-device da Apple viveu atrás de um muro: você o alcançava apenas a partir do Swift, apenas dentro de um app que você construía no Xcode¹. O macOS 27 derruba esse muro. A Apple agora distribui uma ferramenta de linha de comando chamada fm pré-instalada com o sistema operacional, e um Foundation Models SDK para Python que você instala com pip¹. O modelo que antes exigia um projeto, um build e um LanguageModelSession em Swift compilado agora responde a um comando de uma linha no shell e roda dentro de um notebook Jupyter. Eric Gourlaouen, engenheiro da equipe do Foundation Models Framework, resumiu a mudança de forma direta na sessão 334 da WWDC26: “até agora, esses modelos estavam disponíveis somente a partir de código Swift”¹. A mudança não é um modelo novo. A mudança é que o mesmo modelo on-device de repente é scriptável, automatizável e avaliável fora de um app, sem API key e sem custo de nuvem¹.

Resumo

• O macOS 27 traz o fm, uma ferramenta de linha de comando pré-instalada para o Apple Foundation Model on-device. Seus subcomandos incluem respond (prompt único para a stdout), chat (sessão interativa) e schema (definir saída estruturada)¹.
• O fm respond aceita opções para o modelo (alternar para o Private Cloud Compute), uma entrada de imagem e um schema para saída estruturada; o --help lista o restante¹.
• O SDK Python alcança o mesmo modelo on-device a partir do Python, exigindo Python 3.10 ou superior, o Xcode instalado e um Mac com Apple Silicon, instalado por meio do pip ou de outro gerenciador de pacotes¹.
• O SDK espelha o framework Swift: um LanguageModelSession no qual você chama respond, tool calling e guided generation por meio do decorador fm.generable passado ao fm.respond como o argumento de geração¹.
• As duas superfícies usam por padrão o modelo on-device sempre disponível e podem optar pelo modelo maior do Private Cloud Compute, que é mais capaz, mas tem limites de uso¹.
• O ganho está na prototipagem e na automação: scripts de shell que ordenam arquivos por significado e pipelines de avaliação em Python que avaliam variantes de prompt com Pandas e matplotlib¹.

A ferramenta de linha de comando fm

Abra o Terminal no macOS 27 e digite fm, e a ferramenta imprime os comandos que ela suporta¹. A Apple destaca três. O fm respond envia um prompt ao modelo e retorna uma resposta. O fm chat inicia uma conversa interativa. O fm schema cria um schema para saída estruturada¹. O uso mais simples possível é o que Eric demonstrou primeiro: digite fm respond, digite um prompt, pressione enter e leia a resposta do modelo no terminal um instante depois¹.

Os dois comandos de nível superior se dividem por uma linha bem nítida: exploração versus scripting. O fm chat serve para ter uma primeira impressão do modelo. Você faz uma pergunta, faz outra de acompanhamento, e a conversa se mantém, com seus próprios comandos de barra: o /model alterna a conversa para o modelo do Private Cloud Compute e o /save salva a conversa para retomar depois¹. Quando você prefere uma resposta inline que possa capturar, como em um script, recorre ao fm respond, que escreve a saída do modelo na stdout¹.

É no fm respond que ficam as opções. Eric nomeou três explicitamente. Uma opção de modelo envia o prompt ao modelo do Private Cloud Compute em vez do padrão on-device. Uma opção de imagem inclui uma imagem no prompt. E uma opção de schema se combina com o fm schema object para restringir a saída a uma estrutura que você definiu¹. Ele observou que há mais e apontou para a opção de ajuda para listá-las todas¹. A transcrição nomeia as opções pelo papel que cumprem, e não pela grafia exata de cada flag (a única forma literal mostrada na tela é fm schema object), então, onde descrevo uma opção abaixo, estou descrevendo o comportamento documentado, e não inventando uma string de flag.

A escolha do modelo é a decisão que mais importa. Por padrão, o fm usa o modelo on-device que vem com o macOS, que está sempre disponível¹. Você pode alternar para o Apple Foundation Model no Private Cloud Compute, que Eric descreveu como “um modelo muito maior do que o on-device, então terá um desempenho melhor em problemas complexos”, com a contrapartida de que ele tem limites de uso¹. O padrão é o ponto de partida certo: é gratuito, local e não tem limite. Você sobe para o Private Cloud Compute quando uma tarefa é genuinamente difícil a ponto de precisar dele.

Construindo um script de automação

A demonstração de ordenação de arquivos é o argumento mais claro de por que uma CLI importa. Eric tinha uma pasta de projeto cheia de versões de rascunho e finais de assets e queria um script repetível que mantém as finais, faz backup delas e move as de rascunho para um disco de arquivamento¹. A parte difícil não é mover arquivos. A parte difícil é decidir qual arquivo é um rascunho quando os nomes estão bagunçados. Como ele colocou, chamar um modelo de linguagem a partir do script permite que ele “ordene arquivos de rascunho versus finais” mesmo quando “os nomes estão bagunçados e são difíceis de ordenar de forma previsível”¹.

O formato se generaliza para qualquer automação de “julgamento sobre uma lista”. O script carrega os arquivos do diretório de trabalho e, então, envia um prompt ao modelo por meio do fm respond para separar essa lista em dois grupos: arquivos finais e arquivos de rascunho¹. Para tornar a saída utilizável, ele define um schema de antemão com o fm schema object descrevendo dois campos, uma lista de finais e uma lista de rascunhos, e passa esse schema ao fm respond por meio da opção de schema¹. O modelo retorna sua resposta como JSON, e o script a lê para copiar as finais para um backup e mover as de rascunho para o arquivamento¹.

A etapa de saída estruturada é a que sustenta tudo. Uma resposta em texto livre forçaria o script a fazer parsing de prosa, a parte frágil de todo pipeline de shell que conversa com um LLM. Ao declarar o schema com o fm schema object e receber JSON de volta, o script ganha um contrato sobre o qual pode agir diretamente¹. O padrão é o mesmo que os desenvolvedores Swift conhecem como guided generation, exposto aqui como uma opção de CLI¹. Qualquer tarefa que termine em “faça algo determinístico com a decisão do modelo” quer exatamente esse formato: prompt, schema, JSON, ação.

O SDK Python

A segunda superfície é para uma pessoa diferente em um momento diferente. Como Eric colocou, “se você é engenheiro de machine learning, talvez use mais Python do que Swift”, e o SDK “facilita usar o modelo on-device no seu código Python”¹. A proposta se apoia no ecossistema do Python: “o Python tem um ecossistema rico de pacotes open-source para machine learning e ciência de dados”, o que significa que você pode escrever pipelines de avaliação e “aproveitar esses pacotes para quantificar a qualidade do seu recurso”¹.

A instalação tem quatro requisitos, todos declarados na sessão. Você precisa de Python 3.10 ou superior, do Xcode instalado e de um Mac com Apple Silicon, e instala o SDK por meio do pip ou de qualquer outro gerenciador de pacotes de sua escolha¹. Os requisitos de Apple Silicon e Xcode são o indício de que o pacote é um binding para o mesmo modelo on-device que o sistema operacional executa, e não uma API hospedada.

A API parecerá familiar a quem usou o framework Swift², por design: “as APIs e abstrações vão parecer familiares rapidamente”¹. Você envia um prompt criando um LanguageModelSession, opcionalmente passando instructions, e então chamando session.respond com o seu prompt; o resultado contém a saída do modelo¹. O SDK leva consigo os recursos centrais do framework: entradas de texto e imagem, respostas em streaming, tool calling para que o modelo possa interagir com o seu código, e guided generation para saída estruturada¹.

Dois desses recursos receberam tratamento concreto. Para tool calling, Eric definiu uma ferramenta que o modelo pode chamar para buscar os últimos pedidos de um usuário, “para que possa fornecer informações mais personalizadas”, o mesmo padrão do protocolo Tool do framework Swift¹. Para guided generation, ele usou o decorador fm.generable para definir a estrutura de saída desejada, um objeto ItemsSuggestion, e o passou ao fm.respond como o argumento de geração¹. O decorador é o análogo em Python da macro @Generable do Swift, e o argumento de geração é como você entrega ao modelo o formato que quer de volta. Como a transcrição mostra esses elementos pelo papel e pelo nome do objeto, em vez de imprimir o corpo completo da classe, trate ItemsSuggestion como o nome que o exemplo dá a uma estrutura que você mesmo definiria.

Pipelines de avaliação: a verdadeira razão para usar Python

O estudo de caso é onde o SDK Python deixa de ser uma conveniência e se torna um método. Eric estava construindo um recurso para prever o que um usuário quer adicionar ao carrinho de compras, e tinha três implementações de prompt diferentes: uma mínima, uma mais descritiva e uma detalhada que detalhava uma lista completa de regras¹. A pergunta que todo prompt engineer enfrenta é qual delas é de fato a melhor, e a resposta honesta exige medição, não gosto pessoal.

A Apple é explícita ao dizer que os desenvolvedores Swift têm a própria resposta aqui. O framework Evaluations vem com o Xcode 27 e facilita criar avaliações e acompanhar a acurácia do recurso ao longo das iterações¹. O SDK Python é o caminho paralelo para cientistas de dados que vivem em notebooks. Eric rodou toda a análise a partir do Jupyter¹.

O pipeline se lê como um loop padrão de avaliação de ML apontado para o modelo on-device. Primeiro, ele usou um grande modelo de servidor para gerar dados de avaliação, dando-lhe entradas e uma saída esperada para cada uma¹. Depois, para cada entrada, gerou saídas a partir de cada uma das três implementações de prompt e armazenou as entradas e as saídas como linhas em um DataFrame do Pandas¹. Em seguida, funções de juiz apoiadas por um modelo de servidor pontuaram cada saída em relação a critérios que ele escolheu, e essas métricas voltaram para o DataFrame¹. Por fim, o matplotlib transformou as notas em gráficos¹.

Os gráficos contaram uma história que nenhuma quantidade de tempo encarando os prompts revelaria: o prompt detalhado atingiu uma taxa alta de erros de geração, que Eric atribuiu a alcançar o tamanho máximo da janela de contexto do modelo; os dois prompts menos detalhados adicionaram itens em excesso ao carrinho, enquanto o detalhado adicionou menos; o prompt detalhado deixou de fora mais itens esperados; e o prompt mínimo alucinou a maior quantidade de itens¹. Cada prompt tinha um modo de falha diferente, e só a medição os trouxe à tona. Esse é o argumento de toda a abordagem. “Com o Python, posso fazer essas iterações rapidamente direto do meu notebook, sem ter que reconstruir o projeto inteiro”, disse Eric¹.

Quando recorrer a cada um

Algumas regras decorrem dos contratos acima.

Recorra ao fm respond quando um script de shell precisa de uma decisão de julgamento. Ordenar nomes de arquivo bagunçados, classificar uma linha de entrada, extrair um campo de texto não estruturado. Combine-o com o fm schema object e a opção de schema para que o script aja sobre JSON em vez de fazer parsing de prosa¹.

Recorra ao fm chat quando você está explorando, não criando scripts. É a forma mais rápida de ter uma primeira impressão de como o modelo lida com seus prompts, com o /model para escalar ao Private Cloud Compute e o /save para guardar uma sessão¹.

Recorra ao SDK Python quando você quer medir, além de simplesmente chamar. No momento em que você tem mais de um prompt e precisa saber qual é melhor, o loop de notebook mais Pandas mais matplotlib é a ferramenta, porque o modelo on-device é gratuito e local o suficiente para rodar um conjunto inteiro de avaliação sem uma conta a pagar¹.

Use por padrão o modelo on-device; suba para o Private Cloud Compute de forma deliberada. O modelo on-device está sempre disponível e não tem limite de uso. O Private Cloud Compute é maior e melhor em problemas complexos, mas tem limites de uso, então guarde-o para as tarefas que o justificam¹.

Prototipe aqui, entregue em Swift. O próprio enquadramento de Eric é que você pode usar essas ferramentas “ao lado do seu projeto Xcode, como forma de prototipar e avaliar prompts”, ou “por conta própria, para usar o modelo de maneiras inéditas”¹. O exemplo do app de compras prototipa prompts em Python “antes de implementá-los em Swift”¹. A CLI e o SDK encurtam o loop entre ideia e evidência; o app continua sendo onde o recurso aterrissa.

Perguntas frequentes

O que é a ferramenta de linha de comando fm?

O fm é uma ferramenta de linha de comando que vem pré-instalada com o macOS 27 e alcança o Apple Foundation Model on-device a partir do app Terminal¹. Seus subcomandos incluem respond para enviar um prompt ao modelo e imprimir uma resposta, chat para iniciar uma conversa interativa e schema para definir saída estruturada. Você o executa sem API key e sem custo de nuvem, porque o modelo padrão roda on-device¹.

Como obtenho JSON estruturado do fm?

Defina um schema com o fm schema object e, em seguida, passe esse schema ao fm respond por meio da opção de schema. O modelo retorna sua resposta como JSON correspondente ao schema, sobre o qual um script pode agir diretamente em vez de fazer parsing de texto livre¹. O mecanismo é a versão de CLI da guided generation do framework¹.

O que o Foundation Models Python SDK exige?

Python 3.10 ou superior, o Xcode instalado e um Mac com Apple Silicon¹. Você o instala por meio do pip ou de outro gerenciador de pacotes de sua escolha. Os requisitos de Apple Silicon e Xcode refletem que o SDK faz binding para o mesmo modelo on-device que o sistema operacional executa, em vez de chamar uma API hospedada¹.

Como o SDK Python difere do framework Swift?

É o mesmo modelo e uma API deliberadamente familiar em outra linguagem. Você cria um LanguageModelSession, chama respond, expõe ferramentas e usa guided generation por meio do decorador fm.generable passado ao fm.respond como o argumento de geração¹. A razão para escolher Python é o ecossistema: Pandas, matplotlib, Jupyter e o resto da stack de ciência de dados, para pipelines de avaliação que o Swift não alcança de forma tão direta¹.

Quando devo usar o Private Cloud Compute em vez do modelo on-device?

Tanto o fm quanto o SDK usam por padrão o modelo on-device, que está sempre disponível e não tem limite de uso¹. Alterne para o Private Cloud Compute, pela opção de modelo do fm respond ou pelo comando /model do fm chat, quando um problema é complexo o bastante para precisar do modelo maior, aceitando que ele tem limites de uso¹.

O cluster completo do Apple Ecosystem: o explicador do framework Foundation Models para a base em Swift que essas ferramentas espelham; os controles de tool calling do iOS 27 para como o modelo usa ferramentas; o fluxo de trabalho agentic do Foundation Models para a escolha entre o modelo on-device e o maior; e os agentes de codificação do Xcode 27 para o lado, dentro da IDE, de um fluxo de trabalho com muitos agentes. O hub está na Série Apple Ecosystem. Para o panorama mais amplo de construir iOS com agentes, veja o guia de Desenvolvimento de Agentes para iOS.