> ## Documentation Index
> Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt
> Use this file to discover all available pages before exploring further.

# LangSmith 托管的 ClickHouse

<Check>
  在继续本指南之前，请阅读 [LangSmith 架构概述](/langsmith/self-hosted) 和 [连接外部 ClickHouse 的指南](/langsmith/self-host-external-clickhouse)。
</Check>

LangSmith 使用 ClickHouse 作为 **跟踪** 和 **反馈** 的主要存储引擎。为了便于管理和扩展，建议将自托管的 LangSmith 实例连接到外部 ClickHouse 实例。LangSmith 托管的 ClickHouse 是一个选项，允许您使用由 LangSmith 团队监控和维护的全托管 ClickHouse 实例。

## 架构概述

将 LangSmith 托管的 ClickHouse 与您的自托管 LangSmith 实例一起使用的架构，与使用完全自托管的 ClickHouse 实例类似，但有几个关键区别：

* 您需要在您的 LangSmith 实例和 LangSmith 托管的 ClickHouse 实例之间建立私有网络连接。这是为了确保您的数据安全，并且您可以从自托管的 LangSmith 实例连接到 ClickHouse 实例。
* 使用此选项时，您跟踪的敏感信息（输入和输出）将存储在您云内的云对象存储（S3 或 GCS）中，而不是 ClickHouse 中，以确保敏感信息不会离开您的 VPC。有关特定数据字段存储位置的更多详细信息，请参阅 [数据存储](#数据存储)。
* LangSmith 团队将监控您的 ClickHouse 实例并确保其平稳运行。这使我们能够跟踪诸如运行摄取延迟和查询性能等指标。

整体架构如下所示：

<img className="block dark:hidden" src="https://mintcdn.com/other-405835d4/X4LKQZjW6RjHveuz/langsmith/images/managed-clickhouse-light.png?fit=max&auto=format&n=X4LKQZjW6RjHveuz&q=85&s=7ff6e7a7c8f6b3c81b6daa15383b3df7" alt="LangSmith 托管的 ClickHouse 架构。" width="2196" height="1755" data-path="langsmith/images/managed-clickhouse-light.png" />

<img className="hidden dark:block" src="https://mintcdn.com/other-405835d4/X4LKQZjW6RjHveuz/langsmith/images/managed-clickhouse-dark.png?fit=max&auto=format&n=X4LKQZjW6RjHveuz&q=85&s=dcf107859fb12f36c828c50984fbfb78" alt="LangSmith 托管的 ClickHouse 架构。" width="2196" height="1755" data-path="langsmith/images/managed-clickhouse-dark.png" />

## 要求

* **您必须使用受支持的 Blob 存储选项。** 阅读 [Blob 存储指南](/langsmith/self-host-blob-storage) 了解更多信息。
* 要使用私有端点，请确保您的 VPC 位于 ClickHouse Cloud 支持的 [区域](https://clickhouse.com/docs/en/cloud/reference/supported-regions)。否则，您将需要使用我们将通过防火墙规则保护的公共端点。您的 VPC 需要有一个 NAT 网关，以便我们能够将您的流量加入白名单。
* 您必须拥有一个可以连接到 LangSmith 托管的 ClickHouse 服务的 VPC。您需要与我们的团队合作设置必要的网络。
* 您必须有一个正在运行的 LangSmith 自托管实例。您可以将我们的托管 ClickHouse 服务与 [Kubernetes](/langsmith/kubernetes) 安装一起使用。

## 数据存储

ClickHouse 存储 **运行** 和 **反馈** 数据，具体包括：

* 所有反馈数据字段。
* 部分运行数据字段。

有关字段列表，请参阅 [存储的运行数据字段](#存储的运行数据字段) 和 [存储的反馈数据字段](#存储的反馈数据字段)。

LangChain 将敏感应用数据定义为运行的 `inputs`、`outputs`、`errors`、`manifests`、`extras` 和 `events`，因为这些字段可能包含 LLM 提示和补全。使用 LangSmith 托管的 ClickHouse 时，这些敏感字段存储在您云内的云对象存储（S3 或 GCS）中，而其余的运行数据存储在 ClickHouse 中，确保敏感信息永远不会离开您的 VPC。

### 存储的反馈数据字段

<Note>
  由于所有反馈数据都存储在 ClickHouse 中，请勿在反馈（分数和注释/评论）或 [存储的运行数据字段](#存储的运行数据字段) 中提到的任何其他运行字段中发送敏感信息。
</Note>

使用 LangSmith 托管的 ClickHouse 设置，**所有反馈数据字段都存储在 ClickHouse 中**：

| 字段名                        | 类型       | 描述                                       |
| -------------------------- | -------- | ---------------------------------------- |
| `id`                       | UUID     | 记录本身的唯一标识符                               |
| `created_at`               | datetime | 记录创建时的时间戳                                |
| `modified_at`              | datetime | 记录最后修改时的时间戳                              |
| `session_id`               | UUID     | 该运行所属实验或追踪项目的唯一标识符                       |
| `run_id`                   | UUID     | 会话内特定运行的唯一标识符                            |
| `key`                      | string   | 描述反馈标准的键，例如 `'correctness'`              |
| `score`                    | number   | 与反馈键关联的数值分数                              |
| `value`                    | string   | 用于存储与分数关联的值。适用于分类反馈。                     |
| `comment`                  | string   | 与记录关联的任何评论或注释。这可以是对给定分数的说明。              |
| `correction`               | object   | 用于存储更正详情（如有）的预留字段                        |
| `feedback_source`          | object   | 包含反馈来源信息的对象                              |
| `feedback_source.type`     | string   | 反馈来源的类型，例如 `'api'`、`'app'`、`'evaluator'` |
| `feedback_source.metadata` | object   | 用于存储额外元数据的预留字段，目前                        |
| `feedback_source.user_id`  | UUID     | 提供反馈的用户的唯一标识符                            |

此 [参考文档](/langsmith/feedback-data-format) 解释了存储的反馈格式，这是 LangSmith 表示运行评估分数和注释的方式。

### 存储的运行数据字段

运行数据字段分布在托管的 ClickHouse 数据库和您的云对象存储（例如 S3 或 GCS）之间。

<Note>
  对于存储在对象存储中的运行字段，ClickHouse 中仅保留引用或指针。例如，`inputs` 和 `outputs` 内容被卸载到 S3/GCS，ClickHouse 记录在 `inputs_s3_urls` 和 `outputs_s3_urls` 字段中存储相应的 S3 URL。
</Note>

下表详细说明了每个运行字段及其存储位置：

| 字段                      | 存储位置       |
| ----------------------- | ---------- |
| `id`                    | ClickHouse |
| `name`                  | ClickHouse |
| `inputs`                | **对象存储**   |
| `run_type`              | ClickHouse |
| `start_time`            | ClickHouse |
| `end_time`              | ClickHouse |
| `extra`                 | **对象存储**   |
| `error`                 | **对象存储**   |
| `outputs`               | **对象存储**   |
| `events`                | **对象存储**   |
| `tags`                  | ClickHouse |
| `trace_id`              | ClickHouse |
| `dotted_order`          | ClickHouse |
| `status`                | ClickHouse |
| `child_run_ids`         | ClickHouse |
| `direct_child_run_ids`  | ClickHouse |
| `parent_run_ids`        | ClickHouse |
| `feedback_stats`        | ClickHouse |
| `reference_example_id`  | ClickHouse |
| `total_tokens`          | ClickHouse |
| `prompt_tokens`         | ClickHouse |
| `completion_tokens`     | ClickHouse |
| `total_cost`            | ClickHouse |
| `prompt_cost`           | ClickHouse |
| `completion_cost`       | ClickHouse |
| `first_token_time`      | ClickHouse |
| `session_id`            | ClickHouse |
| `in_dataset`            | ClickHouse |
| `parent_run_id`         | ClickHouse |
| `execution_order` (已弃用) | ClickHouse |
| `serialized`            | ClickHouse |
| `manifest_id` (已弃用)     | ClickHouse |
| `manifest_s3_id`        | ClickHouse |
| `inputs_s3_urls`        | ClickHouse |
| `outputs_s3_urls`       | ClickHouse |
| `price_model_id`        | ClickHouse |
| `app_path`              | ClickHouse |
| `last_queued_at`        | ClickHouse |
| `share_token`           | ClickHouse |

此 [参考文档](/langsmith/run-data-format) 解释了存储的运行（跨度）的格式，它们是跟踪的构建块。

***

<div className="source-links">
  <Callout icon="terminal-2">
    [通过 MCP 将这些文档](/use-these-docs) 连接到 Claude、VSCode 等，以获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/langsmith/langsmith-managed-clickhouse.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>