使用llama_index时HuggingFaceEmbedding致Jupyter Notebook崩溃求助

核心原因与解决步骤 #

• 内存不足是最常见的崩溃原因，优先从这里排查：

  1. 强制使用CPU加载模型（避免GPU显存不足），修改代码如下：

     Settings.embed_model = HuggingFaceEmbedding(
         model_name="BAAI/bge-small-en-v1.5",
         device="cpu"
     )
     

  2. 若要使用GPU，通过量化加载减少显存占用：

     Settings.embed_model = HuggingFaceEmbedding(
         model_name="BAAI/bge-small-en-v1.5",
         model_kwargs={'device_map': 'auto', 'load_in_8bit': True}
     )
     

     注：使用量化需要安装bitsandbytes库，执行pip install bitsandbytes即可。

• 模型下载与本地路径设置：

  • HuggingFaceEmbedding会自动下载模型到默认缓存目录，无需手动下载，默认路径为~/.cache/huggingface/hub（Windows系统为C:\Users\<你的用户名>\.cache\huggingface\hub）。
  • 若要指定本地自定义路径，可先手动将模型仓库下载到本地文件夹（比如./local_models/bge-small-en-v1.5），然后修改代码：

    Settings.embed_model = HuggingFaceEmbedding(
        model_name="./local_models/bge-small-en-v1.5"
    )
    

• 依赖版本兼容检查：

  • 确保transformers、torch、sentence-transformers版本匹配，建议安装稳定版：

    pip install --upgrade transformers torch sentence-transformers
    

  • 若使用GPU，需确保torch版本与本地CUDA版本兼容，避免因CUDA不匹配导致崩溃。

• Jupyter环境优化：

  • 若本地Jupyter内存限制不足，可尝试用命令行启动时增加内存参数，比如：

    jupyter notebook --NotebookApp.max_buffer_size=10737418240  # 设置10GB内存限制
    

  • 换用VS Code的Jupyter内核运行，部分情况下比原生Jupyter Notebook更稳定。

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