Skip to content

Latest commit

 

History

History
281 lines (193 loc) · 12 KB

README-CN.md

File metadata and controls

281 lines (193 loc) · 12 KB

优图 Logo Youtu-Embedding:
基于协同-差异化学习的先进统一文本表示模型

License: MIT Paper GitHub Huggingface WeChat Community Discord Community

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

🎯 简介

Youtu-RAG Logo

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

⚙️ 使用方法

选项 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 类。

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榜单。

🎉 引用

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

@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},
}