Jina Embeddings v2 到 v3 的迁移指南

Jina Embeddings v3 我们最新推出的 5.7 亿参数的顶级文本向量模型，在多语言和长文本检索任务上达到当前最佳水平 SOTA。

v3 不仅拥有更强大的性能，还有很多惊喜新功能。如果您仍在使用 2023 年 10 月发布的 Jina Embeddings v2，我们强烈建议您尽快迁移至 v3。

先简单说下 Jina Embeddings v3 的亮点：

• 支持 89 种语言: 突破 v2 只能处理少数几种双语的限制，实现真正的多语言文本处理。

• 内置 Lora 适配器: v2 是通用的 Embedding 模型，而 v3 内置了 Lora Adapter，可以根据你的检索、分类、聚类等任务，生成专门优化的向量，获得更优的性能。

• 长文本检索更精准: v3 利用 8192 token 的上下文长度和迟分 (Late Chunking) 技术，生成包含更丰富上下文信息的块向量，可以显著提高长文本检索的准确率。

• 向量维度灵活可控: v3 的向量维度可以灵活调整，在性能和存储空间之间取得平衡，避免高维度向量带来的高昂存储开销。这归功于俄罗斯套娃向量表征学习（Matryoshka Representation Learning, MRL）

开源模型链接: https://huggingface.co/jinaai/jina-embeddings-v3 

模型 API 链接: https://jina.ai/?sui=apikey 

模型论文链接: https://arxiv.org/abs/2409.10173

快速迁移指南

• v3 是全新的模型，所以 v2 的向量和索引都不能直接复用，需要重新索引一遍数据。

• 在大多数场景 (96%) 下，v3 都显著优于 v2，v2 仅在英文摘要任务上偶尔能和 v3 打个平手，甚至略胜一筹。但考虑到 v3 的多语言支持和高级特性，大部分场景下还是应该优先选择 v3。

• v3 的 API 新增了 task、dimensions 和 late_chunking 三个参数，具体用法可以参考我们的博客文章。

维度调整

• v3 默认输出 1024 维的向量，而 v2 只有 768 维。采用 Matryoshka 表示学习后，v3 现在理论上可以输出任意维度。开发者可以通过设置 dimensions 参数灵活控制输出向量的维度，在存储成本和性能间找到最佳的平衡点

• 如果你之前的项目是基于 v2 API 开发的，直接把模型名称改成 jina-embeddings-v3 是不行的，因为默认维度已经变了。如果希望保持数据结构或大小与 v2 一致，可以设置 dimensions=768。即使维度相同，v3 和 v2 的向量在语义空间上的分布也完全不同，因此不能直接互换使用。

模型替换

• v3 强大的多语言支持能力已经全面取代了 v2 中的双语模型 (v2-base-de、v2-base-es、v2-base-zh)。

• 对于纯粹的编码任务，jina-embeddings-v2-based-code 仍是最佳选择。测试显示其得分高达 0.7753，而 v3 通用向量 (未设置 task) 和 LoRA 适配器的得分分别为 0.7537 和 0.7564，v2 编码性能领先 v3 约 2.8%。

任务参数

• v3 API 在未指定 task 参数时可生成质量不错的通用向量，但强烈建议根据具体任务类型设置 task 参数，以获取更优向量表示。

• 若需让 v3 模拟 v2 的行为，请使用 task="text-matching"，但我们建议尝试不同 task 选项以找到最佳方案，而非将 text-matching 作为万能方案。

• 如果你的项目使用 v2 进行信息检索，建议切换到 v3 的检索任务类型（retrieval.passage 和 retrieval.query），可以获得更好的检索效果。

其他注意事项

• 对于全新任务类型 (这种情况比较少见)，可以尝试将 task 参数设置为 None 作为起点。

• 如果你在 v2 中使用过标签改写（label rewriting）技巧来处理零样本分类任务，那么在 v3 中，你可以直接设置 task="classification" 获得类似效果，因为 v3 已针对分类任务优化了向量表示。

• v2 和 v3 均支持最长 8192 token 的上下文长度，但 v3 处理效率更高，这主要得益于 FlashAttention2 技术，也为 v3 的迟分功能奠定了基础。

迟分 (Late Chunking)

• v3 引入了迟分功能，利用 8192 token 长上下文，先生成向量再分块，这样切出来的每一小块就都包含了上下文的信息，检索起来自然就更精准了。

• late_chunking 目前只在 API 中提供，如果你是在本地跑模型，暂时还用不了这个功能。

• 启用 late_chunking 时，每次请求的文本长度不能超过 8192 token，因为 v3 最多只能同时处理这么多内容。

性能和速度

• 在速度方面，即使 v3 的参数量是 v2 的三倍，但推理速度比 v2 更快或者至少持平，这主要归功于 FlashAttention2 技术。

• 不是所有的 GPU 都支持 FlashAttention2。如果你用的 GPU 不支持，v3 仍然可以运行，但速度可能会比 v2 稍微慢一点。

• 使用 API 时，网络延迟、速率限制和可用区域等因素也会影响延迟，因此 API 延迟不能完全反映 v3 模型的真实性能。

与 v2 不同，Jina Embeddings v3 采用的是 CC BY-NC 4.0 许可证。可以通过我们的 API、AWS 或者 Azure 商业化使用 v3。用于研究和非商业用途也是没问题的。如果需要在本地进行商业化部署，请联系我们的销售团队获取授权许可：

https://jina.ai/contact-sales

多语言支持

v3 是目前业界领先的多语言向量模型，并在 MTEB 排行榜上 10 亿参数以下模型中排名第二。它支持 89 种语言，覆盖了全球大多数主要语种。

其中在 30 种语言中具有出色的性能，包括中文、英语、日语、韩语、德语、西班牙语、法语、阿拉伯语、孟加拉语、丹麦语、荷兰语、芬兰语、格鲁吉亚语、希腊语、印地语、印度尼西亚语、意大利语、拉脱维亚语、挪威语、波兰语、葡萄牙语、罗马尼亚语、俄语、斯洛伐克语、瑞典语、泰语、土耳其语、乌克兰语、乌尔都语和越南语。

如果你之前用的是 v2 的英语、英语/德语、英语/西班牙语或者英语/中文模型，现在只需要修改 model 参数并选择合适的 task 类型，就可以轻松切换到 v3。

# v2 英语-德语

data = {
    "model": "jina-embeddings-v2-base-de",
    "input": [
        "The Force will be with you. Always.",
        "Die Macht wird mit dir sein. Immer.",
        "The ability to destroy a planet is insignificant next to the power of the Force.",
        "Die Fähigkeit, einen Planeten zu zerstören, ist nichts im Vergleich zur Macht der Macht."
    ]
}

# v3 多语言

data = {
    "model": "jina-embeddings-v3",
    "task": "retrieval.passage",
    "input": [
        "The Force will be with you. Always.",
        "Die Macht wird mit dir sein. Immer.",
        "力量与你同在。永远。",
        "La Forza sarà con te. Sempre.",
        "フォースと共にあらんことを。いつも。"
    ]
}

response = requests.post(url, headers=headers, json=data)

任务特定的向量表示

v2 使用通用向量表示，即所有任务共享同一个模型。v3 则针对不同任务（例如检索、分类、聚类等）提供专门优化的向量表示，提升特定场景下的性能。

选择不同的 task 类型，就相当于告诉模型要提取哪些和该任务相关的特征，生成更适配任务需求的向量表示。

下面以光剑维修知识库为例，演示如何将 v2 代码迁移到 v3，并体验任务特定的向量表示带来的性能提升：

# 实际项目中我们会使用更大的数据集，这个只是示例
knowledge_base = [
    "为什么我的光剑刀锋在闪烁？刀锋闪烁可能表示电池电量不足或不稳定的水晶。请为电池充电并检查水晶的稳定性。如果闪烁持续，可能需要重新校准或更换水晶。",
    "为什么我的刀锋比以前暗淡？刀锋变暗可能意味着电池电量低或电源分配有问题。首先，请为电池充电。如果问题仍然存在，可能需要更换LED。",
    "我可以更换我的光剑刀锋颜色吗？许多光剑允许通过更换水晶或使用剑柄上的控制面板更改颜色设置来自定义刀锋颜色。请参阅您的型号手册以获得详细说明。",
    "如果我的光剑过热，我该怎么办？过热可能是由于长时间使用导致的。关闭光剑并让其冷却至少10分钟。如果频繁过热，可能表明内部问题，需由技术人员检查。",
    "如何为我的光剑充电？通过剑柄附近的端口，将光剑连接到提供的充电线，确保使用官方充电器以避免损坏电池和电子设备。",
    "为什么我的光剑发出奇怪的声音？奇怪的声音可能表示音响板或扬声器有问题。尝试关闭光剑并重新开启。如果问题仍然存在，请联系我们的支持团队以更换音响板。"
]

query = "光剑太暗了"

对于 v2，只有一个任务（文本匹配），因此我们只需要一个示例代码块：

# v2 代码：使用文本匹配任务对知识库和查询进行编码
data = {
    "model": "jina-embeddings-v2-base-en",
    "normalized": True,  # 注意：v3 中不再需要此参数
    "input": knowledge_base
}

docs_response = requests.post(url, headers=headers, json=data)

data = {
    "model": "jina-embeddings-v2-base-en",
    "task": "text-matching",
    "input": [query]
}

query_response = requests.post(url, headers=headers, json=data)

v3 提供了针对特定任务优化的向量表示，包括检索、分离、分类和文本匹配等任务。

检索任务的向量表示

我们以一个简单的光剑维修知识库为例，演示 v2 和 v3 在处理文本检索任务时的区别。

对于语义检索任务，v3 引入了非对称编码，分别使用 retrieval.passage 和 retrieval.query 对文档和查询进行编码，以提升检索性能和准确率。

文档编码： retrieval.passage

data = {
    "model": "jina-embeddings-v3",
    "task": "retrieval.passage", # "task" 参数是 v3 中的新功能
    "late_chunking": True,
    "input": knowledge_base
}

response = requests.post(url, headers=headers, json=data)

查询编码： retrieval.query

data = {
    "model": "jina-embeddings-v3",
    "task": "retrieval.query",
    "late_chunking": True,
    "input": [query]
}

response = requests.post(url, headers=headers, json=data)

注意：上述代码中启用了late_chunking功能，该功能可以提升长文本的编码效果，我们将在后面详细介绍。

让我们对比一下 v2 和 v3 在处理查询“光剑太暗了”时的表现，v2 基于余弦相似度，返回了一组相关性较低的匹配结果，如下图所示：

相比之下，v3 则更能理解查询意图，返回了与“光剑刀片外观”相关的更准确的结果，如下图所示。

v3 不仅仅做检索，还提供了其他几种特定于任务的向量表示：

分离任务的向量表示

v3 的 separation 任务针对聚类、重新排名等分离任务进行了优化，例如将不同类型的实体分开，这对于组织和可视化大型语料库非常有用。

示例：区分星球大战和迪士尼角色

data = {
    "model": "jina-embeddings-v3",
    "task": "separation",  # 使用 separation 任务
    "late_chunking": True,
    "input": [
        "Darth Vader",
        "Luke Skywalker",
        "Mickey Mouse",
        "Donald Duck"
    ]
}

response = requests.post(url, headers=headers, json=data)

分类任务的向量表示

v3 的 classification 任务针对情感分析、文档分类等文本分类任务进行了优化，例如将文本分为正面和负面评论。

示例：分析星球大战影评的情感倾向

data = {
    "model": "jina-embeddings-v3",
    "task": "classification",
    "late_chunking": True,
    "input": [
        "《星球大战》是一部划时代的杰作，彻底改变了电影业，并永远重新定义了科幻电影！",
        "《星球大战》拥有令人惊叹的视觉效果、令人难忘的角色和传奇的叙事，是一部无与伦比的文化现象。",
        "《星球大战》是一场过度炒作的灾难，充满了浅薄的角色，毫无有意义的情节！",

}

response = requests.post(url, headers=headers, json=data)

文本匹配的向量表示

v3 的 text-matching 专注于语义相似性任务，例如句子相似性或去重，例如排除重复的句子或段落。

示例：识别星球大战台词中的重复内容

data = {
    "model": "jina-embeddings-v3",
    "task": "text-matching",
    "late_chunking": True,
    "input": [
        "Luke, I am your father.",
        "No, I am your father.",
        "Fear leads to anger, anger leads to hate, hate leads to the dark side.",
        "Fear leads to anger. Anger leads to hate. Hate leads to suffering."
    ]
}

response = requests.post(url, headers=headers, json=data)

Late Chunking: 提升长文本编码效果

v3 引入了 late_chunking 参数，当 late_chunking=True 时，模型会先处理整个文档，再将其分割成多个块，生成包含完整上下文信息的块向量；当 late_chunking=False 时，模型会独立处理每个块，生成的块向量不包含跨块的上下文信息。

注意

• 启用 late_chunking=True 时，每次 API 请求的 token 总数不能超过 8192，这是 v3 支持的最大上下文长度。

• late_chunking=False时，token 总数不受限制，但受 Embeddings API 的速率限制约束。

对于长文本处理，启用 late_chunking可以显著提升编码效果，因为它能够保留跨块的上下文信息，使生成的向量表示更完整、更准确。

我们使用一段聊天记录来评估 late_chunking 对长文本检索效果的影响。

history = [
    "Sita，你决定好周六生日晚餐要去哪儿了吗？",
    "我不确定，对这里的餐厅不太熟悉。",
    "我们可以上网看看推荐。",
    "那听起来不错，我们就这么办吧！",
    "你生日那天想吃什么类型的菜？",
    "我特别喜欢墨西哥菜或者意大利菜。",
    "这个地方怎么样，Bella Italia？看起来不错。",
    "哦，我听说过那个地方！大家都说那儿很好！",
    "那我们订张桌子吧？",
    "好，我觉得这会是个完美的选择！我们打电话预定吧。"
]

使用 v2 进行查询 “有什么好的餐馆推荐？”，所得结果不是特别相关。

在使用 v3 且未启用 late chunking的情况下，结果同样不理想。

然而，当使用 v3 并启用 late chunking 时，最相关的结果 (一个好的餐馆推荐) 被准确地排在了首位。

检索结果：

从检索结果可以明显看出，启用 late_chunking 后，v3 能够更为准确地识别与查询相关的聊天内容，将最相关的结果排在首位。

这也表明 late_chunking 可以切实有效地提升长文本检索的准确率，特别是在需要深刻理解上下文语义的场景中。

使用俄罗斯套娃向量表示平衡效率和性能

v3 通过 dimensions 参数支持灵活的向量维度控制，你可以根据实际需求调整输出向量的维度，在性能和存储空间之间取得平衡。

较小的向量维度可以减少向量数据库的存储开销，并提升检索速度，但可能会损失部分信息，导致性能下降。

data = {
    "model": "jina-embeddings-v3",
    "task": "text-matching",
    "dimensions": 768,  # 设置向量维度为 768，默认值为 1024
    "input": [
        "The Force will be with you. Always.",
        "力量与你同在。永远。",
        "La Forza sarà con te. Sempre.",
        "フォースと共にあらんことを。いつも。"
    ]
}

response = requests.post(url, headers=headers, json=data) 

常见问题

Q1: 如果我已经在向量化之前对文档进行了分块，那么使用迟分 (Late Chunking) 还有什么优势？

A1: 迟分与预分块相比，其优势在于能够 在分块之前处理整个文档，从而保留更完整的上下文信息。迟分对于处理复杂或冗长的文档非常重要，它可以帮助在检索期间提供更相关的响应，因为模型在分段之前对文档有一个整体的理解。而预分块是在没有完整上下文的情况下独立处理块的。

Q2: 为什么 v2 在配对分类任务上的 benchmark 得分比 v3 高？我需要担心吗？

A2: v2 在配对分类任务上的得分看起来更高，主要是因为平均得分的计算方式不同。v3 的测试集包含了更多语言，因此其平均得分可能会低于 v2。实际上，v3 在所有语言的配对分类任务上的表现都与 multilingual-e5 等先进模型相当，甚至更好。

Q3: v3 在 v2 双语模型支持的特定语言上的表现是否更好？

A3: v3 和 v2 双语模型在特定语言上的性能对比 取决于具体的语言和任务类型。v2 的双语模型针对特定语言进行了高度优化，因此在某些特定任务上可能表现更好。但 v3 的设计目标是支持更广泛的多语言场景，它具备更强的跨语言泛化能力，并通过特定于任务的 LoRA 适配器，针对各种下游任务进行了优化。因此，在跨多种语言或更复杂的特定任务场景（如语义检索和文本分类）下，v3 通常能够获得更好的整体性能。

如果你只需要处理 v2 双语模型支持的某一种特定语言（中英、英德、西英），并且你的任务比较简单，那么 v2 仍然是一个不错的选择，甚至可能在某些情况下表现更好。

但如果你需要处理多种语言，或者你的任务比较复杂（例如需要进行语义检索或文本分类），那么 v3 有着强大的跨语言泛化能力和基于下游任务的优化策略，是更好的选择。

Q4: 为什么 v2 在摘要任务上的表现优于 v3？我需要担心吗？

A4: v2 在摘要任务上表现更优，主要是因为其模型架构针对语义相似度等任务进行了专门的优化，而语义相似度与摘要任务关系密切。v3 的设计目标是提供更广泛的任务支持，尤其是在检索和分类任务上，因此在摘要任务上的优化程度不如 v2。

但大家也不用太担心，摘要任务的评估目前主要依赖于 SummEval，这个测试主要测量语义相似度，并不能完全代表模型在摘要任务上的综合能力。鉴于 v3 在检索等其他关键任务上表现出色，摘要任务上的些许性能差异通常不会对实际应用产生重大影响。

总结

Jina Embeddings v3 是我们重大的模型升级，在多语言和长文本检索任务上达到当前最佳水平 SOTA。它内置多种 LoRA 适配器可以根据你的需求，针对 检索、聚类、分类和匹配 的不同场景进行定制，获得更精准的向量化效果。我们强烈建议您尽快迁移至 v3。