Guida Langfuse per sviluppatori

Guida Langfuse per sviluppatori

Indice dei contenuti Guida Langfuse per sviluppatori

1. Introduzione a Langfuse
2. Caratteristiche principali della piattaforma
3. Architettura e stack tecnologico
4. Getting Started: primi passi con Langfuse
5. Caso d’uso pratico: implementazione di un sistema RAG con monitoraggio
6. Integrazione con LangChain ed esempi di codice
7. Best practices per un utilizzo efficiente
8. Errori comuni da evitare
9. Piani tariffari e confronto con i competitor
10. Conclusioni: l’importanza della formazione continua

1. Introduzione a Langfuse

Langfuse è una piattaforma open-source di LLM Engineering progettata per fornire observability, tracing, prompt management ed evaluation alle applicazioni basate su Large Language Models. Recentemente acquisita da ClickHouse, rappresenta uno degli strumenti più completi per sviluppatori che lavorano con LLM in ambienti di produzione.

La piattaforma nasce per risolvere una sfida fondamentale: debuggare e ottimizzare applicazioni LLM complesse, dove il comportamento non-deterministico dei modelli rende insufficienti le tecniche di logging tradizionali. Langfuse traccia l’intero execution path di un’applicazione LLM, rendendo visibili input, output e ogni step intermedio.

2. Caratteristiche principali della piattaforma

Langfuse offre un set completo di funzionalità organizzate in quattro pilastri fondamentali:

Observability & Tracing: cattura trace complete delle applicazioni LLM attraverso un’implementazione basata su OpenTelemetry. Ogni trace mostra la gerarchia delle chiamate, latenza, costi e metadati associati. Il sistema supporta session tracking per conversazioni multi-turn e user tracking per analisi comportamentali.

Prompt Management: gestione centralizzata dei prompt con versioning, deployment labels (production, staging, development) e caching sia lato server che client. Il Playground integrato permette di testare varianti di prompt con diversi modelli prima del deployment.

Evaluation Framework: supporta valutazioni sia offline (durante lo sviluppo) che online (in produzione). Include LLM-as-a-Judge evaluators, custom scorers, dataset management e annotation queues per human feedback. Le evaluation possono essere orchestrate via SDK o UI.

Metrics & Analytics: dashboard aggregate che mostrano metriche di costo, latenza, volume di utilizzo e quality scores. Include integrazione con PostHog e Mixpanel per analytics avanzate, oltre a export schedulati verso blob storage.

3. Architettura e stack tecnologico – Guida Langfuse per sviluppatori

L’architettura di Langfuse si basa su PostgreSQL come database principale, una scelta che privilegia semplicità di deployment rispetto alla scalabilità distribuita. Questa architettura centralizzata è perfettamente adeguata per la maggior parte dei casi d’uso, gestendo efficacemente volumi moderati-elevati di traffico.

Il sistema utilizza ClickHouse (dopo l’acquisizione) per analytics ad alta performance su grandi volumi di dati, Redis per caching e code di background jobs gestite con BullMQ. L’ingestion pipeline è progettata con eventual consistency: i dati passano attraverso code asincrone prima di essere persistiti, garantendo alta throughput senza bloccare le applicazioni client.

Langfuse espone sia SDK nativi (Python e JavaScript/TypeScript) sia supporto OpenTelemetry per linguaggi come Java e Go. Questo approccio multi-layer permette di integrare Langfuse in qualsiasi stack tecnologico.

4. Getting Started: primi passi con Langfuse

L’inizializzazione di Langfuse richiede pochi passaggi. Innanzitutto, registrarsi su cloud.langfuse.com (cloud-hosted) oppure effettuare self-hosting tramite Docker. Dopo la registrazione, recuperare le API keys dal dashboard del progetto.

Installazione del SDK Python:

pip install langfuse --upgrade

Configurazione delle credenziali:

import os

os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-..."
os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-..."
os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com"  # EU region
# os.environ["LANGFUSE_HOST"] = "https://us.cloud.langfuse.com"  # US region

Il decorator @observe() è il metodo più semplice per tracciare funzioni:

from langfuse import observe

@observe()
def process_user_query(query: str) -> str:
    # Tutto il codice nested viene automaticamente tracciato
    result = llm_call(query)
    return result

5. Caso d’uso pratico: implementazione di un sistema RAG con monitoraggio

Implementiamo un sistema RAG (Retrieval-Augmented Generation) completo con monitoraggio Langfuse. Questo esempio mostra come tracciare sia la fase di retrieval che quella di generation.

from langfuse import observe
from langfuse.openai import openai  # Drop-in replacement per OpenAI SDK
from langchain_community.vectorstores import Chroma
from langchain_openai import OpenAIEmbeddings
from langchain.text_splitters import RecursiveCharacterTextSplitter

# Inizializzazione del vector store
embeddings = OpenAIEmbeddings()
text_splitter = RecursiveCharacterTextSplitter(
    chunk_size=1000,
    chunk_overlap=200
)

@observe()  # Traccia l'intero retrieval process
def retrieve_relevant_docs(query: str, k: int = 3):
    """Recupera documenti rilevanti dal vector store"""
    vectorstore = Chroma(
        persist_directory="./chroma_db",
        embedding_function=embeddings
    )
    docs = vectorstore.similarity_search(query, k=k)
    return docs

@observe()  # Traccia la generazione della risposta
def generate_answer(query: str, context_docs: list) -> str:
    """Genera risposta usando il contesto recuperato"""
    context = "\n\n".join([doc.page_content for doc in context_docs])
    
    response = openai.chat.completions.create(
        model="gpt-4",
        messages=[
            {"role": "system", "content": "Rispondi usando solo il contesto fornito."},
            {"role": "user", "content": f"Contesto:\n{context}\n\nDomanda: {query}"}
        ],
        temperature=0.3
    )
    return response.choices[0].message.content

@observe()  # Trace top-level che raggruppa retrieval + generation
def rag_pipeline(user_query: str) -> str:
    """Pipeline RAG completa"""
    relevant_docs = retrieve_relevant_docs(user_query)
    answer = generate_answer(user_query, relevant_docs)
    return answer

# Utilizzo
result = rag_pipeline("Qual è la capitale della Francia?")
print(result)

Questo codice produce una trace gerarchica in Langfuse che mostra:

• La chiamata top-level rag_pipeline
• Il retrieval step con i documenti recuperati
• La generation step con prompt, response e token usage
• Metriche di latenza e costo per ogni componente

6. Integrazione con LangChain ed esempi di codice

Langfuse si integra nativamente con LangChain attraverso il CallbackHandler, catturando automaticamente tutti gli step di una chain complessa.

from langfuse.langchain import CallbackHandler
from langchain_openai import ChatOpenAI
from langchain.prompts import ChatPromptTemplate
from langchain.schema.output_parser import StrOutputParser
from langchain.schema.runnable import RunnablePassthrough

# Inizializza il callback handler
langfuse_handler = CallbackHandler()

# Crea una chain LangChain
prompt = ChatPromptTemplate.from_messages([
    ("system", "Sei un assistente esperto in {domain}"),
    ("user", "{question}")
])

model = ChatOpenAI(model="gpt-4", temperature=0)

chain = (
    {"domain": RunnablePassthrough(), "question": RunnablePassthrough()}
    | prompt
    | model
    | StrOutputParser()
)

# Esegui con tracing automatico
response = chain.invoke(
    {"domain": "intelligenza artificiale", "question": "Cos'è il transfer learning?"},
    config={"callbacks": [langfuse_handler]}
)

Per integrazioni più avanzate con gestione dello stato:

from langfuse import observe, get_client
from langfuse.langchain import CallbackHandler

@observe()
def complex_rag_chain(user_input: str):
    langfuse_handler = CallbackHandler()
    
    # Retrieval chain
    retrieval_chain = create_retrieval_chain()
    docs = retrieval_chain.invoke(
        {"query": user_input},
        config={"callbacks": [langfuse_handler]}
    )
    
    # Generation chain
    generation_chain = create_generation_chain()
    answer = generation_chain.invoke(
        {"context": docs, "question": user_input},
        config={"callbacks": [langfuse_handler]}
    )
    
    return answer

7. Best practices per un utilizzo efficiente

Organizzazione dei progetti: separare ambienti (development, staging, production) in progetti Langfuse distinti. Questo permette di controllare accessi e limitare la visibility di dati sensibili in produzione.

Gestione dei costi: utilizzare sampling per ambienti ad alto volume. Non tutte le trace devono essere registrate; campionare il 10-20% del traffico è spesso sufficiente per identificare pattern e anomalie.

import random
from langfuse import observe

@observe(sample_rate=0.1)  # Traccia solo il 10% delle chiamate
def high_volume_endpoint(query: str):
    return process_query(query)

Prompt management strategico: utilizzare deployment labels per gestire rollout graduali. Testare nuove versioni di prompt su un subset di utenti prima del full deployment.

Dataset curation: popolare dataset con esempi rappresentativi dal traffico reale. Utilizzare l’annotation queue per etichettare failure cases e costruire evaluation sets di qualità.

Evaluation automation: configurare evaluation pipelines che girano automaticamente su ogni deployment. Combinare LLM-as-a-Judge con metriche domain-specific per coverage completa.

Monitoring di metriche chiave: impostare alert su soglie critiche (costi giornalieri, latenza p95, error rate). Utilizzare l’API metrics per dashboard custom.

8. Errori comuni da evitare – Guida Langfuse per sviluppatori

Mancata gestione del flushing: in applicazioni short-lived (serverless functions, scripts), dimenticare di chiamare langfuse.flush() causa perdita di dati. Le trace vengono inviate in modo asincrono e potrebbero non essere completate prima della terminazione del processo.

from langfuse import get_client

langfuse = get_client()

# Esegui operazioni...

# IMPORTANTE: flush prima della terminazione
langfuse.flush()

Over-instrumentation: tracciare ogni singola funzione genera overhead e rumore. Concentrarsi sui boundary points significativi: chiamate LLM, retrieval steps, business logic critica.

Ignorare eventual consistency: dopo l’ingestion, i dati possono richiedere alcuni secondi per apparire in ClickHouse. Non aspettarsi availability immediata per query analitiche.

Configurazione errata del rate limiting: in ambienti ad alto volume, rispettare i rate limits dell’API. Il piano Hobby ha 30 requests/min; in produzione utilizzare piani con limiti più elevati o implementare batching.

Prompt versioning disorganizzato: creare troppe versioni di prompt senza una strategia di naming coerente rende difficile tracciare quali versioni sono in uso. Adottare convenzioni di naming chiare (es: customer_support_v2.3_production).

Dataset non rappresentativi: creare evaluation dataset con esempi sintetici o edge cases estremi produce metriche che non riflettono performance reale. Includere sempre distribuzione realistica di query.

Mancanza di context propagation: in architetture distribuite (microservizi, queue workers), non propagare trace context tra componenti frammenta le trace. Utilizzare OpenTelemetry context propagation per trace end-to-end.

9. Piani tariffari e confronto con i competitor

Langfuse offre quattro tier di pricing cloud-hosted:

Hobby (Gratuito): 50.000 units/mese incluse, retention 30 giorni, 2 utenti massimi. Ideale per progetti personali e proof-of-concept. Include tutte le features core con limitazioni di volume.

Core (€27/mese circa): 100.000 units incluse, €7.50/100k units addizionali, retention 90 giorni, utenti illimitati. Suitable per applicazioni in produzione early-stage.

Pro (€186/mese circa): 100.000 units incluse, retention illimitata, rate limits elevati (20.000 req/min ingestion), SOC2 & ISO27001 reports. Add-on Teams opzionale (+€280/mese) per SSO enterprise e RBAC avanzato.

Enterprise (€2.330/mese circa): volume pricing personalizzato, SLA dedicati, support engineer assegnato, audit logs, SCIM API. Deployment via AWS Marketplace disponibile.

Self-hosted: completamente gratuito senza limitazioni funzionali (licenza MIT). Costi solo per infrastruttura (tipicamente €50-2.000/mese secondo la scala).

Confronto con competitor principali

Caratteristica	Langfuse	LangSmith	Helicone
Licenza	Open-source (MIT)	Proprietaria	Open-source
Integrazione primaria	Framework-agnostic, forte su LangChain	Nativa LangChain/LangGraph	Proxy-based, provider-agnostic
Self-hosting	Gratuito illimitato	Solo tier Enterprise	Gratuito illimitato
Architettura	PostgreSQL centralizzato	Centralizzata proprietaria	Distribuita (Cloudflare Workers + ClickHouse)
Setup complexity	Media (SDK-based)	Bassa per LangChain	Molto bassa (proxy URL change)
Prompt management	UI completa + versioning	Prompt Hub limitato	Basico
Evaluation features	LLM-as-judge + custom scorers + datasets	Framework integrato	Limitato, focus su monitoring
Pricing entry	€0 (self-host) / €27 cloud	€0 (5K traces) / €36/user	€0 (100K req) / €74/mese
Best for	Team che vogliono controllo completo + evaluation robusta	Team all-in su LangChain	Rapid deployment + cost optimization

LangSmith eccelle per deep integration con l’ecosistema LangChain ma comporta vendor lock-in. Helicone offre setup immediato tramite proxy ma features evaluation meno mature. Langfuse bilancia flessibilità open-source, observability completa ed evaluation avanzata, rappresentando la scelta migliore per team che vogliono ownership dei dati e tooling production-grade.

10. Conclusioni: l’importanza della formazione continua

L’adozione di tecnologie come Langfuse rappresenta solo il primo step verso applicazioni LLM production-ready. Il vero differenziale competitivo risiede nella capacità del team IT di comprendere a fondo paradigmi di observability, evaluation e prompt engineering.

La formazione continua non è più opzionale in un panorama tecnologico che evolve così rapidamente. Investire nello sviluppo delle competenze del team significa ridurre time-to-market, minimizzare errori costosi in produzione e costruire applicazioni LLM robuste e affidabili.

Innovaformazione offre percorsi formativi specializzati in AI Generativa progettati per team che vogliono padroneggiare le tecnologie emergenti. I corsi coprono LLM engineering, prompt optimization, observability platforms e deployment best practices. Maggiori informazioni sono disponibili sul nostro sito a questo LINK.

Su richiesta, Innovaformazione attiva anche corsi aziendali dedicati a Langfuse, con programmi personalizzati sulle esigenze specifiche del team. I corsi si svolgono in modalità online classe virtuale, con calendario concordato e preventivo dedicato.

Per informazioni e preventivi personalizzati:

• Email: info@innovaformazione.net
• Telefono: 3471012275 (Dario Carrassi)

Investire nella formazione del team IT su piattaforme come Langfuse significa dotarsi degli strumenti culturali e tecnici per affrontare con successo progetti AI complessi, accelerando l’innovation cycle e riducendo i rischi di implementazione.

(fonte) (fonte) (fonte) (fonte)