主题
LangSmith 使用 ClickHouse 作为**追踪（traces）和反馈（feedback）**的主要存储引擎。为了便于管理和扩展，建议将自托管的 LangSmith 实例连接到外部的 ClickHouse 实例。LangSmith 托管的 ClickHouse 是一个选项，允许您使用由 LangSmith 团队监控和维护的全托管 ClickHouse 实例。
架构概述
将 LangSmith 托管的 ClickHouse 与您的自托管 LangSmith 实例结合使用的架构，与使用完全自托管的 ClickHouse 实例类似，但存在几个关键区别：
- 您需要在您的 LangSmith 实例和 LangSmith 托管的 ClickHouse 实例之间建立私有网络连接。这是为了确保您的数据安全，并且您可以从自托管的 LangSmith 实例连接到 ClickHouse 实例。
- 使用此选项时，追踪中的敏感信息（输入和输出）将存储在您云环境内的云对象存储（S3 或 GCS）中，而不是 ClickHouse 中，以确保敏感信息不会离开您的 VPC。有关特定数据字段存储位置的更多详细信息，请参阅数据存储。
- LangSmith 团队将监控您的 ClickHouse 实例，并确保其平稳运行。这使我们能够跟踪诸如运行摄取延迟和查询性能等指标。
整体架构如下所示：
要求
- 您必须使用受支持的 Blob 存储选项。 请阅读 Blob 存储指南 了解更多信息。
- 要使用私有端点，请确保您的 VPC 位于 ClickHouse Cloud 支持的区域内。否则，您将需要使用一个我们将通过防火墙规则进行保护的公共端点。您的 VPC 需要有一个 NAT 网关，以便我们能够将您的流量加入白名单。
- 您必须拥有一个可以连接到 LangSmith 托管 ClickHouse 服务的 VPC。您需要与我们的团队合作来设置必要的网络。
- 您必须运行一个 LangSmith 自托管实例。您可以将我们的托管 ClickHouse 服务与 Kubernetes 和 Docker 安装一起使用。
数据存储
ClickHouse 存储**运行（runs）和反馈（feedback）**数据，具体包括：
- 所有反馈数据字段。
- 部分运行数据字段。
有关字段列表，请参阅存储的运行数据字段和存储的反馈数据字段。
LangChain 将敏感应用数据定义为运行的 inputs、outputs、errors、manifests、extras 和 events，因为这些字段可能包含 LLM 提示词和补全。使用 LangSmith 托管的 ClickHouse 时，这些敏感字段存储在您云环境内的云对象存储（S3 或 GCS）中，而运行数据的其余部分存储在 ClickHouse 中，确保敏感信息永远不会离开您的 VPC。
存储的反馈数据字段
由于所有反馈数据都存储在 ClickHouse 中，请勿在反馈（分数和注释/评论）或存储的运行数据字段中提到的任何其他运行字段中发送敏感信息。
使用 LangSmith 托管的 ClickHouse 设置时，所有反馈数据字段都存储在 ClickHouse 中：
| 字段名称 | 类型 | 描述 |
|---|---|---|
id | UUID | 记录本身的唯一标识符 |
created_at | datetime | 记录创建时的时间戳 |
modified_at | datetime | 记录最后修改时的时间戳 |
session_id | UUID | 运行所属的实验或追踪项目的唯一标识符 |
run_id | UUID | 会话中特定运行（run）的唯一标识符 |
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 表示运行评估分数和注释的方式。
存储的运行数据字段
运行数据字段分布在托管的 ClickHouse 数据库和您的云对象存储（例如 S3 或 GCS）之间。
对于存储在对象存储中的运行字段，ClickHouse 中仅保留引用或指针。例如，inputs 和 outputs 的内容被卸载到 S3/GCS，ClickHouse 记录在 inputs_s3_urls 和 outputs_s3_urls 字段中存储相应的 S3 URL。
下表详细说明了每个运行字段及其存储位置：
| 字段 | 存储位置 |
|---|---|
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 |
这份参考文档解释了存储的运行（span）的格式，它们是追踪（trace）的构建块。