---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: evergreen
tags: [langchain, python, embeddings, huggingface, ollama, tei, self-hosted]
topic: LangChain Python 本地开源 Embedding 模型、Sentence Transformers、Ollama 与 TEI 自托管
sources:
  - https://docs.langchain.com/oss/python/integrations/embeddings/bge_huggingface
  - https://docs.langchain.com/oss/python/integrations/embeddings/huggingfacehub
  - https://docs.langchain.com/oss/python/integrations/embeddings/instruct_embeddings
  - https://docs.langchain.com/oss/python/integrations/embeddings/ollama
  - https://docs.langchain.com/oss/python/integrations/embeddings/sentence_transformers
  - https://docs.langchain.com/oss/python/integrations/embeddings/text_embeddings_inference
last_verified: 2026-08-11
---

# Embedding：本地开源与自托管

## 选择结论

- 本机/单 worker 快速验证：`langchain-huggingface` 的 `HuggingFaceEmbeddings`。
- 无 GPU 的简单本地服务：`langchain-ollama` 的 `OllamaEmbeddings`，前提是已锁定模型 tag/digest。
- 高并发/生产 GPU 服务：Hugging Face Text Embeddings Inference（TEI），用 `OpenAIEmbeddings` 连其 `/v1/embeddings` 兼容端点。
- 任何场景都先确定模型授权、revision、query/document prompt、归一化、dimension 与截断策略。

## 页面要点

| 集成 | 安装/初始化 | 必须保留的契约 |
|---|---|---|
| BGE on Hugging Face | `langchain-huggingface`; `HuggingFaceEmbeddings` | `BAAI/bge-m3` 建议 `normalize_embeddings=True`，不需 query prompt；`bge-*-en-v1.5` 查询应使用模型指定 prompt，且 query/doc 都归一化 |
| Hugging Face | `langchain-huggingface`; local `HuggingFaceEmbeddings` 或 `HuggingFaceEndpointEmbeddings` | 本地、Inference Endpoint/Provider 与 TEI 是三种部署边界；Hub token、model revision、实际端点和预处理都需记录 |
| Instructor | `langchain-community`, `InstructorEmbedding`, `sentence-transformers`; 页面同时引入 `HuggingFaceEmbeddings` | 页面将 Instructor 用法标为 legacy；新接入先评估当前 `HuggingFaceEmbeddings` + 显式 query/document prompt，避免旧依赖 |
| Ollama | `langchain-ollama`; `OllamaEmbeddings(model=...)` | 启动前拉取并 pin 模型；对 query/doc 分别测试，管理本地端点、并发、keep-alive、内存/GPU 与请求大小 |
| Sentence Transformers | `langchain-huggingface`; `HuggingFaceEmbeddings(model_name=...)` | 默认设备选择顺序是 CUDA → MPS → CPU；GPU 用 `batch_size` 提高吞吐，使用 cosine 时归一化；E5/Qwen3/BGE/GTE 按 model card 设定 query/doc prompt |
| TEI | 部署 Hugging Face TEI；客户用 `langchain-openai` 的 `OpenAIEmbeddings(base_url=.../v1)` | 旧指南用 `HuggingFaceEndpointEmbeddings(model=URL)` 已无效，现会要求 model 是 Hub repo ID。TEI 服务端 tokenization 时设 `check_embedding_ctx_length=False` |

## 初始化参数

`HuggingFaceEmbeddings` 的核心参数应配置化并记录到索引元数据：

- `model_name` + 不可变 revision/commit；
- `model_kwargs` 中的 device、dtype/trust-remote-code 等，其中 remote code 默认关闭，开启前需审查并 pin commit；
- `encode_kwargs` 的 batch size、prompt、normalize；
- `query_encode_kwargs` 的查询 prompt/normalize；
- chunk 最大 token 和超长策略。

## TEI 生产化

文档示例中 TEI 本地端点默认不要 API key，这不是生产安全基线。对端点加服务间认证/mTLS 或经过受控网关，禁止公网直达；设置每租户并发、batch/token 上限、请求 deadline 和 cancel。

TEI 镜像、模型权重/revision、tokenizer、dtype、扩容参数和 GPU 型号共同形成一个发布版本。readiness 必须真实执行一次小 embedding，不只检查端口。

## 质量与性能

1. 在目标语言/领域上建 query-document 评测集，比较 Recall@k、MRR/nDCG 与业务成功率；不只看 MTEB。
2. 分别压测单查询 p95 和批量索引吞吐；调整 batch size 时同时观察显存、OOM 与 tail latency。
3. 用确定文本做向量维度、数值 finite、范数、相似度排序和重启一致性测试。
4. 对 query/document prompt 设置保存独立版本；新 prompt 不对旧向量直接查询。

## 依赖与安全

本地模型会下载大型权重和可能的自定义代码。只从允许仓库拉取，锁定 commit/hash，验证许可和供应链；权重缓存不进 Git、不与租户文档共享可写目录。对 Transformers/torch/sentence-transformers/optimum 做版本锁定和镜像扫描。