> ## 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.

# Импорт данных трассировки из Langfuse Cloud

> Как загрузить данные трассировки LLM, экспортированные из Langfuse Cloud, в ClickHouse Cloud с помощью ClickPipes.

В этом руководстве пошагово описано, как загрузить данные трассировки LLM из [Langfuse Cloud](https://cloud.langfuse.com/) в ClickHouse Cloud для Real-time аналитики.

## Экспорт из Langfuse Cloud

Чтобы настроить в Langfuse Cloud интеграцию с Blob Storage для экспорта по расписанию, следуйте [этому руководству](https://langfuse.com/docs/api-and-data-platform/features/export-to-blob-storage). Экспорт данных трассировки в объектное хранилище можно запускать не чаще чем раз в `20 minutes` либо по расписанию `hourly`, `daily` или `weekly`. По умолчанию каждый экспорт включает `observations` (дополненные атрибутами трассировок) и `scores`.

### Структура экспортируемых файлов

Интеграция Blob Storage в Langfuse Cloud записывает данные в целевой бакет или контейнер хранилища со следующей структурой каталогов:

```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
```

## Импорт в ClickHouse Cloud

После настройки интеграции Blob Storage в Langfuse Cloud данные трассировки будут по расписанию экспортироваться в целевой бакет или контейнер хранилища. Чтобы импортировать эти данные в ClickHouse Cloud, воспользуйтесь [ClickPipes](https://clickhouse.com/docs/ru/integrations/clickpipes.md) и его управляемыми коннекторами к объектным хранилищам:

| Источник данных | Подробности |
| - | - |
| ![Логотип 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** *и S3-совместимые объектные хранилища* | Интеграция через [S3 ClickPipes](https://clickhouse.com/docs/ru/integrations/clickpipes/object-storage/amazon-s3/overview.md). |
| ![Логотип 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** | Интеграция через [GCS ClickPipes](https://clickhouse.com/docs/ru/integrations/clickpipes/object-storage/google-cloud-storage/overview.md). |
| ![Логотип 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** | Интеграция через [ABS ClickPipes](https://clickhouse.com/docs/ru/integrations/clickpipes/object-storage/azure-blob-storage/overview.md). |

### Создание ClickPipe

В этом примере S3 ClickPipe используется для импорта данных из S3 бакета, в который по расписанию выгружаются данные из Langfuse Cloud. Этот пример можно взять за основу и для других объектных хранилищ, в которые выполняется экспорт. Рекомендации для конкретных источников данных см. в [документации ClickPipes](https://clickhouse.com/docs/ru/integrations/clickpipes.md).

**1. Выберите источник данных**

**1.** В ClickHouse Cloud выберите **Data sources** в главном меню навигации и нажмите **Create ClickPipe**.

![Создание 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.** Нажмите на плитку **Amazon S3**. Через эту плитку можно также подключиться к другим S3-совместимым сервисам, которых нет в интерфейсе ClickPipes.

![Выбор источника данных 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. Настройте соединение**

**1.** Укажите данные, которые нужны ClickPipes для подключения и аутентификации в бакете, куда экспортируются данные из Langfuse Cloud.

* **Authentication method**: S3 ClickPipe поддерживает [учётные данные IAM](https://clickhouse.com/docs/ru/integrations/clickpipes/object-storage/amazon-s3/overview.md#iam-credentials) (`Credentials`) и [аутентификацию на основе роли IAM](https://clickhouse.com/docs/ru/integrations/clickpipes/object-storage/amazon-s3/overview.md#iam-role) (`IAM role`). ClickPipes требуется только доступ к бакету на чтение. Рекомендации по аутентификации и разрешениям приведены в [справочной документации](https://clickhouse.com/docs/ru/integrations/clickpipes/object-storage/amazon-s3/overview.md#access-control).

* **S3 file path**: укажите для ClickPipe подкаталог и используйте подстановочный символ `*`, чтобы охватить все экспортированные файлы. Для каждого подкаталога **необходимо** создать отдельный ClickPipe, поскольку экспортированные файлы в разных подкаталогах имеют разные схемы.

  | Подкаталог | Путь к файлам |
  | - | - |
  | `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/*` |

  Рекомендации по поддерживаемым шаблонам, в том числе по сопоставлению файлов во вложенных префиксах, приведены в [справочной документации](https://clickhouse.com/docs/ru/integrations/clickpipes/object-storage/amazon-s3/overview.md#file-pattern-matching).

**2.** Выберите **Continuous ingestion**, чтобы новые файлы загружались автоматически по мере того, как Langfuse записывает их в целевой бакет.

![Сведения о подключении для экспорта Langfuse с включённой непрерывной ингестией.](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.** Нажмите **Incoming data**. ClickPipes получит метаданные из вашего бакета и на следующем шаге автоматически определит схему целевой таблицы.

**3. Проверьте корректность поступающих данных**

**1.** ClickPipes подключится к вашему бакету, получит список файлов по указанному пути и автоматически определит их формат. В этом примере используется формат экспорта Langfuse Cloud по умолчанию (Parquet).

![Файлы, соответствующие пути экспорта Langfuse, с типом файла 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.** Нажмите **Parse information**. ClickPipes определит схему экспортированных данных по файлу-образцу и автоматически сопоставит поля источника с полями целевой таблицы ClickHouse.

**4. Настройте целевую систему**

**1.** На этом шаге можно просмотреть автоматически определённую схему и настроить параметры целевой таблицы: скорректировать сопоставление типов данных, задать [ключ сортировки](https://clickhouse.com/docs/ru/best-practices/choosing-a-primary-key.md) и выбрать [движок таблицы](https://clickhouse.com/docs/ru/reference/engines/table-engines.md).

![Экспорт scores с записью в отдельную базу данных langfuse; ключ сортировки задан как environment, name, timestamp, trace\_id, observation\_id и 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)

В разделе **Upload data to** оставьте выбранным вариант **New table** и укажите:

* **Database** и **Name**: отдельную базу данных для данных Langfuse (например, `langfuse`) и понятное имя целевой таблицы (например, `scores`). По умолчанию ClickPipes использует `default.s3-<uuid>`, чтобы избежать конфликтов имён.

* **Sorting key**: [ключ упорядочивания](https://clickhouse.com/docs/ru/best-practices/choosing-a-primary-key.md) целевой таблицы, который определяет, как ClickHouse хранит данные на диске. Для оптимальной производительности ключ сортировки должен соответствовать тому, как ваши запросы обращаются к данным, — тогда они смогут пропускать чтение как можно большего объёма данных.

  | Подкаталог | Целевая таблица | Рекомендуемый ключ сортировки |
  | - | - | - |
  | `observations_v2/` | `observations_v2` | `environment, start_time, trace_id, id` |
  | `scores/` | `scores` | `environment, name, timestamp, trace_id, observation_id, id` |

  Этот ключ также используется для дедупликации в таблицах `ReplacingMergeTree`, поэтому набор столбцов должен однозначно идентифицировать запись. Если вы загружаете **несколько проектов Langfuse** в одну таблицу, добавьте `project_id` в начало ключа сортировки. Рекомендации по выбору ключа сортировки см. в [справочной документации](https://clickhouse.com/docs/ru/best-practices/choosing-a-primary-key.md).

* **Partition by**: оставьте поле пустым, если не планируете удалять устаревшие трассировки. [Партиционирование](https://clickhouse.com/docs/ru/best-practices/choosing-a-partitioning-key.md) в ClickHouse предназначено для управления данными, а не для оптимизации запросов; рекомендуемый ключ сортировки и так отсекает лишние данные в запросах по временному диапазону. Если же нужно ограничить срок хранения, партиционируйте таблицу по столбцу времени (`toYYYYMM(start_time)` или `toYYYYMM(timestamp)` для `scores`) — тогда удаление трассировок за месяц сведётся к одной операции `DROP PARTITION`.

**2.** Затем разверните **Advanced settings**, выберите для **Engine** значение [`ReplacingMergeTree`](https://clickhouse.com/docs/ru/engines/table-engines/mergetree-family/replacingmergetree), чтобы обеспечить дедупликацию, и укажите `updated_at` в качестве столбца **Version**.

![Расширенные настройки с движком ReplacingMergeTree и updated\_at в качестве столбца версии](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)

Окна экспорта в интеграции Langfuse Cloud Blob Storage включают обе границы, поэтому одна и та же запись может попасть в несколько экспортированных файлов. Если ваши аналитические запросы не идемпотентны (идемпотентны, например, `uniq()`, `max()`, `min()`), вы **обязаны** обрабатывать дедупликацию на уровне последующей модели данных, используя `ReplacingMergeTree` в качестве целевого движка.

> [!NOTE]
>
> **Дедупликация с помощью ReplacingMergeTree**
>
> Этот движок таблицы схлопывает дубликаты во время фоновых слияний. Для полной дедупликации при чтении (т. е. семантики merge-on-read) **необходимо** использовать в запросах модификатор `FINAL` (или агрегации в стиле `argMax()`).

**5. Настройте разрешения**

ClickPipes создаёт отдельного пользователя для записи данных в целевую таблицу. Выберите для этого внутреннего пользователя пользовательскую роль или одну из предопределённых ролей:

* `Full access`: полный доступ к кластеру. Требуется, если с целевой таблицей используется materialized view или словарь.
* `Only destination table`: разрешения `INSERT` только на целевую таблицу.

![Разрешения](https://mintcdn.com/private-7c7dfe99/KW34O4k4cC0oxlHH/images/integrations/data-ingestion/clickpipes/cp_step5.webp?fit=max\&auto=format\&n=KW34O4k4cC0oxlHH\&q=85\&s=481731570edc891610aea57fe1925c51)

Нажмите **Complete setup**, чтобы создать ClickPipe.

**6. Завершите настройку**

Готово! Сначала ClickPipes выполнит дозагрузку исторических данных из всех файлов по указанному пути, а затем начнёт принимать новые файлы по мере их поступления в бакет.

![Работающие ClickPipes для observations и scores в разделе 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)

Повторите шаги из этого руководства для каждого подкаталога, который нужно импортировать в ClickHouse Cloud.

### Запросы к данным трассировки

Когда ClickPipes будут запущены, вы сможете выполнять запросы к данным трассировки Langfuse Cloud непосредственно в ClickHouse Cloud. Ниже приведены примеры нескольких распространённых шаблонов запросов: агрегирование затрат и задержек, восстановление отдельной трассировки, а также сопоставление оценок с моделями и промптами.

#### Агрегация метрик по временным интервалам

> [!TIP]
>
> Некоторые поля, например `usage_details` и `cost_details`, экспортируются как столбцы типа `Map`. Чтобы получить отдельное значение, обратитесь к нему по ключу (например, `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 = '<environment>'
GROUP BY t, provided_model_name
ORDER BY t;
```

#### Восстановление трассировки

```sql theme={null}
SELECT *
FROM observations_v2 FINAL
WHERE trace_id = '<trace_id>'
ORDER BY start_time;
```

#### Анализ качества

```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 = '<environment>'
GROUP BY o.provided_model_name, s.name
ORDER BY avg_score DESC;
```

## См. также

* [Langfuse и ClickHouse](https://clickhouse.com/docs/ru/products/cloud/features/ai-ml/langfuse.md)
* [Экспорт данных Langfuse Cloud в Blob Storage](https://langfuse.com/docs/api-and-data-platform/features/export-to-blob-storage)
* [ClickPipes для объектного хранилища](https://clickhouse.com/docs/ru/integrations/clickpipes/object-storage/amazon-s3/overview.md)
