故障排除

本指南将为您介绍在运行自托管的 LangSmith 实例时可能遇到的常见问题。

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

排查问题的第一步是检查构成 LangSmith 的各项服务的日志。

如果在 Kubernetes 上运行，您可以通过运行以下命令来查看部署的日志（如果使用了其他名称进行部署，请将 langsmith 替换为您的部署名称）：

kubectl logs -l app.kubernetes.io/instance=langsmith --prefix -n <namespace> >> logs.txt

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

docker compose logs >> logs.txt

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

• langsmith-backend：主要后端服务。
• langsmith-queue: 队列服务。

常见问题

DB::Exception：无法预留 1.00 MiB，空间不足：执行 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: truekubectl 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. 如果使用绑定挂载（bind mount），则需要增大挂载点的大小。
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"

2. 将您的更改应用到集群。

详细信息：错误代码：497，消息：default：权限不足。要执行此查询，必须拥有在 default.feedbacks_rmt 上的 CREATE ROW POLICY 权限。

当您的用户在 ClickHouse 中没有创建行策略所需的必要权限时，会出现此错误。在部署 Docker 版本时，您还需要从 GitHub 仓库复制 users.xml 文件。 此举会向 users.xml 文件中添加 <access_management> 标签，从而允许用户创建行策略。以下是默认的 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