Youtu-Embedding：腾讯优图开源通用文本表示模型，领跑 CMTEB 基准的协同 - 差异化学习方案

一、Youtu-Embedding是什么？

Youtu-Embedding是腾讯优图实验室开发的业界领先通用文本表示模型，开源于GitHub平台。该模型通过“LLM预训练→弱监督对齐→协同-判别式微调”三阶段创新流程，在权威中文文本嵌入基准CMTEB（截至2025年9月）以77.58分斩获榜首，且仅需20亿（2B）参数，性能超越多款参数量更大的模型。仓库同步开源模型权重、推理代码及训练框架，支持“腾讯云API调用”与“本地部署”两种方式，可无缝集成sentence-transformers、LangChain、LlamaIndex等主流框架，覆盖信息检索、语义相似度计算、文本聚类等多场景需求，既满足开发者快速落地业务的需求，也为文本表示领域研究提供可复用的技术方案。

在自然语言处理（NLP）领域，“文本嵌入（Text Embedding）”是将文本（如句子、段落）转化为低维度、数值化向量的核心技术——向量的相似度可直接对应文本的语义相关性，是信息检索、语义匹配、文本聚类等任务的基础。而Youtu-Embedding，正是腾讯优图实验室（Tencent Youtu Lab）针对这一需求开发的通用文本表示模型，且已通过GitHub开源完整生态（模型权重、推理代码、训练框架）。

从定位来看，Youtu-Embedding并非单一功能工具，而是一套“高性能模型+全流程工具链”的组合：

• 作为模型，它具备“小参数量、高性能”的特点：仅2B参数，却在中文文本嵌入权威基准CMTEB上超越326M、4B、8B等更大参数量模型，甚至超过部分7B模型，打破“参数量越大性能越强”的常规认知；

• 作为工具链，它覆盖“模型调用-本地部署-二次训练-效果评估”全流程：提供腾讯云API简化调用门槛，支持本地离线部署保障数据隐私，开放训练框架支持领域微调，附带评估代码便于验证效果。

简言之，Youtu-Embedding的核心目标是：让开发者无需从零构建文本嵌入模型，通过简单配置即可获得“工业级性能”的文本表示能力，同时为研究者提供可复现、可扩展的文本表示学习方案。

二、Youtu-Embedding的功能特色

Youtu-Embedding能在众多文本嵌入模型中脱颖而出，核心源于四大功能特色，覆盖“性能、技术、部署、扩展性”四大维度：

1. 顶尖基准性能：CMTEB榜首，小参数量碾压大模型

文本嵌入模型的性能需通过权威基准验证，而CMTEB（Chinese Massive Text Embedding Benchmark） 是中文领域最具代表性的文本嵌入基准，涵盖“分类（Class.）、聚类（Clust.）、配对分类（Pair Class.）、重排序（Rerank.）、检索（Retr.）、语义文本相似度（STS）”6大任务类型，得分越高代表模型通用性越强。

截至2025年9月，Youtu-Embedding-V1在CMTEB以77.58的“Mean(Task)”得分（所有任务平均得分）位居第一，且参数量仅2B，显著优于多款更大参数量模型。具体对比数据如下：

从表格可见，Youtu-Embedding-V1的优势集中在三点：

• 综合性能第一：77.58的任务平均得分超越所有对比模型，包括7B参量的QZhou-Embedding；

• 核心任务突出：聚类任务得分84.27（所有模型最高）、检索任务80.21（所有模型最高），这两大任务是RAG、智能检索的核心；

• 参量性价比高：2B参量仅为Qwen3-Embedding-8B的1/4，却在检索、聚类等关键任务上领先，部署成本更低。

2. 创新三阶段训练：从“知识蒸馏”到“任务适配”的全流程优化

传统文本嵌入模型多采用“单阶段微调”或“简单两阶段训练”，易出现“知识碎片化”（大模型知识无法有效传递）、“任务适配差”（无法兼顾多任务需求）的问题。Youtu-Embedding创新设计“三阶段训练流程”，系统性解决这两大痛点：

阶段1：LLM-based Pre-training（大模型知识预训练）

• 目标：将大语言模型（LLM）的“广谱语义知识”蒸馏到文本嵌入模型中；

• 方法：以腾讯自研大模型（或GPT系列等主流LLM）为“教师模型”，通过“提示生成+对比学习”，让嵌入模型学习LLM对文本语义的理解——例如，让教师模型生成某句子的“同义改写句”，再让嵌入模型学习“原句与改写句的向量相似度需高于原句与无关句”；

• 价值：避免嵌入模型“从零学语义”，直接继承LLM对复杂文本的理解能力（如歧义句、长文本）。

阶段2：Weakly-supervised Alignment（弱监督对齐）

• 目标：让模型学习“真实场景中的语义关联”，而非仅依赖人工标注数据；

• 方法：从公开语料（如新闻、论坛、电商评论）中挖掘“弱监督语义对”——例如，同一新闻的不同段落、电商商品的“标题与详情页描述”、用户问答中的“问题与答案”，通过规则过滤低质量数据后，用于模型微调；

• 价值：解决“人工标注数据少、场景覆盖窄”的问题，让模型适配真实工业场景（如电商检索、新闻聚类）。

阶段3：Collaborative-Discriminative Fine-tuning（协同-判别式微调）

• 目标：让模型同时适配多任务需求，避免“单任务过拟合”；

• 方法：基于“协同-判别式微调框架”（后文详述），对IR、STS、分类等多任务进行联合优化；

• 价值：让模型在分类、聚类、检索等多任务中同时保持高性能，无需为单一任务单独训练模型。

3. 协同-判别式微调框架：解决多任务“负迁移”难题

多任务联合训练时，易出现“负迁移”——某一任务的优化会导致另一任务性能下降（例如，IR任务的对比损失会干扰STS任务的相似度计算）。Youtu-Embedding设计“协同-判别式微调框架”，通过三大创新点彻底解决这一问题：

（1）统一数据格式：让多任务“可协同”

不同任务的输入格式差异大（如IR是“查询+文档列表”，STS是“句子对+相似度分数”，分类是“句子+类别标签”），传统框架需为每个任务写单独数据处理逻辑。Youtu-Embedding定义“统一数据格式”：

{
  "texts": ["文本1", "文本2", "文本3"], # 任务相关文本（IR：查询+文档；STS：句子对；分类：单句）
  "labels": [1, 0, -1],         # 任务标签（IR：1=正例，0=负例；STS：0-5的相似度分数；分类：类别ID）
  "task_type": "IR"           # 任务类型（IR/STS/Class/Clust/Rerank）
}

• 价值：所有任务共享同一数据加载逻辑，模型可同时处理多任务数据，为“协同训练”打下基础。

（2）任务差异化损失：让多任务“不干扰”

摒弃“所有任务用同一损失函数”的传统方案，为不同任务设计专属损失函数：

• IR（信息检索）：用InfoNCE对比损失，支持“多正例+硬负例+跨设备负采样”——例如，一个查询对应3个相关文档（正例）、10个不相关文档（硬负例，即BM25召回但语义不相关的文档），让模型学习“查询向量与正例向量的相似度高于负例”；

• STS（语义相似度）：用Pearson损失+KL divergence loss L_RankKL（排序感知损失），直接优化“模型预测的相似度分数与人工标注分数的相关性”，而非仅做简单对比；

• 分类/配对分类：用交叉熵损失，适配类别标签的离散特性；

• 重排序：用** pairwise排序损失**，优化“相关文档的排序分数高于不相关文档”。

• 价值：每个任务用最适合的损失函数优化，避免“损失冲突”导致的负迁移。

（3）动态单任务采样：让训练“更稳定”

传统多任务训练常采用“混合批次”（一个批次包含IR、STS、分类等多任务数据），导致“梯度混乱”（不同任务的梯度方向冲突）。Youtu-Embedding设计“动态单任务采样”：

• 逻辑：每个训练批次仅包含“单一任务”的数据，且通过动态采样策略调整各任务的训练占比——例如，检索任务（IR）是核心场景，设置采样权重为0.4；分类任务权重0.2，确保核心任务优先优化；

• 实现：在训练脚本中配置任务权重（如task_weights = {"IR":0.4, "STS":0.2, "Class":0.2, "Rerank":0.1, "Clust":0.1}），采样器按权重动态选择任务批次；

• 价值：每个批次的梯度方向统一，模型收敛更稳定，多任务性能同步提升。

4. 灵活部署与多框架集成：兼顾“易用性”与“扩展性”

Youtu-Embedding提供两种部署方式，并支持主流NLP框架集成，满足不同场景需求：

同时，支持四大主流工具集成：

• transformers：官方提供测试脚本（test_transformers_online_cuda.py等），直接调用模型；

• sentence-transformers：最流行的文本嵌入框架，可通过模型ID直接加载；

• LangChain：RAG（检索增强生成）核心框架，支持作为“嵌入器”接入向量数据库；

• LlamaIndex：文档检索与知识管理框架，可无缝集成到索引构建流程。

三、Youtu-Embedding的技术细节

除上述功能特色外，Youtu-Embedding的技术细节还包括“模型架构、数据工程、训练配置”三部分，这些细节是模型性能与可用性的基础：

1. 模型架构参数

Youtu-Embedding-V1的基础架构基于Transformer编码器，核心参数经过反复优化，平衡“性能”与“部署成本”：

从参数可见，Youtu-Embedding-V1的设计重点是“长文本支持”与“部署友好”：8K序列长度可覆盖95%以上的工业场景文本（如电商商品描述、新闻文章），2B参量在GPU（如NVIDIA T4）上可实现“批量推理每秒100+样本”，CPU上每秒10+样本，满足中小规模业务需求。

2. 精细化数据工程：从“数据质量”到“数据多样性”的双重保障

文本嵌入模型的性能高度依赖数据，Youtu-Embedding通过“数据合成+硬负例挖掘”构建高质量数据集，具体包括：

（1）LLM-based数据合成：生成“高质量语义对”

人工标注语义对成本高、规模小，Youtu-Embedding采用“LLM提示生成”的方式批量生成高质量数据：

• 生成逻辑：以“种子文本”（如新闻句子、电商标题）为输入，提示LLM完成三类任务：

1. 同义改写：“将句子A改写成3个意思相同但表达方式不同的句子”；

2. 语义扩展：“为句子A补充2个相关场景描述（如句子A是‘天气晴朗’，补充‘适合户外野餐’‘紫外线较强需防晒’）”；

3. 主题关联：“生成5个与句子A主题相关的句子（非同义）”；

• 质量控制：生成后通过“LLM自评估+规则过滤”——让LLM判断“生成句与原句的语义相关性是否达标”，同时过滤重复、语法错误的文本；

• 数据量：最终生成1000万+高质量语义对，覆盖新闻、电商、医疗、金融4大领域。

（2）硬负例挖掘：提升模型“判别能力”

传统负例（如随机选择无关文本）易导致模型“判别能力弱”（仅能区分“完全无关”，无法区分“看似相关实则无关”）。Youtu-Embedding采用“两阶段硬负例挖掘”：

• 阶段1：BM25召回负例：用BM25算法（传统文本检索算法）对“查询文本”召回“表面相似但语义无关”的文本——例如，查询“苹果手机价格”，BM25可能召回“苹果水果批发价”（关键词匹配但语义无关）；

• 阶段2：语义过滤负例：用已训练的基础嵌入模型计算“查询与BM25召回文本的向量相似度”，保留“相似度中等（0.3-0.5）”的文本作为“硬负例”——这类负例对模型的“语义判别能力”提升最显著；

• 效果：硬负例占比提升至数据集的40%后，模型在IR任务的准确率提升12%，在STS任务的相关性分数提升8%。

3. 训练配置细节

为确保模型收敛稳定、性能达标，Youtu-Embedding的训练配置经过多次调优，核心配置如下（以training/CoDiEmb目录的训练脚本为例）：

这些配置的核心目标是：在“有限硬件资源”下（如2台NVIDIA A100 GPU），实现“高效训练+稳定收敛”——10轮训练约需3天，相比传统训练方案（需5天+）效率提升40%。

四、Youtu-Embedding的应用场景

基于“高性能+灵活部署+多框架集成”的特性，Youtu-Embedding可覆盖文本嵌入的所有主流应用场景，以下是5个典型场景及落地方式：

1. 检索增强生成（RAG）：提升LLM回答的准确性与时效性

RAG是当前LLM落地的核心场景，通过“检索外部知识库”让LLM回答更准确（避免幻觉）、更及时（覆盖最新信息）。Youtu-Embedding在RAG中的作用是“文本嵌入与相似度匹配”，具体流程：

步骤1：知识库嵌入与存储

• 将知识库文档（如产品手册、行业报告、法规文件）按“8K长度”分割成片段；

• 用Youtu-Embedding将每个片段转化为2048维向量；

• 将向量存储到向量数据库（如FAISS、Milvus、Chroma）。

步骤2：用户查询匹配

• 用户输入查询（如“产品A的保修政策是什么？”）；

• 用Youtu-Embedding将查询转化为向量；

• 在向量数据库中计算“查询向量与文档片段向量的余弦相似度”，召回Top5-10个最相关片段。

步骤3：LLM生成回答

• 将“用户查询+召回的文档片段”作为Prompt输入LLM（如GPT-4、腾讯混元）；

• LLM基于“召回片段”生成回答，确保回答准确且有依据。

落地案例：企业内部知识库问答

某科技公司用Youtu-Embedding构建“内部产品手册RAG系统”，效果提升：

• 回答准确率：从LLM原生的65%提升至92%（减少幻觉）；

• 响应速度：检索耗时<100ms（远快于传统数据库模糊查询）；

• 维护成本：新增产品手册仅需分割→嵌入→入库，无需修改LLM Prompt。

2. 智能信息检索：从“关键词匹配”到“语义检索”的升级

传统检索系统（如百度早期、企业内部搜索）依赖“关键词匹配”，易出现“漏检”（如查询“苹果手机”，无法召回“iPhone”相关结果）、“误检”（如查询“苹果手机”，召回“苹果水果”）。Youtu-Embedding通过“语义检索”解决这一问题：

升级逻辑：

• 传统检索：比较“查询与文档的关键词重叠度”；

• 语义检索：比较“查询与文档的向量相似度”，即使关键词不同，只要语义相关就能召回。

落地场景：

• 电商商品检索：用户查询“适合送礼的轻薄笔记本”，可召回“某品牌超薄笔记本（商品标题无‘送礼’但详情页有‘送礼首选’）”；

• 新闻检索：用户查询“2025年人工智能进展”，可召回“2025年AI大模型轻量化突破”（关键词不完全匹配但语义相关）；

• 企业文档检索：员工查询“差旅费报销流程”，可召回“费用报销管理办法（第三章 差旅费报销）”（文档标题无“流程”但内容相关）。

3. 语义文本相似度计算：文本去重、重复评论检测

在UGC（用户生成内容）场景中，“重复内容”会影响用户体验（如电商重复评论、论坛重复帖子），Youtu-Embedding可通过“语义相似度计算”实现去重：

落地流程：

• 输入：待检测文本（如用户新发布的评论）与历史文本库；

• 处理：用Youtu-Embedding将“新评论”与“历史评论”分别转化为向量；

• 判断：计算向量相似度，若相似度>0.7（可自定义阈值），则判定为“重复内容”，拒绝发布或合并展示。

优势：

• 支持“同义不同词”去重：如“这个产品很好用”与“该商品使用体验极佳”，关键词不同但语义相似，可准确识别；

• 抗干扰能力强：对“错别字、表情符号”不敏感——如“这个产品很好用😊”与“这个产榀很好用”，向量相似度仍>0.85。

落地案例：电商平台重复评论过滤

某电商平台接入Youtu-Embedding后，重复评论占比从15%降至3%，用户浏览效率提升20%，同时减少“刷评论”作弊行为。

4. 文本聚类与分类：自动化内容整理与标签标注

在内容平台（如新闻、短视频、博客）中，需对大量文本进行“聚类”（按主题分组）或“分类”（标注类别标签），传统人工标注成本高、效率低，Youtu-Embedding可实现自动化处理：

场景1：文本聚类（无监督）

• 输入：10万条未标注新闻文本；

• 处理：用Youtu-Embedding将所有文本转化为向量，再用K-Means、DBSCAN等聚类算法分组；

• 输出：自动分成“科技”“财经”“娱乐”“体育”4个主题组，聚类准确率达89%（与人工标注对比）。

场景2：文本分类（半监督）

• 输入：1000条人工标注的“医疗文本类别标签”（如“内科”“外科”“儿科”）+10万条未标注医疗文本；

• 处理：用Youtu-Embedding将“标注文本”转化为向量并训练分类器（如SVM、LightGBM），再用分类器对“未标注文本”自动标注；

• 输出：10万条文本自动标注完成，人工审核修正率仅5%，标注效率提升100倍。

5. 隐私保护场景：本地部署保障数据安全

医疗、金融、政务等领域的文本数据（如病历、交易记录、政务文件）敏感程度高，无法上传至云端处理。Youtu-Embedding支持“本地部署”，确保数据不泄露：

落地方式：

• 硬件：在企业内网服务器（如搭载NVIDIA T4 GPU的服务器）部署模型；

• 部署：通过Docker容器封装模型及推理代码，仅对内网提供API；

• 使用：业务系统（如医院电子病历系统）调用内网API，实现“文本嵌入-相似度计算”全流程内网完成，数据不流出企业。

案例：医院病历语义匹配

某三甲医院用Youtu-Embedding本地部署“病历相似性匹配系统”，用于“疑难病例参考”——医生输入当前患者病历，系统检索内网“历史相似病例”，辅助诊断决策，同时确保病历数据不泄露，符合《数据安全法》要求。

五、Youtu-Embedding的使用方法

Youtu-Embedding提供“腾讯云API调用”“本地部署”两种使用方式，以下是详细步骤（基于官方文档，确保可复现）：

方式1：腾讯云API调用（推荐：快速落地，无需部署）

适合无服务器、无GPU资源，或追求快速上线的场景，通过调用腾讯云API获取嵌入结果。

步骤1：准备腾讯云账号与密钥

• 注册腾讯云账号：访问腾讯云官网注册并完成实名认证；

• 获取API密钥：登录腾讯云控制台→访问“访问管理→API密钥管理”→创建“SecretId”与“SecretKey”（需妥善保存，避免泄露）。

步骤2：安装腾讯云SDK

打开终端，执行以下命令安装Python SDK：

pip install --upgrade tencentcloud-sdk-python

步骤3：编写API调用代码

参考仓库usage/tencent_cloud_api.py，核心代码如下（需替换自己的SecretId、SecretKey）：

from tencentcloud.common import credential
from tencentcloud.common.profile.client_profile import ClientProfile
from tencentcloud.common.profile.http_profile import HttpProfile
from tencentcloud.youtu.v20200324 import youtu_client, models

# 1. 配置密钥与客户端
cred = credential.Credential("你的SecretId", "你的SecretKey")
httpProfile = HttpProfile()
httpProfile.endpoint = "youtu.tencentcloudapi.com" # API端点
clientProfile = ClientProfile()
clientProfile.httpProfile = httpProfile
client = youtu_client.YoutuClient(cred, "ap-guangzhou", clientProfile) # 地域选择ap-guangzhou

# 2. 构造请求参数（文本列表）
req = models.TextEmbeddingRequest()
req.TextList = [
  "今天天气很好",
  "适合去户外野餐",
  "明天会下雨吗"
]

# 3. 调用API获取嵌入结果
resp = client.TextEmbedding(req)
# 4. 解析结果（embeddings为2048维向量列表）
for i, text in enumerate(req.TextList):
  embedding = resp.Embeddings[i].Vector
  print(f"文本：{text}")
  print(f"嵌入向量（前5维）：{embedding[:5]}")
  print(f"向量长度：{len(embedding)}") # 输出2048
  print("-" * 50)

步骤4：运行代码与查看结果

• 执行代码后，API会返回每个文本的2048维向量；

• 注意：API调用有额度限制，新用户可享受免费额度（具体以腾讯云官网为准），超出后按流量计费。

方式2：本地部署（推荐：离线使用、隐私保护）

适合需离线推理、数据敏感，或需二次开发的场景，支持CPU/GPU（CUDA/macOS）运行。以下是“基于transformers的本地推理”步骤（最常用方式）：

步骤1：环境准备（Python+依赖库）

• 安装Python：推荐Python 3.8-3.11（兼容性最好）；

• 创建虚拟环境（避免依赖冲突）：

 # 创建虚拟环境
 python -m venv youtu-env
 # 激活环境（Windows）
 youtu-env\Scripts\activate
 # 激活环境（macOS/Linux）
 source youtu-env/bin/activate

• 安装依赖库（指定版本确保兼容性）：

 pip install -U pip
 pip install "transformers==4.51.3" torch numpy scipy scikit-learn huggingface_hub

步骤2：克隆仓库与下载模型权重

• 克隆GitHub仓库：

 git clone https://github.com/TencentCloudADP/youtu-embedding.git
 cd youtu-embedding # 进入仓库目录

• 下载模型权重（两种方式任选）： 方式A：通过Hugging Face CLI下载（需先安装huggingface_hub）：

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

方式B：手动下载（适合Hugging Face访问慢的情况）：

1. 访问模型Hugging Face页面；

2. 点击“Files and versions”→下载所有文件（包括pytorch_model-00001-of-00002.bin、config.json等）；

3. 将下载的文件放入仓库目录下的youtu-model文件夹。

步骤3：运行官方测试脚本

仓库提供3个测试脚本，对应不同环境，直接运行即可查看效果：

以“本地模型+macOS M1”为例，运行命令：

python test_transformers_local.py --model_path ./youtu-model

步骤4：查看测试结果

脚本会自动加载模型，对“查询文本”与“候选文本”进行嵌入并计算相似度，输出类似以下结果（与仓库示例一致）：

Loading checkpoint shards: 100%|███████████████████████████████| 2/2 [00:00<00:00, 28.64it/s]
Model loaded: ./youtu-model
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]]

• 结果解读：相似度分数越高（0-1之间），代表文本语义相关性越强；脚本已按分数排序，可直接获取最相关文本。

方式3：集成sentence-transformers（推荐：简化开发）

sentence-transformers是文本嵌入领域最流行的框架，提供简洁API，Youtu-Embedding可直接集成：

步骤1：安装sentence-transformers

pip install sentence-transformers==5.1.0

步骤2：编写代码

from sentence_transformers import SentenceTransformer
import numpy as np

# 1. 加载模型（本地模型路径或Hugging Face ID）
model = SentenceTransformer("./youtu-model") # 本地模型
# 或 model = SentenceTransformer("tencent/Youtu-Embedding") # 在线加载（需联网）

# 2. 文本嵌入
queries = ["今天天气怎么样？"] # 查询文本
passages = [
  "今天天气很好，适合去公园",
  "明天会降温，记得加衣服",
  "这家餐厅的火锅很好吃"
] # 候选文本

# 3. 生成嵌入向量（encode_query用于查询，encode_document用于文档，优化过性能）
query_embeddings = model.encode_query(queries, convert_to_tensor=True)
passage_embeddings = model.encode_document(passages, convert_to_tensor=True)

# 4. 计算相似度（余弦相似度）
similarities = model.similarity(query_embeddings, passage_embeddings)
similarities = similarities.cpu().numpy() # 转为numpy数组便于查看

# 5. 输出结果
print("查询文本：", queries[0])
for i, (passage, score) in enumerate(zip(passages, similarities[0])):
  print(f"候选文本{i+1}：{passage} | 相似度：{score:.4f}")

步骤3：运行结果

查询文本： 今天天气怎么样？
候选文本1：今天天气很好，适合去公园 | 相似度：0.5236
候选文本2：明天会降温，记得加衣服 | 相似度：0.3189
候选文本3：这家餐厅的火锅很好吃 | 相似度：0.0215

方式4：集成LangChain（RAG场景推荐）

LangChain是RAG核心框架，Youtu-Embedding可作为“嵌入器”接入，步骤如下：

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

步骤1：安装依赖

步骤2：编写RAG示例代码

from langchain_community.document_loaders import TextLoader
from langchain_community.vectorstores import FAISS
from langchain_text_splitters import CharacterTextSplitter
from langchain_huggingface import HuggingFaceEmbeddings
from langchain.chains import RetrievalQA
from langchain_community.llms import FakeListLLM # 用FakeLLM演示，实际替换为真实LLM

# 1. 加载本地文档（示例：产品手册.txt）
loader = TextLoader("产品手册.txt", encoding="utf-8")
documents = loader.load()

# 2. 分割文档（按8K长度）
text_splitter = CharacterTextSplitter(chunk_size=8192, chunk_overlap=0)
docs = text_splitter.split_documents(documents)

# 3. 初始化Youtu-Embedding作为嵌入器
embeddings = HuggingFaceEmbeddings(
  model_name="./youtu-model", # 本地模型路径
  model_kwargs={"device": "mps"}, # 设备：mps（macOS）/cuda（GPU）/cpu
  encode_kwargs={"normalize_embeddings": True} # 归一化向量（提升相似度计算准确性）
)

# 4. 构建向量数据库（FAISS）
db = FAISS.from_documents(docs, embeddings)

# 5. 构建检索链（示例用FakeLLM，实际替换为GPT-4、混元等）
fake_llm = FakeListLLM(responses=["根据知识库信息，答案是：{context}"])
qa_chain = RetrievalQA.from_chain_type(
  llm=fake_llm,
  chain_type="stuff", # 简单将检索结果传入LLM
  retriever=db.as_retriever(search_kwargs={"k": 3}) # 召回Top3相关文档
)

# 6. 发起查询
query = "产品A的保修期限是多久？"
result = qa_chain.invoke({"query": query})

# 7. 输出结果
print("查询结果：", result["result"])

六、常见问题解答（FAQ）

Q1：模型下载慢或失败怎么办？

A1：有三种解决方式：

• 方式1：使用Hugging Face镜像源，下载时添加--endpoint-url参数：

 huggingface-cli download tencent/Youtu-Embedding 
 --local-dir ./youtu-model --endpoint-url https://hf-mirror.com

• 方式2：手动下载：访问模型Hugging Face页面，点击“Files and versions”下载所有文件，解压到./youtu-model；

• 方式3：使用Git LFS下载大文件（模型权重文件较大，需Git LFS支持）：

 git lfs install
 git clone https://huggingface.co/tencent/Youtu-Embedding ./youtu-model

Q2：本地部署需要什么硬件配置？

A2：根据使用场景推荐配置：

• 测试/小规模推理（单次1-10条文本）：

• CPU：Intel i5/i7（4核以上）、AMD Ryzen 5/7；

• 内存：8GB以上（加载模型需约4GB内存）；

• 中规模推理（单次10-100条文本）：

• GPU：NVIDIA Tesla T4（16GB显存）、RTX 3060（12GB显存）；

• macOS：M1/M2芯片（8核以上，支持MPS加速）；

• 大规模推理/训练：

• GPU：NVIDIA A100（40GB显存）、RTX 4090（24GB显存）；

• 内存：32GB以上（批量推理时需缓存数据）。

Q3：如何评估模型在自己数据上的效果？

A3：使用项目evaluation/目录下的评估代码，步骤如下：

1. 准备评估数据：按“CMTEB格式”整理数据，示例：

  [
    {"query": "文本1", "positive": ["相关文本1", "相关文本2"], "negative": ["无关文本1"]},
    {"query": "文本2", "positive": ["相关文本3"], "negative": ["无关文本2", "无关文本3"]}
  ]

2. 运行评估脚本：

  cd evaluation
  python evaluate.py --model_path ../youtu-model 
  --data_path ./your_data.json --task_type IR

3. 查看评估指标：脚本会输出“准确率（Accuracy）、召回率（Recall）、MRR（平均倒数排名）”等指标，MRR越高代表模型检索效果越好。

Q4：能否微调模型适配特定领域（如医疗、金融）？

A4：可以，项目提供完整的微调框架，步骤如下：

1. 准备领域数据：按“统一数据格式”整理（参考前文“协同-判别式微调框架”的 data format）；

2. 配置训练参数：修改training/CoDiEmb/configs/youtuemb_config.yaml，主要配置：

• data_path：领域数据路径；

• task_weights：任务权重（如医疗领域IR任务权重设为0.5）；

• model_path：预训练模型路径（./youtu-model）；

• device：训练设备（cuda）；

1. 启动训练：

  cd training/CoDiEmb/scripts
  bash train_youtuemb.sh

4. 评估微调效果：用evaluation/目录代码测试微调后模型在领域数据上的性能。

Q5：API调用有额度限制吗？如何查看剩余额度？

A5：腾讯云API调用有额度限制，具体规则以腾讯云官网为准：

• 新用户额度：通常提供1000-5000次免费调用（需实名认证）；

• 查看剩余额度：登录腾讯云控制台→访问“费用中心→资源用量→Youtu-Embedding API”；

• 计费方式：免费额度用完后，按“调用次数”计费，具体价格参考腾讯云Youtu-Embedding定价页。

Q6：为什么我的相似度得分和官方示例不一样？

A6：可能有三个原因：

• 模型版本差异：确保使用的是Youtu-Embedding-V1（最新版本），旧版本可能性能不同；

• 输入文本预处理差异：官方示例文本是英文（"What's the weather like?"），若输入中文需确保编码正确，且无额外空格、标点；

• 设备精度差异：CPU推理用FP32精度，GPU用FP16精度，会导致微小分数差异（通常在0.01以内，不影响排序）。

Q7：模型支持多语言吗？

A7：当前开源的Youtu-Embedding-V1主要优化中文文本，对英文的支持有限（在英文STS任务上得分约55-60，低于中文的68.82）。未来腾讯优图可能推出多语言版本，具体以GitHub仓库更新为准。

Q8：如何将模型部署为HTTP服务，供其他系统调用？

A8：推荐使用FastAPI将模型封装为HTTP服务，步骤如下：

1. 安装FastAPI与Uvicorn：

  pip install fastapi uvicorn

2. 编写服务代码（embedding_service.py）：

  from fastapi import FastAPI
  from sentence_transformers import SentenceTransformer
  import uvicorn

  app = FastAPI()
  # 加载模型（启动时加载一次，避免每次请求加载）
  model = SentenceTransformer("./youtu-model", device="mps")

  @app.post("/embed")
  def get_embedding(texts: list[str]):
    """获取文本嵌入向量"""
    embeddings = model.encode(texts, convert_to_tensor=False)
    return {"embeddings": embeddings.tolist(), "dimension": len(embeddings[0])}

  if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000) # 服务端口8000

3. 启动服务：

  python embedding_service.py

4. 测试服务（用curl或Postman）：

  curl -X POST "http://localhost:8000/embed" -H 
  "Content-Type: application/json" -d '{"texts": ["今天天气好", "适合去爬山"]}'

Q9：模型支持长文本（超过8K）吗？

A9：当前Youtu-Embedding-V1的最大序列长度是8K，超过8K的文本会被截断（默认截断右侧），导致语义信息丢失。若需处理超长文本（如10K以上的报告），建议：

• 文本分割：按8K长度分割成多个片段，分别嵌入后取“片段向量的平均值”作为长文本的总向量；

• 注意：分割时尽量按“段落边界”分割，避免破坏句子完整性（如用LangChain的RecursiveCharacterTextSplitter）。

Q10：项目的许可证是什么？可以商用吗？

A10：项目基于MIT许可证开源，具体规则：

• 允许商用：可用于商业产品，但需在产品文档中注明“使用Youtu-Embedding开源模型”；

• 需保留版权信息：复制或修改代码时，需保留原许可证文件（LICENSE）中的版权声明；

• 免责声明：腾讯优图不对模型的“准确性、适用性”做担保，使用前需自行测试；

• 注意：许可证注明“不适用于欧盟地区”，若业务涉及欧盟，需联系腾讯云获取额外授权。

七、相关链接

• GitHub仓库：https://github.com/TencentCloudADP/youtu-embedding

• Hugging Face模型页：https://huggingface.co/tencent/Youtu-Embedding

• 论文链接（arXiv）：https://arxiv.org/abs/2508.11442

八、总结

Youtu-Embedding作为腾讯优图实验室开源的通用文本表示模型，以“顶尖性能、创新技术、灵活部署”为核心优势，通过“三阶段训练流程”与“协同-判别式微调框架”，在CMTEB基准实现77.58分的榜首成绩，且2B参量的部署成本显著低于同类大模型；仓库提供“API调用+本地部署”两种方式，支持sentence-transformers、LangChain、LlamaIndex等主流框架集成，可覆盖RAG、智能检索、文本聚类等多场景需求，同时通过精细化数据工程与训练配置，确保模型在工业场景的可用性与稳定性；此外，项目开源完整的训练框架与评估代码，既满足开发者快速落地业务的需求，也为文本表示领域的研究提供可复现、可扩展的技术方案，是当前中文文本嵌入领域“工业级应用+学术研究”的优质开源选择。