> ## Documentation Index > Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Importar dados de trace do Langfuse Cloud > Como carregar no ClickHouse Cloud dados de trace de LLM exportados do Langfuse Cloud usando ClickPipes. Este guia mostra como carregar dados de trace de LLM do [Langfuse Cloud](https://cloud.langfuse.com/) no ClickHouse Cloud para fazer analytics em tempo real. ## Exportar do Langfuse Cloud Siga [este guia](https://langfuse.com/docs/api-and-data-platform/features/export-to-blob-storage) para configurar uma integração de Blob Storage no Langfuse Cloud e realizar exportações agendadas. Você pode agendar a exportação dos seus dados de trace para o armazenamento de objetos a cada `20 minutes`, no mínimo, ou com agendamento `hourly`, `daily` ou `weekly`. Por padrão, cada exportação inclui suas `observations` (enriquecidas com atributos de trace) e `scores`. ### Estrutura dos arquivos exportados A integração de Blob Storage do Langfuse Cloud grava os dados no bucket ou contêiner de armazenamento de destino usando a seguinte estrutura de diretórios: ```text theme={null} {prefix}{project-id}/ ├── observations_v2/ # observations enriched with trace attributes ├── scores/ # scores └── manifests/ # one JSON file per completed run with export metadata ``` ## Importar para o ClickHouse Cloud Depois que uma integração de Blob Storage for configurada no Langfuse Cloud, os dados de trace serão exportados conforme um agendamento para o bucket ou contêiner de armazenamento de destino. Para importar esses dados para o ClickHouse Cloud, você pode usar o [ClickPipes](https://clickhouse.com/docs/pt-BR/integrations/clickpipes) e seus connectors gerenciados de armazenamento de objetos: | Fonte de dados | Detalhes | | - | - | | ![Logotipo do Amazon S3](https://mintcdn.com/private-7c7dfe99/f0pPCSRBU8VWwYgc/images/integrations/logos/amazon_s3_logo.svg?fit=max\&auto=format\&n=f0pPCSRBU8VWwYgc\&q=85\&s=ff77c6f2009aebb6c768d33b48d41457)**Amazon S3** *e armazenamentos de objetos compatíveis com S3* | Integre usando os [S3 ClickPipes](https://clickhouse.com/docs/pt-BR/integrations/clickpipes/object-storage/amazon-s3/overview.md). | | ![Logotipo do Google Cloud Storage](https://mintcdn.com/private-7c7dfe99/f0pPCSRBU8VWwYgc/images/integrations/logos/gcs.svg?fit=max\&auto=format\&n=f0pPCSRBU8VWwYgc\&q=85\&s=3dc40faaa9ca1c1fbb7f41d6aecacb9b) **Google Cloud Storage** | Integre usando os [GCS ClickPipes](https://clickhouse.com/docs/pt-BR/integrations/clickpipes/object-storage/google-cloud-storage/overview.md). | | ![Logotipo do Azure Blob Storage](https://mintcdn.com/private-7c7dfe99/f0pPCSRBU8VWwYgc/images/integrations/logos/azureblobstorage.svg?fit=max\&auto=format\&n=f0pPCSRBU8VWwYgc\&q=85\&s=5247cc3f10c4cb15fea074d8c52de3a0) **Azure Blob Storage** | Integre usando os [ClickPipes do ABS](https://clickhouse.com/docs/pt-BR/integrations/clickpipes/object-storage/azure-blob-storage/overview.md). | ### Crie um ClickPipe Este exemplo usa o S3 ClickPipe para importar dados de um bucket do S3 que recebe exportações agendadas do Langfuse Cloud e pode servir de modelo para qualquer destino de exportação em armazenamento de objetos. Para orientações específicas de cada fonte de dados, consulte a [documentação do ClickPipes](https://clickhouse.com/docs/pt-BR/integrations/clickpipes). **1. Selecione a fonte de dados** **1.** No ClickHouse Cloud, selecione **Data sources** no menu de navegação principal e clique em **Criar ClickPipe**. ![Criar ClickPipe](https://mintcdn.com/private-7c7dfe99/KW34O4k4cC0oxlHH/images/integrations/data-ingestion/clickpipes/cp_step0.webp?fit=max\&auto=format\&n=KW34O4k4cC0oxlHH\&q=85\&s=9e134912809363f85f1602e2f744c872) **2.** Clique no bloco **Amazon S3**. Você também pode usar esse bloco para se conectar a outros serviços compatíveis com S3 que não aparecem na interface do ClickPipes. ![Selecione a fonte de dados Amazon S3](https://mintcdn.com/private-7c7dfe99/KW34O4k4cC0oxlHH/images/integrations/data-ingestion/clickpipes/object-storage/amazon-s3/cp_step1.webp?fit=max\&auto=format\&n=KW34O4k4cC0oxlHH\&q=85\&s=d5cf3cc2b771d92a85b7c436c1be3a2d) **2. Configure a conexão** **1.** Preencha os dados de que o ClickPipes precisa para se conectar e se autenticar no bucket que recebe suas exportações do Langfuse Cloud. * **Método de autenticação**: o S3 ClickPipe oferece suporte a [credenciais do IAM](https://clickhouse.com/docs/pt-BR/integrations/clickpipes/object-storage/amazon-s3/overview.md#iam-credentials) (`Credentials`) e a [autenticação baseada em IAM role](https://clickhouse.com/docs/pt-BR/integrations/clickpipes/object-storage/amazon-s3/overview.md#iam-role) (`IAM role`). O ClickPipes precisa apenas de acesso de leitura ao bucket. Consulte a [documentação de referência](https://clickhouse.com/docs/pt-BR/integrations/clickpipes/object-storage/amazon-s3/overview.md#access-control) para obter orientações sobre autenticação e permissões. * **Caminho de arquivo do S3**: aponte o ClickPipe para um subdiretório e use um wildcard `*` para corresponder a todos os arquivos exportados. Você **deve** criar um ClickPipe por subdiretório, pois os arquivos exportados em cada subdiretório têm schemas diferentes. | Subdiretório | Caminho do arquivo | | - | - | | `observations_v2/` | `https://{bucket-name}.s3.{region-code}.amazonaws.com/{prefix}{project-id}/observations_v2/*` | | `scores/` | `https://{bucket-name}.s3.{region-code}.amazonaws.com/{prefix}{project-id}/scores/*` | Consulte a [documentação de referência](https://clickhouse.com/docs/pt-BR/integrations/clickpipes/object-storage/amazon-s3/overview.md#file-pattern-matching) para obter orientações sobre os padrões compatíveis, incluindo como corresponder arquivos em prefixos aninhados. **2.** Selecione **Continuous ingestion** para que novos arquivos sejam ingeridos automaticamente à medida que o Langfuse os grava no bucket de destino. ![Detalhes de conexão de uma exportação do Langfuse, com a ingestão contínua habilitada.](https://mintcdn.com/private-7c7dfe99/gZE48P0cpgbtYuL4/images/use-cases/AI_ML/Langfuse/cp_continuous_ingestion.webp?fit=max\&auto=format\&n=gZE48P0cpgbtYuL4\&q=85\&s=d5035efd8715342cb034d628a080e1f4) **3.** Clique em **Incoming data**. O ClickPipes buscará os metadados do seu bucket e inferirá o schema da tabela de destino na próxima etapa. **3. Valide os dados recebidos** **1.** O ClickPipes se conectará ao seu bucket e listará os arquivos no caminho especificado, inferindo o formato dos arquivos. Neste exemplo, usamos o formato de arquivo de exportação padrão do Langfuse Cloud (Parquet). ![Arquivos correspondentes ao caminho de exportação do Langfuse, com o tipo de arquivo definido como Parquet](https://mintcdn.com/private-7c7dfe99/gZE48P0cpgbtYuL4/images/use-cases/AI_ML/Langfuse/cp_incoming_data.webp?fit=max\&auto=format\&n=gZE48P0cpgbtYuL4\&q=85\&s=ca9d5198596a77b752871eaa366aa1ff) **2.** Clique em **Parse information**. O ClickPipes usará um arquivo de amostra para inferir o schema dos dados exportados e mapeará automaticamente os campos de origem para uma tabela de destino no ClickHouse. **4. Configure o destino** **1.** Nesta etapa, você pode revisar o esquema inferido e personalizar a configuração da tabela de destino, incluindo ajustar o mapeamento de tipos de dados, definir a [sorting key](https://clickhouse.com/docs/pt-BR/best-practices/choosing-a-primary-key.md) e escolher o [motor de tabela](https://clickhouse.com/docs/pt-BR/reference/engines/table-engines.md). ![Uma exportação de scores gravando em um banco de dados langfuse dedicado, com a sorting key definida como environment, name, timestamp, trace\_id, observation\_id e id](https://mintcdn.com/private-7c7dfe99/gZE48P0cpgbtYuL4/images/use-cases/AI_ML/Langfuse/cp_table_settings.webp?fit=max\&auto=format\&n=gZE48P0cpgbtYuL4\&q=85\&s=5a3e26397f8896dd46d1de69aba80ff4) Em **Upload data to**, mantenha **New table** selecionado e defina: * **Database** e **Name**: um banco de dados dedicado para os seus dados do Langfuse (por exemplo, `langfuse`) e um nome legível para a tabela de destino (por exemplo, `scores`). Por padrão, o ClickPipes usa `default.s3-` para evitar conflitos de nomes. * **Sorting key**: a [chave de ordenação](https://clickhouse.com/docs/pt-BR/best-practices/choosing-a-primary-key.md) da tabela de destino, que determina como o ClickHouse persiste os dados em disco. Para obter o melhor desempenho, a sorting key deve corresponder aos seus padrões de acesso aos dados, de modo que as consultas possam pular a leitura do maior volume de dados possível. | Subdiretório | Tabela de destino | Sorting key sugerida | | - | - | - | | `observations_v2/` | `observations_v2` | `environment, start_time, trace_id, id` | | `scores/` | `scores` | `environment, name, timestamp, trace_id, observation_id, id` | Essa chave também é usada para desduplicação em tabelas `ReplacingMergeTree`, portanto o conjunto de colunas também precisa identificar cada registro de forma única. Se você carregar **vários projetos do Langfuse** em uma única tabela, adicione `project_id` no início da sorting key. Consulte a [documentação de referência](https://clickhouse.com/docs/pt-BR/best-practices/choosing-a-primary-key.md) para obter orientações sobre como escolher uma sorting key. * **Partition by**: deixe em branco, a menos que você pretenda expirar traces antigos. O [particionamento](https://clickhouse.com/docs/pt-BR/best-practices/choosing-a-partitioning-key.md) no ClickHouse serve para o gerenciamento de dados, e não para a otimização de consultas; a sorting key sugerida já elimina dados irrelevantes em consultas por intervalo de tempo. Se você precisar de retenção, particione pela coluna de tempo (`toYYYYMM(start_time)`, ou `toYYYYMM(timestamp)` para `scores`), para que expirar um mês de traces seja uma única operação `DROP PARTITION`. **2.** Em seguida, expanda **Advanced settings** e defina o **Engine** como [`ReplacingMergeTree`](https://clickhouse.com/docs/pt-BR/engines/table-engines/mergetree-family/replacingmergetree) para garantir a desduplicação, usando `updated_at` como a coluna **Version**. ![Configurações avançadas com o motor ReplacingMergeTree e updated\_at como a coluna de versão](https://mintcdn.com/private-7c7dfe99/gZE48P0cpgbtYuL4/images/use-cases/AI_ML/Langfuse/cp_advanced_settings.webp?fit=max\&auto=format\&n=gZE48P0cpgbtYuL4\&q=85\&s=e2b3eb395da8f93da0c5aa4a63987a40) As janelas de exportação na integração Blob Storage do Langfuse Cloud incluem ambos os limites, portanto o mesmo registro pode aparecer em mais de um arquivo exportado. A menos que seus padrões de consulta analítica sejam idempotentes (por exemplo, `uniq()`, `max()`, `min()`), você **deve** tratar a desduplicação no modelo de dados downstream, usando `ReplacingMergeTree` como motor de destino. > [!NOTE] > > **Desduplique com ReplacingMergeTree** > > Este motor de tabela elimina duplicatas por meio de mesclagens em segundo plano. Para uma desduplicação completa na leitura (ou seja, semântica de mesclagem na leitura), você **deve** usar o modificador `FINAL` (ou agregações no estilo `argMax()`) no momento da consulta. **5. Configure as permissões** O ClickPipes cria um usuário dedicado para a gravação de dados na tabela de destino. Selecione uma função para esse usuário interno, seja uma função personalizada ou uma das funções predefinidas: * `Full access`: com acesso total ao cluster. Obrigatório se você usar uma visão materializada ou um dicionário com a tabela de destino. * `Only destination table`: com permissões de `INSERT` apenas na tabela de destino. ![Permissões](https://mintcdn.com/private-7c7dfe99/KW34O4k4cC0oxlHH/images/integrations/data-ingestion/clickpipes/cp_step5.webp?fit=max\&auto=format\&n=KW34O4k4cC0oxlHH\&q=85\&s=481731570edc891610aea57fe1925c51) Clique em **Complete setup** para criar o ClickPipe. **6. Concluir a configuração** E pronto! O ClickPipes primeiro fará um backfill histórico de todos os arquivos no caminho especificado e, em seguida, passará a ingerir os novos arquivos à medida que forem chegando ao bucket. ![Os ClickPipes de observations e scores em execução em Data sources](https://mintcdn.com/private-7c7dfe99/gZE48P0cpgbtYuL4/images/use-cases/AI_ML/Langfuse/cp_clickpipes_running.webp?fit=max\&auto=format\&n=gZE48P0cpgbtYuL4\&q=85\&s=defa1b3465595c0c2c5fdb7977534967) Repita as etapas deste guia para cada subdiretório que você quiser importar para o ClickHouse Cloud. ### Consultar dados de trace Com os ClickPipes em execução, você pode consultar os dados de trace do Langfuse Cloud diretamente no ClickHouse Cloud. Os exemplos abaixo abordam alguns padrões de consulta comuns: agregações de custo e latência, reconstrução de um único trace e correlação de pontuações com modelos e prompts. #### Agregações de métricas por intervalos de tempo > [!TIP] > > Alguns campos, como `usage_details` e `cost_details`, são exportados como colunas `Map`. Para ler um único valor, acesse-o pela chave (por exemplo, `sum(cost_details['total'])`). ```sql theme={null} SELECT toStartOfHour(start_time) AS t, provided_model_name, count() AS spans, quantile(0.95)(latency) AS p95_latency, sum(total_cost) AS cost, sum(usage_details['total']) AS tokens FROM observations_v2 FINAL WHERE start_time >= now() - INTERVAL 7 DAY -- AND environment = '' GROUP BY t, provided_model_name ORDER BY t; ``` #### Reconstrução de traces ```sql theme={null} SELECT * FROM observations_v2 FINAL WHERE trace_id = '' ORDER BY start_time; ``` #### Análise de qualidade ```sql theme={null} SELECT o.provided_model_name, s.name, avg(s.value) AS avg_score FROM "s3-26237f63-84dc-4a7d-a0e1-7361cf55ee0b" AS s FINAL JOIN "s3-80899034-ce1e-4dc9-a4e6-b059ddec4175" AS o FINAL ON s.trace_id = o.trace_id --WHERE s.environment = '' GROUP BY o.provided_model_name, s.name ORDER BY avg_score DESC; ``` ## Veja também * [Langfuse e ClickHouse](https://clickhouse.com/docs/pt-BR/products/cloud/features/ai-ml/langfuse.md) * [Exportação do Langfuse Cloud para Blob Storage](https://langfuse.com/docs/api-and-data-platform/features/export-to-blob-storage) * [ClickPipes para armazenamento de objetos](https://clickhouse.com/docs/pt-BR/integrations/clickpipes/object-storage/amazon-s3/overview.md)