跳到主要内容
feedback
feedback

部署文本向量化模型 (Embedding)

一、模型原理与结构​

文本向量化模型（Text Embedding Model）将文本转换为高维稠密向量，捕捉文本的语义信息。以 Qwen3-Embedding 为代表的现代 Embedding 模型采用：

  • 双塔架构（Dual-Encoder）：输入层将文本映射到统一的语义空间
  • 大规模对比学习（Contrastive Learning）：通过正负样本对优化相似度空间
  • 多语言与长文本支持：支持中英双语，上下文窗口达 32k tokens
  • 向量维度与质量权衡：Qwen3-Embedding 输出 1024 维向量，兼顾精度与计算效率

Embedding 模型的优势：

  • 支持对任意长度文本编码（分块后进行平均池化）
  • 向量可直接用于相似性搜索、聚类、分类任务
  • 与向量数据库（Milvus、Weaviate、Pinecone）无缝集成
  • 为 RAG（检索增强生成）系统奠定基础

二、应用场景​

文本向量化模型可应用于：

  • 语义搜索：用户查询与文档库进行相似度匹配，排序候选结果
  • 检索增强生成（RAG）：在生成回答前从知识库检索相关文档
  • 推荐系统：基于用户兴趣向量，推荐相似的内容或商品
  • 文本聚类与分类：无监督或半监督地组织和标注文本
  • 重复检测：识别近似重复的用户提交、新闻稿或学术论文
  • 意图识别：微调向量模型快速识别用户意图（如情绪分析）

三、部署指南与示例​

本指南将指导您如何在不同芯片架构的算力实例上部署文本 Embedding 模型。我们将以 Qwen3-Embedding-8B 为示例模型，重点介绍如何部署 Embedding 服务并与向量数据库集成。

框架概览​

  • Hugging Face Transformers：基础框架，用于加载和推理 Embedding 模型
  • vLLM：支持 Embedding 模型推理的高性能引擎，提供 OpenAI 兼容的 API 接口
  • FastAPI：轻量级 Web 框架，快速构建自定义 Embedding API 服务
  • Chroma：轻量级向量数据库，开箱即用，适合快速原型开发
  • Milvus / Weaviate：高性能向量数据库，适合生产级别的大规模应用

一、沐曦 (MetaX) 部署指南​

本章节适用于 曦云 C500 等沐曦系列算力卡。

1.1 环境准备​

  • 算力型号：曦云 C500 (64GB)
  • 镜像选择：PyTorch / 2.6.0 / Python 3.10 / maca 3.2.1.3
  • 版本要求：pytorch>=2.4

镜像选择

1.2 基础部署步骤​

  1. 进入工作台：启动实例后，点击 JupyterLab 进入容器环境。

    进入容器

  2. 新建脚本：点击 "Notebook" 图标，新建一个 .ipynb 文件。

    新建Notebook

1.3 Embedding 推理示例​

使用官方优化的代码，支持指令微调和L2归一化：

!pip install transformers
import torch
import torch.nn.functional as F
from torch import Tensor
from transformers import AutoTokenizer, AutoModel

#“句向量”绑定在最后一个有效 token上
def last_token_pool(last_hidden_states: Tensor,
                 attention_mask: Tensor) -> Tensor:
    left_padding = (attention_mask[:, -1].sum() == attention_mask.shape[0])
    if left_padding:
        return last_hidden_states[:, -1]
    else:
        sequence_lengths = attention_mask.sum(dim=1) - 1
        batch_size = last_hidden_states.shape[0]
        return last_hidden_states[torch.arange(batch_size, device=last_hidden_states.device), sequence_lengths]


model_name = "/mnt/moark-models/Qwen3-Embedding-8B"
tokenizer = AutoTokenizer.from_pretrained(model_name, padding_side='left')
model = AutoModel.from_pretrained(model_name, torch_dtype=torch.bfloat16, device_map="cuda")

texts = ["天空是蓝色的，天气晴朗。", "今天阳光灿烂，非常适合出游。"]

batch_dict = tokenizer(
    texts,
    padding=True,
    truncation=True,
    max_length=8192,
    return_tensors="pt"
).to("cuda")

batch_dict.to(model.device)
outputs = model(**batch_dict)

embeddings = last_token_pool(outputs.last_hidden_state, batch_dict['attention_mask'])
print(embeddings)

print(f"编码完成，生成 {len(texts)} 个向量")

二、燧原 (Enflame) 部署指南​

本章节适用于 S60 等燧原系列算力卡。由于底层架构差异，需引入适配库。

2.1 环境准备​

  • 算力型号：Enflame S60 (48GB)
  • 镜像选择：Ubuntu / 22.04 / Python 3.13 / ef 1.5.0.604

镜像选择

2.2 Embedding 推理示例​

!pip install transformers
import torch
import torch_gcu
from torch_gcu import transfer_to_gcu # CUDA代码一键迁移
import torch.nn.functional as F
from torch import Tensor
from transformers import AutoTokenizer, AutoModel

#“句向量”绑定在最后一个有效 token上
def last_token_pool(last_hidden_states: Tensor,
                 attention_mask: Tensor) -> Tensor:
    left_padding = (attention_mask[:, -1].sum() == attention_mask.shape[0])
    if left_padding:
        return last_hidden_states[:, -1]
    else:
        sequence_lengths = attention_mask.sum(dim=1) - 1
        batch_size = last_hidden_states.shape[0]
        return last_hidden_states[torch.arange(batch_size, device=last_hidden_states.device), sequence_lengths]


model_name = "/mnt/moark-models/Qwen3-Embedding-8B"
tokenizer = AutoTokenizer.from_pretrained(model_name, padding_side='left')
model = AutoModel.from_pretrained(model_name, torch_dtype=torch.bfloat16, device_map="cuda")

texts = ["天空是蓝色的，天气晴朗。", "今天阳光灿烂，非常适合出游。"]

batch_dict = tokenizer(
    texts,
    padding=True,
    truncation=True,
    max_length=8192,
    return_tensors="pt"
).to("cuda")

batch_dict.to(model.device)
outputs = model(**batch_dict)

embeddings = last_token_pool(outputs.last_hidden_state, batch_dict['attention_mask'])
print(embeddings)

print(f"编码完成，生成 {len(texts)} 个向量")

三、vLLM 高性能部署​

vLLM 提供了对 Embedding 模型的优化支持，可直接生成 OpenAI 兼容的 API 接口，无需额外开发。

快速启动​

# 使用 vLLM 启动 Embedding 服务（内置模型路径）
vllm serve /mnt/moark-models/Qwen3-Embedding-8B \
  --port 8188 \
  --task embed

vLLM 会自动处理批处理、GPU 优化和 API 兼容性，开箱即用。

五、本地访问与服务验证​

请参考【SSH 隧道配置指南】建立安全连接。

六、实战课题​

课题目标​

部署 Embedding 向量化服务，对文档进行切片处理，存入向量数据库，并使用重排模型优化检索结果。完成以下任务：

所有输出文件请保存至 /data/exam/ 目录。

任务一：部署 Embedding API 服务​

任务要求：

  • 选择两种方式之一进行部署：
    • 方式 A（推荐）：使用 vLLM 启动服务，命令参考上文第四部分
    • 方式 B：使用 FastAPI 构建自定义服务
  • 在 8188 端口运行
  • 提供 OpenAI 兼容的 /v1/embeddings 端点或 vLLM 原生接口
  • 支持批量编码，返回 1024 维向量

实现提示：

  • 若使用 vLLM，直接执行启动命令即可获得 API 服务
  • 若使用 FastAPI，参考官方示例中的 last_token_pool 和 L2 归一化方法
  • 测试接口：curl -X POST http://localhost:8188/v1/embeddings -d '{"input": ["test text"]}'

任务二：文档切片与 Chroma 向量数据库存储​

任务要求：

  • 将提供的测试文档 /mnt/moark-models/L1_exam/embedding_documents.txt 进行智能切片（至少分成 10 个 chunk）
  • 使用 Embedding API 对每个 chunk 进行编码
  • 将向量与 chunk 内容存入 Chroma 向量数据库

任务三：使用重排模型优化检索结果​

任务要求：

  • 使用 bge-reranker-v2-m3 模型对检索结果进行重排
  • 对用户查询进行 embedding，从向量数据库检索 Top-10 候选
  • 使用 bge-reranker-v2-m3 对这 10 条候选进行重新排序，返回 Top-5
  • 记录重排前后的排序变化

实现提示：

  • query的查询问题可自定义，不做要求
  • bge-reranker-v2-m3 是交叉编码器（Cross-Encoder），直接计算查询与文本对的相关性分数
  • 使用 FlagEmbedding 库中的 FlagReranker 类加载模型
  • 对 Top-10 候选文本逐一计算相关性分数
  • 按分数降序排列，取 Top-5 作为最终结果

结果文件格式示例：

将结果写入 /data/exam/reranking_results.txt，建议使用如下格式：

query=今天天气适合出游吗？
initial_top10=
1|0.72|今天阳光明媚，适合外出。
2|0.69|天气晴朗，出游体验佳。
...
reranked_top5=
2|0.86|天气晴朗，出游体验佳。
1|0.84|今天阳光明媚，适合外出。
...

字段说明：索引 | 分数 | 文本片段。

提交要求：

完成作答后，直接提交检测即可。本课程采取程序自动检测的方式。

需确保以下文件输出完整：

  1. 重排结果对比：/data/exam/reranking_results.txt（显示索引、初始排名、重排后排名及分数）
Copyright © 2026 模力方舟京ICP备2025119063号京公网安备11011502039387号京公网安备11011502039387号