Prompt Flow: The Complete Guide

Olá, daqui é o Alex da DEV STORIES DOT EU. Prompt Flow: O Guia Completo, episódio 1 de 14. A maioria das bibliotecas de IA tenta abstrair a complexidade ao esconder os teus prompts bem no fundo de wrapper functions. Mas, quando passas para produção, esses prompts são exatamente aquilo que precisas de controlar. Esta é a filosofia central do Prompt Flow. Vamos primeiro esclarecer um equívoco comum. O Prompt Flow não é uma framework como o LangChain. O LangChain é uma framework de desenvolvimento que fornece chains e agents pré-construídos, que muitas vezes encapsulam os prompts subjacentes. O Prompt Flow é um conjunto de ferramentas concebido para experimentação e avaliação. Ele existe porque o princípio tradicional de encapsulamento da engenharia de software torna-se, na verdade, um problema quando estás a construir aplicações com large language models. Na programação tradicional, escondes a lógica complexa por trás de uma interface de função limpa. Não precisas de saber como a função funciona internamente, só te importas com o que ela devolve. Mas os prompts são altamente voláteis. Não são lógica estática. Se mudares o teu modelo de uma versão para outra, um prompt que funcionava perfeitamente ontem pode falhar hoje. Se estiveres a usar uma biblioteca opaca de terceiros para resumir documentos, e o prompt subjacente estiver preso dentro dessa biblioteca, não consegues corrigir um mau resumo. Ficas totalmente dependente dos maintainers da biblioteca. O Prompt Flow inverte este design pattern ao expor os prompts. Trata-os como developer assets de primeira classe. Precisas de os visualizar, afinar e versionar continuamente. Em vez de uma black box, ficas com uma toolchain transparente onde controlas o texto e as variáveis exatas que entram no language model. Esta é a parte que importa. Como os prompts são voláteis, construir aplicações de IA exige uma forma de trabalhar fundamentalmente nova. No software tradicional, escreves unit tests. Fazes um assert de que um input específico produz um output específico. Os language models são probabilísticos, o que significa que não fornecem respostas determinísticas. Não podes escrever uma simples assertion para verificar se um email gerado é educado ou se um resumo é preciso. Em vez disso, tens de adotar um workflow centrado na avaliação. Tens de correr o teu prompt sobre centenas de exemplos diversos e medir métricas como a relevância ou a precisão da formatação. O Prompt Flow foi construído diretamente à volta deste workflow. Ele integra o prompt tuning com a avaliação em massa. Quando mudas uma única palavra no teu prompt, as ferramentas ajudam-te a ver estatisticamente se essa alteração melhorou a tua taxa de sucesso em todo o teu dataset ou se a piorou. O pilar final desta filosofia é otimizar para a visibilidade. As aplicações de IA raramente são apenas uma API call. São execution graphs complexos. Podes pegar numa pergunta do utilizador, fazer uma query a uma vector database, formatar os dados recuperados, injetá-los num prompt e, depois, fazer a call ao modelo. Quando a resposta final está errada, precisas de saber exatamente onde a chain quebrou. O Prompt Flow torna este execution graph visível. Podes inspecionar cada node para ver os inputs e outputs precisos nessa etapa exata do processo, tornando o debugging simples. A principal conclusão é que os prompts são variáveis vivas e voláteis que exigem observação constante, e não código estático que podes escrever uma vez e esconder. Se achas estes episódios úteis e queres apoiar o programa, podes procurar por DevStoriesEU no Patreon. É tudo por este episódio. Obrigado por ouvires, e continua a construir!

Olá, daqui é o Alex da DEV STORIES DOT EU. Prompt Flow: O Guia Completo, episódio 2 de 14. Antes de escreveres uma única linha de código, tens de parar de pensar em aplicações LLM como scripts monolíticos. Se tentares escrevê-las de forma linear, fazer o tracking de dependências e o debugging do state através de múltiplos serviços externos torna-se rapidamente incontrolável. A solução estrutural para isto é veres a tua aplicação como um grafo de function calls independentes, um conceito conhecido no Prompt Flow como flows e arquitetura DAG. Um flow é simplesmente um workflow executável. Na sua essência, uma aplicação LLM é uma sequência orquestrada de chamadas externas unidas por lógica. Podes chamar um motor de busca, fazer uma query a uma base de dados, correr um script Python para formatar os dados obtidos e, finalmente, enviar um prompt para um LLM. O Prompt Flow modela esta sequência como um Directed Acyclic Graph, ou DAG. Neste grafo, cada passo discreto da tua aplicação é um node, e as ligações entre esses nodes representam o flow de dados. É direcionado porque os dados avançam de uma função para a seguinte, e é acíclico porque o data path não faz loop sobre si mesmo. Considera uma aplicação simples que responde a perguntas com base em dados internos da empresa. O utilizador faz uma pergunta, que serve como o teu input inicial. Esse input flui para o primeiro node, uma função Python que executa uma query à base de dados. A base de dados devolve um bloco de texto. Esse texto, juntamente com a pergunta original do utilizador, flui para o próximo node, que faz a chamada real ao LLM. O LLM gera uma resposta, que se torna o output final de todo o grafo. Ao estruturares a app desta forma, cada função fica estritamente isolada. Sabes exatamente o que entrou na chamada à base de dados e exatamente o que saiu antes mesmo de o LLM ser acionado. Ao construíres estes workflows, os developers deparam-se frequentemente com dois termos e perguntam-se qual é o superior: Flex flow e DAG flow. É aqui que a coisa fica interessante. Ambos atingem exatamente o mesmo resultado. Apenas oferecem developer experiences diferentes. O Flex flow é uma abordagem code-first. Encapsulas a tua lógica dentro de uma função ou classe Python standard, designas isso como entry point, e escreves raw code. O Prompt Flow simplesmente executa-o. O DAG flow, por outro lado, define o routing usando um ficheiro YAML. Ao listares explicitamente as funções como nodes e ligares os seus inputs e outputs em YAML, permites que a plataforma faça o render de uma representação visual da tua aplicação. Os DAG flows são altamente UI-friendly, tornando fácil inspecionar a arquitetura de relance. Se escolheres a abordagem DAG flow, vais trabalhar com três tipos específicos de flows. O primeiro é o Standard flow. Este é o teu pipeline de propósito geral, onde ligas tools, código Python e modelos para construir aplicações típicas. O segundo é o Chat flow. Este baseia-se diretamente no Standard flow, mas é especificamente adaptado para aplicações conversacionais. Adiciona suporte nativo para a gestão do chat history e configura automaticamente os inputs e outputs de chat necessários. O terceiro tipo é o Evaluation flow. Não usas este flow para servir utilizadores finais. Em vez disso, corres um Evaluation flow contra os outputs dos teus Standard ou Chat flows. Funciona como um mecanismo de teste para calcular métricas como precisão factual ou relevância com base nos dados que o teu flow principal produziu. Quer definas a tua lógica em Python puro ou a ligues visualmente com YAML, a tua aplicação LLM é, em última análise, apenas um pipeline a fazer o routing de texto entre sistemas externos. Domina o grafo, e controlas a aplicação. É tudo por este episódio. Obrigado por ouvires, e continua a desenvolver!

Olá, daqui é o Alex da DEV STORIES DOT EU. Prompt Flow: O Guia Completo, episódio 3 de 14. Desenhaste o workflow perfeito para a tua aplicação de IA, mas um blueprint por si só não processa dados. Precisas de componentes que realmente executem o trabalho, como fazer fetch de URLs, formatar strings e chamar APIs. Se os flows são o blueprint da tua aplicação, as tools são os tijolos. Hoje, vamos olhar para as Tools. No Prompt Flow, as tools são os blocos de construção fundamentais e executáveis de um flow. Cada node no teu graph é uma tool. Quando o teu flow corre, está simplesmente a passar dados de uma tool para a seguinte. Embora possas estender a plataforma, existem três built-in tools que vais usar em quase todos os projetos: a Python tool, a Prompt tool e a LLM tool. Vamos analisar um cenário prático para ver como elas se encaixam. Queres uma aplicação que vá buscar uma webpage, formate o raw text e gere um resumo. Primeiro, precisas de obter o conteúdo da webpage. Usas a Python tool. Esta tool permite-te escrever scripts Python customizados e atua como a tua ponte para o mundo exterior. Escreves um pequeno script que recebe um URL como input, faz um pedido HTTP e devolve o raw text da página. A Python tool trata da execução e passa esse raw text para a frente como um output. A seguir, precisas de preparar as instruções para o modelo de linguagem. Usas a Prompt tool. Esta tool recebe inputs de texto, como o raw text da tua Python tool e um system prompt que define a persona da IA, e formata-os numa única string limpa. Esta é a parte que interessa. A Prompt tool não chama um modelo de IA. Ela estritamente prepara e formata texto. Separar este passo torna o teu flow muito mais fácil de ler e testar, especialmente quando lidas com prompts complexos e de várias partes. Finalmente, envias essa string preparada para o modelo usando a LLM tool. Esta tool trata da ligação real a um endpoint de Large Language Model. Passas-lhe a string formatada da tua Prompt tool, configuras os parâmetros do modelo, como a temperature, e ela devolve o resumo gerado. A LLM tool faz o trabalho pesado de formatar o payload da API e de interagir com o provider. Embora estas três cubram a maioria dos casos de uso principais, não são as tuas únicas opções. O Prompt Flow suporta partner tools fornecidas por terceiros. Um exemplo comum é a Vector DB Lookup tool, que pesquisa em bases de dados vetoriais por texto semelhante com base em embeddings. Também podes instalar packages customizados ou criar as tuas próprias tools para integrações altamente específicas. Independentemente da sua origem, todas operam exatamente com o mesmo princípio: recebem inputs, executam uma função específica e devolvem um output. A coisa mais importante a reter é a estrita separation of concerns. Não escrevas código Python para formatar prompts, e não uses a LLM tool para concatenar strings. Usar a built-in tool certa para o seu propósito exato mantém os teus graphs limpos e fáceis de fazer debug. Obrigado por estares aí. Espero que tenhas aprendido algo novo.

Olá, daqui é o Alex da DEV STORIES DOT EU. Prompt Flow: O Guia Completo, episódio 4 de 14. Nada arruína um deploy em produção mais rápido do que uma API key acidentalmente comitada para o controlo de versões. Mesmo que evites esse desastre, gerir credenciais entre ambientes de desenvolvimento local e na cloud leva muitas vezes a ficheiros de configuração confusos e a riscos de segurança. Gerir secrets com connections resolve isto, ao isolar completamente os teus dados sensíveis da lógica do teu flow. Uma connection no Prompt Flow é um recurso dedicado que armazena os endpoints e as credenciais necessárias para interagir com serviços externos. Se o teu flow precisa de chamar um language model externo, pesquisar na web usando um serviço externo, ou consultar uma base de dados remota, ele precisa de autorização. Em vez de escreveres API keys diretamente nos teus scripts de Python ou ficheiros de configuração, tu crias uma connection. O teu flow depois referencia essa connection pelo nome. Ao usares connections, desacoplas os teus dados confidenciais da tua lógica de execução. O teu código só sabe que precisa de uma connection chamada, por exemplo, main_language_model. Ele não conhece a API key em si. Vamos ver como isto funciona ao migrar um projeto do teu portátil para a cloud. Quando desenvolves localmente, as tuas connections são guardadas no teu disco local. Para manter a segurança, o Prompt Flow encripta os valores dos secrets usando uma encryption key local. Podes construir e testar o teu flow usando este setup local, sem deixares keys em plaintext expostas no teu diretório de trabalho. Quando estiveres pronto para fazer o deploy deste flow para o Azure AI, o environment muda, mas o teu código não. No Azure AI, as connections são suportadas de forma segura pelo Azure Key Vault. Os secrets são guardados e geridos na infraestrutura do Key Vault, protegidos por políticas de acesso rigorosas. Esta é a parte que interessa. Como o teu flow apenas referencia a connection pelo nome, a transição de um ambiente local para a cloud requer zero alterações à lógica do teu flow. Tu simplesmente garantes que existe uma connection com o nome idêntico no teu workspace do Azure. Quando o flow é executado na cloud, ele pede a main_language_model. O sistema interceta esse pedido de forma transparente e fornece as credenciais suportadas pelo Key Vault, em vez das encriptadas locais. O teu código permanece limpo e agnóstico ao ambiente. O Prompt Flow categoriza estas connections em dois tipos principais. O primeiro são as connections fortemente tipadas. Estes são templates built-in para serviços amplamente utilizados, como o Azure OpenAI. Eles fornecem campos predefinidos para o URL do endpoint, a API key e o tipo de API. O sistema sabe exatamente como lidar com estes campos, o que mantém a configuração de tools standard simples. O segundo tipo é a custom connection. Quando precisas de integrar uma API interna da empresa ou um serviço de terceiros que não tem um template built-in, usas uma custom connection. Esta atua como um dicionário flexível onde defines os teus próprios pares key-value. Podes marcar explicitamente keys específicas como secrets. Uma vez marcados, esses custom secrets recebem exatamente a mesma encriptação local e proteção do Key Vault que as built-in connections. O valor principal das connections é que elas atuam como uma camada de abstração rigorosa para autenticação, garantindo que o teu flow permanece completamente portátil e que os teus secrets permanecem seguros em qualquer ambiente de execução. É tudo por este episódio. Obrigado por ouvires, e continua a desenvolver!

Olá, daqui é o Alex da DEV STORIES DOT EU. Prompt Flow: O Guia Completo, episódio 5 de 14. Para de enterrar os prompts do teu language model dentro de strings Python gigantes. Quando fazes hardcode de prompts na lógica da tua aplicação, monitorizar alterações, correr testes standalone e colaborar com prompt engineers torna-se um autêntico pesadelo. A solução é a Prompty Specification. Um Prompty é um formato standard para gerir prompts. Ele tira o teu prompt do código e passa-o para um único ficheiro markdown com controlo de versões e uma extensão dot prompty. O ficheiro está dividido em duas secções distintas. No topo, tens o front matter em YAML. Na parte de baixo, tens um prompt template formatado em Jinja. Três traços separam os dois. O bloco YAML funciona como o centro de controlo. Podes definir metadados básicos, como o nome, a descrição e o autor. Mais importante ainda, é lá que fica a configuração do modelo. Especificas o tipo de API, como chat ou completion. Defines os detalhes de configuração, como apontar para um deploy de GPT-3.5 no Azure OpenAI. Também fixas os parâmetros do modelo logo aqui. Se um prompt específico precisar de uma temperature de zero ponto sete e um limite de max tokens de mil, declaras isso no YAML. Isto liga as settings de execução diretamente ao texto do prompt, garantindo que o prompt se comporta de forma consistente, não importa onde seja usado. A secção YAML também define inputs e sample data. Se o teu prompt espera uma variável dinâmica, listas essa variável aqui e dás sample values. Isto torna o ficheiro totalmente self-contained. Qualquer pessoa que o abra sabe exatamente que dados ele espera, sem ter de fazer reverse-engineering ao código da tua aplicação. Abaixo do YAML e dos três traços, fica o prompt template propriamente dito. Esta secção usa a sintaxe Jinja2 para injetar dinamicamente os inputs que definiste acima. Como os language models modernos usam interfaces de chat, o template suporta designações de roles. Defines as roles usando um formato de texto simples, separando as system instructions dos user inputs. Imagina um cenário de chat minimalista onde queres um prompt que cumprimente um utilizador pelo seu primeiro nome. No topo do teu ficheiro dot prompty, escreves o front matter em YAML. Defines a secção do teu modelo, configurando o tipo de API para chat e apontando a configuração para um deploy de GPT-3.5. A seguir, adicionas uma secção de inputs a declarar uma variável chamada first name. Também adicionas um bloco de sample onde o first name é definido como Jane. Digitas três traços para terminar o front matter em YAML. Agora constróis o template. Digitas a palavra system seguida de dois pontos, e depois dás ao modelo as suas instruções de base, como dizer-lhe para ser um assistente útil. Abaixo disso, digitas a palavra user seguida de dois pontos. Finalmente, escreves a saudação, colocando a variável first name entre chavetas duplas para que o Jinja engine saiba onde injetar o texto. Agora tens um asset completo e reutilizável. Tratar os prompts como ficheiros self-contained, em vez de strings soltas no teu código, é o primeiro passo para uma prompt engineering rigorosa, porque força um contrato claro entre a aplicação que fornece os dados e o language model que gera a resposta. Obrigado por passares uns minutos comigo. Até à próxima, fica bem.

Olá, daqui fala o Alex da DEV STORIES DOT EU. Prompt Flow: O Guia Completo, episódio 6 de 14. Crias um prompt template cuidadosamente ajustado para produção, mas quando o queres testar com um modelo mais económico ou ajustar a temperatura para um edge case específico, dás por ti a editar manualmente o ficheiro de origem. Um template estático cria fricção quando o teu ambiente ou a tua lógica precisam de mudar on the fly. Essa fricção é exatamente o que a Dynamic Prompty Execution foi desenhada para eliminar. Um asset Prompty normalmente define as settings do modelo, como o nome do deployment, a ligação à API e os parâmetros dentro do seu bloco de header. No entanto, fazer hardcode destes valores restringe a forma como usas o ficheiro em diferentes ambientes. A execução dinâmica permite-te tratar o ficheiro Prompty como uma base layer flexível, fazendo override das suas configurações diretamente em Python ou através da command line em runtime. Para correres um ficheiro Prompty em Python, usas a função load prompty da core library do Prompt Flow. Passas o file path para esta função, e ela devolve um objeto callable em memória. Para o executares, basta chamares esse objeto, passando as tuas variáveis de prompt como keyword arguments standard. A library trata da compilação e da API call, devolvendo o output de texto final. É exatamente neste ponto que a execução dinâmica prova o seu valor. Podes intercetar a execução para fazeres override das settings do modelo sem tocares no ficheiro original. Imagina que tens um Prompty configurado para um deployment standard do Azure OpenAI, mas, para um batch job específico, precisas de o apontar para um endpoint diferente do Azure e aumentar a temperatura para obteres respostas mais variadas. Em vez de duplicares o ficheiro, defines um dicionário no teu código Python com as tuas novas settings. Adicionas o teu endpoint alternativo e o teu novo valor de temperatura a este dicionário. Depois, quando chamas o teu objeto Prompty carregado, passas este dicionário para o keyword argument model, juntamente com os teus inputs de prompt standard. O runtime do Prompt Flow faz merge do teu dicionário com a configuração do ficheiro base. Os teus overrides dinâmicos têm precedência, o prompt é executado com as novas settings, e o ficheiro original permanece completamente inalterado. Isto permite-te trocar API keys, alterar os max tokens, ou redirecionar o target do modelo programaticamente, com base no state da tua aplicação. Às vezes, não queres escrever um script em Python apenas para ver se um prompt dá um bom resultado. Para uma validação rápida, podes testar um ficheiro Prompty diretamente do teu terminal. Usas o comando pf flow test, fornecendo o path para o teu ficheiro usando a flag source. Podes acrescentar a flag inputs para passares as tuas variáveis diretamente para o comando como pares key-value. A command line interface executa o Prompty e imprime a resposta do modelo diretamente no standard output. Isto dá-te um feedback loop imediato durante o desenvolvimento, sem teres de escrever wrapper code. O verdadeiro valor de um asset Prompty não está em bloquear as configurações, mas sim em isolar o texto do prompt do ambiente de execução. Ao injetar overrides de modelo dinamicamente em runtime, um único ficheiro pode servir perfeitamente a tua sandbox de testes local, os teus pipelines automatizados e os teus endpoints de produção. É tudo por este episódio. Obrigado por ouvires, e continua a desenvolver!

Olá, daqui é o Alex da DEV STORIES DOT EU. Prompt Flow: O Guia Completo, episódio 7 de 14. Podes pensar que usar uma framework especializada para grandes modelos de linguagem significa aprender uma interface visual complexa ou manter ficheiros de configuração enormes. Mas se já sabes escrever um script em Python, já sabes o suficiente para construir uma aplicação totalmente rastreável. Os Flex Flows baseados em funções resolvem completamente esta tensão. No desenvolvimento standard do Prompt Flow, constróis um Grafo Acíclico Direcionado. Essa estrutura é altamente eficaz para pipelines rígidos de várias etapas, mas às vezes os developers querem escrever código Python puro sem se adaptarem a um sistema visual de nodes. Os Flex Flows permitem-te fazer exatamente isso. Encapsulas a lógica da tua aplicação LLM dentro de funções Python standard, e a plataforma trata do tracking e da orquestração em segundo plano. Considera a abordagem baseada em funções. Começas por escrever uma função Python normal. Dá-lhe um nome descritivo, como chat, e define os seus inputs, como receber uma pergunta como parâmetro de string. Dentro desta função, escreves a tua lógica como farias normalmente. Podes carregar um ficheiro Prompty para obter a tua system message, inicializar o cliente do modelo de linguagem, passar a pergunta para o modelo e, em seguida, devolver a resposta de texto como uma string. Nesta fase, tens simplesmente um script Python standard. Corre localmente, é fácil de testar e não requer conhecimentos especiais de nenhuma framework. Para transformar este script Python puro num componente rastreável do Prompt Flow, importas o decorator trace do package de tracing do promptflow. Colocas este decorator diretamente acima da tua função de chat. Quando corres o teu código, este decorator diz ao sistema para monitorizar a execução silenciosamente. Regista automaticamente os inputs passados à função, o output de texto devolvido, o tempo exato de execução e quaisquer erros internos. Se aplicares o decorator trace a outras funções auxiliares dentro do teu script, o sistema constrói uma call tree completa. Obténs a observabilidade total de um flow visual, incluindo a capacidade de ver o trace de execução na interface de utilizador local, sem mudares a forma como estruturas a tua lógica. Agora, as tools precisam de uma forma de saber que esta função específica é o entry point da tua aplicação. Forneces isso criando um único e muito curto ficheiro de configuração chamado flow.flex.yaml no mesmo diretório do teu código. Este ficheiro não define um grafo de routing complexo. Só precisa de uma informação crucial, que é o entry mapping. Escreves a palavra entry seguida do nome do teu module Python, dois pontos, e o nome da tua função. Se o teu ficheiro se chamar app.py e a tua função for chat, o teu valor de entry é simplesmente app dois pontos chat. Quando testas ou corres este flow usando a command line tool do Prompt Flow ou a extension do VS Code, o sistema lê esse ficheiro yaml. Procura a função chat no teu module app, injeta os inputs fornecidos, corre o teu código Python puro e recolhe os traces gerados pelo decorator. O verdadeiro poder dos flex flows baseados em funções é que eliminam a fricção entre prototipar um script e fazer o deploy de uma aplicação em produção; a tua lógica Python pura permanece totalmente sob o teu controlo, enquanto um único decorator e um ficheiro de configuração de duas linhas desbloqueiam uma observabilidade de nível enterprise. É tudo por este episódio. Obrigado por ouvirem, e continuem a construir!

Olá, daqui fala o Alex da DEV STORIES DOT EU. Prompt Flow: O Guia Completo, episódio 8 de 14. Fazes o deploy de uma nova app de language model, mas cada vez que um utilizador envia uma mensagem, demora segundos preciosos só para estabelecer a ligação à base de dados e carregar as credenciais do client. Quando a tua app precisa de manter uma ligação persistente ou lembrar-se do histórico de chat, um script standalone falha porque começa completamente do zero em cada run. A resposta para este problema são os Flex Flows: Class-Based Development. Quando constróis aplicações que escalam, o state management torna-se uma preocupação principal. Se o teu flow depende de um recurso externo, como um client do Azure OpenAI, inicializar esse client requer ler secrets, verificar endpoints e alocar memória. Se colocares essa lógica dentro de uma sequência de execução básica, pagas esse custo pesado de startup cada vez que entra um request. Usar uma classe Python como entry point para o teu Flex Flow permite-te separar fundamentalmente a tua lógica de inicialização da tua lógica de execução. Um class-based flow depende de dois métodos standard de Python para gerir este lifecycle. O primeiro é o construtor, ou o método init. Esta é a tua fase de setup. O Prompt Flow corre este método exatamente uma vez quando o flow é carregado para a memória pela primeira vez. É aqui que fazes todo o trabalho pesado. O segundo método é o método call. Esta é a tua fase de execução, e corre sempre que o flow é triggered por um request do utilizador. Imagina uma classe de chat flow. Defines o teu método init para aceitar um objeto de connection do Azure OpenAI e uma string de system prompt. Dentro do método init, crias o teu client do Azure OpenAI e guardas-o como uma propriedade na própria instância da classe. O client está agora pronto e à espera. A seguir, defines o teu método call. Este método aceita uma nova pergunta do utilizador e uma lista de mensagens passadas que representam o histórico de chat. Como o client já está totalmente inicializado, o método call formata imediatamente o prompt, envia o histórico de chat para o language model e devolve a resposta. A execução é rápida porque o setup dispendioso do client foi completamente bypassed. Para que isto funcione, o Prompt Flow precisa de saber como instanciar a tua classe. Configuras isto criando um ficheiro YAML para o teu flow. O entry point neste ficheiro de configuração usa um formato específico, nomeando o módulo Python seguido de dois pontos e do nome da tua classe. Esta é a parte que interessa. A tua configuração YAML não aponta apenas para a classe, ela define os parâmetros exigidos pelo teu método init. Se o construtor da tua classe requer uma connection do Azure e um nome de modelo, declaras esses inputs no ficheiro YAML numa secção init dedicada. Quando o engine do Prompt Flow arranca, lê o YAML, injeta esses parâmetros configurados no construtor da tua classe e, depois, mantém esse objeto instanciado vivo na memória para lidar com incoming calls. Testar um class-based flow localmente é incrivelmente simples, porque depende do comportamento standard do Python. Não precisas de um test harness complexo. Basta escreveres um script Python standard, importares a tua classe, criares uma instância passando mock connections ou credenciais locais para o construtor e, depois, invocares o objeto diretamente, passando-lhe uma mensagem de teste. Podes fazer debug da lógica de setup e da lógica de execução de forma independente. A principal conclusão é que os class-based flows dão-te a estrutura arquitetural para separar o trabalho pesado da inicialização do trabalho repetitivo da execução, mantendo o teu state persistente e as tuas respostas rápidas. Se achas estes episódios úteis e queres apoiar o programa, podes procurar por DevStoriesEU no Patreon. É tudo por este episódio. Obrigado por ouvires, e continua a desenvolver!

Olá, daqui é o Alex da DEV STORIES DOT EU. Prompt Flow: O Guia Completo, episódio 9 de 14. Às vezes, olhar para uma parede de código não é suficiente para compreender uma aplicação complexa. Quando prompts, scripts e API calls interagem de dezenas de maneiras, precisas de ver fisicamente os dados a moverem-se entre eles para detetar os bottlenecks. Os DAG flows são a resposta para equipas que querem uma clareza arquitetónica explícita. DAG significa Directed Acyclic Graph. No Prompt Flow, um DAG flow é um método para construir aplicações de IA ligando diferentes tools como nodes. Em vez de escreveres um único script grande, defines a estrutura da tua aplicação num ficheiro chamado flow dot dag dot yaml. Este ficheiro funciona como o blueprint principal. Ele declara os inputs iniciais, os steps individuais e os outputs finais da tua aplicação. Cada step num DAG flow é chamado de node. Um node representa uma tool específica a executar uma única tarefa. Podes ter um node que corre um Python snippet, outro node que formata um prompt, e um terceiro node que faz uma call a um Large Language Model. O ficheiro yaml descreve como estes nodes se relacionam entre si através de dependências de input e output. Este mapeamento de dependências é o que faz o flow funcionar. Não dizes manualmente ao sistema em que ordem executar os steps. Em vez disso, especificas que o node B requer o output do node A. Como o node B não pode começar até que o node A termine, uma ordem de execução forma-se naturalmente. Se adicionares um node C que depende apenas do user input inicial, o Prompt Flow vai reconhecer que não precisa de esperar pelo node A ou B. Ele vai correr o node C em paralelo automaticamente. O engine lê o ficheiro yaml, resolve o graph e trata da orquestração. Escrever e manter este ficheiro yaml à mão pode tornar-se difícil à medida que a tua aplicação cresce. É por isso que a maioria dos developers usa a VS Code extension do Prompt Flow. Esta extension lê o teu ficheiro flow dot dag dot yaml e renderiza uma user interface visual drag-and-drop. Podes ver a tua aplicação como um mapa literal de blocos ligados. Considera um cenário concreto. Estás a construir uma aplicação para ler relatórios financeiros e escrever pequenos resumos executivos. No editor visual, crias um node de Python tool e dás-lhe o nome de Extract Text. Ao lado, adicionas um node de LLM tool chamado Summarize. Em vez de escreveres código para gerir o state entre estas duas operações, usas a interface. Clicas no output port do node Extract Text e arrastas uma linha até ao input port do node Summarize. Acabaste de ligar visualmente o data path. A extension atualiza instantaneamente o ficheiro yaml subjacente para registar essa ligação. Tens a velocidade e a clareza de um visual low-code builder, mas continuas a gerar um ficheiro de configuração em plain text que podes seguir em version control. Esta abordagem visual impõe disciplina arquitetónica. O graph é acíclico, o que significa que os dados só podem fluir para a frente. Não há infinite loops. Os dados entram, passam pela tua sequência de tools, e saem. Este flow direcional estrito torna o debugging simples. Se um resumo final parecer errado, podes abrir o visual graph, clicar na ligação entre os nodes de extração e sumarização, e inspecionar a string exata de texto que passou por esse wire. Sabes exatamente de onde os dados vieram e para onde foram. A verdadeira vantagem de um DAG flow é que o diagrama de arquitetura do teu sistema e a tua aplicação executável são exatamente a mesma coisa. É tudo por este episódio. Obrigado por ouvires, e continua a construir!

Olá, daqui é o Alex da DEV STORIES DOT EU. Prompt Flow: O Guia Completo, episódio 10 de 14. Quando um modelo de linguagem devolve uma resposta alucinada e sem sentido, como é que sabes se foi o próprio modelo que falhou, ou se a tua lógica de formatação do prompt tinha um bug? Podes espalhar print statements por toda a tua aplicação, mas isso torna-se impossível de manter à medida que a aplicação cresce. Fazer o tracing das interações com o LLM resolve isto, ao capturar o contexto exato de cada execução. O tracing transforma uma aplicação LLM de caixa preta numa sequência de eventos transparente e passível de debug. Regista precisamente que dados entram numa function, o que sai, e quanto tempo demora a execução. Neste ecossistema, geres isto com o package promptflow-tracing. Os dados que gera baseiam-se na especificação OpenTelemetry, o que significa que os teus registos de execução seguem um formato standard da indústria para observabilidade. Para capturar as interações de base com um modelo, usas uma function chamada start trace. Se chamares esta function logo no início do teu script Python, o Prompt Flow instrumenta automaticamente os clients de modelo suportados. Por exemplo, se estiveres a usar o package Python standard da OpenAI, não precisas de modificar as tuas API calls de todo. O tracer interceta silenciosamente a interação, fazendo o log da system message, do user prompt, dos parâmetros específicos do modelo e da response string final. Capturar a API call é apenas metade da batalha. A lógica que leva a essa call é geralmente onde os bugs se escondem. Para fazeres o tracing da lógica da tua própria aplicação, aplicas o decorator trace às tuas custom functions. Considera uma function chamada math to code. Esta function recebe um utilizador a descrever um problema de matemática, vai buscar o contexto necessário, constrói um prompt e, finalmente, pede código Python ao GPT-4. Ao colocares o decorator trace diretamente acima da definição da function math to code, dizes ao Prompt Flow para registar cada execução deste bloco específico de lógica. Isto fará o log da input string do utilizador, do código final devolvido e da latência de toda a operação. Como também correste o start trace no topo do teu ficheiro, o sistema entende a relação entre o teu código e a call ao modelo. Ele constrói um registo hierárquico. A tua function math to code torna-se o parent span, e a call interna da OpenAI torna-se um child span aninhado lá dentro. Podes ver esta hierarquia usando a Trace UI local. Quando corres um script com tracing, o Prompt Flow inicia um servidor local que podes abrir no teu web browser. Esta interface dá-te uma timeline visual do flow da tua aplicação. Podes selecionar o parent span math to code para verificar os argumentos que recebeu. Depois, podes selecionar o child span da OpenAI para inspecionar a raw prompt string exata que foi enviada com sucesso para o modelo através da rede. Se a tua lógica de montagem de contexto se esqueceu de uma variável, vais ver o espaço vazio na raw prompt imediatamente. O verdadeiro poder do tracing não é apenas recolher execution logs, mas provar definitivamente o que aconteceu na fronteira exata entre o código da tua aplicação e o modelo externo. É tudo por este episódio. Obrigado por ouvires, e continua a desenvolver!

Olá, daqui é o Alex da DEV STORIES DOT EU. Prompt Flow: O Guia Completo, episódio 11 de 14. Acabaste de passar três meses a construir uma aplicação complexa com o LangChain. A lógica funciona na maior parte, mas quando um agente ocasionalmente entra num mau loop ou perde o context, descobrir exatamente onde descarrilou é um pesadelo, e reescrever tudo só para ter melhores logs está completamente fora de questão. O Advanced Tracing para LangChain e AutoGen é como resolves isto diretamente. Quando constróis com frameworks de orquestração, ganhas velocidade através da abstração. A framework esconde os detalhes chatos do sequenciamento de prompts, da execução de tools e do parsing. Mas a abstração cria inerentemente uma black box. Quando o teu agente devolve uma resposta confusa, precisas de ver a sua chain of thought interna. Precisas de saber o sub-prompt exato que ele gerou, a raw API response que recebeu e que tool call específica falhou. O Prompt Flow inclui uma capacidade de tracing standalone desenhada exatamente para isto. Não exige que uses o Prompt Flow para a tua lógica ou execução. Manténs o teu código LangChain ou AutoGen existente exatamente como está. Estás apenas a ligar o sistema de tracking do Prompt Flow à tua aplicação externa. Pensa no teu script Python existente a correr um agente LangChain. Para teres visibilidade total, não tocas nas definições da tua chain. Vais simplesmente ao topo do teu ficheiro de execução principal. Importas a função de setup de trace do módulo prompt flow, e chamas essa função uma vez antes do teu agente começar a fazer o seu trabalho. Esse único comando é a integração toda. Quando chamas essa função, ela instrumenta o teu ambiente. Como o tracing do Prompt Flow é construído sobre os standards do OpenTelemetry, ele sabe como ouvir os eventos específicos disparados por estas frameworks populares. À medida que a tua aplicação LangChain corre, a instrumentação interceta automaticamente as API calls subjacentes. Captura os inputs, a duração da execução, os outputs e o uso de tokens para cada passo. Isto também se aplica perfeitamente ao AutoGen. Setups multi-agent no AutoGen são notoriamente difíceis de fazer debug, porque múltiplos agentes enviam mensagens uns aos outros de forma autónoma. Fazer o tracking de quem passou que context a quem, normalmente significa vasculhar paredes gigantes de texto no terminal. Ao inicializar o trace no topo do teu script AutoGen, cada troca de mensagens é automaticamente capturada e estruturada. Assim que o teu script termina a execução, abres a Trace UI local do Prompt Flow. Em vez de fazeres scroll por print statements na consola, tens uma timeline visual. Vês uma execution tree clara. Clicas na run do agente de topo, expandes o node, e vês a sequência de LLM calls aninhadas e execuções de tools. Se um agente alucinou no passo quatro, podes clicar diretamente no passo quatro para ler o texto exato e não formatado que foi enviado para o modelo. Ganhas visibilidade completa sobre uma framework opaca sem teres de migrar uma única linha da tua business logic. A verdadeira vantagem aqui é a liberdade de arquitetura; podes orquestrar a tua aplicação com a framework que melhor se adapta à tua equipa, enquanto manténs o teu debugging e observabilidade centralizados numa interface visual e limpa. Como sempre, obrigado por ouvires. Vemo-nos no próximo episódio.

Olá, daqui é o Alex do DEV STORIES DOT EU. Prompt Flow: O Guia Completo, episódio 12 de 14. O teu prompt funcionou perfeitamente na tua pergunta de teste, mas o que acontece quando o corres contra dez mil queries reais de utilizadores? Geralmente, falha. Testar um prompt manualmente com dois exemplos é fácil, mas provar que funciona em centenas de edge cases exige algo mais robusto. É aí que entra o Scaling Up: Batch Runs with Data. Um batch run pega no teu flow individual e executa-o num grande dataset. Isto faz-te passar da construção da lógica para a sua verificação à escala. Em vez de escreveres inputs numa user interface, tu disparas este processo usando a command line interface. O comando principal é pf run create. Ao executares isto, estás a instruir o Prompt Flow a arrancar uma nova run instance, ler um flow directory específico e alimentá-lo com um ficheiro que contém todos os teus test records. O motor processa estes records executando todo o teu flow graph de forma independente para cada linha do teu dataset. O formato de dados necessário para este ficheiro de input é JSONL. JSONL significa JSON Lines. Se estás habituado ao JSON standard, podes estar à espera de um único grande array a envolver todos os teus objects. O JSONL descarta o array. Cada linha no ficheiro de texto é o seu próprio JSON object válido e independente, representando exatamente um test case. Este formato é muito popular em machine learning e data pipelines porque é leve e faz stream facilmente. O motor consegue lê-lo linha a linha sem carregar um ficheiro enorme para a memória de uma só vez. Considera um flow de web classification. O teu flow foi desenhado para receber um endereço web, fazer scrape do conteúdo e usar um language model para o categorizar. O flow graph espera uma input string específica chamada url. Tu queres testar esta lógica contra cem sites diferentes para ver como lida com edge cases. Tu constróis o teu ficheiro JSONL. Cada linha contém um JSON object com uma key, talvez chamada web link, que guarda o endereço de destino. Para iniciar o batch run, escreves pf run create. Especificas o teu flow directory usando a flag flow, e apontas para o teu ficheiro JSONL usando a flag data. Mas há uma incompatibilidade estrutural imediata. A lógica do teu flow exige estritamente um input chamado url, enquanto o teu data file fornece um field chamado web link. Se correres o comando agora mesmo, vai falhar. O motor não adivinha quais data fields pertencem a quais flow inputs. Tu resolves esta discrepância usando a column mapping flag. Esta flag diz ao execution engine exatamente como ligar as keys no teu ficheiro JSONL aos input nodes específicos do teu flow. Nos teus command line arguments, escreves o nome do flow input, um sinal de igual, e depois uma referência à data column. O Prompt Flow usa uma binding syntax específica para estas referências. Escreves um cifrão, seguido da palavra data, um ponto, e depois o nome da coluna do teu ficheiro. Para o cenário de web classification, fazes o map escrevendo url igual a cifrão data ponto web link. Esta instrução explícita faz o bind do data field ao requisito do flow. O motor vai agora extrair a string web link da linha um do teu ficheiro JSONL e injetá-la no input url do teu flow. Depois repete exatamente esse processo para a linha dois, linha três, e por aí fora até que todo o ficheiro seja processado. Podes mapear múltiplos inputs desta forma. Se o teu flow espera um url e um user id, simplesmente adicionas outra instrução de mapping ao mesmo comando. Desacoplar a tua test data dos teus flow inputs usando column mapping explícito significa que nunca tens de alterar o teu core code só para correr um novo dataset. Obrigado por passares uns minutos comigo. Até à próxima, fica bem.

Olá, daqui é o Alex da DEV STORIES DOT EU. Prompt Flow: O Guia Completo, episódio 13 de 14. Não podes escrever um unit test standard a garantir que a resposta de um large language model é igual a uma string exata. Se o output muda de cada vez, como é que provas matematicamente que a tua aplicação realmente funciona antes de fazeres o deploy? A resposta é o Paradigma de Avaliação. Na engenharia de software tradicional, o unit testing é determinístico. Passas um input específico para uma função e esperas um output exato. Os large language models são estocásticos. São inerentemente imprevisíveis. Pede a um modelo para classificar uma webpage, e ele pode dar output da palavra desporto, ou pode dizer que a categoria é desporto, ou pode simplesmente dar-te um emoji relacionado. Uma test assertion standard vai falhar em duas dessas três situações, mesmo que o modelo tenha, no fundo, acertado na resposta. Para provares que está pronto para release, tens de ir além dos unit tests e adotar a avaliação estatística. No Prompt Flow, isto é tratado por um Evaluation Flow. Um evaluation flow é apenas um flow normal, mas em vez de gerar texto para um end user, o seu único trabalho é avaliar o output de outro flow. Ele pega nas previsões que a tua aplicação principal gerou, compara-as com um conjunto conhecido de respostas corretas e dá output de métricas calculadas. Vamos tornar isto mais concreto. Imagina que acabaste de concluir uma batch run de um flow de classificação web. Ele processou cem endereços de sites e deu output de uma categoria prevista para cada um. Agora precisas de saber exatamente qual é a precisão dessas previsões. Pegas nos outputs dessa base run e passas tudo para um novo evaluation flow dedicado, desenhado para calcular a precisão da classificação. Podes disparar isto a partir da command line usando o comando run create. Especificas o teu evaluation flow, mas em vez de lhe dares simplesmente um ficheiro estático com novos inputs, passas-lhe uma referência para a tua batch run anterior. O evaluation flow precisa de duas informações para fazer o seu trabalho. Precisa da previsão do modelo, e precisa da ground truth, que é a resposta historicamente correta. Tu forneces um data mapping que liga estes pontos. Dizes ao sistema para mapear o input de previsão do evaluation flow para o output de categoria da tua base run. A seguir, mapeias o input da ground truth para a coluna da true label real localizada no teu test dataset original. Esta é a parte que interessa. O evaluation flow é executado linha a linha, percorrendo todo o histórico da run anterior. Para cada linha, ele olha para o que o teu flow principal previu e compara com a ground truth. Ele atribui um score para essa interação específica. No nosso cenário de classificação, isso pode ser um simples um para um match e um zero para uma falha. Outros evaluation flows podem usar um language model para avaliar a qualidade de um resumo numa escala de um a cinco. Assim que o flow termina de avaliar cada uma das linhas, ele agrega esses scores individuais numa métrica final e geral. Não ficas apenas com um log gigante de uns e zeros. Ficas com um número definitivo de top-level, como uma accuracy geral de noventa e dois por cento. Podes então ver estas métricas agregadas para decidir se a versão atual da tua aplicação está pronta para produção. Já não tens de adivinhar se um ajuste no prompt melhorou o teu sistema; tens provas estatísticas de exatamente quanto melhor ou pior ele se comporta em todo o teu dataset. Obrigado por ouvires. Até à próxima!

Olá, daqui fala o Alex da DEV STORIES DOT EU. Prompt Flow: O Guia Completo, episódio 14 de 14. Construíste, fizeste trace e avaliaste o teu flow de modelo de linguagem, e ele funciona perfeitamente. Mas, neste momento, está apenas no teu ambiente de desenvolvimento, completamente isolado dos teus utilizadores reais. Tirar esse flow do teu IDE e transformá-lo num serviço estável e acessível é exatamente o que vamos abordar hoje, ao passar flows para produção. Em repouso, um prompt flow é simplesmente uma pasta. Contém um ficheiro YAML de configuração e os teus scripts Python ou templates Jinja. Para que essa pasta faça algo no mundo real, precisas de um ambiente de execução para carregar esses ficheiros e ficar à escuta de requests HTTP. Durante o desenvolvimento, provavelmente usaste o servidor local integrado. Executas um comando simples e ele levanta um endpoint local para testar inputs e outputs. Isto serve para verificar a lógica, mas não foi concebido para lidar com tráfego concorrente em produção, gerir memória de forma eficiente ou sobreviver a um crash do sistema. Para chegar à produção, precisas de containerização. O Prompt Flow foi construído para se integrar diretamente com o Docker. Em vez de escreveres o teu próprio web server do zero, usas as ferramentas do Prompt Flow para exportar o teu flow como um container Docker. Quando corres o processo de exportação, o sistema gera um Dockerfile. Este ficheiro define uma imagem base, copia o diretório do teu flow para dentro dela, instala as dependências exatas de Python listadas no teu ficheiro de requirements e configura um web server pronto para produção para servir o flow como uma REST API. Esta é a parte que interessa. Assim que o teu flow estiver num container Docker, deixa de ser uma experiência especial de machine learning e passa a ser um artefacto de software standard. Podes tratá-lo como qualquer outro microservice. Imagina um cenário concreto. Tens um chat flow de suporte ao cliente validado. Fazes build da imagem Docker e fazes push para o teu container registry privado. A seguir, fazes deploy dessa imagem num cluster Kubernetes. Escreves uma configuração de deploy standard a dizer ao Kubernetes para levantar três réplicas do teu container de chat flow, e colocas um load balancer à frente delas. Agora, a tua aplicação de frontend envia requests HTTP standard para o load balancer, que distribui o tráfego pelos teus containers. Se o teu chat flow for sobrecarregado com requests de utilizadores, o Kubernetes simplesmente faz scale up de mais instâncias do teu flow. Se não quiseres gerir um cluster Kubernetes, essa mesma imagem Docker funciona perfeitamente em serviços de plataforma geridos. Podes fazer deploy diretamente no Azure App Service ou em qualquer outro cloud provider que aloje containers. O flow não quer saber onde corre, desde que tenha um container runtime. Existe um padrão de deploy alternativo. Se não estiveres a construir um web service, podes distribuir um flow como uma aplicação executável. Isto empacota o flow e as suas dependências de runtime num ficheiro executável standalone. Isto é útil se precisares de correr a lógica diretamente numa máquina cliente ou num edge device, evitando completamente a necessidade de instalar Python ou configurar um servidor. Passar um prompt flow para produção não requer hosting proprietário ou infraestrutura especializada de machine learning. Ao exportar para Docker, os teus flows de modelo de linguagem integram-se perfeitamente nos mesmos pipelines de continuous delivery e orquestradores de containers que já usas para os teus serviços de backend tradicionais. Se quiseres ir mais longe, recomendo que leias a documentação oficial do Prompt Flow, tentes fazer deploy de um container tu mesmo, ou visites devstories dot eu para sugerir tópicos que queiras ver em futuras séries. Gostaria de aproveitar um momento para te agradecer por ouvires — isso ajuda-nos muito. Tem um ótimo dia!