学习笔记 · Obsidian
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，不只检查端口。
质量与性能
- 在目标语言/领域上建 query-document 评测集，比较 Recall@k、MRR/nDCG 与业务成功率；不只看 MTEB。
- 分别压测单查询 p95 和批量索引吞吐；调整 batch size 时同时观察显存、OOM 与 tail latency。
- 用确定文本做向量维度、数值 finite、范数、相似度排序和重启一致性测试。
- 对 query/document prompt 设置保存独立版本；新 prompt 不对旧向量直接查询。
依赖与安全
本地模型会下载大型权重和可能的自定义代码。只从允许仓库拉取，锁定 commit/hash，验证许可和供应链；权重缓存不进 Git、不与租户文档共享可写目录。对 Transformers/torch/sentence-transformers/optimum 做版本锁定和镜像扫描。