跳到主要内容

故障排除

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

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

获取有用信息​

要诊断并解决问题，您首先需要检索一些相关信息。下面，我们将解释如何在 Kubernetes 设置、Docker 设置以及如何获取有用的浏览器信息。

通常，您需要分析的主要服务有

  • langsmith-backend：主要后端服务。
  • 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 文件，您可以遵循本指南，其中解释了各种浏览器获取 HAR 文件的简短过程。

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

常见问题​

DB::Exception: 无法预留 1.00 MiB，空间不足: 执行 WaitForAsyncInsert 时。（空间不足）​

当 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 有状态集 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. 如果使用绑定挂载，您需要增加挂载点的大小。
  3. 如果使用 Docker volume，您需要为该卷/Docker 分配更多空间。

错误: 脏数据库版本 'version'。修复并强制版本​

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

Kubernetes​

  1. 强制迁移到更早的版本，其中 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 = 脏版本 - 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 - 请求实体过大​

当请求大小超出允许的最大值时，会发生此错误。您需要增加 Nginx 配置中的最大请求大小。

Kubernetes​

  1. 编辑您的 langsmith_config.yaml 并增加 frontend.maxBodySize 的值。它可能看起来像这样
frontend:
  maxBodySize: "100M"
  1. 将您的更改应用到集群。

详细信息: code: 497, message: default: 权限不足。要执行此查询，需要具有 default.feedbacks_rmt 上的 CREATE ROW POLICY 权限​

当您的用户没有在 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

本页有帮助吗？


您可以留下详细反馈 在 GitHub 上.