解决常见错误

打开的文件过多 (OS error 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 卷（Volume）而不是绑定挂载（Bind mount）

# 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 共享挂载带来的问题。

无法打开集合元数据预写式日志 (Collections meta Wal)

当将 Qdrant 实例作为分布式部署的一部分启动时，您可能会遇到类似以下的错误消息

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

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

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

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

在 `multiprocessing` 中使用 Python gRPC 客户端

当在 multiprocessing（多进程）中使用 Python gRPC 客户端时，您可能会遇到如下错误

<_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(...) 函数。