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