163 lines
4.8 KiB
Markdown
163 lines
4.8 KiB
Markdown
# Guia de Integração Langfuse
|
||
|
||
Este guia descreve como o Langfuse está integrado ao assistente e como utilizar suas funcionalidades de observabilidade e rastreamento.
|
||
|
||
## Índice
|
||
|
||
- [O que é Langfuse](#o-que-e-langfuse)
|
||
- [Como está integrado](#como-esta-integrado)
|
||
- [Credenciais](#credenciais)
|
||
- [Rastreamento automático via LangChain](#rastreamento-automatico-via-langchain)
|
||
- [Tags por dashboard](#tags-por-dashboard)
|
||
- [Adicionando scores customizados](#adicionando-scores-customizados)
|
||
- [Visualizando traces](#visualizando-traces)
|
||
|
||
---
|
||
|
||
## O que é Langfuse
|
||
|
||
Langfuse é uma plataforma de observabilidade para aplicações LLM que permite:
|
||
|
||
- Rastrear automaticamente todas as chamadas ao modelo (tokens, latência, erros)
|
||
- Inspecionar o histórico de mensagens e chamadas de tools
|
||
- Adicionar scores e métricas customizadas por trace
|
||
- Analisar performance e uso ao longo do tempo
|
||
|
||
---
|
||
|
||
## Como está integrado
|
||
|
||
A integração é feita em dois módulos:
|
||
|
||
### `dynamo.py` — inicialização do cliente
|
||
|
||
O cliente `Langfuse` é instanciado na carga do módulo, usando credenciais obtidas do AWS Secrets Manager:
|
||
|
||
```python
|
||
from langfuse import Langfuse
|
||
|
||
secrets = json.loads(get_secret())
|
||
langfuse = Langfuse(
|
||
public_key=secrets["LANGFUSE-PUBLIC-KEY"],
|
||
secret_key=secrets["LANGFUSE-SECRET-KEY"],
|
||
host=os.environ["LANGFUSE_HOST"],
|
||
)
|
||
```
|
||
|
||
O objeto `langfuse` é exportado e reutilizado pelo `orquestrador.py`.
|
||
|
||
### `orquestrador.py` — rastreamento por execução
|
||
|
||
A cada chamada ao agente, um `CallbackHandler` do LangChain é criado e passado na configuração do grafo LangGraph. Isso registra automaticamente no Langfuse todas as etapas da execução — chamadas ao modelo, chamadas de tools e mensagens trocadas.
|
||
|
||
Ao final da execução, `langfuse.flush()` garante o envio dos dados pendentes.
|
||
|
||
```python
|
||
from langfuse.langchain import CallbackHandler
|
||
from .dynamo import langfuse
|
||
|
||
langfuse_handler = CallbackHandler()
|
||
config = {"callbacks": [langfuse_handler], "tags": [base]}
|
||
final_state = agent.invoke(initial_state, config=config)
|
||
|
||
langfuse.flush()
|
||
```
|
||
|
||
---
|
||
|
||
## Credenciais
|
||
|
||
As chaves do Langfuse são armazenadas no AWS Secrets Manager, no secret definido pela variável de ambiente `SECRET_NAME`. O secret deve conter as seguintes chaves:
|
||
|
||
| Chave no secret | Descrição |
|
||
|-----------------|-----------|
|
||
| `LANGFUSE-PUBLIC-KEY` | Chave pública do projeto Langfuse |
|
||
| `LANGFUSE-SECRET-KEY` | Chave secreta do projeto Langfuse |
|
||
|
||
O endpoint do servidor é configurado pela variável de ambiente `LANGFUSE_HOST`.
|
||
|
||
---
|
||
|
||
## Rastreamento automático via LangChain
|
||
|
||
O `CallbackHandler` captura automaticamente, sem código adicional:
|
||
|
||
- Cada chamada ao modelo Bedrock (input, output, tokens)
|
||
- Chamadas às tools `get_monthly_report` e `get_consolidated_keys`
|
||
- Sequência de passos do grafo LangGraph
|
||
- Erros e exceções durante a execução
|
||
|
||
Cada invocação de `orquestrador.main()` gera um trace independente no Langfuse.
|
||
|
||
---
|
||
|
||
## Tags por dashboard
|
||
|
||
A tag `base` (nome do dashboard, ex: `bacio_transacional_loja_app`) é passada em cada execução:
|
||
|
||
```python
|
||
config = {"callbacks": [langfuse_handler], "tags": [base]}
|
||
```
|
||
|
||
Isso permite filtrar traces no Langfuse por cliente/dashboard.
|
||
|
||
---
|
||
|
||
## Adicionando scores customizados
|
||
|
||
Para registrar métricas adicionais em um trace, use a API do cliente `langfuse` após a execução do agente. O trace ID pode ser obtido via `langfuse_handler.get_trace_id()`.
|
||
|
||
### Tipos de score
|
||
|
||
| Tipo | Uso |
|
||
|------|-----|
|
||
| `NUMERIC` | Valores numéricos (ex: satisfação 1–5, tempo de resposta) |
|
||
| `CATEGORICAL` | Valores de categoria (ex: canal de origem, qualidade) |
|
||
| `BOOLEAN` | Verdadeiro/falso |
|
||
|
||
### Exemplo: score após execução
|
||
|
||
```python
|
||
from langfuse.langchain import CallbackHandler
|
||
from .dynamo import langfuse
|
||
|
||
langfuse_handler = CallbackHandler()
|
||
config = {"callbacks": [langfuse_handler], "tags": [base]}
|
||
final_state = agent.invoke(initial_state, config=config)
|
||
|
||
trace_id = langfuse_handler.get_trace_id()
|
||
if trace_id:
|
||
langfuse.score(
|
||
trace_id=trace_id,
|
||
name="canal_origem",
|
||
value="api",
|
||
data_type="CATEGORICAL",
|
||
)
|
||
|
||
langfuse.flush()
|
||
```
|
||
|
||
> Sempre chame `langfuse.flush()` depois de registrar scores para garantir o envio.
|
||
|
||
---
|
||
|
||
## Visualizando traces
|
||
|
||
Acesse a interface web do Langfuse no endereço configurado em `LANGFUSE_HOST`.
|
||
|
||
### Navegação útil
|
||
|
||
| O que ver | Onde ir |
|
||
|-----------|---------|
|
||
| Todas as execuções | Traces |
|
||
| Execuções por dashboard | Traces → filtrar por tag |
|
||
| Tokens por modelo | Dashboard → Usage |
|
||
| Erros e falhas | Traces → filtrar por status `ERROR` |
|
||
| Scores registrados | Trace individual → aba Scores |
|
||
|
||
### Referências
|
||
|
||
- [Documentação Oficial Langfuse](https://langfuse.com/docs)
|
||
- [Integração LangChain/LangGraph](https://langfuse.com/docs/integrations/langchain)
|
||
- [API de Scores](https://langfuse.com/docs/scores/custom)
|