Langfuse

Instrumente uma aplicação LLM existente com observações rastreáveis e minimizadas, e entradas de avaliação versionadas. Modificado pelos mantenedores do AAS em 05/09/2026 para substituir exemplos de SDK legados misturados por um procedimento de configuração atual e limitado; a atribuição de origem existente é preservada.

Quando Usar

Use quando uma aplicação já precisa de rastreamento Langfuse, gerenciamento de prompts ou avaliação, ou ao depurar spans ausentes/duplicados. Não adicione um serviço de observabilidade meramente porque um LLM está presente; comece a partir do incidente ou da decisão do produto que os dados devem suportar.

Entradas e Pré-requisitos

• Versão do SDK Python ou JS instalada, framework e ciclo de vida do runtime.
• O projeto/endpoint Langfuse explicitamente autorizado, credenciais fornecidas através do mecanismo de segredo do projeto, e política de retenção/acesso de dados.
• Uma lista de permissão de campos observáveis e uma requisição sintética que não contém conteúdo privado.
• Um verificador definido: spans pai/filho esperados, status, tempo, versão do modelo/prompt e comportamento de flush.

Procedimento

1. Inspecione o lock de dependências e a instrumentação existente. Não misture exemplos antigos langfuse.trace(), langfuse.decorators ou langfuse.callback com o SDK atual sem verificar seu guia de migração.
2. Escolha uma camada de integração: spans diretos do SDK, um callback de framework ou instrumentação OpenTelemetry. Evite rastrear a mesma chamada duas vezes através de wrappers sobrepostos.
3. Configure o endpoint e as credenciais aprovados fora do código-fonte. Verifique a permissão de exportação antes de executar um exemplo: a instrumentação pode enviar entradas, saídas, metadados e exceções externamente.
4. Comece com observações explícitas contendo apenas valores sintéticos ou permitidos. Adicione IDs de correlação apenas quando seu escopo e tratamento de privacidade forem definidos.
5. Execute uma requisição de sucesso e uma de falha; inspecione a árvore de spans exportada e verifique se nenhum campo sensível escapou através de metadados aninhados ou instrumentação de terceiros.
6. Faça o flush em processos de curta duração e teste o desligamento/timeouts. Uma chamada de SDK retornada não prova por si só a ingestão.
7. Adicione metadados de prompt/avaliação apenas após o limite do trace funcionar. Fixe a versão do prompt ou registre a versão exata resolvida; um rótulo de produção mutável não é uma entrada de experimento imutável.

Observação Mínima em Python

A visão geral atual do SDK Python documenta get_client() e observações gerenciadas por contexto. Use a API que corresponde ao SDK instalado. Após a configuração e autorização de exportação, este exemplo sintético cria um span e nenhuma chamada LLM:

from langfuse import get_client

client = get_client()
with client.start_as_current_observation(as_type="span", name="synthetic-health-check") as span:
    span.update(output={"status": "ok"})
client.flush()

Observação esperada: um span synthetic-health-check concluído no projeto pretendido com o valor de status fixo. Esta habilidade não afirma que uma verificação de ingestão ao vivo foi executada. Um endpoint incorreto, credenciais ausentes ou falha do exportador devem ser relatados como uma verificação falha/não verificada.

Privacidade e Mascaramento

Não trate truncamento como redação. Prefira omitir prompts brutos, mensagens de usuário e cargas úteis de ferramentas; inspecione todos os exportadores configurados. Os SDKs Python atuais fornecem mask_otel_spans para transformação no momento da exportação; o hook legado mask cobre um conjunto mais restrito de atributos criados pelo SDK. Escolha o mecanismo de versão instalada usando a documentação de mascaramento, e teste um segredo sintético em metadados aninhados e uma exceção. A filtragem no lado do coletor ocorre após os dados saírem da aplicação, portanto, coloque-a dentro do limite de confiança aprovado.

Gerenciamento de Prompts e Avaliação

Registre a revisão do conjunto de dados, a versão do prompt, o identificador do modelo, a configuração da ferramenta e a definição do avaliador. Mantenha os erros do avaliador distintos de pontuações baixas. Uma resposta do juiz deve passar por um schema limitado e validação de intervalo finito; nunca converta texto arbitrário do modelo diretamente com float() e chame-o de qualidade medida. Calibre os julgamentos contra exemplos revisados e relate desacordos. Separe o feedback do usuário de uma pontuação automática do juiz.

…