连接到外部 ClickHouse 数据库

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

LangSmith 使用 ClickHouse 作为追踪和反馈的主要数据存储。默认情况下，自托管 LangSmith 会使用一个随 LangSmith 实例一起打包的内部 ClickHouse 数据库。它作为有状态集（stateful set）运行在与 LangSmith 应用相同的 Kubernetes 集群中。

不过，你可以将 LangSmith 配置为使用外部 ClickHouse 数据库，以便更轻松地管理和扩展。通过配置一个外部 ClickHouse 数据库，你可以管理数据库的备份、扩展和其他运维任务。虽然 ClickHouse 目前还不是 Azure、AWS 或 Google Cloud 的原生服务，但你可以按以下方式让 LangSmith 配合外部 ClickHouse 数据库运行：

LangSmith 托管的 ClickHouse
直接或通过云提供商市场预配一个 ClickHouse Cloud：
在你的云提供商中的一台 VM 上

NOTE

使用前两种选项（LangSmith 托管的 ClickHouse 或 ClickHouse Cloud）会在你的 VPC 之外预配一个 Clickhouse 服务。但两种选项都支持私有端点，这意味着你可以将流量导向该 ClickHouse 服务而不将它暴露给公共互联网（例如通过 AWS PrivateLink 或 GCP Private Service Connect）。

此外，可以将敏感信息配置为不存储在 Clickhouse 中。更多信息请通过 support.langchain.com 联系支持。

要求

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

WARNING

将 ClickHouse 降级到较早版本会导致系统表数据损坏并造成重大停机。如果你需要在 ClickHouse 版本变更方面获得协助，或在升级后遇到问题，请在尝试降级之前通过 support.langchain.com 联系支持。

我们依赖于在你的 ClickHouse 实例上设置的若干配置参数。这些参数在下文详述：

xml

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

WARNING

我们的系统经过调优以配合上述配置参数工作。更改这些参数可能导致意外行为。

HA 复制型 Clickhouse 集群

WARNING

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

如果你想使用多节点 Clickhouse 集群来实现高可用，我们通过额外的必需配置对此提供支持。这一设置可以使用一个多节点 Clickhouse 集群，其中数据通过 Zookeeper 或 Clickhouse Keeper 复制。有关 Clickhouse 复制的更多信息，参阅 Clickhouse Data Replication Docs。

要用复制型多节点 Clickhouse 设置来配置 LangSmith：

你需要一个用 Keeper 或 Zookeeper 设置好以进行数据复制并配有适当设置的 Clickhouse 集群。参阅 Clickhouse Replication Setup Docs。
你需要在 LangSmith 配置一节中设置 cluster 设置，具体来说是将 cluster 设置与你的 Clickhouse 集群名称相匹配。这会在运行 Clickhouse 迁移时使用 Replicated 表引擎。
如果除 HA 之外，你还希望在 Clickhouse 节点之间做负载均衡（以分配读取或写入），我们建议使用负载均衡器或 DNS 负载均衡在你的 Clickhouse 服务器之间轮询。
注意：你需要在首次启动 LangSmith 并运行 Clickhouse 迁移之前启用你的 cluster 设置。这是一项要求，因为表引擎需要被创建为 Replicated 表引擎，而非非复制的引擎类型。

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

NOTE

有关复制型 ClickHouse 集群的示例设置，参阅 LangSmith Helm chart 仓库 examples 下的复制型 ClickHouse 章节。

LangSmith 托管的 ClickHouse

如果使用 LangSmith 托管的 ClickHouse，你需要在 LangSmith VPC 与 ClickHouse VPC 之间建立一个 VPC peering 连接。更多信息请通过 support.langchain.com 联系支持。
你还需要设置 Blob 存储。你可以在 Blob 存储文档中了解更多关于 Blob 存储的内容。

NOTE

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

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

参数

你需要向 LangSmith 安装提供若干参数以配置一个外部 ClickHouse 数据库。这些参数包括：

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

WARNING

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

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

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

配置

有了这些参数，你就可以配置你的 LangSmith 实例以使用已预配的 ClickHouse 数据库。你可以通过修改 LangSmith Helm Chart 安装的 config.yaml 文件来做到这一点。

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"  # Optional: Set this if using an external Clickhouse cluster

配置完成后，你应当可以重新安装你的 LangSmith 实例。如果一切都正确配置，你的 LangSmith 实例现在应当正在使用你的外部 ClickHouse 数据库。

ClickHouse 的 TLS

使用本节为 ClickHouse 连接配置 TLS。要挂载内部/公共 CA 以使 LangSmith 信任你的 ClickHouse 服务器证书，参阅配置自定义 TLS 证书。

服务器 TLS（单向）

要为 ClickHouse 连接启用 TLS：

在你的配置中设置 tls: true（或对外部 secret 使用 tlsSecretKey）。
使用合适的 TLS 端口（HTTP 通常为 8443，原生 TCP 连接为 9440）。
如果使用内部 CA，通过 config.customCa.secretName 和 config.customCa.secretKey 提供一个 CA bundle。

WARNING

仅当你的 ClickHouse 服务器使用内部或私有 CA 时才挂载自定义 CA。公共可信 CA 不需要此配置。

Helm (server TLS)Kubernetes Secret (CA bundle)

yaml

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

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 (client auth)Kubernetes Secret (client cert/key)

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 原生端口

WARNING

当对 ClickHouse 使用 mTLS 时，你必须为我们的迁移作业保留一个非 TLS 原生（TCP）端口开启，该作业在 helm 安装和升级时运行。应用本身不会通过这个端口通信，它仅由迁移作业使用。

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

yaml

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

证书卷的 pod 安全上下文

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

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

选项 1：使用 commonPodSecurityContext

在顶层设置 fsGroup 以将其应用于所有 pod：

yaml

commonPodSecurityContext:
  fsGroup: 1000

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

如果你需要更细粒度的控制，请将 fsGroup 逐个添加到每个 pod 的安全上下文中。有关完整参考，参阅 mTLS 配置示例。

数据集

创建数据集

运行评估

评估技术

定义评估目标

打分方法

实验配置

多模态评估

分析实验结果

微调

教程

常见数据类型

评估器类型

UI

SDK

框架与集成

改进评估器

反馈

追踪设置

集成

手动埋点

配置与故障排除

项目与环境设置

高级追踪技术

数据与隐私

故障排除指南

查看与管理追踪

批量导出追踪数据

轨迹视图

数据类型参考

监控与告警

在线评估器

自动化

开发你的应用

设置依赖

持久化

能力

助手

运行

并发消息处理

如何构建

鉴权与访问控制

自定义鉴权教程

服务器定制

静态加密

替换内置后端

扩展 HTTP 服务器

请求头与日志

部署指南

参考

配置

参考

提示词

创建与管理提示词

连接模型

上下文中枢

教程

全栈 Web 应用

Agent Server API

控制平面 API

计费与用量

参考

按云服务商起步

用 Terraform 部署

AWS

GCP

Azure

安装实例

配置实例

连接外部服务

平台鉴权与访问控制

管理实例

自托管可观测性

混合部署

脚本

参考

组织