ClickHouse 是一个高性能的列式数据库系统。它支持快速的数据摄取，并针对分析查询进行了优化。
LangSmith 使用 ClickHouse 作为追踪和反馈数据的主要存储。默认情况下，自托管的 LangSmith 将使用与 LangSmith 实例捆绑的内部 ClickHouse 数据库。该数据库作为有状态集运行在与 LangSmith 应用相同的 Kubernetes 集群中，或作为 Docker 容器运行在与 LangSmith 应用相同的主机上。
但是，您可以配置 LangSmith 使用外部 ClickHouse 数据库，以便于管理和扩展。通过配置外部 ClickHouse 数据库，您可以管理数据库的备份、扩展和其他运维任务。虽然 ClickHouse 目前还不是 Azure、AWS 或 Google Cloud 的原生服务，但您可以通过以下方式使用外部 ClickHouse 数据库运行 LangSmith：
使用前两个选项（LangSmith 托管的 ClickHouse 或 ClickHouse Cloud）将在您的 VPC 之外 配置 ClickHouse 服务。但是，这两个选项都支持私有端点，这意味着您可以将流量定向到 ClickHouse 服务，而无需将其暴露在公共互联网上（例如通过 AWS PrivateLink 或 GCP Private Service Connect）。此外，可以配置为不将敏感信息存储在 ClickHouse 中。更多信息请联系支持：support.langchain.com。
- 一个已配置的 ClickHouse 实例，您的 LangSmith 应用将具有网络访问权限（选项见上文）。
- 一个对 ClickHouse 数据库具有管理员访问权限的用户。此用户将用于创建必要的表、索引和视图。
- 我们支持独立的 ClickHouse 和外部管理的集群部署。对于集群部署，请确保所有节点运行相同的版本。请注意，捆绑的 ClickHouse 安装不支持集群设置。
- 我们仅支持 ClickHouse 版本 >= 23.9。使用 ClickHouse 版本 >= 24.2 需要 LangSmith v0.6 或更高版本。
将 ClickHouse 降级到较早版本可能导致系统表数据损坏并造成严重停机。如果您需要有关 ClickHouse 版本更改的帮助，或在升级后遇到问题，请在尝试降级之前联系支持：support.langchain.com。
- 我们依赖一些在您的 ClickHouse 实例上设置的配置参数。详细信息如下：
<profiles>
<default>
<async_insert>1</async_insert> # 开启异步插入
<async_insert_max_data_size>25000000</async_insert_max_data_size> # 在 25MB 后刷新数据到磁盘。您可能需要根据工作负载调整此值。
<wait_for_async_insert>0</wait_for_async_insert> # 默认禁用等待异步插入
<parallel_view_processing>1</parallel_view_processing> # 启用并行视图处理
<materialize_ttl_after_modify>0</materialize_ttl_after_modify> # 修改后禁用 TTL 物化
<wait_for_async_insert_timeout>120</wait_for_async_insert_timeout> # 设置等待异步插入的超时时间
<lightweight_deletes_sync>0</lightweight_deletes_sync> # 禁用轻量级删除同步
<allow_materialized_view_with_bad_select>1</allow_materialized_view_with_bad_select> # 允许使用会导致 CH 失败的旧版 SELECT 语句的物化视图
</default>
</profiles>
我们的系统已针对上述配置参数进行了调优。更改这些参数可能导致意外行为。
高可用复制的 ClickHouse 集群
默认情况下，上述设置过程仅适用于单节点 ClickHouse 集群。
- 您需要拥有一个已配置 Keeper 或 Zookeeper 进行数据复制并具有适当设置的 ClickHouse 集群。请参阅 ClickHouse 复制设置文档。
- 您需要在 LangSmith 配置 部分设置集群设置，特别是
cluster 设置，以匹配您的 ClickHouse 集群名称。这将在运行 ClickHouse 迁移时使用 Replicated 表引擎。
- 如果除了高可用性之外，您还希望在 ClickHouse 节点之间进行负载均衡（以分发读取或写入），我们建议使用负载均衡器或 DNS 负载均衡在您的 ClickHouse 服务器之间进行轮询。
- 注意：您需要在首次启动 LangSmith 并运行 ClickHouse 迁移之前启用
cluster 设置。这是一个要求，因为表引擎需要创建为 Replicated 表引擎，而不是非复制引擎类型。
当启用 cluster 运行迁移时，迁移将创建 Replicated 表引擎类型。这意味着数据将在集群中的服务器之间复制。这是一个主-主设置，任何服务器都可以处理读取、写入或合并。
LangSmith 托管的 ClickHouse
- 如果使用 LangSmith 托管的 ClickHouse，您需要在 LangSmith VPC 和 ClickHouse VPC 之间建立 VPC 对等连接。更多信息请联系支持：support.langchain.com。
- 您还需要设置 Blob 存储。您可以在 Blob 存储文档 中阅读更多信息。
由 LangSmith 管理的 ClickHouse 安装使用 SharedMerge 引擎，该引擎会自动对它们进行集群化并将计算与存储分离。
- 主机：ClickHouse 数据库的主机名或 IP 地址
- HTTP 端口：ClickHouse 数据库监听 HTTP 连接的端口
- 原生端口：ClickHouse 数据库监听 原生连接 的端口
- 数据库：LangSmith 应使用的 ClickHouse 数据库名称
- 用户名：用于连接到 ClickHouse 数据库的用户名
- 密码：用于连接到 ClickHouse 数据库的密码
- 集群（可选）：如果使用外部 ClickHouse 集群，则为 ClickHouse 集群的名称。设置后，LangSmith 将在集群上运行迁移并在实例之间复制数据。
集群部署的重要注意事项：
-
集群设置必须在全新的架构上配置 - 现有的独立 ClickHouse 实例无法转换为集群模式。
-
集群仅支持外部管理的 ClickHouse 部署。它与捆绑的 ClickHouse 安装不兼容，因为这些安装不包含所需的 ZooKeeper 配置。
-
使用集群部署时，LangSmith 将自动：
- 在集群中的所有节点上运行数据库迁移
- 配置表以在集群中进行数据复制
请注意，虽然数据在节点之间复制，但 LangSmith 不配置分布式表或处理查询路由 - 查询将被定向到指定的主机。如果需要，您需要在基础设施层面处理任何负载均衡或查询分发。 config.yaml 文件或 Docker 安装的 .env 文件来完成此操作。
clickhouse:
external:
enabled: true
host: "主机"
port: "http 端口"
nativePort: "原生端口"
user: "default"
password: "密码"
database: "default"
tls: false
cluster: "my_cluster_name" # 可选：如果使用外部 Clickhouse 集群，请设置此项
# 在您的 .env 文件中
CLICKHOUSE_HOST=langchain-clickhouse # 如果使用外部 Clickhouse，请更改为您的 Clickhouse 主机。否则，保持原样
CLICKHOUSE_USER=default # 如果需要，请更改为您的 Clickhouse 用户
CLICKHOUSE_DB=default # 如果需要，请更改为您的 Clickhouse 数据库
CLICKHOUSE_PORT=8123 # 如果需要，请更改为您的 Clickhouse 端口
CLICKHOUSE_TLS=false # 如果您使用 TLS 连接到 Clickhouse，请更改为 true。否则，保持原样
CLICKHOUSE_PASSWORD=password # 如果需要，请更改为您的 Clickhouse 密码
CLICKHOUSE_NATIVE_PORT=9000 # 如果需要，请更改为您的 Clickhouse 原生端口
CLICKHOUSE_CLUSTER=my_cluster_name # 可选：如果使用外部 Clickhouse 集群，请设置此项
与 ClickHouse 的 TLS
使用本节配置 ClickHouse 连接的 TLS。有关挂载内部/公共 CA 以便 LangSmith 信任您的 ClickHouse 服务器证书的信息，请参阅 配置自定义 TLS 证书。
服务器 TLS（单向）
要为 ClickHouse 连接启用 TLS：
- 在配置中设置
tls: true（或使用带有外部密钥的 tlsSecretKey）。
- 使用适当的 TLS 端口（通常 HTTP 为
8443，原生 TCP 连接为 9440）。
- 如果使用内部 CA，请使用
config.customCa.secretName 和 config.customCa.secretKey 提供 CA 包。
仅当您的 ClickHouse 服务器使用内部或私有 CA 时才挂载自定义 CA。公开信任的 CA 不需要此配置。
config:
customCa:
secretName: "langsmith-custom-ca" # 包含您的 CA 包的密钥
secretKey: "ca.crt" # 密钥中存储 CA 包的键名
clickhouse:
external:
enabled: true
host: "your-clickhouse-host.example.com"
port: "8443"
nativePort: "9440"
user: "default"
password: "password"
database: "default"
tls: true
apiVersion: v1
kind: Secret
metadata:
name: langsmith-custom-ca
type: Opaque
stringData:
ca.crt: |
-----BEGIN CERTIFICATE-----
<ROOT_OR_INTERMEDIATE_CA_CERT_CHAIN>
-----END CERTIFICATE-----
双向 TLS 与客户端认证 (mTLS)
自 LangSmith helm chart 版本 0.12.29 起，我们支持 ClickHouse 客户端的 mTLS。对于 mTLS 中的服务器端认证，除了以下客户端证书配置外，还需使用 服务器 TLS 步骤（自定义 CA）。
如果您的 ClickHouse 服务器需要客户端证书认证：
- 提供包含客户端证书和密钥的密钥。
- 通过
clickhouse.external.clientCert.secretName 引用它，并使用 certSecretKey 和 keySecretKey 指定密钥。
clickhouse:
external:
enabled: true
host: "your-clickhouse-host.example.com"
port: "8443"
nativePort: "9440"
user: "default"
password: "password"
database: "default"
tls: true
clientCert:
secretName: "clickhouse-client-cert"
certSecretKey: "tls.crt"
keySecretKey: "tls.key"
apiVersion: v1
kind: Secret
metadata:
name: clickhouse-client-cert
type: Opaque
stringData:
tls.crt: |
-----BEGIN CERTIFICATE-----
<CLIENT_CERT>
-----END CERTIFICATE-----
tls.key: |
-----BEGIN PRIVATE KEY-----
<CLIENT_KEY>
-----END PRIVATE KEY-----
用于迁移的非 TLS 原生端口
当对 ClickHouse 使用 mTLS 时，您必须 保持一个非 TLS 原生（TCP）端口 开放，以供我们的迁移作业使用，该作业在 helm 安装和升级时运行。应用本身不会通过此端口通信，它 仅由迁移作业使用。
9000 进行迁移。如果您的 ClickHouse 实例使用不同的非 TLS 原生端口，您可以使用 CLICKHOUSE_MIGRATE_NATIVE_PORT 环境变量进行配置：
backend:
clickhouseMigrations:
extraEnv:
- name: CLICKHOUSE_MIGRATE_NATIVE_PORT
value: "9000" # 更改为您的非 TLS 原生端口
证书卷的 Pod 安全上下文
为 mTLS 挂载的证书卷受文件访问限制保护。为确保所有 LangSmith Pod 都能读取证书文件，您必须在 Pod 安全上下文中设置 fsGroup: 1000。
您可以通过以下两种方式之一进行配置：
选项 1：使用 commonPodSecurityContext
在顶层设置 fsGroup 以应用于所有 Pod：
commonPodSecurityContext:
fsGroup: 1000
fsGroup 单独添加到每个 Pod 的安全上下文中。有关完整参考，请参阅 mTLS 配置示例。
