PyInstaller打包FastAPI+ChromaDB项目遇ONNXMiniLM_L6_V2未定义错误

问题原因 #

PyInstaller打包时未自动识别chromadb中动态导入的默认嵌入模型模块，导致运行exe时找不到ONNXMiniLM_L6_V2。

解决方案 #

1. 显式导入缺失模块

在项目入口文件（比如main.py）开头添加显式导入，让PyInstaller能检测到该模块：

from chromadb.utils.embedding_functions import ONNXMiniLM_L6_V2

2. 利用spec文件添加隐藏导入

• 生成spec文件：

pyi-makespec --onefile main.py

• 打开生成的main.spec文件，修改hiddenimports参数，添加chromadb相关的嵌入函数模块：

a = Analysis(
    ['main.py'],
    ...
    hiddenimports=['chromadb.utils.embedding_functions', 'chromadb.utils.embedding_functions.onnx_mini_lm_l6_v2'],
    ...
)

• 使用spec文件重新打包：

pyinstaller main.spec --clean

3. 确保打包时包含ONNX模型文件

chromadb的ONNX模型文件需要被打包到exe中，否则运行时会找不到模型。在main.spec的datas参数中添加模型路径：

1. 找到本地Python环境中chromadb模型的存放路径，通常是：
   • Windows：你的虚拟环境目录/Lib/site-packages/chromadb/utils/embedding_functions/onnx_models
   • macOS/Linux：你的虚拟环境目录/lib/pythonX.X/site-packages/chromadb/utils/embedding_functions/onnx_models
2. 在spec文件的datas中添加路径映射：

datas=[('完整的模型目录路径', 'chromadb/utils/embedding_functions/onnx_models')],

3. 再次执行pyinstaller main.spec --clean打包。

4. 代码中显式指定嵌入函数

在初始化chromadb客户端时，显式传入定义好的嵌入函数，避免依赖动态导入：

import chromadb
from chromadb.utils.embedding_functions import ONNXMiniLM_L6_V2
from chromadb.config import Settings

embedding_func = ONNXMiniLM_L6_V2()
client = chromadb.Client(
    Settings(
        embedding_function=embedding_func,
        # 其他配置
    )
)

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