Youtu-Embedding:

基于协同-差异化学习的先进统一文本表示模型

🔖 English Version • 🤗 模型下载 • 🚀 快速开始推理 • 🛠️ 如何训练

🎯 简介

Youtu-Embedding 是一款由腾讯优图实验室研发的业界领先的通用文本表示模型。它在信息检索（IR）、语义相似度（STS）、聚类、重排序和分类等一系列广泛的自然语言处理任务上，均展现出卓越的性能。

Youtu-Embedding核心优势包括：

• 🏆 顶尖性能: 在权威的中文文本嵌入评测基准 CMTEB 上，以 77.58 的高分荣登榜首（截至2025年09月），证明了其强大的表征能力。

• 🧠 精密的三阶段训练: 通过“LLM基础预训练 → 弱监督对齐 → 协同-判别式微调”的训练流程，系统性地将大模型的广博知识转化为专用于嵌入任务的判别能力。

• ⭐ 创新的微调框架: 设计了统一数据格式、任务差异化损失函数和动态单任务采样机制，解决了多任务学习中的“负迁移”难题，实现了多任务的稳定协同训练。（该框架在多种基础编码器上进行了验证，保障其通用性和有效性）

• 🛠️ 精细化的数据工程: 结合了基于LLM的高质量数据合成技术与高效的难负例挖掘策略，为模型训练提供了最坚实的数据基础。

我们在此开源模型权重、推理代码及完整的训练框架，希望能助力社区开发者创造更大的价值！

## 🤗 模型下载

我们已在 Hugging Face 上发布了首个模型版本。这是一个拥有20亿（2B）参数的通用语义表示模型。

模型	参数量	维度	序列长度	Hugging Face
Youtu-Embedding-V1	2B	2048	8K	Model

🚀 快速开始推理

您可以通过两种方式来生成文本嵌入（Embeddings）：便捷的官方 API 调用，或在本地环境中完全控制地运行模型。

选项 1：☁️ 使用官方 API

📦 安装 SDK

pip install --upgrade tencentcloud-sdk-python

• API 指南：有关身份验证和终端节点的详细信息，请参阅 腾讯云 API 文档。
• SDK 参考：有关 SDK 的更多信息，请参阅 SDK 安装指南。

⚙️ 使用方法

• 请参见 usage/tencent_cloud_api.py 中的脚本。

选项 2：💻 本地化自托管推理

在您自己的机器上运行模型可以赋予您完全的控制权，非常适合离线使用、自定义或数据隐私优先的场景。下面提供一套可直接执行的步骤，并配合本仓库内的预置测试脚本。

1）快速开始（仓库 + 环境）

# 克隆仓库
git clone https://github.com/TencentCloudADP/youtu-embedding.git
cd youtu-embedding

# 创建并激活虚拟环境
python -m venv youtu-env
source youtu-env/bin/activate  # Windows: youtu-env\Scripts\activate

# 安装依赖
pip install -U pip
pip install "transformers==4.51.3" torch numpy scipy scikit-learn huggingface_hub

2）获取模型权重（二选一）

• 方式 A：使用 Hugging Face 命令行下载到本地目录

huggingface-cli download tencent/Youtu-Embedding --local-dir ./youtu-model

• 方式 B：直接克隆模型仓库

git clone https://huggingface.co/tencent/Youtu-Embedding ./Youtu-Embedding

3）运行预置测试脚本（推荐）

根据你当前的运行环境选择脚本。本仓库已内置以下脚本：

• CUDA 环境：

python test_transformers_online_cuda.py

• macOS（Apple Silicon 的 MPS 或自动回退 CPU）：

python test_transformers_online_macos.py

• 仅使用本地模型（例如 ./Youtu-Embedding）：

python test_transformers_local.py

这些脚本会：加载模型、对示例查询与段落进行编码，并打印相似度分数（按相关性排序，最佳匹配一目了然）。

示例输出（Sample Output）

nv/bin/python /Users/pro/Desktop/youtu-embedding/test_transformers_local.py
Loading checkpoint shards: 100%|███████████████████████████████| 2/2 [00:00<00:00, 28.64it/s]
Model loaded: ./Youtu-Embedding
Device: mps

================================================================================
🔍 Query: What's the weather like?
================================================================================

🥇 BEST MATCH
   Score: 0.4465 | ⚡ Moderately Relevant
   Visual: [█████████████░░░░░░░░░░░░░░░░░] 44.7%
   Content: "The weather is lovely today."

🥈 2nd BEST
   Score: 0.3124 | ⚡ Moderately Relevant
   Visual: [█████████░░░░░░░░░░░░░░░░░░░░░] 31.2%
   Content: "It's so sunny outside!"

🥉 3rd BEST
   Score: 0.0688 | ❌ Not Relevant
   Visual: [██░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 6.9%
   Content: "Would you want to play a game?"

#4
   Score: 0.0304 | ❌ Not Relevant
   Visual: [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 3.0%
   Content: "He drove to the stadium."

================================================================================

Raw scores: [[0.4465198516845703, 0.31240472197532654, 0.03040437400341034, 0.06884326785802841]]

4）使用自定义 LLMEmbeddingModel 类

如果需要更专业的实现或查看我们的直接封装，你可以使用 LLMEmbeddingModel 类。 * 完整示例脚本：usage/infer_llm_embedding.py

5）使用 sentence-transformers

如果你偏好 sentence-transformers，可以通过模型 ID 或本地目录加载相同模型。

📦 安装

pip install sentence-transformers==5.1.0

⚙️ 使用方法

from sentence_transformers import SentenceTransformer

model = SentenceTransformer("model_id")
queries = ["天气怎么样？"]
passages = [
    '今天天气很好。',
    '外面阳光明媚！',
    '他开车去了体育场。'
]
queries_embeddings = model.encode_query(queries)
passages_embeddings = model.encode_document(passages)

similarities = model.similarity(queries_embeddings, passages_embeddings)
print(similarities)

6）使用 LangChain 🦜

如果你希望在检索/问答链路中使用本模型作为嵌入器，可以参考本仓库提供的示例脚本。

📦 安装

pip install langchain==0.3.27 langchain-community==0.3.29 langchain-huggingface==0.3.1 sentence-transformers==5.1.0 faiss-cpu==1.11.0

📄 示例脚本 - 请参阅：usage/langchain_embedding.py

7）使用 LlamaIndex 🦙

如果你使用 LlamaIndex 进行文档索引与检索，也可以集成本模型作为嵌入器。

📦 安装

pip install llama-index==0.14.2 llama-index-embeddings-huggingface==0.6.1 sentence-transformers==5.1.0 llama-index-vector-stores-faiss==0.5.1

📄 示例脚本 - 请参阅：usage/llamaindex_embedding.py

💡 微调训练框架

我们提供的协同-判别式微调训练框架，旨在克服不同文本嵌入任务联合优化的挑战。通过系统地解耦任务实现了统一表示学习。

🌐 1. 统一且可扩展的数据格式

我们设计的统一数据结构能够无缝处理来自 IR、STS、分类、重排序等任务的异构数据，为未来接入新任务提供了极高的可扩展性。

🎯 2. 任务差异化的损失函数

我们摒弃了“一刀切”的损失函数，为不同任务设计了专属的优化目标。

• 对于 IR (信息检索) 类任务，它采用了一个强大的 InfoNCE 对比损失，支持多正例和困难负例，并结合跨设备负采样以实现更清晰的区分度。
• 对于 STS (语义相似度) 类任务，它超越了简单的对比学习方法，转而使用一套排序感知目标来直接优化排序一致性，包括皮尔逊损失、归一化排序KL散度损失。

🔄 3. 动态单任务采样

为避免混合任务批次带来的梯度干扰，我们实现了定制化的动态采样器。它确保在单次训练迭代中，所有 GPU 处理的都是同一个数据集的不重叠分片，从而为模型提供纯粹、稳定的梯度信号。

🛠️ 如何训练

我们的训练框架的代码位于 training/ 目录下。

1. 安装

下载项目并安装依赖：

git clone https://github.com/TencentCloudADP/youtu-embedding.git
cd training/CoDiEmb
pip install -r requirements.txt

2. 训练

cd scripts 
bash train_youtuemb.sh

3. 评估

重现结果可以在evaluation/部分找到。

📊 CMTEB

模型	参数量	平均分(任务)	平均分(类型)	分类	聚类	句子对分类	重排序	检索	语义相似度
bge-multilingual-gemma2	9B	67.64	68.52	75.31	59.30	79.30	68.28	73.73	55.19
ritrieve_zh_v1	326M	72.71	73.85	76.88	66.50	85.98	72.86	76.97	63.92
Qwen3-Embedding-4B	4B	72.27	73.51	75.46	77.89	83.34	66.05	77.03	61.26
Qwen3-Embedding-8B	8B	73.84	75.00	76.97	80.08	84.23	66.99	78.21	63.53
Conan-embedding-v2	1.4B	74.24	75.99	76.47	68.84	92.44	74.41	78.31	65.48
Seed1.6-embedding	-	75.63	76.68	77.98	73.11	88.71	71.65	79.69	68.94
QZhou-Embedding	7B	76.99	78.58	79.99	70.91	95.07	74.85	78.80	71.89
Youtu-Embedding-V1	2B	77.58	78.86	78.65	84.27	86.12	75.10	80.21	68.82

注意: 各模型分数来自2025年9月28日记录的MTEB榜单。

🎉 引用

如果您在您的研究中使用了我们的工作，请考虑引用我们的论文：

```bibtex @misc{zhang2025codiemb, title={CoDiEmb: A Collaborative yet Distinct Framework for Unified Representation Learning in Information Retrieval and Semantic Textual Similarity}, author={Zhang, Bowen and Song, Zixin and Chen, Chunquan and Zhang, Qian-Wen and Yin, Di and Sun, Xing}, year={2025}, eprint={2508.11442}, archivePrefix={arXiv}, url={https://arxiv.org/abs/2508.11442}, }