如何在调用chromadb的collections.add时引用本地onnx.tar.gz文件

核心原因 #

Chromadb默认使用all-MiniLM-L6-v2作为默认嵌入模型，调用collection.add时会自动从AWS下载该模型的ONNX压缩包。离线环境下需要手动指定本地模型路径，跳过自动下载步骤。

具体解决方案 #

步骤1：准备本地模型文件 #

将你已下载的onnx.tar.gz解压，得到完整的模型文件夹（解压后通常是all-MiniLM-L6-v2目录，包含onnx_model.onnx、tokenizer.json等核心文件）。把这个文件夹放到项目目录下，比如./local_models/all-MiniLM-L6-v2。

步骤2：修改代码，指定本地嵌入模型 #

直接在初始化客户端时，配置自定义的嵌入函数，指向本地模型路径：

import chromadb
from chromadb.utils import embedding_functions

# 初始化本地嵌入函数，替换为你的实际模型文件夹路径
local_embedding_function = embedding_functions.SentenceTransformerEmbeddingFunction(
    model_name="./local_models/all-MiniLM-L6-v2"
)

# 创建客户端并绑定本地嵌入函数
client = chromadb.Client()
collection = client.get_or_create_collection(
    name='test',
    embedding_function=local_embedding_function
)

# 调用add时将使用本地模型，不再触发下载
collection.add(
    documents=['ABCD'],
    metadatas=[{'source':'xyz'}],  # 修正原代码中metadatas的格式错误，需为字典列表
    ids=['id1']
)

备选方案：通过环境变量指定缓存路径 #

若不想修改代码，可通过环境变量让Chromadb读取本地缓存：

1. 设置环境变量指定Chromadb的缓存根目录：

export CHROMA_DB_DIR="./local_chroma_cache"

2. 将解压后的模型文件夹放到$CHROMA_DB_DIR/models目录下，确保路径结构与默认缓存一致（即$CHROMA_DB_DIR/models/all-MiniLM-L6-v2/包含所有模型文件）。

注意事项 #

• 确保本地模型文件夹的结构和官方下载的完全一致，解压时不要遗漏任何文件。
• 原代码中的metadatas参数格式错误，需为每个document对应一个字典的列表，示例中已修正该问题。

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