连接到外部 ClickHouse 数据库 - 以编程方式使用文档

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

LangSmith 使用 ClickHouse 作为追踪和反馈的主要数据存储。默认情况下，自托管的 LangSmith 将使用随 LangSmith 实例一起打包的内部 ClickHouse 数据库。这作为有状态副本集运行在与 LangSmith 应用相同的 Kubernetes 集群中，或作为 Docker 容器运行在与 LangSmith 应用相同的主机上。

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

* LangSmith 托管的 ClickHouse
* 配置一个 ClickHouse Cloud 可以直接或通过云提供商市场：
* Azure 市场
* Google Cloud 市场
* AWS 市场
* 在您云提供商的虚拟机上

要求

* 一个已配置的 ClickHouse 实例，您的 LangSmith 应用可以访问该实例的网络（有关选项，请参阅上文）。
* 一个对 ClickHouse 数据库具有管理员访问权限的用户。此用户将用于创建必要的表、索引和视图。
* 我们同时支持独立 ClickHouse 和外部管理的集群部署。对于集群部署，请确保所有节点运行相同的版本。请注意，集群设置不支持随附的 ClickHouse 安装。
* 我们仅支持 ClickHouse 版本 >= 23.9。使用 ClickHouse 版本 >= 24.2 需要 LangSmith v0.6 或更高版本。

* 我们依赖几个需要在 ClickHouse 实例上设置的配置参数。详情如下：

<profiles>
  <default>
      <async_insert>1</async_insert> # Turn on async insert
      <async_insert_max_data_size>25000000</async_insert_max_data_size> # Flush data to disk after 25MB. You may need to adjust this based on your workload.
      <wait_for_async_insert>0</wait_for_async_insert> # Disable waiting for async insert by default
      <parallel_view_processing>1</parallel_view_processing> # Enable parallel view processing
      <materialize_ttl_after_modify>0</materialize_ttl_after_modify> # Disable TTL materialization after modify
      <wait_for_async_insert_timeout>120</wait_for_async_insert_timeout> # Set the timeout for waiting for async insert
      <lightweight_deletes_sync>0</lightweight_deletes_sync> # Disable lightweight deletes sync
      <allow_materialized_view_with_bad_select>1</allow_materialized_view_with_bad_select> # Allow materialized views with legacy SELECT statements that cause CH to fail
  </default>
</profiles>

高可用复制的 ClickHouse 集群

如果您想使用多节点 ClickHouse 集群来实现高可用性，我们支持通过额外的必要配置来实现。此设置可以使用具有多个节点的 ClickHouse 集群，其中数据通过 Zookeeper 或 ClickHouse Keeper 进行复制。有关 ClickHouse 复制的更多信息，请参阅 ClickHouse 数据复制文档.

为了使用复制的多节点 ClickHouse 设置配置 LangSmith：

* 您需要拥有一个已设置 Keeper 或 Zookeeper 进行数据复制以及相应配置的 ClickHouse 集群。请参阅 ClickHouse 复制设置文档.
* 您需要在 LangSmith 配置部分设置集群配置，具体是 cluster 设置以匹配您的 ClickHouse 集群名称。这将在运行 ClickHouse 迁移时使用 Replicated 表引擎。
* 如果您希望在 HA 之外还想在 ClickHouse 节点之间进行负载均衡（以分配读取或写入），我们建议使用负载均衡器或 DNS 负载均衡来轮询您的 ClickHouse 服务器。
* **注意**：您需要启用 cluster 设置，然后再首次启动 LangSmith 并运行 ClickHouse 迁移。这是必需的，因为表引擎需要创建为 Replicated 表引擎而非非复制引擎类型。

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

LangSmith 托管的 ClickHouse

* 如果使用 LangSmith 托管的 ClickHouse，您需要在 LangSmith VPC 和 ClickHouse VPC 之间设置 VPC 对等连接。请通过以下方式联系支持 support.langchain.com 获取更多信息。
* 您还需要设置 Blob Storage。您可以在以下位置阅读更多关于 Blob Storage 的信息 Blob Storage 文档.

有关更多信息，请参阅托管 ClickHouse page.

参数

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

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

配置

有了这些参数，您可以配置 LangSmith 实例使用已配置的 ClickHouse 数据库。您可以通过修改 config.yaml 文件（用于 LangSmith Helm Chart 安装）或 .env 文件（用于 Docker 安装）。

clickhouse:
  external:
    enabled: true
    host: "host"
    port: "http port"
    nativePort: "native port"
    user: "default"
    password: "password"
    database: "default"
    tls: false
    cluster: "my_cluster_name"  # Optional: Set this if using an external Clickhouse cluster

# In your .env file
CLICKHOUSE_HOST=langchain-clickhouse # Change to your Clickhouse host if using external Clickhouse. Otherwise, leave it as is
CLICKHOUSE_USER=default # Change to your Clickhouse user if needed
CLICKHOUSE_DB=default # Change to your Clickhouse database if needed
CLICKHOUSE_PORT=8123 # Change to your Clickhouse port if needed
CLICKHOUSE_TLS=false # Change to true if you are using TLS to connect to Clickhouse. Otherwise, leave it as is
CLICKHOUSE_PASSWORD=password # Change to your Clickhouse password if needed
CLICKHOUSE_NATIVE_PORT=9000 # Change to your Clickhouse native port if needed
CLICKHOUSE_CLUSTER=my_cluster_name # Optional: Set this if using an external Clickhouse cluster

配置完成后，您应该能够重新安装 LangSmith 实例。如果一切配置正确，您的 LangSmith 实例现在应该正在使用您的外部 ClickHouse 数据库。

ClickHouse 的 TLS

Use this section to configure TLS for ClickHouse connections. For mounting internal/public CAs so LangSmith trusts your ClickHouse server certificate, see 配置自定义 TLS 证书.

服务器 TLS（单向）

要为 ClickHouse 连接启用 TLS：

- 在配置中设置 tls: true （或配合外部密钥使用 tlsSecretKey ）。
- 使用适当的 TLS 端口（通常为 8443 用于 HTTP， 9440 用于原生 TCP 连接）。
- 使用 config.customCa.secretName 和 config.customCa.secretKey 提供 CA 证书包（如果使用内部 CA）。

config:
  customCa:
    secretName: "langsmith-custom-ca"  # Secret containing your CA bundle
    secretKey: "ca.crt"    # Key in the Secret with the CA bundle
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-----

    -----END CERTIFICATE-----

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

从 LangSmith helm chart 版本 **0.12.29**开始，我们支持 ClickHouse 客户端的 mTLS。对于 mTLS 中的服务器端认证，请使用服务器 TLS 步骤（自定义 CA）以及以下客户端证书配置。

如果您的 ClickHouse 服务器需要客户端证书认证：

- 提供包含您的客户端证书和密钥的 Secret。
- 通过 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-----

    -----END CERTIFICATE-----
  tls.key: |
    -----BEGIN PRIVATE KEY-----

    -----END PRIVATE KEY-----

用于迁移的非 TLS 原生端口

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

backend:
  clickhouseMigrations:
    extraEnv:
      - name: CLICKHOUSE_MIGRATE_NATIVE_PORT
        value: "9000"  # Change to your non-TLS native port

证书卷的 Pod 安全上下文

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

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

**选项 1：使用 commonPodSecurityContext**

设置 fsGroup 在顶层以将其应用到所有 Pod：

commonPodSecurityContext:
  fsGroup: 1000

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

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