解决常见错误

打开文件过多 (操作系统错误 24)

每个集合段都需要打开一些文件。在某个时刻，您可能会在服务器日志中遇到以下错误

Error: Too many files open (OS error 24)

在这种情况下，您可能需要增加打开文件的限制。例如，您可以在启动 Docker 容器时执行此操作

docker run --ulimit nofile=10000:10000 qdrant/qdrant:latest

上述命令会将软限制和硬限制都设置为 10000。

如果您不使用 Docker，以下命令将更改当前用户会话的限制

ulimit -n 10000

请注意，该命令应在您运行 Qdrant 服务器之前执行。

不兼容的文件系统

Qdrant 对持久文件存储有一系列要求。最重要的要求是文件系统**必须**与POSIX 兼容。

从 v1.15.0 开始，Qdrant 在启动时执行文件系统兼容性运行时检查。如果检测到未知文件系统，您可能会看到如下警告

WARN qdrant: There is a potential issue with 
the filesystem for storage path ./storage. Details:
HFS/HFS+ filesystem support is untested

如果运行时检查失败，您可能会看到错误消息

ERROR qdrant: Filesystem check failed for storage path ./storage.
Details: FUSE filesystems may cause data corruption due to caching issues

如果报告此类错误，则继续使用当前配置是不安全的，并且您有丢失数据的风险。

如果继续使用不兼容文件系统的 Qdrant，您可能会看到最常见的错误

ERROR
Panic occurred in file /qdrant/lib/gridstore/src/gridstore.rs at line 53:
called `Result::unwrap()` on an `Err` value: OutputTooSmall { expected: 4, actual: 0 }

或

ERROR
Service internal error: task XXX panicked with message
"called `Result::unwrap()` on an `Err` value: OutputTooSmall { expected: 4, actual: 0 }"

还可能发生的情况是，服务重启后矢量数据会丢失（设置为全零）。

如何避免不兼容的文件系统？

最常见的不兼容文件系统配置是在 Windows 中使用基于 WSL 的 Docker 容器。当您将 Windows 文件夹挂载到 Qdrant Docker 容器中时，Windows 虚拟机监控程序会创建一个共享挂载，该挂载不完全兼容 POSIX。

优先使用 Docker 卷而不是绑定挂载

# Create named volume
docker volume create qdrant-storage

# Use named volume with qdrant container
docker run --rm -it \
	-p 6333:6333 -p 6334:6334 \
	-v qdrant-storage:/qdrant/storage qdrant/qdrant:v1.15.3

上述操作将卷保留在 Linux 容器内，从而防止与 Windows 共享挂载的问题。

无法打开集合元 Wal

当您在分布式部署中启动 Qdrant 实例时，可能会遇到类似这样的错误消息

Can't open Collections meta Wal: Os { code: 11, kind: WouldBlock, message: "Resource temporarily unavailable" }

这意味着 Qdrant 无法启动，因为集合无法加载。其关联的 WAL 文件当前不可用，很可能是因为相同的文件已被另一个 Qdrant 实例使用。

每个节点必须有自己独立的存储目录、卷或挂载。

形成的集群将负责与每个节点共享所有数据，并将其全部放置在正确的位置。如果使用 Kubernetes，每个节点必须有自己的卷。如果使用 Docker，每个节点必须有自己的存储挂载或卷。如果直接使用 Qdrant，每个节点必须有自己的存储目录。

将 Python gRPC 客户端与 `multiprocessing` 一起使用

当将 Python gRPC 客户端与 multiprocessing 一起使用时，您可能会遇到类似这样的错误

<_InactiveRpcError of RPC that terminated with:
	status = StatusCode.UNAVAILABLE
	details = "sendmsg: Socket operation on non-socket (88)"
	debug_error_string = "UNKNOWN:Error received from peer  {grpc_message:"sendmsg: Socket operation on non-socket (88)", grpc_status:14, created_time:"....."}"

发生此错误是因为 multiprocessing 创建了 gRPC 通道的副本，这些副本共享同一个套接字。当父进程关闭通道时，它会关闭套接字，子进程会尝试使用已关闭的套接字。

为了防止此错误，您可以对 multiprocessing 使用 forkserver 或 spawn 启动方法。

import multiprocessing

multiprocessing.set_start_method("forkserver")  # or "spawn"

或者，您可以切换到 REST API、异步客户端，或者使用 Python 客户端中内置的并行化功能，例如 qdrant.upload_points(...)