【避坑指南】部署 Open WebUI 报错：ModuleNotFoundError: No module named ‘pkg_resources‘ 彻底解决方法

原因分析

报错定位在 pymilvus 的内部调用中。

1. 直接原因：pkg_resources 是 setuptools 库的一个模块。在较新的 Python 环境中，如果只安装了基础包，可能并没有包含 setuptools。
2. 深层原因：旧版本的 pymilvus 使用了 pkg_resources 来管理版本和依赖检查，而这种方式在 Python 3.12+ 或某些精简版 Conda 环境中已不再推荐，甚至会因为缺少安装包直接导致导入失败。

解决方案

第一步：补齐基础依赖

首先，我们需要手动为环境安装 setuptools，这是最快捷的补丁方案：

Bash

pip install setuptools 

第二步：彻底解决（推荐）

仅仅补丁可能不够，因为旧版 pymilvus 可能还存在其他的兼容性小坑。建议直接升级 pymilvus 到最新版本，新版已经优化了对版本检索的逻辑，减少了对 pkg_resources 的硬依赖。

Bash

pip install --upgrade pymilvus 

第三步：验证修复

在终端中输入以下一行命令，如果不报错并输出 Success，说明环境已经恢复正常：

Bash

python -c "import pkg_resources; print('Success')" 

进阶：针对 Open WebUI 的额外提示

如果你是在配置 DATABASE_URL 使用 PostgreSQL 和 Milvus 进行 RAG（检索增强生成）开发，请确保：

1. Milvus 服务已启动：使用 Docker Desktop 确保 milvus-standalone 正常运行。
2. 环境变量生效：确保 VECTOR_DB=milvus 等配置已正确加载。

总结

在部署复杂的开源项目（如 Open WebUI）时，Python 环境的'微小差异'往往是导致启动失败的元凶。遇到 pkg_resources 报错时，别慌，'先装 setuptools，再升 pymilvus' 这一套组合拳基本能解决 90% 的问题。

希望这篇博文能帮到遇到同样问题的开发者。如果你正在折腾 RAG 或本地 LLM 部署，欢迎留言交流！