故障排除
本指南将带您了解在运行自托管的 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 的大小。为此，您可以执行以下步骤：
- 获取 PVC 的存储类：
kubectl get pvc data-langsmith-clickhouse-0 -n <namespace> -o jsonpath='{.spec.storageClassName}' - 确保存储类具有 AllowVolumeExpansion: true：
kubectl get sc <storage-class-name> -o jsonpath='{.allowVolumeExpansion}'- 如果为 false，某些存储类可以更新以允许卷扩展。
- 要更新存储类，您可以运行
kubectl patch sc <storage-class-name> -p '{"allowVolumeExpansion": true}' - 如果此操作失败，您可能需要创建一个具有正确设置的新存储类。
- 编辑你的 PVC 以设置新大小：
kubectl edit pvc data-langsmith-clickhouse-0 -n <namespace>或kubectl patch pvc data-langsmith-clickhouse-0 '{"spec":{"resources":{"requests":{"storage":"100Gi"}}}}' -n <namespace> - 更新您的 Helm 图表
langsmith_config.yaml至新大小（例如100 Gi） - 删除 clickhouse statefulset
kubectl delete statefulset langsmith-clickhouse --cascade=orphan -n <namespace> - 应用具有更新大小的 Helm Chart（您可以参考升级指南 此处）
- 您的 PVC 现在应具有新的大小。通过运行
kubectl get pvc和kubectl exec langsmith-clickhouse-0 -- bash -c "df"进行验证。
Docker
在 Docker 中，您需要增加 ClickHouse 卷的大小。为此，您可以执行以下步骤：
- 停止您的 LangSmith 实例。
docker compose down - 如果使用绑定挂载，您需要增加挂载点的大小。
- 如果使用 docker
volume，您需要为卷/docker 分配更多空间。
错误：数据库版本'版本'不干净。请修复并强制更新版本
当 ClickHouse 数据库与我们执行的迁移处于不一致状态时，会出现此错误。您需要将数据库重置到更早的版本，然后重新运行升级/迁移操作。
Kubernetes
- 强制迁移到更早的版本，其中版本 = 脏版本 - 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>'
- 重新运行您的升级/迁移操作。
Docker
- 强制迁移到更早的版本，其中版本 = 脏版本 - 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>
- 重新运行您的升级/迁移操作。
413 - 请求实体过大
当请求大小超过允许的最大值时会出现此错误。您需要在 Nginx 配置中增加最大请求大小。
Kubernetes
- 编辑您的
langsmith_config.yaml并增加frontend.maxBodySize的 值。 这看起来可能像这样：
frontend:
maxBodySize: "100M"
- 将您的更改应用到集群。
详细信息：代码：497，消息：默认值：权限不足。要执行此查询，必须拥有在 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
然后执行以下步骤：
- 构建您的自定义图像。
docker build -t <image-name> .
- 更新您的
docker-compose.yaml以使用自定义镜像。请确保移除 users.xml 挂载点。
langchain-clickhouse:
image: <image-name>
- 重启您的 LangSmith 实例。
docker compose down --volumes
docker compose up