LangChain 官方中文文档

ClickHouse 是一款高性能的列式数据库系统。它支持快速的数据摄取，并针对分析查询进行了优化。

LangSmith 使用 ClickHouse 作为追踪（traces）和反馈（feedback）数据的主要存储。默认情况下，自托管（self-hosted）的 LangSmith 会使用一个与 LangSmith 实例捆绑的内部 ClickHouse 数据库。该数据库在 Kubernetes 集群中作为有状态集（stateful set）运行（与 LangSmith 应用在同一集群），或在同一主机上作为 Docker 容器运行（与 LangSmith 应用在同一主机）。

但是，您可以配置 LangSmith 使用外部 ClickHouse 数据库，以便于管理和扩展。通过配置外部 ClickHouse 数据库，您可以管理数据库的备份、扩展和其他运维任务。虽然 ClickHouse 目前还不是 Azure、AWS 或 Google Cloud 的原生服务，但您可以通过以下方式使用外部 ClickHouse 数据库运行 LangSmith：

LangSmith 托管的 ClickHouse
直接或通过云提供商市场部署一个 ClickHouse Cloud 实例：
在您云提供商的虚拟机（VM）上部署

使用前两个选项（LangSmith 托管的 ClickHouse 或 ClickHouse Cloud）将在您的 VPC 之外部署 ClickHouse 服务。但是，这两个选项都支持私有端点（private endpoints），这意味着您可以将流量定向到 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 实例上设置的一些配置参数。详细信息如下：

xml

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

我们的系统已针对上述配置参数进行了调优。更改这些参数可能导致意外行为。

高可用（HA）复制的 ClickHouse 集群

默认情况下，上述设置过程仅适用于单节点 ClickHouse 集群。

如果您希望使用多节点 ClickHouse 集群实现高可用性（HA），我们支持此功能，但需要额外的配置。此设置可以使用通过 Zookeeper 或 ClickHouse Keeper 进行数据复制的多节点 ClickHouse 集群。有关 ClickHouse 复制的更多信息，请参阅 ClickHouse 数据复制文档。

要使用复制的多节点 ClickHouse 设置来配置 LangSmith：

您需要拥有一个已配置 Keeper 或 Zookeeper 进行数据复制并具有适当设置的 ClickHouse 集群。请参阅 ClickHouse 复制设置文档。
您需要在 LangSmith 配置部分设置集群配置，特别是 cluster 设置，以匹配您的 ClickHouse 集群名称。这将在运行 ClickHouse 迁移时使用 Replicated 表引擎。
如果除了高可用性之外，您还希望在 ClickHouse 节点之间进行负载均衡（以分发读取或写入），我们建议使用负载均衡器或 DNS 负载均衡在您的 ClickHouse 服务器之间进行轮询。
注意：您需要在首次启动 LangSmith 并运行 ClickHouse 迁移之前启用 cluster 设置。这是一个必要条件，因为表引擎需要创建为 Replicated 表引擎，而不是非复制引擎类型。

当启用 cluster 运行迁移时，迁移将创建 Replicated 表引擎类型。这意味着数据将在集群中的服务器之间复制。这是一个主-主（master-master）设置，任何服务器都可以处理读取、写入或合并操作。

有关复制 ClickHouse 集群的示例设置，请参考 LangSmith Helm chart 仓库中示例下的复制 ClickHouse 部分。

LangSmith 托管的 ClickHouse

如果使用 LangSmith 托管的 ClickHouse，您需要在 LangSmith VPC 和 ClickHouse VPC 之间建立 VPC 对等连接。更多信息请联系支持团队 support.langchain.com。
您还需要设置 Blob 存储。您可以在 Blob 存储文档中阅读更多相关信息。

由 LangSmith 管理的 ClickHouse 安装使用 SharedMerge 引擎，该引擎会自动对它们进行集群化，并将计算与存储分离。

更多信息，请参阅托管 ClickHouse 页面。

参数

您需要为 LangSmith 安装提供几个参数来配置外部 ClickHouse 数据库。这些参数包括：

主机（Host）：ClickHouse 数据库的主机名或 IP 地址
HTTP 端口（HTTP Port）：ClickHouse 数据库监听 HTTP 连接的端口
原生端口（Native Port）：ClickHouse 数据库监听原生连接的端口
数据库（Database）：LangSmith 应使用的 ClickHouse 数据库名称
用户名（Username）：用于连接 ClickHouse 数据库的用户名
密码（Password）：用于连接 ClickHouse 数据库的密码
集群（Cluster，可选）：如果使用外部 ClickHouse 集群，则为 ClickHouse 集群的名称。设置后，LangSmith 将在集群上运行迁移并在实例之间复制数据。

集群部署的重要注意事项：

集群设置必须在全新的数据库模式（schema）上配置 - 现有的独立 ClickHouse 实例无法转换为集群模式。
集群功能仅支持外部管理的 ClickHouse 部署。它与捆绑的 ClickHouse 安装不兼容，因为这些安装不包含所需的 ZooKeeper 配置。
当使用集群部署时，LangSmith 将自动：
- 在集群中的所有节点上运行数据库迁移
- 配置表以在集群中进行数据复制

请注意，虽然数据在节点之间复制，但 LangSmith 不配置分布式表或处理查询路由 - 查询将被定向到指定的主机。如果需要，您需要在基础设施层面处理任何负载均衡或查询分发。

配置

有了这些参数，您就可以配置您的 LangSmith 实例以使用已部署的 ClickHouse 数据库。您可以通过修改 LangSmith Helm Chart 安装的 config.yaml 文件或 Docker 安装的 .env 文件来完成此操作。

HelmDocker

yaml

clickhouse:
  external:
    enabled: true
    host: "host"
    port: "http port"
    nativePort: "native port"
    user: "default"
    password: "password"
    database: "default"
    tls: false
    cluster: "my_cluster_name"  # 可选：如果使用外部 Clickhouse 集群，请设置此项

bash

# 在您的 .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 集群，请设置此项

配置完成后，您应该能够重新安装 LangSmith 实例。如果一切配置正确，您的 LangSmith 实例现在应该正在使用您的外部 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 不需要此配置。

Helm (服务器 TLS)Kubernetes Secret (CA 证书包)

yaml

config:
  customCa:
    secretName: "langsmith-custom-ca"  # 包含您的 CA 证书包的 Secret
    secretKey: "ca.crt"    # Secret 中包含 CA 证书包的键名
clickhouse:
  external:
    enabled: true
    host: "your-clickhouse-host.example.com"
    port: "8443"
    nativePort: "9440"
    user: "default"
    password: "password"
    database: "default"
    tls: true

yaml

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 服务器要求客户端证书认证：

提供一个包含您的客户端证书和密钥的 Secret。
通过 clickhouse.external.clientCert.secretName 引用它，并使用 certSecretKey 和 keySecretKey 指定密钥。

Helm (客户端认证)Kubernetes Secret (客户端证书/密钥)

yaml

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"

yaml

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 install 和 upgrade 时运行。应用程序本身不会通过此端口通信，它仅由迁移作业使用。

默认情况下，迁移作业连接到端口 9000 进行迁移。如果您的 ClickHouse 实例使用不同的非 TLS 原生端口，您可以使用 CLICKHOUSE_MIGRATE_NATIVE_PORT 环境变量进行配置：

yaml

backend:
  clickhouseMigrations:
    extraEnv:
      - name: CLICKHOUSE_MIGRATE_NATIVE_PORT
        value: "9000"  # 更改为您的非 TLS 原生端口

用于证书卷的 Pod 安全上下文

为 mTLS 挂载的证书卷受文件访问限制保护。为确保所有 LangSmith Pod 都能读取证书文件，您必须在 Pod 安全上下文中设置 fsGroup: 1000。

您可以通过以下两种方式之一进行配置：

选项 1：使用 commonPodSecurityContext

在顶层设置 fsGroup 以应用于所有 Pod：

yaml

commonPodSecurityContext:
  fsGroup: 1000

选项 2：添加到各个 Pod 的安全上下文

如果您需要更精细的控制，请将 fsGroup 单独添加到每个 Pod 的安全上下文中。有关完整参考，请参阅 mTLS 配置示例。

LangSmith

管理安装实例

连接到外部 ClickHouse 数据库

要求

高可用（HA）复制的 ClickHouse 集群

LangSmith 托管的 ClickHouse

参数

配置

与 ClickHouse 的 TLS

服务器 TLS（单向）

双向 TLS 与客户端认证（mTLS）

用于迁移的非 TLS 原生端口

用于证书卷的 Pod 安全上下文

连接到外部 ClickHouse 数据库

要求 ​

高可用（HA）复制的 ClickHouse 集群 ​

LangSmith 托管的 ClickHouse ​

参数 ​

配置 ​

与 ClickHouse 的 TLS ​

服务器 TLS（单向） ​

双向 TLS 与客户端认证（mTLS） ​

用于迁移的非 TLS 原生端口 ​

用于证书卷的 Pod 安全上下文 ​

要求

高可用（HA）复制的 ClickHouse 集群

LangSmith 托管的 ClickHouse

参数

配置

与 ClickHouse 的 TLS

服务器 TLS（单向）

双向 TLS 与客户端认证（mTLS）

用于迁移的非 TLS 原生端口

用于证书卷的 Pod 安全上下文