Apresentando Tracy: a biblioteca de observabilidade de IA para Kotlin

Ecossistema de IA Kotlin

Tracy é uma biblioteca Kotlin de código aberto que adiciona observabilidade de nível de produção a aplicativos com tecnologia de IA em minutos. Ele ajuda a depurar falhas, medir o tempo de execução e rastrear o uso do LLM em chamadas de modelo, chamadas de ferramenta e em sua própria lógica de aplicativo personalizada. Em última análise, a observabilidade abrangente garante que você tenha os dados exatos necessários para entender o comportamento do aplicativo no mundo real, analisar o desempenho desde tendências de alto nível até rastreamentos granulares e potencializar avaliações on-line e off-line abrangentes.

Funciona perfeitamente com pilhas Kotlin/LLM comuns (incluindo OkHttp e Qual clientes, bem como OpenAI, Antrópicoe Gêmeos uns) enquanto confia no OpenTelemetry nos bastidores. Esta arquitetura garante total flexibilidade sobre seus dados de rastreamento, permitindo a exportação padrão para qualquer back-end compatível (como JaegerZipkin ou Grafana) e integração direta com plataformas de engenharia LLM dedicadas, como Langfus e Tecido W&B.

Embora estruturas de IA completas, como Spring AI ou Koog, forneçam observabilidade integrada, as chamadas LLM devem ser feitas exclusivamente por meio de APIs de estrutura para serem rastreadas e não fornecem uma maneira fácil de rastrear o fluxo interno do aplicativo. Por outro lado, Tracy ajuda a monitorar o uso do LLM por meio de API ou instrumentação de cliente HTTP. Também ajuda a desenrolar o tempo e as relações causais entre os componentes de IA ou os estados internos do agente de IA, anotando funções Kotlin ou blocos de código.

Ao tornar o Tracy de código aberto, convidamos você a ajudar a ampliar sua funcionalidade – seja solicitando novas integrações para back-ends de IA e clientes de API ou enviando solicitações pull para implementá-los.

Componentes da observabilidade da IA ​​e como Tracy ajuda

Como engenheiros, quer estejamos adicionando observabilidade a um aplicativo existente ou construindo um novo do zero, queremos rastrear, armazenar e analisar o seguinte:

1. Metadados de chamada LLM, incluindo a API que está sendo chamada, o modelo e seus parâmetros. Opcionalmente, podemos querer rastrear entradas e saídas do LLM durante o desenvolvimento para depuração, garantindo ao mesmo tempo que não sejam rastreadas na produção.
2. Fluxo lógico do aplicativo que leva de e para chamadas LLM – onde uma determinada chamada se origina e quais ferramentas estão envolvidas.

Imagine um aplicativo de chat LLM muito simples que cumprimenta o usuário, utilizando ferramentas para tornar a saudação mais pessoal. Usando o cliente OpenAI, o código do aplicativo pode ser assim:

/** Interface for LLM tool */
interface Tool {
   /** Tool call */
   fun execute(): T
}

/** Gets the current user's name from the system */
class GetUserName() : Tool { ... }

/** Gets the current date and time */
class GetCurrentDateTime() : Tool { ... }

fun main() {
   // Create OpenAI-client using environment variables
   val client: OpenAIClient = OpenAIOkHttpClient.fromEnv()
   ...
   val params = ResponseCreateParams.builder()
       .model(ChatModel.GPT_4O_MINI)
       .maxOutputTokens(2048)
       .addTool(GetUserName::class.java)
       .addTool(GetCurrentDateTime::class.java)
       .input(ResponseCreateParams.Input.ofResponse(inputs))
       .build()

   // Get the response. 
   // In a real application, it would use a loop to process tool calls.
   val response: Response = client.responses().create(params)
   ...
   println(finalGreeting)
}

As coisas importantes a serem rastreadas aqui são:

1. O fato de o agente de saudação ter sido chamado.
2. O LLM chama.
3. As execuções da ferramenta.

Poderíamos usar o OpenTelemetry SDK básico, mas isso exigiria que adicionássemos código de instrumentação manualmente e levaria à repetição de código para rastreamentos de chamadas de ferramentas.

Em um cenário ideal, seríamos capazes de configurar o rastreamento de ferramentas uma vez e ter todas as implementações rastreadas automaticamente, garantindo que nunca acabaríamos em uma situação em que ferramentas recém-adicionadas não fossem rastreadas. Tracy torna esse cenário uma realidade.

Adicionando observabilidade com Tracy

Tracy fornece três APIs de alto nível que nos ajudam a cobrir totalmente nosso aplicativo de bate-papo com rastreamento.

Períodos com escopo definido

O withSpan A API permite que você crie períodos com escopo definido. Esses vãos são ativados automaticamente quando um bloco começa e terminam quando o bloco termina, garantindo o aninhamento e o tempo corretos.

fun main() {
   // Encapsulation into withSpan ensures that all nested events will be
   // traced as part of the greeting agent’s work.  
   withSpan("Greeting agent") {
       ...
   }  
}

Instrumentação de cliente LLM

As chamadas LLM são uma parte crucial de qualquer agente de IA. Eles definem o custo, a latência e a eficiência da aplicação e são as primeiras coisas a serem investigadas caso algo dê errado. É por isso que adicionar observabilidade a um cliente LLM deve ser simples e exigir alterações mínimas na base de código. Por exemplo, adicionar instrumentação ao seu cliente OpenAI é tão fácil quanto:

val client = OpenAIOkHttpClient.fromEnv()
// All calls made with the instrumented client are traced.
instrument(client)

Por padrão, a instrumentação do cliente rastreia apenas metadados. Para rastrear entradas e saídas do LLM, que podem conter dados confidenciais, você deve habilitar isso explicitamente de forma programática com:

TracingManager.traceSensitiveContent()

Alternativamente, você pode habilitá-lo em tempo de execução definindo o TRACY_CAPTURE_INPUT e TRACY_CAPTURE_OUTPUT variáveis ​​de ambiente para true.

Chamadas de ferramentas e rastreamento de funções

LLMs adoram ferramentas: eles ajudam os LLMs a concluir com eficácia tarefas determinísticas, salvar tokens e interagir com o ambiente em que operam. Como desenvolvedores, também amamos ferramentas, mas adicionar observabilidade para cada ferramenta LLM na base de código é uma tarefa mundana que é fácil de esquecer.

Embora os decoradores brilhem em tais cenários em estruturas Python, os desenvolvedores Kotlin anteriormente só podiam olhar com inveja. Tracy muda as coisas para melhor. Com o rastreamento baseado em anotação, basta adicionar o @Trace anotação para um método de interface para permitir o rastreamento em todas as classes de implementação. Se você tiver um método isolado que deseja rastrear, é igualmente fácil. O @Trace a anotação também funciona em métodos ou funções individuais.

/** Interface for LLM tool */
interface Tool {
   // All tool calls are now traced
   @Trace(name = "Tool Call")
   fun execute(): T
}

Juntando tudo

Capturar telemetria do aplicativo é apenas metade da batalha. A outra metade é encaminhá-lo para um back-end adequado, onde possa ser armazenado e analisado. Embora definitivamente recomendemos o uso de soluções de observabilidade direcionadas especificamente ao rastreamento LLM e forneçam suporte pronto para uso para Langfuse e W&B Weave, Tracy também oferece maneiras fáceis de enviar rastreamentos para qualquer back-end, arquivo ou console compatível com OpenTelemetry. O repositório contém vários exemplose o código completo do exemplo deste artigo está disponível aqui.

Configurar a exportação de telemetria para Langfuse leva segundos com Tracy. Como resultado, você obtém um rastreamento hierárquico do aplicativo com LLM e chamadas de ferramenta capturadas.

O que vem a seguir

Acreditamos verdadeiramente que, independentemente do ritmo do progresso do LLM nos próximos anos, a observabilidade continuará a ser uma pedra angular da engenharia de IA eficaz e fiável. Não importa quão bons sejam os LLMs subjacentes, os aplicativos que os utilizam ainda devem ser depurados e avaliados – tanto durante o desenvolvimento quanto em campo. Criamos o Tracy em resposta a essa demanda, com o objetivo de trazer observabilidade de IA de nível de produção para o ecossistema Kotlin.

E estamos apenas começando! Você pode contribuir para o crescimento do Ecossistema de IA Kotlin por problemas de arquivamentoenviando solicitações pull ou simplesmente testando Tracy em seus projetos e compartilhando seu feedback. Vamos rastrear juntos!

Assine as atualizações do blog Kotlin