以编程方式使用文档

本指南将引导您了解运行自托管 LangSmith 实例时可能遇到的常见问题。

运行 LangSmith 时，您可能会遇到意外的 500 错误、缓慢的性能或其他问题。本指南将帮助您诊断并解决这些问题。

获取有用的信息

要诊断并解决问题，您首先需要获取一些相关信息。以下部分说明如何针对 Kubernetes 或 Docker 设置执行此操作，以及如何提取有用的浏览器信息。

通常，您需要分析的主要服务包括：

  • - langsmith-backend: 处理 CRUD API 请求、业务逻辑、前端和 SDK 的请求、用于摄取的跟踪准备以及 hub API。
  • - langsmith-platform-backend: 处理身份验证、运行摄取以及其他高容量任务。
  • - langsmith-queue: 处理传入的跟踪和反馈、异步摄取和持久化到数据存储、数据完整性检查以及数据库错误或连接问题时的重试。

有关这些服务的更多详细信息，请参阅 自托管概述.

Kubernetes

故障排除的第一步是收集有关 LangSmith 部署的重要调试信息。服务日志、kubernetes 事件以及容器的资源利用率可以帮助识别问题的根本原因。

您可以运行我们的 k8s 故障排除脚本 它将提取所有相关的 kubernetes 信息并将其输出到一个文件夹中进行调查。该脚本还会将此文件夹压缩成一个 zip 文件以便共享。以下是运行此脚本的示例，假设您的 langsmith 部署是在一个 langsmith namespace:

bash get_k8s_debugging_info.sh --namespace langsmith

然后您可以检查生成的文件夹内容，查找任何相关错误或信息。如果您希望 LangSmith 团队协助调试，请与团队共享此 zip 文件。

Docker

如果在 Docker 上运行，您可以通过运行以下命令来检查部署的日志：

docker compose logs >> logs.txt

浏览器错误

如果您遇到以浏览器错误形式出现的问题，检查 HAR 文件也可能有助于获取关键信息。要获取 HAR 文件，您可以按照 本指南 进行操作，其中说明了各种浏览器的简短流程。

然后您可以使用 Google 的 HAR 分析器 进行调查。您也可以将 HAR 文件发送给 LangSmith 团队以帮助调试。

常见问题

*DB::Exception: Cannot reserve 1.00 MiB, not enough space: While executing WaitForAsyncInsert. (NOT\_ENOUGH\_空间)*

当 ClickHouse 磁盘空间不足时会发生此错误。您需要增加 ClickHouse 可用的磁盘空间。

Kubernetes

在 Kubernetes 中，您需要增加 ClickHouse PVC 的大小。要实现这一点，您可以执行以下步骤：

  1. 获取 PVC 的存储类： kubectl get pvc data-langsmith-clickhouse-0 -n <namespace> -o jsonpath='{.spec.storageClassName}'
  1. 确保存储类具有 AllowVolumeExpansion: true： kubectl get sc <storage-class-name> -o jsonpath='{.allowVolumeExpansion}'
  • * 如果是 false，某些存储类可以更新以允许卷扩展。
  • * 要更新存储类，您可以运行 kubectl patch sc <storage-class-name> -p '{"allowVolumeExpansion": true}'
  • * 如果这失败，您可能需要创建一个具有正确设置的新存储类。
  1. 编辑您的 pvc 以设置新大小： kubectl edit pvc data-langsmith-clickhouse-0 -n <namespace> or kubectl patch pvc data-langsmith-clickhouse-0 '{"spec":{"resources":{"requests":{"storage":"100Gi"}}}}' -n <namespace>
  1. 更新您的 helm chart langsmith_config.yaml 到新大小（例如 100 Gi)
  1. 删除 clickhouse statefulset kubectl delete statefulset langsmith-clickhouse --cascade=orphan -n <namespace>
  1. 应用更新大小后的 helm chart（您可以参考 升级指南)
  1. 您的 pvc 现在应该具有新大小。运行以下命令验证 kubectl get pvc 和 kubectl exec langsmith-clickhouse-0 -- bash -c "df"

Docker

在 Docker 中，您需要增加 ClickHouse 卷的大小。要实现此操作，您可以执行以下步骤：

  1. 停止您的 LangSmith 实例。 docker compose down
  2. 如果使用绑定挂载，您需要增加挂载点的大小。
  3. 如果使用 docker volume, you will need to allocate more space to the volume/docker.

*错误：脏数据库版本 'version'。请修复并强制版本*

This error occurs when the ClickHouse database is in an inconsistent state with our migrations. You will need to reset to an earlier database version and then rerun your upgrade/migrations.

Kubernetes

  1. 强制迁移到早期版本，其中 version = dirty version - 1。
kubectl exec -it deployments/langsmith-backend -- bash -c 'migrate -source "file://clickhouse/migrations" -database "clickhouse://$CLICKHOUSE_HOST:$CLICKHOUSE_NATIVE_PORT?username=$CLICKHOUSE_USER&password=$CLICKHOUSE_PASSWORD&database=$CLICKHOUSE_DB&x-multi-statement=true&x-migrations-table-engine=MergeTree&secure=$CLICKHOUSE_TLS" force <version>'
  1. Rerun your upgrade/migrations.

Docker

  1. 强制迁移到早期版本，其中 version = dirty version - 1。
docker compose exec langchain-backend migrate -source "file://clickhouse/migrations" -database "clickhouse://$CLICKHOUSE_HOST:$CLICKHOUSE_NATIVE_PORT?username=$CLICKHOUSE_USER&password=$CLICKHOUSE_PASSWORD&database=$CLICKHOUSE_DB&x-multi-statement=true&x-migrations-table-engine=MergeTree&secure=$CLICKHOUSE_TLS" force <version>
  1. Rerun your upgrade/migrations.

*413 - 请求实体过大*

当请求大小超过允许的最大大小时会出现此错误。您需要在 Nginx 配置中增加最大请求大小。

Kubernetes

  1. 编辑您的 langsmith_config.yaml 并增加 frontend.maxBodySize 值。这可能类似于这样：
frontend:
  maxBodySize: "100M"
  1. 将您的更改应用到集群。

*Details: code: 497, message: default: Not enough privileges. to execute this query, it's necessary to have the grant CREATE ROW POLICY ON default.feedbacks\_rmt*

当您的用户没有在 Clickhouse 中创建行策略的必要权限时会出现此错误。部署 Docker 版本时，您需要从 github 仓库复制 users.xml 文件。这会将 <access_management> 标签添加到 users.xml 文件，这允许用户创建行策略。以下是我们期望使用的默认 users.xml 文件。

<clickhouse>
    <users>
        <default>
            <access_management>1</access_management>
            <named_collection_control>1</named_collection_control>
            <show_named_collections>1</show_named_collections>
            <show_named_collections_secrets>1</show_named_collections_secrets>
            <profile>default</profile>
        </default>
    </users>
    <profiles>
        <default>
            <async_insert>1</async_insert>
            <async_insert_max_data_size>2000000</async_insert_max_data_size>
            <wait_for_async_insert>0</wait_for_async_insert>
            <parallel_view_processing>1</parallel_view_processing>
            <allow_simdjson>0</allow_simdjson>
            <lightweight_deletes_sync>0</lightweight_deletes_sync>
        </default>
    </profiles>
</clickhouse>

在某些环境中，您的挂载点可能无法被容器写入。在这些情况下，我们建议构建包含 users.xml 文件的自定义镜像。

示例 Dockerfile:

FROM clickhouse/clickhouse-server:24.8
COPY ./users.xml /etc/clickhouse-server/users.d/users.xml

然后执行以下步骤：

  1. 构建您的自定义镜像。
docker build -t <image-name> .
  1. 更新您的 docker-compose.yaml 以使用自定义镜像。确保移除 users.xml 挂载点。
langchain-clickhouse:
  image: <image-name>
  1. 重启您的 LangSmith 实例。
docker compose down --volumes
docker compose up

*使用 AquaSec 运行集群时 ClickHouse 启动失败*

在某些环境中，AquaSec 可能会阻止 ClickHouse 正确启动。这可能表现为 ClickHouse pod 没有任何日志输出且无法标记为就绪。 通常这是由于 AquaSec 设置的 LD_PRELOAD 导致的，这会干扰 ClickHouse。要解决此问题，您可以向 ClickHouse 部署添加以下环境变量：

Kubernetes

编辑您的 langsmith_config.yaml （或相应的配置文件）并设置 AQUA_SKIP_LD_PRELOAD 环境变量：

clickhouse:
  statefulSet:
    extraEnv:
      - name: AQUA_SKIP_LD_PRELOAD
        value: "true"

Docker

编辑您的 docker-compose.yaml 并设置 AQUA_SKIP_LD_PRELOAD 环境变量：

langchain-clickhouse:
  environment:
    - AQUA_SKIP_LD_PRELOAD=true