Docker容器中Qdrant Client嵌入模型误报不支持问题排查咨询

使用Qdrant Python客户端并设置嵌入模型时，Docker容器内运行报错，错误信息如下：

File "/app/.venv/lib/python3.12/site-packages/qdrant_client/qdrant_fastembed.py", line 122, in set_model
    self._get_or_init_model(
  File "/app/.venv/lib/python3.12/site-packages/qdrant_client/qdrant_fastembed.py", line 205, in _get_or_init_model
    raise ValueError(
ValueError: Unsupported embedding model: "BAAI/bge-small-en-v1.5". Supported models: {'BAAI/bge-base-en': (768, <Distance.COSINE: 'Cosine'>), 'BAAI/bge-base-en-v1.5': (768, <Distance.COSINE: 'Cosine'>), 'BAAI/bge-large-en-v1.5': (1024, <Distance.COSINE: 'Cosine'>), 'BAAI/bge-small-en': (384, <Distance.COSINE: 'Cosine'>), 'BAAI/bge-small-en-v1.5': (384, <Distance.COSINE: 'Cosine'>), 'BAAI/bge-small-zh-v1.5': (512, <Distance.COSINE: 'Cosine'>), 'sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2': (384, <Distance.COSINE: 'Cosine'>), 'thenlper/gte-large': (1024, <Distance.COSINE: 'Cosine'>), 'mixedbread-ai/mxbai-embed-large-v1': (1024, <Distance.COSINE: 'Cosine'>), 'snowflake/snowflake-arctic-embed-xs': (384, <Distance.COSINE: 'Cosine'>), 'snowflake/snowflake-arctic-embed-s': (384, <Distance.COSINE: 'Cosine'>), 'snowflake/snowflake-arctic-embed-m': (768, <Distance.COSINE: 'Cosine'>), 'snowflake/snowflake-arctic-embed-m-long': (768, <Distance.COSINE: 'Cosine'>), 'snowflake/snowflake-arctic-embed-l': (1024, <Distance.COSINE: 'Cosine'>), 'intfloat/multilingual-e5-large': (1024, <Distance.COSINE: 'Cosine'>), 'sentence-transformers/paraphrase-multilingual-mpnet-base-v2': (768, <Distance.COSINE: 'Cosine'>), 'Qdrant/clip-ViT-B-32-text': (512, <Distance.COSINE: 'Cosine'>), 'sentence-transformers/all-MiniLM-L6-v2': (384, <Distance.COSINE: 'Cosine'>), 'jinaai/jina-embeddings-v2-base-en': (768, <Distance.COSINE: 'Cosine'>), 'jinaai/jina-embeddings-v2-small-en': (512, <Distance.COSINE: 'Cosine'>), 'jinaai/jina-embeddings-v2-base-de': (768, <Distance.COSINE: 'Cosine'>), 'jinaai/jina-embeddings-v2-base-code': (768, <Distance.COSINE: 'Cosine'>), 'nomic-ai/nomic-embed-text-v1.5': (768, <Distance.COSINE: 'Cosine'>), 'nomic-ai/nomic-embed-text-v1.5-Q': (768, <Distance.COSINE: 'Cosine'>), 'nomic-ai/nomic-embed-text-v1': (768, <Distance.COSINE: 'Cosine'>)}

观察到两个关键点：

• 报错提示不支持的BAAI/bge-small-en-v1.5模型，实际存在于报错给出的支持模型列表中
• 该错误仅在Docker容器中出现，Linux/Windows主机直接运行无问题

• 核对Qdrant客户端版本：确认容器内安装的qdrant-client版本和主机完全一致。不同版本的模型支持逻辑可能存在差异，即使报错显示的列表包含目标模型，版本不匹配也可能触发校验错误。执行pip show qdrant-client对比主机和容器内的版本号，不一致则统一版本。
• 验证模型名称字符串一致性：检查代码中传入的模型名称是否存在隐形字符（如空格、全角符号）、引号转义或大小写问题。Docker环境中字符串处理可能因编码或环境变量解析出现差异，可在代码中打印模型名称的原始字符串和长度，对比主机与容器的输出。
• 检查FastEmbed依赖版本：Qdrant的模型支持依赖FastEmbed库，容器内的FastEmbed版本可能与主机不同。执行pip show fastembed对比版本，若不一致则安装与主机相同的版本，或升级到兼容的最新版本。
• 确认Docker基础环境匹配：检查Docker使用的基础镜像（Python版本、操作系统）是否与主机一致。比如主机用Python 3.11，容器用Python 3.12，可能存在库的兼容性问题，尝试更换与主机一致的基础镜像重新构建容器。
• 清理Docker缓存重新构建：旧缓存层可能保留过时的依赖包，导致模型支持列表不匹配。执行docker build --no-cache重新构建镜像，确保所有依赖都是最新且正确安装的。
• 排查容器内网络连通性：Docker容器可能无法正常访问模型仓库，导致客户端无法验证模型有效性。可在容器内测试访问Hugging Face仓库的连通性，或提前下载模型文件挂载到容器内。
• 调试模型校验逻辑：在容器内代码中添加调试日志，打印客户端内部维护的支持模型列表，对比报错中显示的列表是否一致。查看qdrant_client/qdrant_fastembed.py中的_get_or_init_model方法，确认模型名称的校验逻辑是否存在环境相关的判断。

内容的提问来源于stack exchange，提问作者alok