故障排除

本指南将带你了解运行 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 命名空间中启动的：

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

当 ClickHouse 磁盘空间耗尽时会出现此错误。你需要增加 ClickHouse 可用的磁盘空间。

Kubernetes

在 Kubernetes 中，你需要增加 ClickHouse PVC 的大小。为此，你可以执行以下步骤：

1. 获取 PVC 的存储类：kubectl get pvc data-langsmith-clickhouse-0 -n <namespace> -o jsonpath='{.spec.storageClassName}'

2. 确保该存储类有 AllowVolumeExpansion: true：kubectl get sc <storage-class-name> -o jsonpath='{.allowVolumeExpansion}'

   • 如果它是 false，某些存储类可以更新以允许卷扩展。
   • 要更新存储类，你可以运行 kubectl patch sc <storage-class-name> -p '{"allowVolumeExpansion": true}'
   • 如果这失败，你可能需要用正确的设置创建一个新存储类。

3. 编辑你的 PVC 使其具有新大小：kubectl edit pvc data-langsmith-clickhouse-0 -n <namespace> 或 kubectl patch pvc data-langsmith-clickhouse-0 '{"spec":{"resources":{"requests":{"storage":"100Gi"}}' -n <namespace>

4. 更新你的 helm chart langsmith_config.yaml 到新大小（例如 100 Gi）

5. 删除 clickhouse statefulset kubectl delete statefulset langsmith-clickhouse --cascade=orphan -n <namespace>

6. 用更新后的大小应用 helm chart（你可以遵循升级指南）

7. 你的 pvc 现在应当有新大小。通过运行 kubectl get pvc 和 kubectl exec langsmith-clickhouse-0 -- bash -c "df" 验证。

Docker

在 Docker 中，你需要增加 ClickHouse 卷的大小。为此，你可以执行以下步骤：

1. 停止你的 LangSmith 实例。docker compose down
2. 如果使用 bind mount，你需要增加挂载点的大小。
3. 如果使用一个 docker volume，你需要为卷/docker 分配更多空间。

error: Dirty database version 'version'. fix and force version

当 ClickHouse 数据库与我们的迁移处于不一致状态时会出现此错误。你需要重置到一个较早的数据库版本，然后重新运行你的升级/迁移。

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. 重新运行你的升级/迁移。

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. 重新运行你的升级/迁移。

413 - request entity too large

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

Kubernetes

1. 编辑你的 langsmith_config.yaml 并增加 frontend.maxBodySize 值。这可能看起来像这样：

frontend:
  maxBodySize: "100M"

2. 把你的更改应用到集群。

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

2. 更新你的 docker-compose.yaml 以使用自定义镜像。确保移除 users.xml 挂载点。

langchain-clickhouse:
  image: <image-name>

3. 重启你的 LangSmith 实例。

docker compose down --volumes
docker compose up

ClickHouse fails to start up when running a cluster with AquaSec

在某些环境中，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

---