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 等），公司网络需找管理员放行，或干脆换镜像。