Sessão prática de codificação: integre a IA no dispositivo ao seu app usando o framework Foundation Models

Olá! Meu nome é Naomy. Vamos mergulhar no mundo da SwiftUI e da inteligência no dispositivo. Nesta sessão prática, vamos explorar como adicionar novos recursos aos seus apps usando o framework Foundation Models. Vou dar um exemplo passo a passo enquanto crio um app que vai planejar minha próxima viagem. O framework Foundation Models oferece acesso direto ao grande modelo de linguagem da Apple no dispositivo, e as possibilidades do que você pode criar são infinitas. Tudo é executado no dispositivo. Os dados dos usuários permanecerem privados. O modelo é offline e já está integrado ao sistema operacional. Ele não vai aumentar o tamanho dos apps. Com este framework, podemos criar recursos poderosos, privados e com bom desempenho no macOS, iPadOS, iOS e visionOS. Meus amigos e eu queremos fazer uma viagem, mas precisamos de inspiração sobre para onde ir e o que fazer. Pode ser difícil planejar, mas usando o framework Foundation Models fica fácil. Vamos usá-lo para criar um app que fará todo o planejamento para nós. Veja o que vamos criar hoje. No meu app, a página de destino exibe vários pontos turísticos em destaque, que podemos pesquisar. Aquelas árvores parecem interessantes. Vamos selecionar Joshua Tree. Podemos tocar no botão Generate, e o modelo fará o trabalho para nós. Ele vai criar um itinerário e, no processo, também vai usar chamadas de ferramentas para escolher do modo autônomo os melhores pontos de interesse do ponto turístico. Meus amigos vão gostar deste app, então vamos criá-lo. Há alguns passos para usar o framework que vamos revisar hoje. Tudo começa com engenharia de prompt. Vou mostrar como aperfeiçoar os prompts usando o playground do Xcode. Vamos usar chamadas de ferramentas para complementar o modelo, permitindo que ele acesse fontes externas para buscar pontos de interesse para os pontos turísticos. Vamos transmitir a saída para mostrar o itinerário enquanto é gerado pelo modelo. Para finalizar, vamos analisar nosso app e aplicar otimizações para obter um ótimo desempenho com o framework Foundation Models. Um bom prompt é a chave para obter ótimos resultados. Criar prompts pode ser uma tarefa cansativa, que exige muitas iterações. Eu poderia executar meu app, examinar a saída, mudar o prompt, reexecutá-lo e repetir tudo de novo, mas aí eu passaria o dia todo aqui e não teria tempo para a minha viagem. Felizmente, o recurso atualizado Playground do Xcode pode ajudar. Para começar, confira se a tela está ativada.

É como os Previews da SwiftUI, mas nos dará feedback ao vivo para qualquer código Swift. Em qualquer arquivo do projeto, posso importar Playgrounds

e escrever #Playground para iterar no meu código.

Vamos começar pelo básico. Vou importar o Foundation Models, criar uma sessão e fazer uma solicitação.

No prompt, direi: "Crie um itinerário". Assim que digitei, o prompt foi executado automaticamente, e podemos ver os resultados na tela.

Não fui específica, né? Vou começar adicionando um local.

Nosso prompt está muito melhor. Agora temos um itinerário. Estou satisfeita por ora. Posso voltar quando quiser para ajustar meu prompt. Descobrimos como é simples começar com o framework Foundation Models: é só dar um prompt e receber uma string como resultado. Mas, para o meu itinerário, quero uma saída mais estruturada. Quero usar minhas próprias estruturas de dados para representar o resultado, sem ter que me preocupar em analisar a saída do modelo. Com a geração guiada, o modelo consegue criar as estruturas de dados desejadas, desde que eu as marque como Generable. Vamos colocar isso em prática. Aqui está uma estrutura de Itinerário que quero que o modelo gere. Vamos começar importando o Foundation Models e adicionando a anotação Generable.

A única exigência de Generable é que os tipos das propriedades também sejam Generable. Por sorte, tipos comuns como string são Generable por padrão. Se houver tipos aninhados, como DayPlan neste exemplo, basta torná-los Generable também. Agora que temos uma hierarquia de tipos totalmente Generable, vamos prosseguir e deixar o modelo gerar estruturas de Itinerário como nossa resposta. Se desejar mais controle sobre o resultado, a macro Guide permite impor restrições aos valores das suas propriedades. É possível incluir um guia com uma descrição, como vou fazer para o título aqui.

Também é possível limitar uma propriedade a um subconjunto específico de valores.

Posso especificar uma contagem para assegurar que a matriz de dias tenha três itens, e também usar vários guias para uma mesma propriedade. Vou adicionar mais alguns guias às minhas propriedades.

As descrições dos guias são uma outra maneira de orientar o modelo. Confira o vídeo "Conhecer melhor", em que o Louis apresenta a geração Guided. E agora que temos nosso prompt, nosso tipo Generable, podemos juntar tudo.

Este é o Planejador de Itinerário, em que guardaremos a lógica do Foundation Models. Vamos criar uma sessão.

E dar instruções. Posso usar a API de construção para criar minhas instruções facilmente. Neste fechamento, posso passar várias strings e até instâncias do meu tipo Generable. Instruções são uma forma mais avançada de prompt. Aqui, vou definir qual é a função do modelo.

Queremos um itinerário, e vou passar ao modelo algumas informações sobre o local escolhido.

Incluir um exemplo é ótimo, pois oferece ao modelo uma noção mais clara do tipo de resposta desejada.

Também posso passar uma instância da minha struct Itinerary, definida abaixo com uma viagem ao Japão.

Como minha struct Itinerary é Generable, o Foundation Models vai convertê-la automaticamente em texto que o modelo possa entender. Tudo pronto para fazer nossa solicitação, com nosso tipo Generable como saída.

No nosso prompt, vamos pedir explicitamente ao modelo um itinerário.

E, para integrar tudo, vamos definir o itinerário com base na resposta do modelo.

A última etapa é mostrar isso na nossa interface. Vamos tornar nosso ItineraryPlanner Observable, para que nossa interface saiba quando o itinerário for gerado.

Vamos inclui-lo como propriedade de estado em LandmarkTripView, para que a visualização seja atualizada quando o planejador for alterado.

Se fizermos a inicialização aqui, o objeto será recriado desnecessariamente, mesmo quando a visualização não estiver na tela, o que prejudica o desempenho. É melhor adiar a criação do objeto usando um modificador de tarefa. Vamos adicionar uma tarefa e inicializar o planejador aqui.

Isso será chamado apenas uma vez, quando a visualização aparecer. Assim que recebermos um itinerário do modelo, podemos exibi-lo.

Vou usar outra visualização, chamada ItineraryView. Nela, vou exibir meu título e, depois, adicionar alguns estilos.

Vou repetir o processo para a descrição e a justificativa.

Vou exibir o restante das propriedades do itinerário de maneira parecida, usando as outras visualizações. Esse é um ótimo começo, e o modelo usará a descrição que fornecemos nas instruções para gerar um itinerário básico. Vamos dar um passo adiante. O framework oferece um protocolo de ferramentas flexível que permite ao modelo incluir informações externas em suas respostas. Você pode usar muita criatividade, desde os contatos do telefone e os eventos no calendário, até conteúdos disponíveis online. De forma autônoma, o modelo determina quando e quantas vezes invocar suas ferramentas. Para especializar mais meu app de planejamento, vou criar uma ferramenta que consulta o MapKit para buscar os melhores pontos de interesse de um ponto turístico. Para criar uma ferramenta, você precisará seguir o protocolo de ferramenta.

Inclui um nome exclusivo para a ferramenta, uma descrição em linguagem natural sobre quando chamá-la, e uma função de chamada, que permite ao modelo invocar sua ferramenta com os argumentos que você define. Vamos começar a criar a ferramenta. Vamos importar Foundation Models e MapKit.

Tenho uma estrutura de dados que segue o protocolo de ferramenta,

com um nome e uma descrição.

O framework insere essas strings nas instruções automaticamente, para que o modelo possa entender o que sua ferramenta faz e decidir quando chamá-la. Uma ferramenta pode receber dados do usuário, como o local turístico escolhido.

Para que nossa ferramenta obtenha vários tipos de pontos de interesse, vamos incluir enum.

O modelo usará seu conhecimento de mundo para decidir quais categorias são mais promissoras para um certo ponto turístico. Por exemplo, é mais provável achar uma marina na Grande Barreira de Corais do que em regiões secas, como o deserto de Joshua Tree. O modelo vai gerar enum, então ele precisa ser Generable.

Depois, vamos definir a struct Arguments, que utiliza nosso enum, junto com uma consulta em linguagem natural.

Para a implementação, existe o método call, que é como o modelo vai invocar sua ferramenta quando decidir fazê-lo. Eu já havia escrito uma lógica para o MapKit, que faz uma solicitação ao MapKit

usando a consulta em linguagem natural gerada pelo modelo como entrada, além da categoria selecionada pelo modelo, e busca pontos de interesse em um raio de 20 km das coordenadas do ponto turístico.

Faremos uma busca com as restrições solicitadas e retornaremos os resultados.

Podemos então implementar o método call. Vamos acessar o MapKit, filtrar nossos resultados e retornar nossa saída.

E isso é tudo o que você precisa para definir uma ferramenta que busca informações do MapKit. Para integrá-lo, vamos voltar a ItineraryPlanner.

E esta é a sessão que criamos antes. Vamos criar uma instância da ferramenta com o ponto turístico escolhido pelo usuário.

Podemos passar nossa ferramenta para o inicializador da sessão.

Isso basta para que o modelo invoque nossa ferramenta, porém podemos incluir prompts para que ela seja chamada mais vezes. Podemos pedir explicitamente ao modelo para usar nossa ferramenta e categorias.

E pronto! Já podemos testar! Se você não tiver um dispositivo de teste em mãos, sem problemas. Se sua máquina de desenvolvimento estiver executando o macOS mais recente, e tiver a Apple Intelligence ativada e pronta, podemos executar o teste nos simuladores de iPhone e Vision Pro. Vamos selecionar Joshua Tree e pedir um itinerário.

Você pode perceber que está demorando um pouco. Isso ocorre porque o modelo está retornando toda a saída de uma vez: cada atividade é gerada antes de recebermos qualquer resultado. Não se preocupe, mais adiante vou mostrar como acelerar isso. Pronto. Recebemos um itinerário legal.

Porém, esquecemos algo realmente importante. Assumimos que o Foundation Model no dispositivo está sempre disponível, mas nem sempre é o caso. A disponibilidade do modelo depende da disponibilidade da Apple Intelligence, que pode não ser compatível, estar ativada ou pronta em um dispositivo. É importante verificar o status do modelo e lidar com isso adequadamente na nossa interface. Agora, em vez de testar isso com dispositivos físicos ou, o impensável: desativar a Apple Intelligence apenas para fins de teste, podemos usar uma boa opção de esquema no Xcode.

No nosso esquema, podemos ver a substituição da disponibilidade do Foundation Models. No momento, está desativado. Mas qualquer uma das três primeiras opções é motivo para os modelos não estarem no dispositivo. Vamos escolher uma, tentar gerar um itinerário e ver o que acontece no nosso app.

Nossa, isso não é bom. Estamos apenas mostrando um erro aqui, e ele não é realmente acionável. Preciso voltar e pensar em como vou integrar a disponibilidade no meu app. Vamos considerar os três casos que mostrei antes. Se o dispositivo não for elegível para receber a Apple Intelligence, não faz sentido mostrar o botão de gerar itinerário. Ao selecionar o ponto turístico, vamos exibir uma breve descrição dele, usando os dados offline que temos no nosso app. No segundo caso, o dispositivo é capaz, mas não foi configurado para usar a Apple Intelligence. Devemos informar ao usuário que é por isso que o planejador de itinerário está indisponível. Eles podem decidir se querem ativar e acessar o recurso. Por fim, Modelo não pronto significa que é necessário mais tempo para o modelo terminar o download. Basta informar ao usuário para tentar novamente depois, já que o recurso estará disponível em breve.

Agora que definimos o comportamento do app, podemos usar a API Availability para saber qual é o estado de disponibilidade do dispositivo. Na minha visualização, vou adicionar uma nova variável para o modelo usado, neste caso, o modelo de linguagem do sistema.

Podemos ativar o estado de disponibilidade: se o modelo estiver disponível, seguimos com o comportamento anterior.

Quando a Apple Intelligence não estiver ativada, vamos avisar o usuário.

Caso o modelo não esteja pronto, avisaremos para tentar novamente depois.

Caso contrário, vamos ocultar o botão de itinerário e exibir um fato curioso.

Já defini a substituição do Foundation Models no meu esquema como Dispositivo não elegível. Vamos tentar novamente.

Certo, muito melhor. Agora, vemos um fato curioso, e o botão Gerar itinerário foi removido para não permitir que o usuário tente usar um recurso incompatível com o dispositivo. Considerando o que foi feito até agora, o app espera todo o itinerário ser criado antes de apresentá-lo na interface. Por sorte, ao transmitir o itinerário conforme ele é gerado pelo modelo, conseguimos ler as recomendações na hora. Para usar streaming, vamos alterar o método respond que estamos chamando.

Em vez de receber um itinerário completo, recebemos uma versão parcial. É possível utilizar a estrutura de dados PartiallyGenerated, que é gerada automaticamente. Essa é a sua estrutura Generable, mas todas as propriedades são opcionais. Portanto, vou alterar o tipo esperado para o meu itinerário.

Nosso resultado agora será uma nova sequência assíncrona com o tipo PartiallyGenerated como saída.

Cada elemento no nosso fluxo é uma versão do itinerário atualizada incrementalmente. Por exemplo, o primeiro elemento pode ter um título, mas as outras propriedades do itinerário seriam nil. O segundo elemento poderia ter um título e uma descrição, e assim por diante, até recebermos um itinerário totalmente gerado. Preciso extrair essas propriedades nas minhas visualizações. Também é importante considerar quais propriedades podem ser mostradas sem as demais. No meu caso, o itinerário tem um título, uma descrição e os planos do dia, e essa ordem faz sentido.

Vou fazer meu itinerário parcialmente gerado, e vou extrair o título,

a descrição e a justificativa.

Agora, para a lista de dias:

Também preciso exibir meus planos diários parcialmente gerados. É ótimo que as estruturas PartiallyGenerable sejam automaticamente identificáveis, assim não preciso gerenciar os IDs. Posso usar o forEach da SwiftUI com minhas estruturas parcialmente geradas.

É muito fácil! Vamos adicionar uma animação com base no itinerário.

E transições de conteúdo às propriedades,

para que os resultados apareçam de maneira fluida nas visualizações. Vou extrair todas as outras propriedades e agora estamos quase com o produto final. Vamos testar no meu celular! Vamos fazer a mesma solicitação de antes.

Desta vez, vamos começar a ver saída sendo transmitida na nossa interface. Como usuário, posso ler o primeiro dia enquanto o conteúdo está sendo gerado.

Talvez você tenha notado um leve atraso antes do primeiro campo aparecer na tela. Para resolver isso, seria útil entender o que está acontecendo nos bastidores.

Agora é uma excelente oportunidade para usar o novo instrumento Foundation Models e entender melhor os fatores que afetam nosso desempenho. Vamos ver o que podemos encontrar criando o perfil do nosso app. Mais cedo, falamos sobre executar nosso app no simulador. Isso é ótimo para testar a funcionalidade, mas pode não gerar resultados precisos de desempenho. Por exemplo, um simulador em um Mac M4 pode gerar resultados mais depressa que um iPhone antigo. Ao analisar o desempenho, é importante ter essas diferenças em mente. Vou criar o perfil em um iPhone físico.

Para começar, tenho o app Instruments aberto no Mac e vou conectar meu telefone.

Podemos ir em frente e adicionar o novo instrumento Foundation Models,

começar a gravar e criar um itinerário.

A trilha Asset Loading analisa o tempo gasto para carregar os modelos. O modelo de linguagem padrão do sistema e a proteção de segurança foram carregados. A trilha Inference também está presente em azul.

E a barra roxa mostra o tempo gasto chamando a ferramenta. É possível monitorar o tempo total para gerar o itinerário, além da quantidade de tokens de entrada, que é proporcional ao tamanho das instruções e prompts. E esse atraso no começo foi o tempo necessário para carregar o modelo de linguagem do sistema. Há algumas formas de acelerar esse processo. Percebemos que uma parte da latência inicial ficou registrada na trilha Asset Loading. O modelo de linguagem no dispositivo é gerenciado pelo sistema operacional e pode não ser mantido na memória se o sistema estiver executando outras funções críticas ou se não tiver em uso por algum tempo. Ao chamar session.respond, o sistema operacional carrega o modelo, caso ele ainda não esteja na memória. O pré-carregamento pode acelerar sua sessão ao carregar o modelo antes de a solicitação ser feita. O ideal é fazer isso quando seu app estiver relativamente ocioso e logo após o usuário dar um forte indício de que usará a sessão. O momento ideal para pré-carregar o modelo é assim que o usuário começa a digitar em um campo de texto que vai gerar um prompt. No app, quando o usuário toca em um ponto turístico, é bem provável que ele faça uma solicitação em breve. É possível pré-carregar o modelo antes que o usuário toque no botão Gerar Itinerário. Assim que o usuário terminar de ler a descrição, o modelo estará preparado para responder.

A segunda otimização pode ser adicionada no momento da solicitação. Lembra do argumento generating das funções de resposta? Usamos Itinerary aqui. O framework insere automaticamente os esquemas de geração das estruturas de dados nos prompts. Mas isso adiciona mais tokens, aumentando a latência e o tamanho do contexto. Se o modelo já souber o formato da resposta antes da solicitação, podemos definir IncludeSchemaInPrompt como false para ganhar desempenho.

Quando podemos aplicar essa otimização? O primeiro caso é se você estiver fazendo solicitações subsequentes do mesmo tipo em uma conversa de vários turnos. A primeira solicitação na sessão já forneceu o contexto para a geração guiada, incluindo o esquema no prompt. Não precisamos fazer isso para as solicitações subsequentes nessa sessão. O segundo caso é quando suas instruções já incluem um exemplo completo do esquema. Lembra como passamos um exemplo de itinerário nas instruções? No nosso caso, isso é suficiente, pois nossa estrutura Itinerary não tem propriedades opcionais.

Se você tiver propriedades opcionais no esquema, precisará fornecer exemplos com todas as propriedades opcionais preenchidas e com valor nil. Uma consideração final: definir IncludeSchemaInPrompt como false significa que perderemos as descrições adicionadas aos guias, mas, se você estiver usando um exemplo detalhado, isso não deve ser um problema. Vamos testar essas otimizações. Vamos definir a opção IncludeSchemaInPrompt como false na nossa solicitação. Vamos pré-carregar a sessão enquanto o usuário está na página de descrição do ponto turístico. Vamos criar um wrapper rápido e invocá-lo na nossa sessão.

Este é o resultado. Gravei isso novamente e podemos dar uma olhada nos resultados. A trilha Asset Loading já apresentava alguma atividade antes de eu tocar no botão Generate. Vemos uma redução na quantidade de tokens de entrada e o tempo total de resposta agora está menor. Considerando os segundos economizados com essas otimizações, chegaremos ao voo no horário. Com isso, está tudo pronto para minha viagem.

Mas antes de partir, aqui estão algumas outras sessões que podem interessar. Se você ainda não viu, não deixe de conferir a sessão de introdução para saber tudo sobre o framework. Para se aprofundar, tem o vídeo detalhado e, para melhores práticas de prompt, confira "Criação e segurança de prompts". Agradeço sua participação.