[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-huggingface--sentence-transformers":3,"tool-huggingface--sentence-transformers":61},[4,18,26,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",156804,2,"2026-04-15T11:34:33",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108322,"2026-04-10T11:39:34",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":32,"last_commit_at":50,"category_tags":51,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[52,13,15,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":32,"last_commit_at":59,"category_tags":60,"status":17},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[52,14],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":66,"readme_en":67,"readme_zh":68,"quickstart_zh":69,"use_case_zh":70,"hero_image_url":71,"owner_login":72,"owner_name":73,"owner_avatar_url":74,"owner_bio":75,"owner_company":76,"owner_location":76,"owner_email":76,"owner_twitter":72,"owner_website":77,"owner_url":78,"languages":79,"stars":88,"forks":89,"last_commit_at":90,"license":91,"difficulty_score":32,"env_os":92,"env_gpu":93,"env_ram":94,"env_deps":95,"category_tags":101,"github_topics":76,"view_count":32,"oss_zip_url":76,"oss_zip_packed_at":76,"status":17,"created_at":102,"updated_at":103,"faqs":104,"releases":135},7813,"huggingface\u002Fsentence-transformers","sentence-transformers","State-of-the-Art Text Embeddings","sentence-transformers 是一个专为处理文本语义而设计的开源框架，能够轻松生成高质量的文本向量（Embeddings）。它核心解决了计算机难以直接理解自然语言含义的难题，通过将句子、段落甚至整篇文档转化为数值向量，让机器可以高效地计算文本间的相似度、进行语义搜索或识别复述内容。\n\n这款工具非常适合开发者、数据科学家及 AI 研究人员使用。无论是需要构建智能问答系统、推荐引擎，还是进行大规模文本数据挖掘，sentence-transformers 都能提供强大的支持。其独特亮点在于极高的易用性与丰富的生态：用户仅需几行代码即可调用 Hugging Face 上超过 15,000 个预训练模型，其中包含众多在权威评测榜（MTEB）上表现顶尖的模型。此外，它不仅支持稠密向量检索，还集成了重排序（Reranker）和稀疏编码功能，并允许用户基于自有数据轻松微调或从头训练定制模型，灵活适配各种特定业务场景。配合对 PyTorch 的深度优化，它能帮助团队快速将先进的自然语言处理能力落地到实际应用中。","\u003C!--- BADGES: START --->\n\n[![HF Models](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F%F0%9F%A4%97-models-yellow)](https:\u002F\u002Fhuggingface.co\u002Fmodels?library=sentence-transformers)\n[![GitHub - License](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002Fhuggingface\u002Fsentence-transformers?logo=github&style=flat&color=green)][#github-license]\n[![PyPI - Python Version](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fpyversions\u002Fsentence-transformers?logo=pypi&style=flat&color=blue)][#pypi-package]\n[![PyPI - Package Version](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fsentence-transformers?logo=pypi&style=flat&color=orange)][#pypi-package]\n[![Docs - GitHub.io](https:\u002F\u002Fimg.shields.io\u002Fstatic\u002Fv1?logo=github&style=flat&color=pink&label=docs&message=sentence-transformers)][#docs-package]\n\n\u003C!-- [![PyPI - Downloads](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fdm\u002Fsentence-transformers?logo=pypi&style=flat&color=green)][#pypi-package] -->\n\n\u003C!--- BADGES: END --->\n\n# Sentence Transformers: Embeddings, Retrieval, and Reranking\n\nThis framework provides an easy method to compute embeddings for accessing, using, and training state-of-the-art embedding and reranker models. It can be used to compute embeddings using Sentence Transformer models ([quickstart](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fquickstart.html#sentence-transformer)), to calculate similarity scores using Cross-Encoder (a.k.a. reranker) models ([quickstart](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fquickstart.html#cross-encoder)) or to generate sparse embeddings using Sparse Encoder models ([quickstart](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fquickstart.html#sparse-encoder)). This unlocks a wide range of applications, including [semantic search](https:\u002F\u002Fsbert.net\u002Fexamples\u002Fapplications\u002Fsemantic-search\u002FREADME.html), [semantic textual similarity](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fsentence_transformer\u002Fusage\u002Fsemantic_textual_similarity.html), and [paraphrase mining](https:\u002F\u002Fsbert.net\u002Fexamples\u002Fapplications\u002Fparaphrase-mining\u002FREADME.html).\n\nA wide selection of over [15,000 pre-trained Sentence Transformers models](https:\u002F\u002Fhuggingface.co\u002Fmodels?library=sentence-transformers) are available for immediate use on 🤗 Hugging Face, including many of the state-of-the-art models from the [Massive Text Embeddings Benchmark (MTEB) leaderboard](https:\u002F\u002Fhuggingface.co\u002Fspaces\u002Fmteb\u002Fleaderboard). Additionally, it is easy to train or finetune your own [embedding models](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fsentence_transformer\u002Ftraining_overview.html), [reranker models](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fcross_encoder\u002Ftraining_overview.html) or [sparse encoder models](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fsparse_encoder\u002Ftraining_overview.html) using Sentence Transformers, enabling you to create custom models for your specific use cases.\n\nFor the **full documentation**, see **[www.SBERT.net](https:\u002F\u002Fwww.sbert.net)**.\n\n## Installation\n\nWe recommend **Python 3.10+**, **[PyTorch 1.11.0+](https:\u002F\u002Fpytorch.org\u002Fget-started\u002Flocally\u002F)**, and **[transformers v4.34.0+](https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Ftransformers)**.\n\n**Install with pip**\n\n```\npip install -U sentence-transformers\n```\n\n**Install with conda**\n\n```\nconda install -c conda-forge sentence-transformers\n```\n\n**Install from sources**\n\nAlternatively, you can also clone the latest version from the [repository](https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsentence-transformers) and install it directly from the source code:\n\n```\npip install -e .\n```\n\n**PyTorch with CUDA**\n\nIf you want to use a GPU \u002F CUDA, you must install PyTorch with the matching CUDA Version. Follow\n[PyTorch - Get Started](https:\u002F\u002Fpytorch.org\u002Fget-started\u002Flocally\u002F) for further details how to install PyTorch.\n\n## Getting Started\n\nSee [Quickstart](https:\u002F\u002Fwww.sbert.net\u002Fdocs\u002Fquickstart.html) in our documentation.\n\n### Embedding Models\n\nFirst download a pretrained embedding a.k.a. Sentence Transformer model.\n\n```python\nfrom sentence_transformers import SentenceTransformer\n\nmodel = SentenceTransformer(\"sentence-transformers\u002Fall-MiniLM-L6-v2\")\n```\n\nThen provide some texts to the model.\n\n```python\nsentences = [\n    \"The weather is lovely today.\",\n    \"It's so sunny outside!\",\n    \"He drove to the stadium.\",\n]\nembeddings = model.encode(sentences)\nprint(embeddings.shape)\n# => (3, 384)\n```\n\nAnd that's already it. We now have numpy arrays with the embeddings, one for each text. We can use these to compute similarities.\n\n```python\nsimilarities = model.similarity(embeddings, embeddings)\nprint(similarities)\n# tensor([[1.0000, 0.6660, 0.1046],\n#         [0.6660, 1.0000, 0.1411],\n#         [0.1046, 0.1411, 1.0000]])\n```\n\n### Reranker Models\n\nFirst download a pretrained reranker a.k.a. Cross Encoder model.\n\n```python\nfrom sentence_transformers import CrossEncoder\n\n# 1. Load a pretrained CrossEncoder model\nmodel = CrossEncoder(\"cross-encoder\u002Fms-marco-MiniLM-L6-v2\")\n```\n\nThen provide some texts to the model.\n\n```python\n# The texts for which to predict similarity scores\nquery = \"How many people live in Berlin?\"\npassages = [\n    \"Berlin had a population of 3,520,031 registered inhabitants in an area of 891.82 square kilometers.\",\n    \"Berlin has a yearly total of about 135 million day visitors, making it one of the most-visited cities in the European Union.\",\n    \"In 2013 around 600,000 Berliners were registered in one of the more than 2,300 sport and fitness clubs.\",\n]\n\n# 2a. predict scores for pairs of texts\nscores = model.predict([(query, passage) for passage in passages])\nprint(scores)\n# => [8.607139 5.506266 6.352977]\n```\n\nAnd we're good to go. You can also use [`model.rank`](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fpackage_reference\u002Fcross_encoder\u002Fcross_encoder.html#sentence_transformers.cross_encoder.model.CrossEncoder.rank) to avoid having to perform the reranking manually:\n\n```python\n# 2b. Rank a list of passages for a query\nranks = model.rank(query, passages, return_documents=True)\n\nprint(\"Query:\", query)\nfor rank in ranks:\n    print(f\"- #{rank['corpus_id']} ({rank['score']:.2f}): {rank['text']}\")\n\"\"\"\nQuery: How many people live in Berlin?\n- #0 (8.61): Berlin had a population of 3,520,031 registered inhabitants in an area of 891.82 square kilometers.\n- #2 (6.35): In 2013 around 600,000 Berliners were registered in one of the more than 2,300 sport and fitness clubs.\n- #1 (5.51): Berlin has a yearly total of about 135 million day visitors, making it one of the most-visited cities in the European Union.\n\"\"\"\n```\n\n### Sparse Encoder Models\n\nFirst download a pretrained sparse embedding a.k.a. Sparse Encoder model.\n\n```python\n\nfrom sentence_transformers import SparseEncoder\n\n# 1. Load a pretrained SparseEncoder model\nmodel = SparseEncoder(\"naver\u002Fsplade-cocondenser-ensembledistil\")\n\n# The sentences to encode\nsentences = [\n    \"The weather is lovely today.\",\n    \"It's so sunny outside!\",\n    \"He drove to the stadium.\",\n]\n\n# 2. Calculate sparse embeddings by calling model.encode()\nembeddings = model.encode(sentences)\nprint(embeddings.shape)\n# [3, 30522] - sparse representation with vocabulary size dimensions\n\n# 3. Calculate the embedding similarities\nsimilarities = model.similarity(embeddings, embeddings)\nprint(similarities)\n# tensor([[   35.629,     9.154,     0.098],\n#         [    9.154,    27.478,     0.019],\n#         [    0.098,     0.019,    29.553]])\n\n# 4. Check sparsity stats\nstats = SparseEncoder.sparsity(embeddings)\nprint(f\"Sparsity: {stats['sparsity_ratio']:.2%}\")\n# Sparsity: 99.84%\n```\n\n## Pre-Trained Models\n\nWe provide a large list of pretrained models for more than 100 languages. Some models are general purpose models, while others produce embeddings for specific use cases.\n\n- [Pretrained Sentence Transformer (Embedding) Models](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fsentence_transformer\u002Fpretrained_models.html)\n- [Pretrained Cross Encoder (Reranker) Models](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fcross_encoder\u002Fpretrained_models.html)\n- [Pretrained Sparse Encoder (Sparse Embeddings) Models](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fsparse_encoder\u002Fpretrained_models.html)\n\n## Training\n\nThis framework allows you to fine-tune your own sentence embedding methods, so that you get task-specific sentence embeddings. You have various options to choose from in order to get perfect sentence embeddings for your specific task.\n\n- Embedding Models\n  - [Sentence Transformer > Training Overview](https:\u002F\u002Fwww.sbert.net\u002Fdocs\u002Fsentence_transformer\u002Ftraining_overview.html)\n  - [Sentence Transformer > Training Examples](https:\u002F\u002Fwww.sbert.net\u002Fdocs\u002Fsentence_transformer\u002Ftraining\u002Fexamples.html) or [training examples on GitHub](https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsentence-transformers\u002Ftree\u002Fmain\u002Fexamples\u002Fsentence_transformer\u002Ftraining).\n- Reranker Models\n  - [Cross Encoder > Training Overview](https:\u002F\u002Fwww.sbert.net\u002Fdocs\u002Fcross_encoder\u002Ftraining_overview.html)\n  - [Cross Encoder > Training Examples](https:\u002F\u002Fwww.sbert.net\u002Fdocs\u002Fcross_encoder\u002Ftraining\u002Fexamples.html) or [training examples on GitHub](https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsentence-transformers\u002Ftree\u002Fmain\u002Fexamples\u002Fcross_encoder\u002Ftraining).\n- Sparse Embedding Models\n  - [Sparse Encoder > Training Overview](https:\u002F\u002Fwww.sbert.net\u002Fdocs\u002Fsparse_encoder\u002Ftraining_overview.html)\n  - [Sparse Encoder > Training Examples](https:\u002F\u002Fwww.sbert.net\u002Fdocs\u002Fsparse_encoder\u002Ftraining\u002Fexamples.html) or [training examples on GitHub](https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsentence-transformers\u002Ftree\u002Fmain\u002Fexamples\u002Fsparse_encoder\u002Ftraining).\n\nSome highlights across the different types of training are:\n\n- Support of various transformer networks including BERT, RoBERTa, XLM-R, DistilBERT, Electra, BART, ...\n- Multi-Lingual and multi-task learning\n- Evaluation during training to find optimal model\n- [20+ loss functions](https:\u002F\u002Fwww.sbert.net\u002Fdocs\u002Fpackage_reference\u002Fsentence_transformer\u002Flosses.html) for embedding models, [10+ loss functions](https:\u002F\u002Fwww.sbert.net\u002Fdocs\u002Fpackage_reference\u002Fcross_encoder\u002Flosses.html) for reranker models and [10+ loss functions](https:\u002F\u002Fwww.sbert.net\u002Fdocs\u002Fpackage_reference\u002Fsparse_encoder\u002Flosses.html) for sparse embedding models, allowing you to tune models specifically for semantic search, paraphrase mining, semantic similarity comparison, clustering, triplet loss, contrastive loss, etc.\n\n## Application Examples\n\nYou can use this framework for:\n\n- **Computing Sentence Embeddings**\n\n  - [Dense Embeddings](https:\u002F\u002Fwww.sbert.net\u002Fexamples\u002Fsentence_transformer\u002Fapplications\u002Fcomputing-embeddings\u002FREADME.html)\n  - [Sparse Embeddings](https:\u002F\u002Fwww.sbert.net\u002Fexamples\u002Fsparse_encoder\u002Fapplications\u002Fcomputing_embeddings\u002FREADME.html)\n\n- **Semantic Textual Similarity**\n\n  - [Dense STS](https:\u002F\u002Fwww.sbert.net\u002Fdocs\u002Fsentence_transformer\u002Fusage\u002Fsemantic_textual_similarity.html)\n  - [Sparse STS](https:\u002F\u002Fwww.sbert.net\u002Fexamples\u002Fsparse_encoder\u002Fapplications\u002Fsemantic_textual_similarity\u002FREADME.html)\n\n- **Semantic Search**\n\n  - [Dense Search](https:\u002F\u002Fwww.sbert.net\u002Fexamples\u002Fsentence_transformer\u002Fapplications\u002Fsemantic-search\u002FREADME.html)\n  - [Sparse Search](https:\u002F\u002Fwww.sbert.net\u002Fexamples\u002Fsparse_encoder\u002Fapplications\u002Fsemantic_search\u002FREADME.html)\n\n- **Retrieve & Re-Rank**\n\n  - [Dense only Retrieval](https:\u002F\u002Fwww.sbert.net\u002Fexamples\u002Fsentence_transformer\u002Fapplications\u002Fretrieve_rerank\u002FREADME.html)\n  - [Sparse\u002FDense\u002FHybrid Retrieval](https:\u002F\u002Fwww.sbert.net\u002Fexamples\u002Fsentence_transformer\u002Fapplications\u002Fretrieve_rerank\u002FREADME.html)\n\n- [Clustering](https:\u002F\u002Fwww.sbert.net\u002Fexamples\u002Fsentence_transformer\u002Fapplications\u002Fclustering\u002FREADME.html)\n\n- [Paraphrase Mining](https:\u002F\u002Fwww.sbert.net\u002Fexamples\u002Fsentence_transformer\u002Fapplications\u002Fparaphrase-mining\u002FREADME.html)\n\n- [Translated Sentence Mining](https:\u002F\u002Fwww.sbert.net\u002Fexamples\u002Fsentence_transformer\u002Fapplications\u002Fparallel-sentence-mining\u002FREADME.html)\n\n- [Multilingual Image Search, Clustering & Duplicate Detection](https:\u002F\u002Fwww.sbert.net\u002Fexamples\u002Fsentence_transformer\u002Fapplications\u002Fimage-search\u002FREADME.html)\n\nand many more use-cases.\n\nFor all examples, see [examples\u002Fsentence_transformer\u002Fapplications](https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsentence-transformers\u002Ftree\u002Fmain\u002Fexamples\u002Fsentence_transformer\u002Fapplications).\n\n## Development setup\n\nAfter cloning the repo (or a fork) to your machine, in a virtual environment, run:\n\n```\npython -m pip install -e \".[dev]\"\n\npre-commit install\n```\n\nTo test your changes, run:\n\n```\npytest\n```\n\n## Citing & Authors\n\nIf you find this repository helpful, feel free to cite our publication [Sentence-BERT: Sentence Embeddings using Siamese BERT-Networks](https:\u002F\u002Fhuggingface.co\u002Fpapers\u002F1908.10084):\n\n```bibtex\n@inproceedings{reimers-2019-sentence-bert,\n    title = \"Sentence-BERT: Sentence Embeddings using Siamese BERT-Networks\",\n    author = \"Reimers, Nils and Gurevych, Iryna\",\n    booktitle = \"Proceedings of the 2019 Conference on Empirical Methods in Natural Language Processing\",\n    month = \"11\",\n    year = \"2019\",\n    publisher = \"Association for Computational Linguistics\",\n    url = \"https:\u002F\u002Farxiv.org\u002Fabs\u002F1908.10084\",\n}\n```\n\nIf you use one of the multilingual models, feel free to cite our publication [Making Monolingual Sentence Embeddings Multilingual using Knowledge Distillation](https:\u002F\u002Fhuggingface.co\u002Fpapers\u002F2004.09813):\n\n```bibtex\n@inproceedings{reimers-2020-multilingual-sentence-bert,\n    title = \"Making Monolingual Sentence Embeddings Multilingual using Knowledge Distillation\",\n    author = \"Reimers, Nils and Gurevych, Iryna\",\n    booktitle = \"Proceedings of the 2020 Conference on Empirical Methods in Natural Language Processing\",\n    month = \"11\",\n    year = \"2020\",\n    publisher = \"Association for Computational Linguistics\",\n    url = \"https:\u002F\u002Farxiv.org\u002Fabs\u002F2004.09813\",\n}\n```\n\nPlease have a look at [Publications](https:\u002F\u002Fwww.sbert.net\u002Fdocs\u002Fpublications.html) for our different publications that are integrated into SentenceTransformers.\n\n### Maintainers\n\nMaintainer: [Tom Aarsen](https:\u002F\u002Fgithub.com\u002Ftomaarsen), 🤗 Hugging Face\n\nDon't hesitate to open an issue if something is broken (and it shouldn't be) or if you have further questions.\n\n---\n\nThis project was originally developed by the [Ubiquitous Knowledge Processing (UKP) Lab](https:\u002F\u002Fwww.ukp.tu-darmstadt.de\u002F) at TU Darmstadt. We're grateful for their foundational work and continued contributions to the field.\n\n> This repository contains experimental software and is published for the sole purpose of giving additional background details on the respective publication.\n\n[#docs-package]: https:\u002F\u002Fwww.sbert.net\u002F\n[#github-license]: https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsentence-transformers\u002Fblob\u002Fmain\u002FLICENSE\n[#pypi-package]: https:\u002F\u002Fpypi.org\u002Fproject\u002Fsentence-transformers\u002F\n","\u003C!--- 徽章：开始 --->\n\n[![HF 模型](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F%F0%9F%A4%97-models-yellow)](https:\u002F\u002Fhuggingface.co\u002Fmodels?library=sentence-transformers)\n[![GitHub - 许可证](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002Fhuggingface\u002Fsentence-transformers?logo=github&style=flat&color=green)][#github-license]\n[![PyPI - Python 版本](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fpyversions\u002Fsentence-transformers?logo=pypi&style=flat&color=blue)][#pypi-package]\n[![PyPI - 包版本](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fsentence-transformers?logo=pypi&style=flat&color=orange)][#pypi-package]\n[![文档 - GitHub.io](https:\u002F\u002Fimg.shields.io\u002Fstatic\u002Fv1?logo=github&style=flat&color=pink&label=docs&message=sentence-transformers)][#docs-package]\n\n\u003C!-- [![PyPI - 下载量](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fdm\u002Fsentence-transformers?logo=pypi&style=flat&color=green)][#pypi-package] -->\n\n\u003C!--- 徽章：结束 --->\n\n# Sentence Transformers：嵌入、检索与重排序\n\n该框架提供了一种简便的方法来计算嵌入，以便访问、使用和训练最先进的嵌入模型及重排序模型。它可以用于通过 Sentence Transformer 模型计算嵌入（[快速入门](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fquickstart.html#sentence-transformer)），使用交叉编码器（即重排序器）模型计算相似度分数（[快速入门](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fquickstart.html#cross-encoder)），或使用稀疏编码器模型生成稀疏嵌入（[快速入门](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fquickstart.html#sparse-encoder)）。这为广泛的应用打开了大门，包括[语义搜索](https:\u002F\u002Fsbert.net\u002Fexamples\u002Fapplications\u002Fsemantic-search\u002FREADME.html)、[语义文本相似性](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fsentence_transformer\u002Fusage\u002Fsemantic_textual_similarity.html)以及[释义挖掘](https:\u002F\u002Fsbert.net\u002Fexamples\u002Fapplications\u002Fparaphrase-mining\u002FREADME.html)。\n\n在 🤗 Hugging Face 上提供了超过[15,000 个预训练的 Sentence Transformers 模型](https:\u002F\u002Fhuggingface.co\u002Fmodels?library=sentence-transformers)，可供立即使用，其中包括许多来自[MTEB 大规模文本嵌入基准排行榜](https:\u002F\u002Fhuggingface.co\u002Fspaces\u002Fmteb\u002Fleaderboard)的最先进模型。此外，使用 Sentence Transformers 轻松训练或微调您自己的[嵌入模型](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fsentence_transformer\u002Ftraining_overview.html)、[重排序模型](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fcross_encoder\u002Ftraining_overview.html)或[稀疏编码器模型](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fsparse_encoder\u002Ftraining_overview.html)，使您能够为特定用例创建自定义模型。\n\n有关**完整文档**，请参阅**[www.SBERT.net](https:\u002F\u002Fwww.sbert.net)**。\n\n## 安装\n\n我们建议使用**Python 3.10+**、**[PyTorch 1.11.0+](https:\u002F\u002Fpytorch.org\u002Fget-started\u002Flocally\u002F)** 和 **[transformers v4.34.0+](https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Ftransformers)**。\n\n**使用 pip 安装**\n\n```\npip install -U sentence-transformers\n```\n\n**使用 conda 安装**\n\n```\nconda install -c conda-forge sentence-transformers\n```\n\n**从源代码安装**\n\n或者，您也可以从[仓库](https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsentence-transformers)克隆最新版本，并直接从源代码进行安装：\n\n```\npip install -e .\n```\n\n**带有 CUDA 的 PyTorch**\n\n如果您希望使用 GPU \u002F CUDA，则必须安装与之匹配的 CUDA 版本的 PyTorch。请按照[PyTorch - 开始使用](https:\u002F\u002Fpytorch.org\u002Fget-started\u002Flocally\u002F)中的说明进一步了解如何安装 PyTorch。\n\n## 入门\n\n请参阅我们文档中的[快速入门](https:\u002F\u002Fwww.sbert.net\u002Fdocs\u002Fquickstart.html)。\n\n### 嵌入模型\n\n首先下载一个预训练的嵌入模型，即 Sentence Transformer 模型。\n\n```python\nfrom sentence_transformers import SentenceTransformer\n\nmodel = SentenceTransformer(\"sentence-transformers\u002Fall-MiniLM-L6-v2\")\n```\n\n然后将一些文本提供给模型。\n\n```python\nsentences = [\n    \"今天的天气真好。\",\n    \"外面阳光明媚！\",\n    \"他开车去了体育场。\",\n]\nembeddings = model.encode(sentences)\nprint(embeddings.shape)\n# => (3, 384)\n```\n\n就这样完成了。我们现在有了包含嵌入的 NumPy 数组，每个文本对应一个。我们可以使用这些嵌入来计算相似度。\n\n```python\nsimilarities = model.similarity(embeddings, embeddings)\nprint(similarities)\n# tensor([[1.0000, 0.6660, 0.1046],\n#         [0.6660, 1.0000, 0.1411],\n#         [0.1046, 0.1411, 1.0000]])\n```\n\n### 重排序模型\n\n首先下载一个预训练的重排序模型，即交叉编码器模型。\n\n```python\nfrom sentence_transformers import CrossEncoder\n\n# 1. 加载一个预训练的交叉编码器模型\nmodel = CrossEncoder(\"cross-encoder\u002Fms-marco-MiniLM-L6-v2\")\n```\n\n然后将一些文本提供给模型。\n\n```python\n# 用于预测相似度分数的文本\nquery = \"柏林有多少人居住？\"\npassages = [\n    \"柏林在891.82平方公里的区域内有3,520,031名注册居民。\",\n    \"柏林每年约有1.35亿游客到访，使其成为欧盟访问量最大的城市之一。\",\n    \"2013年，约有60万名柏林人注册加入了2,300多个体育和健身俱乐部。\",\n]\n\n# 2a. 预测文本对的得分\nscores = model.predict([(query, passage) for passage in passages])\nprint(scores)\n# => [8.607139 5.506266 6.352977]\n```\n\n现在就可以开始了。您还可以使用[`model.rank`](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fpackage_reference\u002Fcross_encoder\u002Fcross_encoder.html#sentence_transformers.cross_encoder.model.CrossEncoder.rank)来避免手动进行重排序：\n\n```python\n# 2b. 对查询的段落列表进行排名\nranks = model.rank(query, passages, return_documents=True)\n\nprint(\"查询：\", query)\nfor rank in ranks:\n    print(f\"- #{rank['corpus_id']} ({rank['score']:.2f})：{rank['text']}\")\n\"\"\"\n查询：柏林有多少人居住？\n- #0 (8.61)：柏林在891.82平方公里的区域内有3,520,031名注册居民。\n- #2 (6.35)：2013年，约有60万名柏林人注册加入了2,300多个体育和健身俱乐部。\n- #1 (5.51)：柏林每年约有1.35亿游客到访，使其成为欧盟访问量最大的城市之一。\n\"\"\"\n```\n\n### 稀疏编码器模型\n\n首先下载一个预训练的稀疏嵌入模型，即稀疏编码器模型。\n\n```python\n\nfrom sentence_transformers import SparseEncoder\n\n# 1. 加载一个预训练的稀疏编码器模型\nmodel = SparseEncoder(\"naver\u002Fsplade-cocondenser-ensembledistil\")\n\n# 要编码的句子\nsentences = [\n    \"今天的天气真好。\",\n    \"外面阳光明媚！\",\n    \"他开车去了体育场。\",\n]\n\n# 2. 通过调用 model.encode() 计算稀疏嵌入\nembeddings = model.encode(sentences)\nprint(embeddings.shape)\n# [3, 30522] - 具有词汇表大小维度的稀疏表示\n\n# 3. 计算嵌入之间的相似度\nsimilarities = model.similarity(embeddings, embeddings)\nprint(similarities)\n# tensor([[   35.629,     9.154,     0.098],\n\n#         [    9.154,    27.478,     0.019],\n#         [    0.098,     0.019,    29.553]])\n\n# 4. 检查稀疏性统计信息\nstats = SparseEncoder.sparsity(embeddings)\nprint(f\"稀疏度: {stats['sparsity_ratio']:.2%}\")\n# 稀疏度: 99.84%\n```\n\n## 预训练模型\n\n我们提供了涵盖100多种语言的大量预训练模型。其中一些是通用模型，而另一些则针对特定应用场景生成嵌入。\n\n- [预训练的 Sentence Transformer（嵌入）模型](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fsentence_transformer\u002Fpretrained_models.html)\n- [预训练的 Cross Encoder（重排序器）模型](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fcross_encoder\u002Fpretrained_models.html)\n- [预训练的 Sparse Encoder（稀疏嵌入）模型](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fsparse_encoder\u002Fpretrained_models.html)\n\n## 训练\n\n该框架允许您微调自己的句子嵌入方法，从而获得特定任务的句子嵌入。为了满足您的具体需求，您可以选择多种不同的选项来构建理想的句子嵌入。\n\n- 嵌入模型\n  - [Sentence Transformer > 训练概述](https:\u002F\u002Fwww.sbert.net\u002Fdocs\u002Fsentence_transformer\u002Ftraining_overview.html)\n  - [Sentence Transformer > 训练示例](https:\u002F\u002Fwww.sbert.net\u002Fdocs\u002Fsentence_transformer\u002Ftraining\u002Fexamples.html)，或访问[GitHub上的训练示例](https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsentence-transformers\u002Ftree\u002Fmain\u002Fexamples\u002Fsentence_transformer\u002Ftraining)。\n- 重排序器模型\n  - [Cross Encoder > 训练概述](https:\u002F\u002Fwww.sbert.net\u002Fdocs\u002Fcross_encoder\u002Ftraining_overview.html)\n  - [Cross Encoder > 训练示例](https:\u002F\u002Fwww.sbert.net\u002Fdocs\u002Fcross_encoder\u002Ftraining\u002Fexamples.html)，或访问[GitHub上的训练示例](https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsentence-transformers\u002Ftree\u002Fmain\u002Fexamples\u002Fcross_encoder\u002Ftraining)。\n- 稀疏嵌入模型\n  - [Sparse Encoder > 训练概述](https:\u002F\u002Fwww.sbert.net\u002Fdocs\u002Fsparse_encoder\u002Ftraining_overview.html)\n  - [Sparse Encoder > 训练示例](https:\u002F\u002Fwww.sbert.net\u002Fdocs\u002Fsparse_encoder\u002Ftraining\u002Fexamples.html)，或访问[GitHub上的训练示例](https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsentence-transformers\u002Ftree\u002Fmain\u002Fexamples\u002Fsparse_encoder\u002Ftraining)。\n\n不同类型的训练中的一些亮点包括：\n\n- 支持多种Transformer网络，包括BERT、RoBERTa、XLM-R、DistilBERT、Electra、BART等。\n- 多语言和多任务学习。\n- 在训练过程中进行评估以找到最优模型。\n- 嵌入模型提供20多种损失函数，重排序器模型提供10多种损失函数，稀疏嵌入模型也提供10多种损失函数，使您可以针对语义搜索、释义挖掘、语义相似度比较、聚类、三元组损失、对比损失等任务对模型进行优化。\n\n## 应用示例\n\n您可以使用此框架实现以下功能：\n\n- **计算句子嵌入**\n\n  - [密集嵌入](https:\u002F\u002Fwww.sbert.net\u002Fexamples\u002Fsentence_transformer\u002Fapplications\u002Fcomputing-embeddings\u002FREADME.html)\n  - [稀疏嵌入](https:\u002F\u002Fwww.sbert.net\u002Fexamples\u002Fsparse_encoder\u002Fapplications\u002Fcomputing_embeddings\u002FREADME.html)\n\n- **语义文本相似度**\n\n  - [密集STS](https:\u002F\u002Fwww.sbert.net\u002Fdocs\u002Fsentence_transformer\u002Fusage\u002Fsemantic_textual_similarity.html)\n  - [稀疏STS](https:\u002F\u002Fwww.sbert.net\u002Fexamples\u002Fsparse_encoder\u002Fapplications\u002Fsemantic_textual_similarity\u002FREADME.html)\n\n- **语义搜索**\n\n  - [密集搜索](https:\u002F\u002Fwww.sbert.net\u002Fexamples\u002Fsentence_transformer\u002Fapplications\u002Fsemantic-search\u002FREADME.html)\n  - [稀疏搜索](https:\u002F\u002Fwww.sbert.net\u002Fexamples\u002Fsparse_encoder\u002Fapplications\u002Fsemantic_search\u002FREADME.html)\n\n- **检索与重排序**\n\n  - [仅密集检索](https:\u002F\u002Fwww.sbert.net\u002Fexamples\u002Fsentence_transformer\u002Fapplications\u002Fretrieve_rerank\u002FREADME.html)\n  - [稀疏\u002F密集\u002F混合检索](https:\u002F\u002Fwww.sbert.net\u002Fexamples\u002Fsentence_transformer\u002Fapplications\u002Fretrieve_rerank\u002FREADME.html)\n\n- [聚类](https:\u002F\u002Fwww.sbert.net\u002Fexamples\u002Fsentence_transformer\u002Fapplications\u002Fclustering\u002FREADME.html)\n\n- [释义挖掘](https:\u002F\u002Fwww.sbert.net\u002Fexamples\u002Fsentence_transformer\u002Fapplications\u002Fparaphrase-mining\u002FREADME.html)\n\n- [翻译句子挖掘](https:\u002F\u002Fwww.sbert.net\u002Fexamples\u002Fsentence_transformer\u002Fapplications\u002Fparallel-sentence-mining\u002FREADME.html)\n\n- [多语言图像搜索、聚类及重复检测](https:\u002F\u002Fwww.sbert.net\u002Fexamples\u002Fsentence_transformer\u002Fapplications\u002Fimage-search\u002FREADME.html)\n\n以及更多其他应用场景。\n\n有关所有示例，请参阅[examples\u002Fsentence_transformer\u002Fapplications](https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsentence-transformers\u002Ftree\u002Fmain\u002Fexamples\u002Fsentence_transformer\u002Fapplications)。\n\n## 开发环境搭建\n\n将仓库（或其分支）克隆到您的机器后，在虚拟环境中运行以下命令：\n\n```\npython -m pip install -e \".[dev]\"\npre-commit install\n```\n\n要测试您的更改，请运行：\n\n```\npytest\n```\n\n## 引用与作者\n\n如果您觉得本仓库对您有所帮助，请随时引用我们的论文《Sentence-BERT：基于孪生BERT网络的句子嵌入》：\n\n```bibtex\n@inproceedings{reimers-2019-sentence-bert,\n    title = \"Sentence-BERT: Sentence Embeddings using Siamese BERT-Networks\",\n    author = \"Reimers, Nils and Gurevych, Iryna\",\n    booktitle = \"Proceedings of the 2019 Conference on Empirical Methods in Natural Language Processing\",\n    month = \"11\",\n    year = \"2019\",\n    publisher = \"Association for Computational Linguistics\",\n    url = \"https:\u002F\u002Farxiv.org\u002Fabs\u002F1908.10084\",\n}\n```\n\n如果您使用的是多语言模型，请随时引用我们的论文《利用知识蒸馏将单语句嵌入转化为多语言句嵌入》：\n\n```bibtex\n@inproceedings{reimers-2020-multilingual-sentence-bert,\n    title = \"Making Monolingual Sentence Embeddings Multilingual using Knowledge Distillation\",\n    author = \"Reimers, Nils and Gurevych, Iryna\",\n    booktitle = \"Proceedings of the 2020 Conference on Empirical Methods in Natural Language Processing\",\n    month = \"11\",\n    year = \"2020\",\n    publisher = \"Association for Computational Linguistics\",\n    url = \"https:\u002F\u002Farxiv.org\u002Fabs\u002F2004.09813\",\n}\n```\n\n请参阅[出版物](https:\u002F\u002Fwww.sbert.net\u002Fdocs\u002Fpublications.html)，了解我们整合到SentenceTransformers中的各类研究成果。\n\n### 维护者\n\n维护者：[Tom Aarsen](https:\u002F\u002Fgithub.com\u002Ftomaarsen)，🤗 Hugging Face\n\n如果遇到任何问题（尽管不应该出现），或者您有其他疑问，请随时提交 Issue。\n\n---\n\n本项目最初由达姆施塔特工业大学的 [无处不在的知识处理（UKP）实验室](https:\u002F\u002Fwww.ukp.tu-darmstadt.de\u002F) 开发。我们感谢他们在该领域所做的基础性工作以及持续的贡献。\n\n> 本仓库包含实验性软件，仅用于提供相关论文的更多背景信息。\n\n[#docs-package]: https:\u002F\u002Fwww.sbert.net\u002F\n[#github-license]: https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsentence-transformers\u002Fblob\u002Fmain\u002FLICENSE\n[#pypi-package]: https:\u002F\u002Fpypi.org\u002Fproject\u002Fsentence-transformers\u002F","# sentence-transformers 快速上手指南\n\n`sentence-transformers` 是一个用于计算文本嵌入（Embeddings）、语义搜索及重排序（Reranking）的 Python 框架。它提供了简单易用的接口来调用和训练最先进的模型，支持稠密向量、稀疏向量及交叉编码器模型。\n\n## 环境准备\n\n在开始之前，请确保满足以下系统要求：\n\n*   **Python**: 推荐版本 3.10 或更高。\n*   **PyTorch**: 推荐版本 1.11.0 或更高。\n    *   若需使用 GPU 加速，请安装匹配 CUDA 版本的 PyTorch。\n*   **Transformers**: 推荐版本 4.34.0 或更高。\n\n> **国内加速建议**：由于模型默认从 Hugging Face 下载，国内用户建议设置镜像环境变量以加速下载：\n> ```bash\n> export HF_ENDPOINT=https:\u002F\u002Fhf-mirror.com\n> ```\n\n## 安装步骤\n\n你可以选择通过 `pip` 或 `conda` 进行安装。\n\n### 方式一：使用 pip 安装（推荐）\n\n```bash\npip install -U sentence-transformers\n```\n\n### 方式二：使用 conda 安装\n\n```bash\nconda install -c conda-forge sentence-transformers\n```\n\n### 方式三：从源码安装\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsentence-transformers.git\ncd sentence-transformers\npip install -e .\n```\n\n## 基本使用\n\n以下是三种核心功能的最简使用示例。\n\n### 1. 生成文本嵌入 (Embedding Models)\n\n这是最常用的功能，将句子转换为固定长度的向量，可用于计算相似度或构建搜索引擎。\n\n```python\nfrom sentence_transformers import SentenceTransformer\n\n# 1. 加载预训练模型\nmodel = SentenceTransformer(\"sentence-transformers\u002Fall-MiniLM-L6-v2\")\n\n# 2. 定义待处理的文本\nsentences = [\n    \"The weather is lovely today.\",\n    \"It's so sunny outside!\",\n    \"He drove to the stadium.\",\n]\n\n# 3. 生成嵌入向量\nembeddings = model.encode(sentences)\nprint(embeddings.shape)\n# 输出: (3, 384)\n\n# 4. 计算相似度矩阵\nsimilarities = model.similarity(embeddings, embeddings)\nprint(similarities)\n```\n\n### 2. 文本重排序 (Reranker Models)\n\n使用 Cross-Encoder 模型对检索结果进行精细排序，适用于提高搜索准确率。\n\n```python\nfrom sentence_transformers import CrossEncoder\n\n# 1. 加载预训练重排序模型\nmodel = CrossEncoder(\"cross-encoder\u002Fms-marco-MiniLM-L6-v2\")\n\n# 2. 定义查询和候选文档\nquery = \"How many people live in Berlin?\"\npassages = [\n    \"Berlin had a population of 3,520,031 registered inhabitants in an area of 891.82 square kilometers.\",\n    \"Berlin has a yearly total of about 135 million day visitors, making it one of the most-visited cities in the European Union.\",\n    \"In 2013 around 600,000 Berliners were registered in one of the more than 2,300 sport and fitness clubs.\",\n]\n\n# 3. 直接对候选文档进行排序\nranks = model.rank(query, passages, return_documents=True)\n\nprint(\"Query:\", query)\nfor rank in ranks:\n    print(f\"- #{rank['corpus_id']} ({rank['score']:.2f}): {rank['text']}\")\n```\n\n### 3. 稀疏嵌入 (Sparse Encoder Models)\n\n生成基于词汇表的稀疏向量，适用于特定场景下的检索任务。\n\n```python\nfrom sentence_transformers import SparseEncoder\n\n# 1. 加载预训练稀疏编码模型\nmodel = SparseEncoder(\"naver\u002Fsplade-cocondenser-ensembledistil\")\n\nsentences = [\n    \"The weather is lovely today.\",\n    \"It's so sunny outside!\",\n    \"He drove to the stadium.\",\n]\n\n# 2. 生成稀疏嵌入\nembeddings = model.encode(sentences)\nprint(embeddings.shape)\n# 输出: [3, 30522] (维度等于词表大小)\n\n# 3. 查看稀疏度统计\nstats = SparseEncoder.sparsity(embeddings)\nprint(f\"Sparsity: {stats['sparsity_ratio']:.2%}\")\n```\n\n---\n更多预训练模型列表及高级训练教程，请访问官方文档：[www.SBERT.net](https:\u002F\u002Fwww.sbert.net) 或 Hugging Face Model Hub。","某电商平台的客服团队每天需处理数千条用户咨询，急需从历史工单库中快速匹配相似问题以辅助人工回复。\n\n### 没有 sentence-transformers 时\n- 只能依赖传统的关键词匹配（如 TF-IDF），无法识别“发货慢”与“物流延迟”这类语义相同但用词不同的问题，导致大量相关工单被遗漏。\n- 面对海量历史数据，计算相似度需要逐条比对，响应时间长达数秒甚至更久，无法满足实时辅助需求。\n- 缺乏现成的高质量预训练模型，团队需从零收集数据并训练深度学习模型，开发周期长且对算法能力要求极高。\n- 系统难以适应多变的口语化表达，用户稍微改变句式或加入语气词，匹配准确率便大幅下降。\n\n### 使用 sentence-transformers 后\n- 利用其内置的 SOTA 预训练模型，将文本转化为稠密向量，轻松捕捉深层语义，精准关联不同表述的相似问题。\n- 结合向量数据库实现毫秒级检索，即便在百万级工单库中也能瞬间返回最相关的历史案例，大幅提升客服效率。\n- 直接调用 Hugging Face 上超过 15,000 个微调好的模型（如 all-MiniLM-L6-v2），无需从头训练，几行代码即可部署高精度服务。\n- 对口语、同义词及句式变化具有极强的鲁棒性，显著提升了复杂场景下的意图识别准确率。\n\nsentence-transformers 通过极简的 API 将前沿的文本嵌入技术转化为生产力，让语义搜索在工程落地中变得高效且低成本。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fhuggingface_sentence-transformers_b7e0c3f1.png","huggingface","Hugging Face","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fhuggingface_90da21a4.png","The AI community building the future.",null,"https:\u002F\u002Fhuggingface.co\u002F","https:\u002F\u002Fgithub.com\u002Fhuggingface",[80,84],{"name":81,"color":82,"percentage":83},"Python","#3572A5",100,{"name":85,"color":86,"percentage":87},"Makefile","#427819",0,18549,2770,"2026-04-15T10:04:10","Apache-2.0","","非必需。若使用 GPU\u002FCUDA，需安装与系统匹配的 CUDA 版本的 PyTorch（具体版本需参考 PyTorch 官方安装指南），未指定具体显卡型号或显存大小。","未说明",{"notes":96,"python":97,"dependencies":98},"该工具支持在 CPU 上运行，也可通过安装对应 CUDA 版本的 PyTorch 来启用 GPU 加速。提供超过 15,000 个预训练模型可供下载。建议使用 pip 或 conda 进行安装。","3.10+",[99,100],"torch>=1.11.0","transformers>=4.34.0",[35,14],"2026-03-27T02:49:30.150509","2026-04-16T03:30:48.590751",[105,110,115,120,125,130],{"id":106,"question_zh":107,"answer_zh":108,"source_url":109},34996,"Sentence Transformers 模型支持多语言（如德语）吗？需要重新训练吗？","是的，预训练的多语言模型（如 distiluse-base-multilingual-cased-v1, paraphrase-multilingual-MiniLM-L12-v2 等）可以直接用于德语或其他支持的语言，无需重新训练。句子可以单独编码也可以一起编码，结果是一致的。对于特定语言对（如德 - 德）的相似度比较，多语言模型同样适用。","https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsentence-transformers\u002Fissues\u002F75",{"id":111,"question_zh":112,"answer_zh":113,"source_url":114},34997,"如何针对特定领域微调多语言模型？","可以直接在现有的多语言学生模型（student model）上继续使用领域相关的平行数据进行微调。推荐使用 MultipleNegativesRankingLoss 损失函数。不需要先微调教师模型再微调学生模型，直接延续训练多语言学生模型即可达到目的。","https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsentence-transformers\u002Fissues\u002F512",{"id":116,"question_zh":117,"answer_zh":118,"source_url":119},34998,"如何使用多 GPU 进行编码或训练？","对于推理（编码），默认的 `SentenceTransformer` 类会将特征发送到单个设备，直接包裹 `nn.DataParallel` 通常无效。如果需要多 GPU 推理，可能需要重构源代码以移除显式的 `.to(device)` 限制，但这可能破坏其他功能。对于训练，框架通常会自动处理多 GPU 情况，用户无需过多担心配置问题。","https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsentence-transformers\u002Fissues\u002F33",{"id":121,"question_zh":122,"answer_zh":123,"source_url":124},34999,"如何将 Sentence Transformer 模型转换为 ONNX 格式以加速推理？","新版 Sentence Transformers 已原生支持 ONNX。只需在加载模型时指定 `backend=\"onnx\"` 即可：\n```python\nfrom sentence_transformers import SentenceTransformer\nmodel = SentenceTransformer(\"all-MiniLM-L6-v2\", backend=\"onnx\")\nsentences = [\"This is an example sentence\", \"Each sentence is converted\"]\nembeddings = model.encode(sentences)\n```\n这种方法比手动转换更简单且能显著提升速度（约 4 倍加速）。","https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsentence-transformers\u002Fissues\u002F46",{"id":126,"question_zh":127,"answer_zh":128,"source_url":129},35000,"遇到 'ModuleNotFoundError: No module named sentence_transformers' 错误怎么办？","这通常意味着库未正确安装或当前 Python 环境不匹配。解决方法包括：\n1. 运行 `pip install sentence_transformers` 或 `python -m pip install sentence_transformers` 进行安装。\n2. 检查 Python 版本兼容性（例如某些版本在 Python 3.10 上可能有问题，尝试降级到 3.9）。\n3. 如果在 IDE（如 PyCharm）中报错，请确保在项目的解释器设置中安装了该包：File -> Settings -> Project -> Python Interpreter -> 点击 '+' -> 搜索 'sentence_transformers' 并安装。","https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsentence-transformers\u002Fissues\u002F10",{"id":131,"question_zh":132,"answer_zh":133,"source_url":134},35001,"Hugging Face 上的预训练模型无法访问或返回 404 错误怎么办？","如果官方仓库的模型暂时不可用，可以尝试使用其他高质量替代模型。例如，可以使用 BAAI 发布的 `BAAI\u002Fbge-large-en` 模型来生成嵌入向量。此外，检查是否可以通过 `langchain` 等中间库调用，或者直接前往 Hugging Face Hub 搜索最新的可用模型版本。","https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsentence-transformers\u002Fissues\u002F1915",[136,141,146,151,156,161,166,171,176,181,186,191,196,201,206,211,216,221,226,231],{"id":137,"version":138,"summary_zh":139,"released_at":140},272335,"v5.4.1","此补丁版本允许 `encode()` 和 `predict()` 接受一维 NumPy 字符串数组作为输入。\n\n可通过以下命令安装此版本：\n```bash\n# 训练 + 推理\npip install sentence-transformers[train]==5.4.1\n\n# 仅推理，可选择：\npip install sentence-transformers==5.4.1\npip install sentence-transformers[onnx-gpu]==5.4.1\npip install sentence-transformers[onnx]==5.4.1\npip install sentence-transformers[openvino]==5.4.1\n\n# 多模态依赖（可选）：\npip install sentence-transformers[image]==5.4.1\npip install sentence-transformers[audio]==5.4.1\npip install sentence-transformers[video]==5.4.1\n\n# 或根据需要组合安装：\npip install sentence-transformers[train,onnx,image]==5.4.1\n```\n\n## 将 NumPy 字符串\u002F对象数组用作批次 (#3720)\n\n`encode()` 和 `predict()` 现在能够正确识别一维 NumPy 字符串\u002F对象数组为批次，而非单个输入。此前，类似 `model.encode(df[\"text\"].to_numpy())` 的代码会被静默地当作单个输入处理，从而产生错误的输出。现在，`dtype.kind` 属于 `(\"U\", \"O\")` 的一维 NumPy 数组会像列表一样被展开，而二维及以上数组则被视为成对的批次（适用于 `CrossEncoder`）。\n\n```python\nimport numpy as np\nfrom sentence_transformers import SentenceTransformer\n\nmodel = SentenceTransformer(\"all-MiniLM-L6-v2\")\n\n# 此前会被视为一个输入；现在则正确编码为三个独立文本\nembeddings = model.encode(np.array([\"first\", \"second\", \"third\"]))\nprint(embeddings.shape)\n# (3, 384)\n```\n\n对于 `CrossEncoder`，一维 NumPy 字符串数组仍被视为单个 `[query, document]` 对，以匹配现有的列表行为；而形状为 `(N, 2)` 的二维数组则会被视为包含 `N` 个对的批次。\n\n## 提升 `Dense` 模块中激活函数加载的安全性 (#3714)\n\n`Dense` 模块会将其激活函数存储为保存配置中的点分导入路径（例如 `\"torch.nn.modules.activation.Tanh\"`），并在每次加载模块时通过 `import_from_string` 解析该路径。由于任何可导入的 Python 可调用对象都可能被引用，因此 Hub 上恶意构造的 `config.json` 文件可能会在模型加载时触发任意导入。\n\n现在，加载器仅解析以 `torch.` 开头的激活函数导入路径。其他路径将被跳过并发出警告，同时替换为默认激活函数（`Tanh`）。若要加载使用自定义（非 torch）激活函数的模型，需显式启用 `trust_remote_code=True`：\n\n```python\nfrom sentence_transformers import SentenceTransformer\n\n# Torch 提供的激活函数仍可正常加载\nmodel = SentenceTransformer(\"some\u002Fmodel-with-torch-activation\")\n\n# 非 torch 激活函数现需显式启用\nmodel = SentenceTransformer(\"some\u002Fmodel-with-custom-activation\", trust_remote_code=True)\n```\n\n这一机制与 `transformers` 库中已用于自定义代码的信任模式一致，可确保不受信任的模型仓库无法通过 `Dense` 激活函数配置偷偷引入任意导入。\n\n## 变更内容\n* [`tests`] F","2026-04-14T13:35:25",{"id":142,"version":143,"summary_zh":144,"released_at":145},272336,"v5.4.0","本次大型发布为 `SentenceTransformer` 和 `CrossEncoder` 引入了一流的多模态支持，使得跨文本、图像、音频和视频计算嵌入并向量重排序变得轻而易举。`CrossEncoder` 类现已完全模块化，可通过全新的 `LogitScore` 模块支持生成式重排序器（基于因果语言模型的模型）。Flash Attention 2 现在会自动跳过纯文本输入中的填充部分，从而显著提升速度并减少内存占用，尤其是在输入长度不一致的情况下。\n\n> **博客文章**：[使用 Sentence Transformers 的多模态嵌入与重排序模型](https:\u002F\u002Fhuggingface.co\u002Fblog\u002Fmultimodal-sentence-transformers)：对新多模态功能的全面介绍，并附有实用示例。\n>\n> **迁移指南**：[从 v5.x 迁移到 v5.4+](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fmigration_guide.html)：涵盖更新的导入路径、重命名的参数以及其他带有弃用警告的轻微破坏性变更。请注意，不存在硬性弃用，现有代码在最坏情况下也应能继续运行，仅会出现警告。\n\n可通过以下命令安装此版本：\n```bash\n# 训练 + 推理\npip install sentence-transformers[train]==5.4.0\n\n# 仅推理，可选择：\npip install sentence-transformers==5.4.0\npip install sentence-transformers[onnx-gpu]==5.4.0\npip install sentence-transformers[onnx]==5.4.0\npip install sentence-transformers[openvino]==5.4.0\n\n# 多模态依赖项（可选）：\npip install sentence-transformers[image]==5.4.0\npip install sentence-transformers[audio]==5.4.0\npip install sentence-transformers[video]==5.4.0\n\n# 或根据需要组合安装：\npip install sentence-transformers[train,onnx,image]==5.4.0\n```\n\n## 使用 SentenceTransformer 进行多模态嵌入 (#3554)\n\n[`SentenceTransformer`](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fpackage_reference\u002Fsentence_transformer\u002FSentenceTransformer.html#sentence_transformers.SentenceTransformer) 现在原生支持视觉-语言模型（VLM）及其他多模态架构。您可以对文本、图像、音频、视频或它们的组合进行编码和比较，并实现自动模态检测与预处理。模型通过新的 [`model.modalities`](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fpackage_reference\u002Fsentence_transformer\u002FSentenceTransformer.html#sentence_transformers.SentenceTransformer.modalities) 属性和 [`model.supports()`](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fpackage_reference\u002Fsentence_transformer\u002FSentenceTransformer.html#sentence_transformers.SentenceTransformer.supports) 方法声明其支持的模态类型。\n\n### 使用预训练的多模态嵌入模型\n\n```python\nfrom PIL import Image\nfrom sentence_transformers import SentenceTransformer\n\nmodel = SentenceTransformer(\n    \"Qwen\u002FQwen3-VL-Embedding-2B\",\n    model_kwargs={\"attn_implementation\": \"flash_attention_2\", \"torch_dtype\": \"bfloat16\"},\n    processor_kwargs={\"min_pixels\": 28 * 28, \"max_pixels\": 600 * 600},\n    revision=\"refs\u002Fpr\u002F23\",\n)\n\n# 检查支持的模态\nprint(model.modalities)\n# ['text', 'image']\n```","2026-04-09T13:41:49",{"id":147,"version":148,"summary_zh":149,"released_at":150},272337,"v5.3.0","这个小版本为对比学习带来了多项改进：`MultipleNegativesRankingLoss` 现在支持替代的 InfoNCE 公式（对称形式、GTE 风格），并可选择性地为较难的负样本施加硬度权重。此外，还引入了两种新损失函数：用于嵌入空间正则化的 `GlobalOrthogonalRegularizationLoss`，以及用于内存高效 SPLADE 训练的 `CachedSpladeLoss`。本次发布还新增了一个更快的哈希批采样器，修复了三元组损失中的 `GroupByLabelBatchSampler` 问题，并确保与最新 Transformers v5 版本的完全兼容。\n\n可通过以下命令安装此版本：\n```bash\n# 训练 + 推理\npip install sentence-transformers[train]==5.3.0\n\n# 仅推理，可选择：\npip install sentence-transformers==5.3.0\npip install sentence-transformers[onnx-gpu]==5.3.0\npip install sentence-transformers[onnx]==5.3.0\npip install sentence-transformers[openvino]==5.3.0\n```\n\n## 更新后的 MultipleNegativesRankingLoss（又称 InfoNCE）\n\n`MultipleNegativesRankingLoss` 获得了两项重大升级：支持文献中提出的其他 InfoNCE 变体，以及可选的硬度权重机制，用于加大对难负样本的重视。\n\n### 支持其他 InfoNCE 变体 (#3607)\n\n`MultipleNegativesRankingLoss` 现在通过新的 `directions` 和 `partition_mode` 参数，支持文献中几种广为人知的对比损失变体。此前，该损失仅支持标准的前向模式（查询 → 文档）。现在，您可以配置哪些相似度交互会被纳入损失计算：\n\n- `\"query_to_doc\"`（默认）：对于每个查询，其匹配的文档得分应高于所有其他文档。\n- `\"doc_to_query\"`：对称的反向模式——对于每个文档，其匹配的查询得分应高于所有其他查询。\n- `\"query_to_query\"`：对于每个查询，所有其他查询的得分应低于其匹配的文档。\n- `\"doc_to_doc\"`：对于每个文档，所有其他文档的得分应低于其匹配的查询。\n\n`partition_mode` 控制着分数的归一化方式：“joint” 会在所有方向上计算单一的 softmax；而“per_direction” 则会为每个方向分别计算 softmax，并对各方向的损失取平均。\n\n这些设置可以组合出文献中提到的多种损失公式：\n\n**标准 InfoNCE**（默认，行为未变）：\n```python\nloss = MultipleNegativesRankingLoss(model)\n# 等价于 directions=(\"query_to_doc\",)，partition_mode=\"joint\"\n```\n\n**对称 InfoNCE**（[Günther 等，2024](https:\u002F\u002Farxiv.org\u002Fabs\u002F2310.19923)）——增加了反向方向，使查询和文档都能被训练去找到各自的匹配对象：\n```python\nloss = MultipleNegativesRankingLoss(\n    model,\n    directions=(\"query_to_doc\", \"doc_to_query\"),\n    partition_mode=\"per_direction\",\n)\n```\n\n**GTE 改进的对比损失**（[Li 等，2023](https:\u002F\u002Farxiv.org\u002Fabs\u002F2308.03281)）——增加了同类型负样本（查询 ↔ 查询，文档 ↔ 文档），以提供更强的训练信号，尤其适用于仅使用成对数据的情景。","2026-03-12T14:54:11",{"id":152,"version":153,"summary_zh":154,"released_at":155},272338,"v5.2.3","此补丁版本引入了对 Transformers v5.2 的兼容性。\n\n可通过以下命令安装该版本：\n\n```bash\n# 训练 + 推理\npip install sentence-transformers[train]==5.2.3\n\n# 仅推理，可选择以下任一命令：\npip install sentence-transformers==5.2.3\npip install sentence-transformers[onnx-gpu]==5.2.3\npip install sentence-transformers[onnx]==5.2.3\npip install sentence-transformers[openvino]==5.2.3\n```\n\n## Transformers v5.2 支持\n[Transformers v5.2](https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Ftransformers\u002Freleases\u002Ftag\u002Fv5.2.0) 刚刚发布，其更新后的 `Trainer` 类导致使用 Sentence Transformers 进行训练时会在日志记录步骤中失败。通过 https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsentence-transformers\u002Fpull\u002F3664 这个拉取请求，已解决了该问题。\n\n如果您不使用 Sentence Transformers 进行训练，则较旧版本的 Sentence Transformers 仍然与 Transformers v5.2 兼容。\n\n## 所有变更\n* [`compat`] 引入 Transformers v5.2 兼容性：`Trainer` 中的 `_nested_gather` 方法被移动，由 @tomaarsen 完成（https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsentence-transformers\u002Fpull\u002F3664）\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsentence-transformers\u002Fcompare\u002Fv5.2.2...v5.2.3","2026-02-17T14:06:18",{"id":157,"version":158,"summary_zh":159,"released_at":160},272339,"v5.2.2","此补丁版本将强制性的 `requests` 依赖替换为可选的 `httpx` 依赖。\n\n使用以下命令安装此版本：\n\n```bash\n# 训练 + 推理\npip install sentence-transformers[train]==5.2.2\n\n# 仅推理，选择其中之一：\npip install sentence-transformers==5.2.2\npip install sentence-transformers[onnx-gpu]==5.2.2\npip install sentence-transformers[onnx]==5.2.2\npip install sentence-transformers[openvino]==5.2.2\n```\n\n## Transformers v5 支持\n[Transformers v5.0](https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Ftransformers\u002Freleases\u002Ftag\u002Fv5.0.0) 及其所需的 `huggingface_hub` 版本已弃用 `requests`，转而支持 `httpx`。此前 `sentence-transformers` 也使用了 `requests`，但并未将其明确列为依赖项。此补丁移除了对 `requests` 的使用，改用 `httpx`，不过现在 `httpx` 已变为可选依赖，不会自动导入。这也有助于节省一些导入时间。\n\n现在，即使未安装 `requests`，导入 Sentence Transformers 也不会导致程序崩溃。\n\n## 所有变更\n* [`deps`] 将 `requests` 依赖替换为可选的 `httpx` 依赖，由 @tomaarsen 完成（https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsentence-transformers\u002Fpull\u002F3618）\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsentence-transformers\u002Fcompare\u002Fv5.2.1...v5.2.2","2026-01-27T11:11:19",{"id":162,"version":163,"summary_zh":164,"released_at":165},272340,"v5.2.1","此补丁版本新增对完整 [Transformers v5 版本](https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Ftransformers\u002Freleases\u002Ftag\u002Fv5.0.0) 的支持。\n\n可通过以下命令安装该版本：\n\n```bash\n# 训练 + 推理\npip install sentence-transformers[train]==5.2.1\n\n# 仅推理，可选择：\npip install sentence-transformers==5.2.1\npip install sentence-transformers[onnx-gpu]==5.2.1\npip install sentence-transformers[onnx]==5.2.1\npip install sentence-transformers[openvino]==5.2.1\n```\n\n## Transformers v5 支持\nSentence Transformers v5.2.0 已经引入了对 Transformers v5.0 发布候选版本的支持，而本次发布则进一步增加了对完整正式版的支持。我们的目标是保持与 v4.x 的向后兼容性。目前，该库同时针对这两个版本运行 CI 测试，以便用户在准备就绪时能够升级到最新的 Transformers 功能。在未来版本中，Sentence Transformers 可能会要求使用 Transformers v5.0 或更高版本。\n\n## 所有变更\n* 引入与 transformers 5.0.0rc01 的兼容性，由 @tomaarsen 提供（https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsentence-transformers\u002Fpull\u002F3597）\n* 在依赖项中手动指定 numpy，因为它被直接使用或导入，由 @tomaarsen 提供（https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsentence-transformers\u002Fpull\u002F3608）\n* 扩展测试套件以覆盖完整的 Transformers v5，由 @tomaarsen 提供（https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsentence-transformers\u002Fpull\u002F3615）\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fsentence-transformers\u002Fcompare\u002Fv5.2.0...v5.2.1","2026-01-26T14:48:31",{"id":167,"version":168,"summary_zh":169,"released_at":170},272341,"v5.2.0","此小版本更新引入了 CrossEncoder（重排序器）的多进程支持、多语言 NanoBEIR 评估器、`mine_hard_negatives` 中的相似度分数输出、对 Transformers v5 的支持、Python 3.9 的弃用内容等。\n\n可通过以下命令安装此版本：\n\n```bash\n# 训练 + 推理\npip install sentence-transformers[train]==5.2.0\n\n# 仅推理，可选择：\npip install sentence-transformers==5.2.0\npip install sentence-transformers[onnx-gpu]==5.2.0\npip install sentence-transformers[onnx]==5.2.0\npip install sentence-transformers[openvino]==5.2.0\n```\n\n## CrossEncoder 多进程支持\n`CrossEncoder` 类现支持多进程，可在 CPU 和多 GPU 环境中实现更快的推理。此举使 CrossEncoder 的功能与 `SentenceTransformer` 模型现有的多进程能力保持一致，允许您在处理大批量句子对时，利用多个 CPU 核心或 GPU 来加速 `predict` 和 `rank` 方法。\n\n该实现引入了以下新方法，与 SentenceTransformer 的方式相呼应：\n- `start_multi_process_pool()` — 初始化工作进程池\n- `stop_multi_process_pool()` — 清理工作进程池\n\n使用非常简单，只需添加新的 `pool` 参数即可：\n\n```python\nfrom sentence_transformers.cross_encoder import CrossEncoder\n\ndef main():\n    model = CrossEncoder('cross-encoder\u002Fms-marco-MiniLM-L6-v2')\n    \n    # 启动工作进程池\n    pool = model.start_multi_process_pool()\n    \n    # 使用进程池加速推理\n    scores = model.predict(sentence_pairs, pool=pool)\n    rankings = model.rank(query, documents, pool=pool)\n    \n    # 完成后清理\n    model.stop_multi_process_pool(pool)\n\nif __name__ == \"__main__\":\n    main()\n```\n\n或者，只需将设备列表传递给 `device` 参数，`predict` 和 `rank` 将自动在后台创建进程池。\n\n```python\nfrom sentence_transformers.cross_encoder import CrossEncoder\n\ndef main():\n    model = CrossEncoder('cross-encoder\u002Fms-marco-MiniLM-L6-v2', device=\"cpu\")\n    \n    # 使用 4 个进程\n    scores = model.predict(sentence_pairs, device=[\"cpu\"] * 4)\n    rankings = model.rank(query, documents, device=[\"cpu\"] * 4)\n\nif __name__ == \"__main__\":\n    main()\n```\n\n此项增强对于基于 CPU 的部署尤为有益，并且能够在 `mine_hard_negatives` 函数中实现多 GPU 重排序，从而加快大型数据集上的难负样本挖掘速度。\n\n## 多语言 NanoBEIR 支持\nNanoBEIR 评估器现支持自定义数据集 ID，允许对非英语的 NanoBEIR 数据集进行评估。三种 NanoBEIR 评估器（稠密、稀疏和交叉编码器）均通过一个简单的 `dataset_id` 参数支持此功能。\n\n例如：\n```python\nimport logging\nfrom pprint import pprint\n\nfrom sentence_transformers import SentenceTransformer\nfrom sentence_transformers.evaluation import NanoBEIREvaluator\n\nlogging.basicConfig(format=\"%(asctime)s - %(message)s\", datefmt=\"%Y-%m-%d %H:%M:%S\", level=l","2025-12-11T14:12:37",{"id":172,"version":173,"summary_zh":174,"released_at":175},272342,"v5.1.2","此补丁庆祝 Sentence Transformers 迁入 Hugging Face，并改进了模型保存、加载默认设置以及损失函数的兼容性。\n\n可通过以下命令安装此版本：\n\n```bash\n# 训练 + 推理\npip install sentence-transformers[train]==5.1.2\n\n# 仅推理，可选择：\npip install sentence-transformers==5.1.2\npip install sentence-transformers[onnx-gpu]==5.1.2\npip install sentence-transformers[onnx]==5.1.2\npip install sentence-transformers[openvino]==5.1.2\n```\n\n## Sentence Transformers 加入 Hugging Face！\n今天，Sentence Transformers 将从达姆施塔特工业大学的 [Ubiquitous Knowledge Processing (UKP) 实验室](http:\u002F\u002Fwww.ukp.tu-darmstadt.de\u002F) 迁至 [Hugging Face](https:\u002F\u002Fhuggingface.co\u002F)。此举正式确立了现有的维护机制：过去两年来，Hugging Face 的 Tom Aarsen（也就是我！）一直负责该项目的维护工作。项目的开发路线图、许可证、支持以及对社区的承诺均保持不变。更多详情请参阅[完整公告](https:\u002F\u002Fhuggingface.co\u002Fblog\u002Fsentence-transformers-joins-hf)！\n\n\u003Cimg width=\"1050\" height=\"548\" alt=\"thumbnail\" src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F95266693-8f8f-4553-9aa3-1b8cc80afb18\" \u002F>\n\n## 模型保存与加载方面的小幅改动\n* 改进包含 StaticEmbedding (#3524) 和 Dense (#3528) 模块的模型保存。\n* 修复在存在更强大的设备（CUDA、MPS）时仍使用 CPU 进行训练的问题 (#3525)。\n* 如果可用“xpu”设备，则默认优先使用“xpu”而非“cpu”(#3537)。\n\n## 损失函数方面的小幅改动\n* 调整 MatryoshkaLoss 的错误和警告信息，以避免容易犯的错误，例如忘记使用原始维度 (#3530)。\n* 引入 MSELoss 与 MatryoshkaLoss 之间的兼容性 (#3538)。\n* 在 MegaBatchMarginLoss 中也为正样本使用小批量处理 (#3550)。\n\n## 所有变更\n* 修复：静态模型保存失败，原因是权重不连续，由 @stephantul 在 https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3524 中修复。\n* 错误：修复训练器中的状态错误，由 @stephantul 在 https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3525 中修复。\n* [`fix`] 修复带有缓存损失的路由训练问题，由 @tomaarsen 在 https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3527 中修复。\n* [`fix`] 允许加载未以 fp32 格式保存的 Dense 模块，由 @tomaarsen 在 https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3528 中修复。\n* [`tests`] 为 Python 3.9 修补正则表达式的预期输出，由 @tomaarsen 在 https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3529 中完成。\n* 为即将到来的 transformers 版本进行未来兼容性测试，由 @tomaarsen 在 https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3533 中完成。\n* 功能：添加套娃维度的边界检查及警告，由 @stephantul 在 https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3530 中实现。\n* 优化性能表格格式并修正 Few markdownlint 错误，由 @kaushikacharya 在 https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3534 中完成。\n* 修复拼写错误：“inaccuracte”改为“inaccurate”，由 @whybe-choi 在 https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsenten 中完成。","2025-10-22T13:00:25",{"id":177,"version":178,"summary_zh":179,"released_at":180},272343,"v5.1.1","此补丁使 Sentence Transformers 在处理错误参数时更加明确，并为多 GPU 处理、评估器以及难负样本挖掘引入了一些修复。\n\n使用以下命令安装此版本：\n\n```bash\n# 训练 + 推理\npip install sentence-transformers[train]==5.1.1\n\n# 仅推理，可选择：\npip install sentence-transformers==5.1.1\npip install sentence-transformers[onnx-gpu]==5.1.1\npip install sentence-transformers[onnx]==5.1.1\npip install sentence-transformers[openvino]==5.1.1\n```\n\n## 传递未使用的关键字参数时抛出错误及 `get_model_kwargs` (#3500)\n某些 SentenceTransformer 或 SparseEncoder 模型支持特定于模型的自定义关键字参数，例如 [jinaai\u002Fjina-embeddings-v4](https:\u002F\u002Fhuggingface.co\u002Fjinaai\u002Fjina-embeddings-v4)。从本版本开始，如果调用 `model.encode` 时传入了该模型不支持的关键字参数，将会抛出错误。\n\n```python\n>>> from sentence_transformers import SentenceTransformer\n>>> model = SentenceTransformer(\"all-MiniLM-L6-v2\")\n>>> model.encode(\"谁是阿米莉亚·埃尔哈特？\", normalize=True)\nTraceback (most recent call last):\n  File \"\u003Cstdin>\", line 1, in \u003Cmodule>\n  File \"[sic]\u002Ftorch\u002Futils\u002F_contextlib.py\", line 116, in decorate_context\n    return func(*args, **kwargs)\n           ^^^^^^^^^^^^^^^^^^^^^\n  File \"[sic]\u002FSentenceTransformer.py\", line 983, in encode\n    raise ValueError(\nValueError: SentenceTransformer.encode() 被调用时传入了该模型不支持的额外关键字参数：['normalize']。根据 SentenceTransformer.get_model_kwargs() 的返回值，该模型不接受任何额外的关键字参数。\n```\n\n这在您不小心忘记获取归一化嵌入的参数是 `normalize_embeddings` 时非常有用。在此版本之前，此类参数会被静默忽略。\n\n要检查您的模型可以使用哪些自定义的额外关键字参数，可以调用新的 `get_model_kwargs` 方法：\n\n```python\n>>> from sentence_transformers import SentenceTransformer, SparseEncoder\n>>> SentenceTransformer(\"all-MiniLM-L6-v2\").get_model_kwargs()\n[]\n>>> SentenceTransformer(\"jinaai\u002Fjina-embeddings-v4\", trust_remote_code=True).get_model_kwargs()\n['task', 'truncate_dim']\n>>> SparseEncoder(\"opensearch-project\u002Fopensearch-neural-sparse-encoding-doc-v3-distill\").get_model_kwargs()\n['task']\n```\n\n**注意：** 您始终可以传递 `task` 参数，它是唯一会被静默忽略的模型特定参数。这意味着您可以始终使用 `model.encode(..., task=\"query\")` 和 `model.encode(..., task=\"document\")`。\n\n## 小功能改进\n* 为 SparseEncoder 评估器添加 FLOPS 计算 (#3456)\n* 添加对 [Knowledgeable Passage Retriever (KPR) 模型](https:\u002F\u002Fhuggingface.co\u002Fknowledgeable-ai\u002Fkpr-bge-large-en-v1.5) 的支持 (#3495)\n\n## 小问题修复\n* 修复 `CrossEncoderRerankingEvaluator` 中 `batch_size` 被忽略的问题 (#3497)\n* 修复使用 `encode` 进行多 GPU 处理时的问题，现在嵌入会从各个设备上正确移动。","2025-09-22T11:28:54",{"id":182,"version":183,"summary_zh":184,"released_at":185},272344,"v5.1.0","本次发布为 SparseEncoder 嵌入模型引入了 2 个新的高效计算后端：[ONNX 和 OpenVINO + 优化与量化，可实现最高 2–3 倍的加速](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fsparse_encoder\u002Fusage\u002Fefficiency.html)；为蒸馏中的难负样本挖掘新增了“n 元组分数”输出格式；在多 GPU 训练中实现了跨设备的聚合，带来免费的性能提升；增加了 trackio 支持；完善了 MTEB 文档；以及许多小修复和新功能。\n\n可通过以下命令安装此版本：\n\n```bash\n# 训练 + 推理\npip install sentence-transformers[train]==5.1.0\n\n# 仅推理，可选择：\npip install sentence-transformers==5.1.0\npip install sentence-transformers[onnx-gpu]==5.1.0\npip install sentence-transformers[onnx]==5.1.0\npip install sentence-transformers[openvino]==5.1.0\n```\n\n## SparseEncoder 模型的更快 ONNX 和 OpenVINO 后端 (#3475)\n在 `SparseEncoder` 初始化中引入了一个新的 `backend` 关键字参数，支持的值包括 `\"torch\"`（默认）、`\"onnx\"` 和 `\"openvino\"`。\n这些后端需要使用特定的 extras 安装 `sentence-transformers`：\n```bash\npip install sentence-transformers[onnx-gpu]\n# 或仅适用于 CPU 的 ONNX：\npip install sentence-transformers[onnx]\n# 或\npip install sentence-transformers[openvino]\n```\n使用方法非常简单：\n```python\nfrom sentence_transformers import SparseEncoder\n\n# 使用 ONNX 后端加载 SparseEncoder 模型\nmodel = SparseEncoder(\"naver\u002Fsplade-v3\", backend=\"onnx\")\n\nquery = \"哪颗行星被称为红色星球？\"\ndocuments = [\n   \"金星常被称为地球的双子星，因为它与地球大小相近且距离较近。\",\n   \"火星因其红褐色外观而常被称为红色星球。\",\n   \"木星是太阳系中最大的行星，拥有一个显著的红色大斑点。\",\n   \"土星以其著名的环而闻名，有时会被误认为是红色星球。\"\n]\n\nquery_embeddings = model.encode_query(query)\ndocument_embeddings = model.encode_document(documents)\nprint(query_embeddings.shape, document_embeddings.shape)\n# torch.Size([30522]) torch.Size([4, 30522])\n\nsimilarities = model.similarity(query_embeddings, document_embeddings)\nprint(similarities)\n# tensor([[12.1450, 26.1040, 22.0025, 23.3877]])\n\ndecoded_query = model.decode(query_embeddings, top_k=5)\ndecoded_documents = model.decode(document_embeddings, top_k=5)\nprint(decoded_query)\n# [('red', 3.0222), ('planet', 2.5001), ('planets', 1.9412), ('known', 1.8126), ('nasa', 0.9347)]\nprint(decoded_documents)\n# [\n#     [('venus', 3.1980), ('twin', 2.7036), ('earth', 2.4310), ('twins', 2.0957), ('planet', 1.9462)],\n#     [('mars', 3.1443), ('planet', 2.4924), ('red', 2.4514), ('reddish', 2.2234), ('planets', 2.1976)],\n#     [('jupiter', 2.9604), ('red', 2.5507), ('planet', 2.3774), ('planets', 2.1641), ('spot', 2.1138)],\n#     [('saturn', 2.9354), ('red', 2.4548), ('planet', 2.3962), ('mistaken', 2.3361), ('cass', 2.2100)]\n# ]\n```\n如果您指定了 `backend` 参数，并且您的模型仓库或目录包含","2025-08-06T13:49:08",{"id":187,"version":188,"summary_zh":189,"released_at":190},272345,"v5.0.0","This release consists of significant updates including the introduction of Sparse Encoder models, new methods `encode_query` and `encode_document`, multi-processing support in `encode`, the `Router` module for asymmetric models, custom learning rates for parameter groups, composite loss logging, and various small improvements and bug fixes.\r\n\r\nInstall this version with\r\n\r\n```bash\r\n# Training + Inference\r\npip install sentence-transformers[train]==5.0.0\r\n\r\n# Inference only, use one of:\r\npip install sentence-transformers==5.0.0\r\npip install sentence-transformers[onnx-gpu]==5.0.0\r\npip install sentence-transformers[onnx]==5.0.0\r\npip install sentence-transformers[openvino]==5.0.0\r\n```\r\n\r\n> [!TIP]\r\nOur [Training and Finetuning Sparse Embedding Models with Sentence Transformers v5 blogpost](https:\u002F\u002Fhuggingface.co\u002Fblog\u002Ftrain-sparse-encoder) is an excellent place to learn about finetuning sparse embedding models!\r\n\r\n> [!NOTE]\r\n> This release is designed to be fully backwards compatible, meaning that you should be able to upgrade from older versions to v5.x without any issues. If you are running into issues when upgrading, feel free to open [an issue](https:\u002F\u002Fgithub.com\u002FuKPLab\u002Fsentence-transformers\u002Fissues\u002Fnew). Also see the [Migration Guide](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fmigration_guide.html) for changes that we would recommend.\r\n\r\n## Sparse Encoder models\r\n\r\nThe Sentence Transformers v5.0 release introduces Sparse Embedding models, also known as Sparse Encoders. These models generate high-dimensional embeddings, often with 30,000+ dimensions, where often only \u003C1% of dimensions are non-zero. This is in contrast to the standard dense embedding models, which produce low-dimensional embeddings (e.g., 384, 768, or 1024 dimensions) where all values are non-zero.\r\n\r\nUsually, each active dimension (i.e. the dimension with a non-zero value) in a sparse embedding corresponds to a specific token in the model's vocabulary, allowing for interpretability. This means that you can e.g. see exactly which words\u002Ftokens are important in an embedding, and that you can inspect exactly because of which words\u002Ftokens two texts are deemed similar.\r\n\r\nLet's have a look at [naver\u002Fsplade-v3](https:\u002F\u002Fhuggingface.co\u002Fnaver\u002Fsplade-v3), a strong sparse embedding model, as an example:\r\n\r\n```python\r\nfrom sentence_transformers import SparseEncoder\r\n\r\n# Download from the 🤗 Hub\r\nmodel = SparseEncoder(\"naver\u002Fsplade-v3\")\r\n\r\n# Run inference\r\nsentences = [\r\n    \"The weather is lovely today.\",\r\n    \"It's so sunny outside!\",\r\n    \"He drove to the stadium.\",\r\n]\r\nembeddings = model.encode(sentences)\r\nprint(embeddings.shape)\r\n# (3, 30522)\r\n\r\n# Get the similarity scores for the embeddings\r\nsimilarities = model.similarity(embeddings, embeddings)\r\nprint(similarities)\r\n# tensor([[   32.4323,     5.8528,     0.0258],\r\n#         [    5.8528,    26.6649,     0.0302],\r\n#         [    0.0258,     0.0302,    24.0839]])\r\n\r\n# Let's decode our embeddings to be able to interpret them\r\ndecoded = model.decode(embeddings, top_k=10)\r\nfor decoded, sentence in zip(decoded, sentences):\r\n    print(f\"Sentence: {sentence}\")\r\n    print(f\"Decoded: {decoded}\")\r\n    print()\r\n```\r\n\r\n```\r\nSentence: The weather is lovely today.\r\nDecoded: [('weather', 2.754288673400879), ('today', 2.610959529876709), ('lovely', 2.431990623474121), ('currently', 1.5520408153533936), ('beautiful', 1.5046082735061646), ('cool', 1.4664798974990845), ('pretty', 0.8986214995384216), ('yesterday', 0.8603134155273438), ('nice', 0.8322536945343018), ('summer', 0.7702118158340454)]\r\n\r\nSentence: It's so sunny outside!\r\nDecoded: [('outside', 2.6939032077789307), ('sunny', 2.535827398300171), ('so', 2.0600898265838623), ('out', 1.5397940874099731), ('weather', 1.1198079586029053), ('very', 0.9873268604278564), ('cool', 0.9406591057777405), ('it', 0.9026399254798889), ('summer', 0.684999406337738), ('sun', 0.6520509123802185)]\r\n\r\nSentence: He drove to the stadium.\r\nDecoded: [('stadium', 2.7872302532196045), ('drove', 1.8208855390548706), ('driving', 1.6665740013122559), ('drive', 1.5565159320831299), ('he', 1.4721972942352295), ('stadiums', 1.449463129043579), ('to', 1.0441515445709229), ('car', 0.7002660632133484), ('visit', 0.5118278861045837), ('football', 0.502326250076294)]\r\n```\r\n\r\nIn this example, the embeddings are 30,522-dimensional vectors, where each dimension corresponds to a token in the model's vocabulary. The `decode` method returned the top 10 tokens with the highest values in the embedding, allowing us to interpret which tokens contribute most to the embedding.\r\n\r\nWe can even determine the intersection or overlap between embeddings, very useful for determining why two texts are deemed similar or dissimilar:\r\n\r\n```python\r\n# Let's also compute the intersection\u002Foverlap of the first two embeddings\r\nintersection_embedding = model.intersection(embeddings[0], embeddings[1])\r\ndecoded_intersection = model.decode(intersection_embedding)\r\nprint(decoded_intersection)\r\n```\r\n\r\n```\r\nDecoded: [('weather', 3.0842742919921875), ('cool","2025-07-01T13:56:10",{"id":192,"version":193,"summary_zh":194,"released_at":195},272346,"v4.1.0","This release introduces 2 new efficient computing backends for CrossEncoder (reranker) models: [ONNX and OpenVINO + optimization & quantization, allowing for speedups up to 2x-3x](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fcross_encoder\u002Fusage\u002Fefficiency.html); improved hard negatives mining strategies, and minor improvements.\r\n\r\nInstall this version with\r\n```bash\r\n# Training + Inference\r\npip install sentence-transformers[train]==4.1.0\r\n\r\n# Inference only, use one of:\r\npip install sentence-transformers==4.1.0\r\npip install sentence-transformers[onnx-gpu]==4.1.0\r\npip install sentence-transformers[onnx]==4.1.0\r\npip install sentence-transformers[openvino]==4.1.0\r\n```\r\n\r\n## Faster ONNX and OpenVINO Backends for CrossEncoder (#3319)\r\nIntroducing a new `backend` keyword argument to the `CrossEncoder` initialization, allowing values of `\"torch\"` (default), `\"onnx\"`, and `\"openvino\"`.\r\nThese require installing `sentence-transformers` with specific extras:\r\n```bash\r\npip install sentence-transformers[onnx-gpu]\r\n# or ONNX for CPU only:\r\npip install sentence-transformers[onnx]\r\n# or\r\npip install sentence-transformers[openvino]\r\n```\r\nIt's as simple as:\r\n```python\r\nfrom sentence_transformers import CrossEncoder\r\n\r\nmodel = CrossEncoder(\"cross-encoder\u002Fms-marco-MiniLM-L6-v2\", backend=\"onnx\")\r\n\r\nquery = \"Which planet is known as the Red Planet?\"\r\npassages = [\r\n   \"Venus is often called Earth's twin because of its similar size and proximity.\",\r\n   \"Mars, known for its reddish appearance, is often referred to as the Red Planet.\",\r\n   \"Jupiter, the largest planet in our solar system, has a prominent red spot.\",\r\n   \"Saturn, famous for its rings, is sometimes mistaken for the Red Planet.\"\r\n]\r\n\r\nscores = model.predict([(query, passage) for passage in passages])\r\nprint(scores)\r\n```\r\nIf you specify a `backend` and your model repository or directory contains an ONNX\u002FOpenVINO model file, it will automatically be used! And if your model repository or directory doesn't have one already, an ONNX\u002FOpenVINO model will be automatically exported. Just remember to `model.push_to_hub` or `model.save_pretrained` into the same model repository or directory to avoid having to re-export the model every time.\r\n\r\nAll keyword arguments passed via `model_kwargs` will be passed on to [`ORTModelForSequenceClassification.from_pretrained`](https:\u002F\u002Fhuggingface.co\u002Fdocs\u002Foptimum\u002Fmain\u002Fen\u002Fonnxruntime\u002Fpackage_reference\u002Fmodeling_ort#optimum.onnxruntime.ORTModel.from_pretrained) or [`OVModelForSequenceClassification.from_pretrained`](https:\u002F\u002Fhuggingface.co\u002Fdocs\u002Foptimum\u002Fintel\u002Fopenvino\u002Freference#optimum.intel.openvino.modeling_base.OVBaseModel.from_pretrained). The most useful arguments are:\r\n\r\n* `provider`: (Only if `backend=\"onnx\"`) ONNX Runtime provider to use for loading the model, e.g. `\"CPUExecutionProvider\"` . See https:\u002F\u002Fonnxruntime.ai\u002Fdocs\u002Fexecution-providers\u002F for possible providers. If not specified, the strongest provider (E.g. `\"CUDAExecutionProvider\"`) will be used.\r\n* `file_name`: The name of the ONNX file to load. If not specified, will default to \"model.onnx\" or otherwise \"onnx\u002Fmodel.onnx\" for ONNX, and \"openvino_model.xml\" and \"openvino\u002Fopenvino_model.xml\" for OpenVINO. This argument is useful for specifying optimized or quantized models.\r\n* `export`: A boolean flag specifying whether the model will be exported. If not provided, export will be set to True if the model repository or directory does not already contain an ONNX or OpenVINO model.\r\n\r\nFor example:\r\n```python\r\nfrom sentence_transformers import CrossEncoder\r\n\r\nmodel = CrossEncoder(\r\n    \"cross-encoder\u002Fms-marco-MiniLM-L6-v2\",\r\n\tbackend=\"onnx\",\r\n\tmodel_kwargs={\r\n\t\t\"file_name\": \"model_O3.onnx\",\r\n\t\t\"provider\": \"CPUExecutionProvider\",\r\n\t}\r\n)\r\n\r\nquery = \"Which planet is known as the Red Planet?\"\r\npassages = [\r\n   \"Venus is often called Earth's twin because of its similar size and proximity.\",\r\n   \"Mars, known for its reddish appearance, is often referred to as the Red Planet.\",\r\n   \"Jupiter, the largest planet in our solar system, has a prominent red spot.\",\r\n   \"Saturn, famous for its rings, is sometimes mistaken for the Red Planet.\"\r\n]\r\n\r\nscores = model.predict([(query, passage) for passage in passages])\r\nprint(scores)\r\n```\r\n\r\n### Benchmarks\r\nWe ran [benchmarks](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fcross_encoder\u002Fusage\u002Fefficiency.html#benchmark) for CPU and GPU, averaging findings across 4 models of various sizes, 3 datasets, and numerous batch sizes. Here are the findings:\r\n\r\n\u003Cp float=\"left\">\r\n  \u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002Feda6bb28-e997-4f95-993d-a0d1783c6c37\" width=\"45%\" \u002F>\r\n  \u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002Fc27e6933-9af6-4d3c-aa4b-66b44956ff85\" width=\"45%\" \u002F> \r\n\u003C\u002Fp>\r\n\r\nThese findings resulted in these recommendations:\r\n![image](https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F1232a60c-0ef0-4be1-b6ea-dab2c0a1a789)\r\n\r\nFor GPU, you can expect **1.88x speedup with fp16 at no cost**, and for CPU you can expect **~3x speedup at no cost of accuracy in our evaluation**. Your mileage with the accu","2025-04-15T13:47:13",{"id":197,"version":198,"summary_zh":199,"released_at":200},272347,"v4.0.2","This patch release updates some logic for maximum sequence lengths, typing issues, FSDP training, and distributed training device placement.\r\n\r\nInstall this version with\r\n```bash\r\n# Training + Inference\r\npip install sentence-transformers[train]==4.0.2\r\n\r\n# Inference only, use one of:\r\npip install sentence-transformers==4.0.2\r\npip install sentence-transformers[onnx-gpu]==4.0.2\r\npip install sentence-transformers[onnx]==4.0.2\r\npip install sentence-transformers[openvino]==4.0.2\r\n```\r\n\r\n## Safer CrossEncoder (reranker) maximum sequence length\r\nWhen loading `CrossEncoder` models, we now rely on the *minimum* of the tokenizer `model_max_length` and the config `max_position_embeddings` (if they exist), rather than only relying on the latter if it exists. This previously resulted in the maximum sequence length of [BAAI\u002Fbge-reranker-base](https:\u002F\u002Fhuggingface.co\u002FBAAI\u002Fbge-reranker-base) being 514, whereas it can only handle sequences up to 512 tokens.\r\n\r\n```python\r\nfrom sentence_transformers import CrossEncoder\r\n\r\nmodel = CrossEncoder(\"BAAI\u002Fbge-reranker-base\")\r\nprint(model.max_length)\r\n# => 512\r\n\r\n# The texts for which to predict similarity scores\r\nquery = \"How many people live in Berlin?\"\r\npassages = [\r\n    \"Berlin had a population of 3,520,031 registered inhabitants in an area of 891.82 square kilometers.\",\r\n    \"In 2013 around 600,000 Berliners were registered in one of the more than 2,300 sport and fitness clubs.\",\r\n]\r\n\r\nscores = model.predict([(query, passage) for passage in passages])\r\nprint(scores)\r\n# => [0.99953485 0.01062613]\r\n\r\n# Or test really long inputs to ensure that there's no crash:\r\nscore = model.predict([[\"one \" * 1000, \"two \" * 1000]])\r\nprint(score)\r\n# => [0.95482624]\r\n```\r\nNote that you can use the `activation_fn` option with `torch.nn.Identity()` to avoid the default Sigmoid that maps everything to [0, 1]:\r\n```python\r\nfrom sentence_transformers import CrossEncoder\r\nimport torch\r\n\r\nmodel = CrossEncoder(\"BAAI\u002Fbge-reranker-base\", activation_fn=torch.nn.Identity())\r\n\r\n# The texts for which to predict similarity scores\r\nquery = \"How many people live in Berlin?\"\r\npassages = [\r\n    \"Berlin had a population of 3,520,031 registered inhabitants in an area of 891.82 square kilometers.\",\r\n    \"In 2013 around 600,000 Berliners were registered in one of the more than 2,300 sport and fitness clubs.\",\r\n]\r\n\r\nscores = model.predict([(query, passage) for passage in passages])\r\nprint(scores)\r\n# => [ 7.672551  -4.5337563]\r\n```\r\n\r\n## Default device placement (#3303)\r\nBy default, in a distributed training setup with multiple CUDA devices, the model is now placed on the CUDA device corresponding with that local rank. This should lower the VRAM usage on GPU 0 when performing distributed training.\r\n\r\n## Minor patches of note\r\n* Resolved typing issues for `SentenceTransformer` class outside of the `encode` method. In v4.0.1, it was possible to no longer get help from your IDE for e.g. `model.similarity`, for example. (#3297)\r\n* Improve FSDP training compatibility by avoiding a faulty \"only if model is wrapped\"-check. Now, the wrapped model should always be laced in the `loss` class instance when required for FSDP training. (#3295)\r\n\r\n## All Changes\r\n* [docs]: update examples by @emmanuel-ferdman in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3292\r\n* Update htaccess, in-line comments were problematic by @tomaarsen in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3293\r\n* [`docs`] Resolve more broken links throughout the docs by @tomaarsen in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3294\r\n* [`docs`] Fix some broken docs redirects by @tomaarsen in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3296\r\n* [`typing`] Move encode typings back to .py from .pyi by @tomaarsen in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3297\r\n* [`fix`] Avoid \"Only if model is wrapped\" check which is faulty for FSDP by @tomaarsen in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3295\r\n* [`cross-encoder`] Set the tokenizer model_max_length to the min. of model_max_length & max_pos_embeds by @tomaarsen in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3304\r\n* [`ci`] Attempt to fix CI by @tomaarsen in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3305\r\n* Fix device assignment in `get_device_name` for distributed training by @uminaty in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3303\r\n* [`docs`] Add missing docstring for push_to_hub by @tomaarsen in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3306\r\n* [`docs`] Specify that exported ONNX\u002FOpenVINO models don't include pooling\u002Fnormalization by @tomaarsen in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3307\r\n\r\n## New Contributors\r\n* @emmanuel-ferdman made their first contribution in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3292\r\n* @uminaty made their first contribution in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3303\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fcompare\u002Fv4.0.1","2025-04-03T11:29:10",{"id":202,"version":203,"summary_zh":204,"released_at":205},272348,"v4.0.1","This release consists of a major refactor that overhauls the reranker a.k.a. Cross Encoder [training approach](https:\u002F\u002Fhuggingface.co\u002Fblog\u002Ftrain-reranker) (introducing multi-gpu training, bf16, loss logging, callbacks, and much more), including all new [Training Overview](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fcross_encoder\u002Ftraining_overview.html), [Loss Overview](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fcross_encoder\u002Floss_overview.html), [API Reference](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fpackage_reference\u002Fcross_encoder\u002Findex.html) docs, [training examples](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fcross_encoder\u002Ftraining\u002Fexamples.html) and more!\r\n\r\nInstall this version with\r\n\r\n```bash\r\n# Training + Inference\r\npip install sentence-transformers[train]==4.0.1\r\n\r\n# Inference only, use one of:\r\npip install sentence-transformers==4.0.1\r\npip install sentence-transformers[onnx-gpu]==4.0.1\r\npip install sentence-transformers[onnx]==4.0.1\r\npip install sentence-transformers[openvino]==4.0.1\r\n```\r\n\r\n> [!TIP]\r\n> My [Training and Finetuning Reranker Models with Sentence Transformers v4](https:\u002F\u002Fhuggingface.co\u002Fblog\u002Ftrain-reranker) blogpost is an excellent place to learn 1) why finetuning rerankers makes sense and 2) how you can do it, too!\r\n\r\n## Reranker (Cross Encoder) training refactor (#3222)\r\nThe v4.0 release centers around this huge modernization of the training approach for `CrossEncoder` models, following v3.0 which introduced the same for `SentenceTransformer` models. Whereas training before v4.0 used to be all about `InputExample`, `DataLoader` and `model.fit`, the new training approach relies on 5 components. You can learn more about these components in our [Training and Finetuning Embedding Models with Sentence Transformers v4](https:\u002F\u002Fhuggingface.co\u002Fblog\u002Ftrain-reranker) blogpost. Additionally, you can read the new [Training Overview](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fcross_encoder\u002Ftraining_overview.html), check out the [Training Examples](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fcross_encoder\u002Ftraining\u002Fexamples.html), or read this summary:\r\n\r\n1. [Dataset](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fsentence_transformer\u002Ftraining_overview.html#dataset)\r\n   A training [`Dataset`](https:\u002F\u002Fhuggingface.co\u002Fdocs\u002Fdatasets\u002Fmain\u002Fen\u002Fpackage_reference\u002Fmain_classes#datasets.Dataset) or [`DatasetDict`](https:\u002F\u002Fhuggingface.co\u002Fdocs\u002Fdatasets\u002Fmain\u002Fen\u002Fpackage_reference\u002Fmain_classes#datasets.DatasetDict). This class is much more suited for sharing & efficient modifications than lists\u002FDataLoaders of `InputExample` instances. A `Dataset` can contain multiple text columns that will be fed in order to the corresponding loss function. So, if the loss expects (anchor, positive, negative) triplets, then your dataset should also have 3 columns. The names of these columns are irrelevant. If there is a \"label\" or \"score\" column, it is treated separately, and used as the labels during training.\r\n    A `DatasetDict` can be used to train with multiple datasets at once, e.g.:\r\n    ```python\r\n    DatasetDict({\r\n        natural_questions: Dataset({\r\n            features: ['anchor', 'positive'],\r\n            num_rows: 392702\r\n        })\r\n        gooaq: Dataset({\r\n            features: ['anchor', 'positive', 'negative'],\r\n            num_rows: 549367\r\n        })\r\n        stsb: Dataset({\r\n            features: ['sentence1', 'sentence2', 'label'],\r\n            num_rows: 5749\r\n        })\r\n    })\r\n    ```\r\n    When a `DatasetDict` is used, the `loss` parameter to the `CrossEncoderTrainer` must also be a dictionary with these dataset keys, e.g.:\r\n    ```python\r\n    {\r\n        'natural_questions': CachedMultipleNegativesRankingLoss(...),\r\n        'gooaq': CachedMultipleNegativesRankingLoss(...),\r\n        'stsb': BinaryCrossEntropyLoss(...),\r\n    }\r\n    ```\r\n2. [Loss Function](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fcross_encoder\u002Ftraining_overview.html#loss-function)\r\n  A loss function, or a dictionary of loss functions like described above. \r\n3. [Training Arguments](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fcross_encoder\u002Ftraining_overview.html#training-arguments)\r\n  A CrossEncoderTrainingArguments instance, subclass of a [TrainingArguments](https:\u002F\u002Fhuggingface.co\u002Fdocs\u002Ftransformers\u002Fmain\u002Fen\u002Fmain_classes\u002Ftrainer#transformers.TrainingArguments) instance. This powerful class controls the specific details of the training.\r\n4. [Evaluator](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fcross_encoder\u002Ftraining_overview.html#evaluator)\r\n  An optional [`SentenceEvaluator`](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fpackage_reference\u002Fevaluation.html) instance. Unlike before, models can now be evaluated both on an evaluation dataset with some loss function and\u002For a `SentenceEvaluator` instance.\r\n5. [Trainer](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fsentence_transformer\u002Ftraining_overview.html#trainer)\r\n  The new `CrossEncoderTrainer` instance based on the `transformers` `Trainer`. This instance can be initialized with a CrossEncoder model, a CrossEncoderTrainingArguments class, a SentenceEvaluator, a training and evaluation Dataset\u002FDatasetDict and a loss function\u002Fdict of loss functions. Most of these parameters are optional. Once provided, all you have to do is call `trainer.trai","2025-03-26T14:59:03",{"id":207,"version":208,"summary_zh":209,"released_at":210},272349,"v3.4.1","This release introduces a convenient compatibility with [Model2Vec models](https:\u002F\u002Fhuggingface.co\u002Fmodels?library=model2vec), and fixes a bug that caused an outgoing request even when using a local model.\r\n\r\nInstall this version with\r\n\r\n```bash\r\n# Training + Inference\r\npip install sentence-transformers[train]==3.4.1\r\n\r\n# Inference only, use one of:\r\npip install sentence-transformers==3.4.1\r\npip install sentence-transformers[onnx-gpu]==3.4.1\r\npip install sentence-transformers[onnx]==3.4.1\r\npip install sentence-transformers[openvino]==3.4.1\r\n```\r\n\r\n## Full Model2Vec integration\r\nThis release introduces support to load an efficient [Model2Vec](https:\u002F\u002Fhuggingface.co\u002Fmodels?library=model2vec) embedding model directly in Sentence Transformers:\r\n```python\r\nfrom sentence_transformers import SentenceTransformer\r\n\r\n# Download from the 🤗 Hub\r\nmodel = SentenceTransformer(\r\n    \"minishlab\u002Fpotion-base-8M\",\r\n    device=\"cpu\",\r\n)\r\n\r\n# Run inference\r\nsentences = [\r\n    'Gadofosveset-enhanced MR angiography of carotid arteries: does steady-state imaging improve accuracy of first-pass imaging?',\r\n    'To evaluate the diagnostic accuracy of gadofosveset-enhanced magnetic resonance (MR) angiography in the assessment of carotid artery stenosis, with digital subtraction angiography (DSA) as the reference standard, and to determine the value of reading first-pass, steady-state, and \"combined\" (first-pass plus steady-state) MR angiograms.',\r\n    'In a longitudinal study we investigated in vivo alterations of CVO during neuroinflammation, applying Gadofluorine M- (Gf) enhanced magnetic resonance imaging (MRI) in experimental autoimmune encephalomyelitis, an animal model of multiple sclerosis. SJL\u002FJ mice were monitored by Gadopentate dimeglumine- (Gd-DTPA) and Gf-enhanced MRI after adoptive transfer of proteolipid-protein-specific T cells. Mean Gf intensity ratios were calculated individually for different CVO and correlated to the clinical disease course. Subsequently, the tissue distribution of fluorescence-labeled Gf as well as the extent of cellular inflammation was assessed in corresponding histological slices.',\r\n]\r\nembeddings = model.encode(sentences)\r\nprint(embeddings.shape)\r\n# [3, 1024]\r\n\r\n# Get the similarity scores for the embeddings\r\nsimilarities = model.similarity(embeddings[0], embeddings[1:])\r\nprint(similarities)\r\n# tensor([[0.8085, 0.4884]])\r\n``` \r\n\u003Cdetails>\u003Csummary>Previously, loading a Model2Vec model required you to load a `StaticEmbedding` module.\u003C\u002Fsummary>\r\n\r\n```python\r\nfrom sentence_transformers import SentenceTransformer\r\nfrom sentence_transformers.models import StaticEmbedding\r\n\r\n# Download from the 🤗 Hub\r\nmodule = StaticEmbedding.from_model2vec(\"minishlab\u002Fpotion-base-8M\")\r\nmodel = SentenceTransformer(modules=[module], device=\"cpu\")\r\n\r\n# Run inference\r\nsentences = [\r\n    'Gadofosveset-enhanced MR angiography of carotid arteries: does steady-state imaging improve accuracy of first-pass imaging?',\r\n    'To evaluate the diagnostic accuracy of gadofosveset-enhanced magnetic resonance (MR) angiography in the assessment of carotid artery stenosis, with digital subtraction angiography (DSA) as the reference standard, and to determine the value of reading first-pass, steady-state, and \"combined\" (first-pass plus steady-state) MR angiograms.',\r\n    'In a longitudinal study we investigated in vivo alterations of CVO during neuroinflammation, applying Gadofluorine M- (Gf) enhanced magnetic resonance imaging (MRI) in experimental autoimmune encephalomyelitis, an animal model of multiple sclerosis. SJL\u002FJ mice were monitored by Gadopentate dimeglumine- (Gd-DTPA) and Gf-enhanced MRI after adoptive transfer of proteolipid-protein-specific T cells. Mean Gf intensity ratios were calculated individually for different CVO and correlated to the clinical disease course. Subsequently, the tissue distribution of fluorescence-labeled Gf as well as the extent of cellular inflammation was assessed in corresponding histological slices.',\r\n]\r\nembeddings = model.encode(sentences)\r\nprint(embeddings.shape)\r\n# [3, 1024]\r\n\r\n# Get the similarity scores for the embeddings\r\nsimilarities = model.similarity(embeddings[0], embeddings[1:])\r\nprint(similarities)\r\n# tensor([[0.8085, 0.4884]])\r\n```\r\n\r\n\u003C\u002Fdetails>\r\n\r\nModel2Vec was the inspiration of the recent [Static Embedding](https:\u002F\u002Fhuggingface.co\u002Fblog\u002Fstatic-embeddings) work; all of these models can be used to approach the performance of normal transformer-based embedding models at a fraction of the latency. For example, both Model2Vec and Static Embedding models are ~25x faster than tiny embedding models on a GPU and ~400x faster than those models on a CPU.\r\n\r\n## Bug Fix\r\n* Using `local_files_only=True` still triggered a request to Hugging Face for the model card metadata; this has been resolved in (#3202).\r\n\r\n## All Changes\r\n* fix loss name in documentation of CachedMultipleNegativesRankingLoss by @JINO-ROHIT in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3191\r\n* Bump jinja2 from 3.1.4 to 3","2025-01-29T14:26:29",{"id":212,"version":213,"summary_zh":214,"released_at":215},272350,"v3.4.0","This release resolves a memory leak when deleting a model & trainer, adds compatibility between the Cached... losses and the Matryoshka loss modifier, resolves numerous bugs, and adds several small features.\r\n\r\nInstall this version with\r\n```bash\r\n# Training + Inference\r\npip install sentence-transformers[train]==3.4.0\r\n\r\n# Inference only, use one of:\r\npip install sentence-transformers==3.4.0\r\npip install sentence-transformers[onnx-gpu]==3.4.0\r\npip install sentence-transformers[onnx]==3.4.0\r\npip install sentence-transformers[openvino]==3.4.0\r\n```\r\n\r\n## Matryoshka & Cached loss compatibility (#3068, #3107)\r\nIt is now possible to combine the strong Cached losses ([CachedMultipleNegativesRankingLoss](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fpackage_reference\u002Fsentence_transformer\u002Flosses.html#cachedmultiplenegativesrankingloss), [CachedGISTEmbedLoss](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fpackage_reference\u002Fsentence_transformer\u002Flosses.html#cachedgistembedloss), [CachedMultipleNegativesSymmetricRankingLoss](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fpackage_reference\u002Fsentence_transformer\u002Flosses.html#cachedmultiplenegativessymmetricrankingloss)) with the Matryoshka loss modifier:\r\n\r\n```python\r\nfrom sentence_transformers import SentenceTransformer, SentenceTransformerTrainer, losses\r\nfrom datasets import Dataset\r\n\r\nmodel = SentenceTransformer(\"microsoft\u002Fmpnet-base\")\r\ntrain_dataset = Dataset.from_dict({\r\n    \"anchor\": [\"It's nice weather outside today.\", \"He drove to work.\"],\r\n    \"positive\": [\"It's so sunny.\", \"He took the car to the office.\"],\r\n})\r\nloss = losses.CachedMultipleNegativesRankingLoss(model, mini_batch_size=16)\r\nloss = losses.MatryoshkaLoss(model, loss, [768, 512, 256, 128, 64])\r\n\r\ntrainer = SentenceTransformerTrainer(\r\n    model=model,\r\n    train_dataset=train_dataset,\r\n    loss=loss,\r\n)\r\ntrainer.train()\r\n```\r\n\r\nSee for example [tomaarsen\u002Fmpnet-base-gooaq-cmnrl-mrl](https:\u002F\u002Fhuggingface.co\u002Ftomaarsen\u002Fmpnet-base-gooaq-cmnrl-mrl) which was trained with [CachedMultipleNegativesRankingLoss](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fpackage_reference\u002Fsentence_transformer\u002Flosses.html#cachedmultiplenegativesrankingloss) (CMNRL) with the Matryoshka loss modifier (MRL).\r\n\r\n## Resolve memory leak when Model and Trainer are reinitialized (#3144)\r\nDue to a circular dependency in the `SentenceTransformerTrainer` -> `SentenceTransformer` -> `SentenceTransformerModelCardData` -> `SentenceTransformerTrainer`, deleting the trainer and model still doesn't clear them up via garbage disposal. I've moved a lot of components around, and now `SentenceTransformerModelCardData` does not need to store the `SentenceTransformerTrainer`, breaking the cycle. \r\n\r\nWe ran the seed optimization script (which frequently creates and deletes models and trainers):\r\n* **Before**: Approximate highest recorded VRAM:\r\n   ```\r\n   16332MiB \u002F  24576MiB\r\n   ```\r\n* **After**: Approximate highest recorded VRAM:\r\n   ```\r\n   8222MiB \u002F  24576MiB\r\n   ```\r\n\r\n## Small Features\r\n* Add Matthews Correlation Coefficient to the BinaryClassificationEvaluator in #3051.\r\n* Add a triplet `margin` parameter to the TripletEvaluator in #2862.\r\n* Put dataset information in the automatically generated model card in \"expanding sections\" blocks if there are many datasets in #3088.\r\n* Add multi-GPU (and CPU multi-process) support for [`mine_hard_negatives`](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fpackage_reference\u002Futil.html#sentence_transformers.util.mine_hard_negatives) in #2967.\r\n\r\n## Notable Bug Fixes\r\n* Subsequent batches were identical when using the `no_duplicates` Batch Sampler (#3069). This has been resolved in #3073\r\n* The old-style `model.fit()` training with `write_csv` on an evaluator would crash (#3062). This has been resolved in #3066.\r\n* The output types of some evaluators were `np.float` instead of `float` (#3075). This has been resolved in #3076 and #3096.\r\n* It was not possible to specify a `revision` or `cache_dir` when loading a PEFT Adapter model (#3061). This has been resolved in #3079 and #3174.\r\n* The CrossEncoder was lazily placed on the incorrect device, did not respond to `model.to` (#3078). This has been resolved in #3104.\r\n* If a model used a custom module with custom kwargs, those `kwargs` keys were not saved in `modules.json` correctly, e.g. relevant for [jina-embeddings-v3](https:\u002F\u002Fhuggingface.co\u002Fjinaai\u002Fjina-embeddings-v3) (#3111). This has been resolved in #3112.\r\n* `HfArgumentParser(SentenceTransformerTrainingArguments)` would crash due to `prompts` typing (#3090). This has been resolved in #3178.\r\n\r\n## Example Updates\r\n* Update the quantization script in #3070.\r\n* Update the seed optimization script in #3092.\r\n* Update the TSDAE scripts in #3137.\r\n* Add PEFT Adapter script in #3180.\r\n\r\n## Documentation Updates\r\n* Add PEFT Adapter documentation in #3180.\r\n* Add links to [backend-export](https:\u002F\u002Fhuggingface.co\u002Fspaces\u002Fsentence-transformers\u002Fbackend-export) in [Speeding up Inference](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fsentence_transformer\u002Fusage\u002Fefficiency.html).\r\n\r\n## All Changes\r\n* [`training`] Pass `steps`\u002F`epoch`\u002F`output_path` to Evaluator dur","2025-01-23T15:21:26",{"id":217,"version":218,"summary_zh":219,"released_at":220},272351,"v3.3.1","This patch release fixes a small issue with loading private models from Hugging Face using the `token` argument.\r\n\r\nInstall this version with\r\n```\r\n# Training + Inference\r\npip install sentence-transformers[train]==3.3.1\r\n\r\n# Inference only, use one of:\r\npip install sentence-transformers==3.3.1\r\npip install sentence-transformers[onnx-gpu]==3.3.1\r\npip install sentence-transformers[onnx]==3.3.1\r\npip install sentence-transformers[openvino]==3.3.1\r\n```\r\n\r\n## Details\r\nIf you're loading model under this scenario:\r\n* Your model is hosted on Hugging Face.\r\n* Your model is private.\r\n* You haven't set the `HF_TOKEN` environment variable via `huggingface-cli login` or some other approach.\r\n* You're passing the `token` argument to `SentenceTransformer` to load the model.\r\n\r\nThen you may have encountered a crash in v3.3.0. This should be resolved now.\r\n\r\n## All Changes\r\n* [`docs`] Fix the prompt link to the training script by @tomaarsen in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3060\r\n* [Fix] Resolve loading private Transformer model in version 3.3.0 by @pesuchin in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3058\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fcompare\u002Fv3.3.0...v3.3.1","2024-11-18T14:38:20",{"id":222,"version":223,"summary_zh":224,"released_at":225},272352,"v3.3.0","4x speedup for CPU with [OpenVINO int8 static quantization](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fsentence_transformer\u002Fusage\u002Fefficiency.html#quantizing-openvino-models), [training with prompts for a free performance boost](https:\u002F\u002Fsbert.net\u002Fexamples\u002Ftraining\u002Fprompts\u002FREADME.html), convenient evaluation on [NanoBEIR](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fpackage_reference\u002Fsentence_transformer\u002Fevaluation.html#nanobeirevaluator): a subset of a strong Information Retrieval benchmark, PEFT compatibility by easily adding\u002Floading adapters, Transformers v4.46.0 compatibility, and Python 3.8 deprecation.\r\n\r\nInstall this version with:\r\n\r\n```bash\r\n# Training + Inference\r\npip install sentence-transformers[train]==3.3.0\r\n\r\n# Inference only, use one of:\r\npip install sentence-transformers==3.3.0\r\npip install sentence-transformers[onnx-gpu]==3.3.0\r\npip install sentence-transformers[onnx]==3.3.0\r\npip install sentence-transformers[openvino]==3.3.0\r\n```\r\n\r\n## OpenVINO int8 static quantization (https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3025)\r\nWe introduce int8 static quantization using [OpenVINO](https:\u002F\u002Fgithub.com\u002Fopenvinotoolkit\u002Fopenvino), a highly performant solution that outperforms all other current backends by a mile, at a minimal loss in performance. Here are the updated benchmarks:\r\n\r\n\u003Cp align=\"center\">\r\n\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F96f96da5-b65e-4293-8b67-d47430aa5fae\" width=\"50%\" \u002F>\r\n\u003C\u002Fp>\r\n\r\n### Quantizing directly to the Hugging Face Hub\r\n\r\n```python\r\nfrom sentence_transformers import SentenceTransformer, export_static_quantized_openvino_model\r\n\r\n# 1. Load a model with the OpenVINO backend\r\nmodel = SentenceTransformer(\"all-MiniLM-L6-v2\", backend=\"openvino\")\r\n\r\n# 2. Quantize the model to int8, push the model to https:\u002F\u002Fhuggingface.co\u002Fsentence-transformers\u002Fall-MiniLM-L6-v2\r\n# as a pull request:\r\nexport_static_quantized_openvino_model(\r\n    model,\r\n    quantization_config=None,\r\n    model_name_or_path=\"sentence-transformers\u002Fall-MiniLM-L6-v2\",\r\n    push_to_hub=True,\r\n    create_pr=True,\r\n)\r\n```\r\nYou can immediately use the model, even before it's merged, by using the `revision` argument:\r\n```python\r\nfrom sentence_transformers import SentenceTransformer\r\n\r\npull_request_nr = 2 # TODO: Update this to the number of your pull request\r\nmodel = SentenceTransformer(\r\n    \"all-MiniLM-L6-v2\",\r\n    backend=\"openvino\",\r\n    model_kwargs={\"file_name\": \"openvino_model_qint8_quantized.xml\"},\r\n    revision=f\"refs\u002Fpr\u002F{pull_request_nr}\"\r\n)\r\n```\r\nAnd once it's merged:\r\n```python\r\nfrom sentence_transformers import SentenceTransformer\r\n\r\nmodel = SentenceTransformer(\r\n    \"all-MiniLM-L6-v2\",\r\n    backend=\"openvino\",\r\n    model_kwargs={\"file_name\": \"openvino\u002Fopenvino_model_qint8_quantized.xml\"},\r\n)\r\n```\r\n\r\n### Quantizing locally\r\nYou can also quantize a model and save it locally:\r\n```python\r\nfrom sentence_transformers import SentenceTransformer, export_static_quantized_openvino_model\r\nfrom optimum.intel import OVQuantizationConfig\r\n\r\nmodel = SentenceTransformer(\"all-mpnet-base-v2\", backend=\"openvino\")\r\nmodel.save_pretrained(\"path\u002Fto\u002Fall-mpnet-base-v2-local\")\r\nquantization_config = OVQuantizationConfig() # \u003C- You can update settings here\r\nexport_static_quantized_openvino_model(model, quantization_config, \"path\u002Fto\u002Fall-mpnet-base-v2-local\")\r\n```\r\nAnd after quantizing, you can load it like so:\r\n```python\r\nfrom sentence_transformers import SentenceTransformer\r\n\r\nmodel = SentenceTransformer(\r\n    \"path\u002Fto\u002Fall-mpnet-base-v2-local\",\r\n    backend=\"openvino\",\r\n    model_kwargs={\"file_name\": \"openvino_model_qint8_quantized.xml\"},\r\n)\r\n```\r\n\r\nAll [original Sentence Transformer models](https:\u002F\u002Fhuggingface.co\u002Fsentence-transformers\u002Fall-MiniLM-L6-v2) already have these new ` openvino_model_qint8_quantized.xml` files, so you can load them without exporting directly! I would recommend making pull requests for [other models on Hugging Face](https:\u002F\u002Fhuggingface.co\u002Fmodels?library=sentence-transformers) that you'd like to see quantized.\r\n\r\nLearn more about how to Speed up Inference in the documentation: https:\u002F\u002Fsbert.net\u002Fdocs\u002Fsentence_transformer\u002Fusage\u002Fefficiency.html\r\n\r\n## Training with Prompts (https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F2964)\r\nMany modern embedding models are trained with “instructions” or “prompts” following the [INSTRUCTOR paper](https:\u002F\u002Farxiv.org\u002Fabs\u002F2212.09741). These prompts are strings, prefixed to each text to be embedded, allowing the model to distinguish between different types of text.\r\n\r\nFor example, the [mixedbread-ai\u002Fmxbai-embed-large-v1](https:\u002F\u002Fhuggingface.co\u002Fmixedbread-ai\u002Fmxbai-embed-large-v1) model was trained with Represent this sentence for searching relevant passages: as the prompt for all queries. This prompt is stored in the [model configuration](https:\u002F\u002Fhuggingface.co\u002Fmixedbread-ai\u002Fmxbai-embed-large-v1\u002Fblob\u002Fmain\u002Fconfig_sentence_transformers.json) under the prompt name \"query\", so users can specify that prompt_name in model.encode:\r\n\r\n```python\r\nfrom sentence_transformers import SentenceTransformer\r\n\r\nmodel = S","2024-11-11T12:02:19",{"id":227,"version":228,"summary_zh":229,"released_at":230},272353,"v3.2.1","This patch release fixes some small bugs, such as related to loading CLIP models, automatic model card generation issues, and ensuring compatibility with third party libraries.\r\n\r\nInstall this version with\r\n```bash\r\n# Training + Inference\r\npip install sentence-transformers[train]==3.2.1\r\n\r\n# Inference only, use one of:\r\npip install sentence-transformers==3.2.1\r\npip install sentence-transformers[onnx-gpu]==3.2.1\r\npip install sentence-transformers[onnx]==3.2.1\r\npip install sentence-transformers[openvino]==3.2.1\r\n```\r\n\r\n## Fixing Loading non-Transformer models\r\nIn v3.2.0, a non-[Transformer](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fpackage_reference\u002Fsentence_transformer\u002Fmodels.html#sentence_transformers.models.Transformer) based model (e.g. CLIP) would not load correctly if the model was saved in the root of the model repository\u002Fdirectory. This has been resolved in #3007.\r\n\r\n## Throw error if `StaticEmbedding`-based model is finetuned with incompatible losses\r\nThe following losses are not compatible with `StaticEmbedding`-based models:\r\n* CachedGISTEmbedLoss\r\n* CachedMultipleNegativesRankingLoss\r\n* CachedMultipleNegativesSymmetricRankingLoss\r\n* DenoisingAutoEncoderLoss\r\n* GISTEmbedLoss\r\n\r\nAn error is now thrown when one of these are used with a `StaticEmbedding`-based model. I recommend using MultipleNegativesRankingLoss to finetune these models, e.g. as in https:\u002F\u002Fhuggingface.co\u002Ftomaarsen\u002Fstatic-bert-uncased-gooaq.\r\nNote: to get good performance, you must use much higher learning rates than otherwise. In my experiments, 2e-1 worked well.\r\n\r\n## Patch ONNX model when the model uses `output_hidden_states`\r\n\r\nFor example, this script used to fail, but passes now:\r\n```python\r\nfrom sentence_transformers import SentenceTransformer\r\n\r\nmodel = SentenceTransformer(\r\n    \"distiluse-base-multilingual-cased\",\r\n    backend=\"onnx\",\r\n    model_kwargs={\"provider\": \"CPUExecutionProvider\"},\r\n)\r\n\r\nsentences = [\"This is an example sentence\", \"Each sentence is converted\"]\r\nembeddings = model.encode(sentences)\r\nprint(embeddings.shape)\r\n```\r\n\r\n## All changes\r\n* Bump optimum version by @echarlaix in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F2984\r\n* [`docs`] Update the training snippets for some losses that should use the v3 Trainer by @tomaarsen in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F2987\r\n* [`enh`] Throw error if StaticEmbedding-based model is trained with incompatible loss by @tomaarsen in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F2990\r\n* [`fix`] Fix semantic_search_usearch with 'binary' by @tomaarsen in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F2989\r\n* [enh] Add support for large_string in model card create by @yaohwang in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F2999\r\n* [`model cards`] Prevent crash on generating widgets if dataset column is empty by @tomaarsen in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F2997\r\n* [fix] Added model2vec import compatible with current and newer version by @Pringled in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F2992\r\n* Fix cache_dir issue with loading CLIPModel by @BoPeng in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3007\r\n* [`warn`] Throw a warning if compute_metrics is set, as it's not used by @tomaarsen in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3002\r\n* [`fix`] Prevent IndexError if output_hidden_states & ONNX by @tomaarsen in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3008\r\n\r\n## New Contributors\r\n* @echarlaix made their first contribution in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F2984\r\n* @yaohwang made their first contribution in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F2999\r\n* @Pringled made their first contribution in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F2992\r\n* @BoPeng made their first contribution in https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fpull\u002F3007\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002FUKPLab\u002Fsentence-transformers\u002Fcompare\u002Fv3.2.0...v3.2.1","2024-10-21T12:19:51",{"id":232,"version":233,"summary_zh":234,"released_at":235},272354,"v3.2.0","This release introduces 2 new efficient computing backends for SentenceTransformer models: [ONNX and OpenVINO + optimization & quantization, allowing for speedups up to 2x-3x](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fsentence_transformer\u002Fusage\u002Fefficiency.html); static embeddings via [Model2Vec](https:\u002F\u002Fgithub.com\u002FMinishLab\u002Fmodel2vec) allowing for lightning-fast models (i.e., 50x-500x speedups) at a ~10%-20% performance cost; and various small improvements and fixes.\r\n\r\nInstall this version with\r\n```bash\r\n# Training + Inference\r\npip install sentence-transformers[train]==3.2.0\r\n\r\n# Inference only, use one of:\r\npip install sentence-transformers==3.2.0\r\npip install sentence-transformers[onnx-gpu]==3.2.0\r\npip install sentence-transformers[onnx]==3.2.0\r\npip install sentence-transformers[openvino]==3.2.0\r\n```\r\n\r\n## Faster ONNX and OpenVINO Backends for SentenceTransformer (#2712)\r\nIntroducing a new `backend` keyword argument to the `SentenceTransformer` initialization, allowing values of `\"torch\"` (default), `\"onnx\"`, and `\"openvino\"`.\r\nThese come with new installations:\r\n```bash\r\npip install sentence-transformers[onnx-gpu]\r\n# or ONNX for CPU only:\r\npip install sentence-transformers[onnx]\r\n# or\r\npip install sentence-transformers[openvino]\r\n```\r\nIt's as simple as:\r\n```python\r\nfrom sentence_transformers import SentenceTransformer\r\n\r\nmodel = SentenceTransformer(\"all-MiniLM-L6-v2\", backend=\"onnx\")\r\n\r\nsentences = [\"This is an example sentence\", \"Each sentence is converted\"]\r\nembeddings = model.encode(sentences)\r\n```\r\nIf you specify a `backend` and your model repository or directory contains an ONNX\u002FOpenVINO model file, it will automatically be used! And if your model repository or directory doesn't have one already, an ONNX\u002FOpenVINO model will be automatically exported. Just remember to `model.push_to_hub` or `model.save_pretrained` into the same model repository or directory to avoid having to re-export the model every time.\r\n\r\nAll keyword arguments passed via `model_kwargs` will be passed on to [`ORTModel.from_pretrained`](https:\u002F\u002Fhuggingface.co\u002Fdocs\u002Foptimum\u002Fmain\u002Fen\u002Fonnxruntime\u002Fpackage_reference\u002Fmodeling_ort#optimum.onnxruntime.ORTModel.from_pretrained) or [`OVBaseModel.from_pretrained`](https:\u002F\u002Fhuggingface.co\u002Fdocs\u002Foptimum\u002Fintel\u002Fopenvino\u002Freference#optimum.intel.openvino.modeling_base.OVBaseModel.from_pretrained). The most useful arguments are:\r\n\r\n* `provider`: (Only if `backend=\"onnx\"`) ONNX Runtime provider to use for loading the model, e.g. `\"CPUExecutionProvider\"` . See https:\u002F\u002Fonnxruntime.ai\u002Fdocs\u002Fexecution-providers\u002F for possible providers. If not specified, the strongest provider (E.g. `\"CUDAExecutionProvider\"`) will be used.\r\n* `file_name`: The name of the ONNX file to load. If not specified, will default to \"model.onnx\" or otherwise \"onnx\u002Fmodel.onnx\" for ONNX, and \"openvino_model.xml\" and \"openvino\u002Fopenvino_model.xml\" for OpenVINO. This argument is useful for specifying optimized or quantized models.\r\n* `export`: A boolean flag specifying whether the model will be exported. If not provided, export will be set to True if the model repository or directory does not already contain an ONNX or OpenVINO model.\r\n\r\nFor example:\r\n```python\r\nfrom sentence_transformers import SentenceTransformer\r\n\r\nmodel = SentenceTransformer(\r\n    \"all-MiniLM-L6-v2\",\r\n\tbackend=\"onnx\",\r\n\tmodel_kwargs={\r\n\t\t\"file_name\": \"model_O3.onnx\",\r\n\t\t\"provider\": \"CPUExecutionProvider\",\r\n\t}\r\n)\r\n\r\nsentences = [\"This is an example sentence\", \"Each sentence is converted\"]\r\nembeddings = model.encode(sentences)\r\n```\r\n\r\n### Benchmarks\r\nWe ran [benchmarks](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fsentence_transformer\u002Fusage\u002Fefficiency.html#benchmark) for CPU and GPU, averaging findings across 4 models of various sizes, 3 datasets, and numerous batch sizes. Here are the findings:\r\n\r\n\u003Cp float=\"left\">\r\n  \u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002Fd3f423ff-ad4e-4c91-9beb-8217a062a61d\" width=\"45%\" \u002F>\r\n  \u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F3b9ae402-1127-4152-a925-70c3d626b27d\" width=\"45%\" \u002F> \r\n\u003C\u002Fp>\r\n\r\nThese findings resulted in these recommendations:\r\n![image](https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F0ace85c5-622b-471a-8e20-9331a1ae12c7)\r\n\r\nFor GPU, you can expect **2x speedup with fp16 at no cost**, and for CPU you can expect **~2.5x speedup at a cost of 0.4% accuracy**.\r\n\r\n\u003Cdetails>\u003Csummary>ONNX Optimization and Quantization\u003C\u002Fsummary>\r\n\r\nIn addition to exporting default ONNX and OpenVINO models, we also introduce 2 helper methods for optimizing and quantizing ONNX models:\r\n\r\n### Optimization\r\n\r\n[`export_optimized_onnx_model`](https:\u002F\u002Fsbert.net\u002Fdocs\u002Fpackage_reference\u002Futil.html#sentence_transformers.backend.export_optimized_onnx_model): This function uses Optimum to implement several optimizations in the ONNX model, ranging from basic optimizations to approximations and mixed precision. Read about the 4 default options [here](https:\u002F\u002Fhuggingface.co\u002Fdocs\u002Foptimum\u002Fmain\u002Fen\u002Fonnxruntime\u002Fusage_guides\u002Foptimization#optimizing-a-model-during-the-onnx-export). This function accepts:","2024-10-10T17:59:24"]