Chroma 首次加載 embedding 模型報下載失敗/超時（HuggingFace 網絡）

首次用 SentenceTransformerEmbeddingFunction("BAAI/bge-small-zh-v1.5") 時，程式在下載模型階段卡住或直接報連接錯誤（ConnectionError / ConnectTimeoutError，有的環境是 http:000）。根因是 huggingface.co 直連不通。設環境變數 HF_ENDPOINT=https://hf-mirror.com 走國內鏡像即可，模型約 92MB，成功後緩存到本地，之後不再聯網。

Issue & Env（案發現場與環境）

業務場景：按官方示例寫完 Chroma 程式碼，第一次跑 get_or_create_collection(... embedding_function=...) 時，Chroma 內部調 sentence-transformers 下載指定模型（如 BAAI/bge-small-zh-v1.5），下載失敗。報錯發生在模型加載階段，程式碼本身沒報語法錯。
環境：chromadb + sentence-transformers，任意 Python 版本；中國大陸網絡環境最典型，公司代理/防火牆環境同樣會出現。
關鍵區分：不是 chromadb 壞了，是它依賴的 HuggingFace 模型倉庫連不上；模型下載成功後該報錯消失。

StackTrace（堆疊日誌）

sentence-transformers 加載模型時連接超時的典型報錯（chatchat 項目實測堆疊，掘金原文，huggingface.co 直連超時）：

embeddings_api.py: ERROR: (MaxRetryError("HTTPSConnectionPool(host='huggingface.co', port=443):
Max retries exceeded with url: /api/models/BAAI/bge-large-zh
(Caused by ConnectTimeoutError(<urllib3.connection.HTTPSConnection object at 0x...>,
'Connection to huggingface.co timed out.'))")

純 chromadb + sentence-transformers 場景更常見的形態（the neural base 與 CSDN 整理）：

requests.exceptions.ConnectionError: HTTPSConnectionPool(host='huggingface.co', port=443): Max retries exceeded

或（部分環境表現，如本機實測 http:000）：

ValueError: Connection error, and we cannot find the requested files in the cached path.
Please try again or make sure your Internet connection is on.

Reproduce（復現程式碼）

import os
from chromadb.utils import embedding_functions

# 直接按官方示例跑，不设任何镜像环境变量
ef = embedding_functions.SentenceTransformerEmbeddingFunction(
    model_name="BAAI/bge-small-zh-v1.5", device="cpu"
)
ef(["你好"])  # 首次调用触发模型下载 → 连接超时报错

網絡不通時在第 5 行拋連接例外；能連通但很慢時表現為長時間卡住（下載 92MB 無進度）。

Root Cause（根因分析）

模型首次使用必須從 HuggingFace 下載

sentence-transformers 的 SentenceTransformer(model_name) 加載流程：先查本地緩存（~/.cache/huggingface/hub/），沒有就去 huggingface.co 拉模型倉庫。模型倉庫不是單個文件，包含 config.json、tokenizer、權重文件（bge-small-zh-v1.5 約 92MB）。任何一個文件拉不下來，整個加載就失敗。

直連 huggingface.co 不通是網絡層問題

報錯的本質是 TCP/TLS 連接建立失敗（ConnectTimeoutError / http:000），不是程式碼問題，也不是模型名拼錯。常見觸發：國內網絡對 huggingface.co 不穩定、公司防火牆只放行了部分域名（2024 年後 HF 新增了 xet 存儲 CDN 域名，舊白名單不夠用）、代理設定缺失。

下載是“一次性”的

模型下載成功後會緩存到 ~/.cache/huggingface/hub/models--BAAI--bge-small-zh-v1.5/，之後所有加載都走本地緩存，不再聯網。所以問題只出現在首次運行。這也是為什麼很多人“換臺機器又踩一次”——緩存是跟著機器走的。

The Fix（解決方案）

方案一（推薦）：HF_ENDPOINT 指到國內鏡像

# Linux / macOS
export HF_ENDPOINT=https://hf-mirror.com

# Windows PowerShell
$env:HF_ENDPOINT="https://hf-mirror.com"

然後再跑原腳本，模型會從鏡像站下載，其餘程式碼一行不用改：

HF_ENDPOINT=https://hf-mirror.com python your_script.py

hf-mirror.com 是社區維護的 HuggingFace 全量鏡像，用法就是在環境變數裡覆蓋 HF_ENDPOINT（huggingface_hub 庫自動讀取）。首次下載 92MB，之後緩存命中不再聯網。

方案二：本地手動下載模型，改用本地路徑

把模型下載到本地目錄後，model_name 直接傳本地路徑，徹底離線：

ef = embedding_functions.SentenceTransformerEmbeddingFunction(
    model_name="/path/to/bge-small-zh-v1.5", device="cpu"
)

目錄結構要完整（config.json + tokenizer + 權重文件）。

方案三：確認網絡到底通不通

排查第一步先分清是“完全不通”還是“部分域名不通”：

curl -I --max-time 10 https://huggingface.co

連接超時/無法解析 → 走方案一或方案二。
能返回 200/302 但下載中斷 → 可能是 xet CDN 域名被攔（transfer.xethub.hf.co、cas-server.xethub.hf.co 等），公司網絡需找管理員放行，或乾脆換鏡像。