文本向量与重排服务

BGE-M3 文本向量服务和 Qwen3-Reranker-0.6B 文本重排服务分别用于生成文本向量和对候选文档重新排序。BGE-M3 是北京智源人工智能研究院（Beijing Academy of Artificial Intelligence，BAAI）发布的通用文本嵌入模型，将文本编码为 1024 维稠密向量，用于向量检索。Qwen3-Reranker-0.6B 根据查询内容计算候选文档的相关性分数，并对候选文档重新排序。两个服务共用 RAG 服务 Docker 镜像，但使用不同的编译模型、接口和端口。

在典型的检索增强生成（Retrieval-Augmented Generation，RAG）检索流程中，BGE-M3 先将查询文本编码为向量，向量检索系统根据该向量召回候选文档，Qwen3-Reranker-0.6B 再对候选文档进行重排。典型处理流程为：BGE-M3 → 向量检索 → Qwen3-Reranker-0.6B。Qwen3-Reranker-0.6B 的输入为原始查询文本和向量检索返回的候选文档文本，不直接接收 BGE-M3 生成的向量。

本文以 S40 卡为例，分别介绍两个服务的部署和验证方法，不包含向量检索系统的部署方法。

前提条件

安装 SOLA Toolkit，详见《SOLA Toolkit 安装指南》。
安装 MOFFETT Container Toolkit，详见《MOFFETT Container Toolkit 用户手册》。
安装 Docker、wget 和 pigz。
当前用户具有运行 Docker 的权限。
至少预留 20 GiB 可用磁盘空间。其中，模型目录所在文件系统至少预留 15 GiB，用于存储下载文件、Docker 镜像包和解压后的编译模型文件；Docker 数据根目录所在文件系统至少预留 5 GiB，用于导入 Docker 镜像。如果模型目录和 Docker 数据根目录位于同一文件系统，该文件系统至少预留 20 GiB。

准备环境

生成容器设备接口（Container Device Interface，CDI）规范文件，用于向容器挂载稀疏处理单元 SPU（Sparse Processing Unit）设备。

注意

更换、增加或移除计算卡，设备编号发生变化，或 SOLA Toolkit 版本、安装路径发生变化后，必须重新生成 CDI 规范文件，并在主机上执行 sudo systemctl restart docker 重启 Docker 服务（可能中断其他容器业务），确保设备映射和挂载路径与当前主机环境一致。
sudo moffett-ctk cdi generate --driver-root / --output=/etc/cdi/moffett.yaml
sudo moffett-ctk cdi generate --driver-root /run/moffett/driver --output=/etc/cdi/moffett.yaml

设置模型目录。

models_dir=/path/to/models # 将 `/path/to/models` 替换为实际路径。
mkdir -p "${models_dir}"
cd "${models_dir}"

获取模型和镜像文件。

wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/ModelZoo/bge-m3/model.onnx
wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/ModelZoo/bge-m3/model.onnx_data
wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/ModelZoo/bge-m3/moffett_bge_m3_v1.tar.gz
wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/ModelZoo/rag-service/moffett_qwen3_reranker_0_6b.tar.gz
wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/ModelZoo/rag-service/rag.tar

各文件的用途如下：

文件	用途
`model.onnx`	BGE-M3 服务运行所需的开放神经网络交换（Open Neural Network Exchange，ONNX）模型文件，也用于与编译模型比较输出
`model.onnx_data`	`model.onnx` 对应的外部权重文件，必须与 `model.onnx` 保存在同一目录
`moffett_bge_m3_v1.tar.gz`	BGE-M3 编译模型包
`moffett_qwen3_reranker_0_6b.tar.gz`	Qwen3-Reranker-0.6B 编译模型包
`rag.tar`	BGE-M3 和 Qwen3-Reranker-0.6B 共用的 RAG 服务 Docker 镜像

解压两个编译模型包。
```
tar --use-compress-program=pigz -pxvf moffett_bge_m3_v1.tar.gz
tar --use-compress-program=pigz -pxvf moffett_qwen3_reranker_0_6b.tar.gz
```
解压后，确认 Qwen3-Reranker-0.6B 模型目录包含 config.json、module_infos_v3.json、token_to_embd.bin、分词器文件、attention_layer_params 目录和 sub_module_* 目录。
导入 RAG 服务 Docker 镜像。
```
docker load -i "${models_dir}/rag.tar"
```

启动 RAG 服务容器

启动容器（以 moffett_test 为例），并挂载 SPU 设备和模型目录。
```
docker run -itd \
  --device moffett.ai/spu=0 \
  --net=host \
  --name moffett_test \
  -v "${models_dir}:/home/moffett/models" \
  llama-backend-rag-dev:latest
```
注意

如果启动容器时提示 failed to fulfil mount request 或 SOLA 路径不存在，参见《MOFFETT Container Toolkit 用户手册》中的运行容器工作负载时提示 SOLA 路径不存在。
确认容器处于运行状态。
```
docker ps --filter name=moffett_test
```
STATUS 列显示 Up 时，表示容器已正常启动。
进入容器。
```
docker exec -it moffett_test /bin/bash
```
镜像的默认工作目录为 /opt/llama_backend。镜像已经编译并安装 BGE-M3 和 Qwen3-Reranker-0.6B 共用的服务后端。

完成环境准备后，按需部署以下对应服务。

部署 BGE-M3 文本向量服务

BGE-M3 文本向量服务提供 /v1/embeddings 应用程序编程接口（Application Programming Interface，API），用于生成文本向量。

可选：比较编译模型与 ONNX 模型输出

在容器中分别运行 BGE-M3 编译模型和 ONNX 模型，并计算两者输出的余弦相似度：

python test/infer_bge.py \
  --model /home/moffett/models/moffett_bge_m3_v1 \
  --onnx /home/moffett/models/model.onnx \
  --text "What is BGE-M3?" \
  --verify-onnx

启动服务

在容器中启动 BGE-M3 文本向量服务。

python test/eval_scope_test/bge_server.py \
  --model /home/moffett/models/moffett_bge_m3_v1 \
  --onnx /home/moffett/models/model.onnx \
  --served-model bge-m3-s40 \
  --device 0 \
  --host 0.0.0.0 \
  --port 8001

保持当前终端中的服务持续运行。

验证文本向量服务

在主机上打开新的终端并进入同一容器。
```
docker exec -it moffett_test /bin/bash
```
在容器中运行镜像提供的 API 冒烟测试。
```
python test/eval_scope_test/bge_smoke_test.py \
  --url http://127.0.0.1:8001/v1/embeddings \
  --model bge-m3-s40
```
测试脚本调用 /v1/embeddings 接口，检查返回的文本向量数量和维度，并确认不同文本的向量结果存在差异。测试成功时，脚本输出向量维度以及测试文本之间的余弦相似度。脚本正常结束且未报错，表示本次服务验证通过。

须知

输入文本过长时，服务会截断文本，截断部分不参与向量生成。

可选：评测语义文本相似度

文本语义相似度评测用于检验模型生成的文本向量对语义相似程度的表征能力。本示例选用大规模文本嵌入基准（Massive Text Embedding Benchmark，MTEB）中的语义文本相似度基准（Semantic Textual Similarity Benchmark，STSBenchmark）任务，并通过 EvalScope 模型评测框架执行评测。

具体步骤如下：

确保 BGE-M3 文本向量服务保持运行。首次运行评测时，容器需要能够访问 Hugging Face Hub 以下载评测数据集。
在主机上打开新的终端并进入同一容器。
```
docker exec -it moffett_test /bin/bash
```
运行 20 条数据的 STSBenchmark 评测。
```
python test/eval_scope_test/run_bge_evalscope.py \
  --task STSBenchmark \
  --query-limit 20
```
--query-limit 指定实际参与评测的数据量，不会减少首次下载的数据量，在数据集加载完成后生效。当设置 --query-limit 0 时，脚本使用完整任务数据进行评测。
查看评测结果。

评测结果保存在容器的以下目录：
```
/opt/llama_backend/outputs/bge-m3-s40/
```
注意

限制数据量的评测用于验证部署和评测链路，结果不代表完整 STSBenchmark 的标准评测成绩。

部署 Qwen3-Reranker-0.6B 文本重排服务

Qwen3-Reranker-0.6B 文本重排服务提供 /v1/rerank API，用于计算查询文本与候选文档的相关性分数并返回重排结果。

可选：验证编译模型推理

在容器中使用一组查询文本和候选文档运行 Qwen3-Reranker-0.6B 编译模型：

export SOLA_WAIT_TIMEOUT=20
python test/infer_reranker.py \
  --model /home/moffett/models/moffett_qwen3_reranker_0_6b \
  --query "What is the capital of China?" \
  --document "Beijing is the capital of China."

命令正常结束并输出 yes_probability，表示本次输入已完成推理。以下为输出格式示例，具体数值以实际结果为准：

scores: shape=(1, 2048, 64), dtype=torch.bfloat16, yes_probability=0.99...

启动服务

在容器中启动 Qwen3-Reranker-0.6B 文本重排服务。

export SOLA_WAIT_TIMEOUT=20 # 如在验证编译模型推理时已执行该命令，此处可跳过
python test/eval_scope_test/rerank_server.py \
  --model /home/moffett/models/moffett_qwen3_reranker_0_6b \
  --served-model qwen3-reranker-0.6b-s40 \
  --device 0 \
  --host 0.0.0.0 \
  --port 8000

保持当前终端中的服务持续运行。

验证文本重排服务

在主机上打开新的终端并进入同一容器。
```
docker exec -it moffett_test /bin/bash
```
在容器中运行镜像提供的 API 冒烟测试。
```
python test/eval_scope_test/smoke_test.py \
  --url http://127.0.0.1:8000/v1/rerank \
  --model qwen3-reranker-0.6b-s40
```
测试脚本提交一条查询文本、一篇相关文档和一篇无关文档，并检查相关文档是否排在首位。服务同时支持 /v1/rerank 和 /v1/reranks 路径，响应结果按照 relevance_score 从高到低排列。脚本正常结束且未报错，表示本次服务验证通过。

须知

候选文档过长时，服务会截断文档，截断部分不参与相关性评分。查询文本或任务指令过长、无法满足输入长度限制时，请求会失败。

可选：评测文本重排结果

文本重排评测用于验证数据集加载、服务调用和排序指标输出。本示例使用 MTEB 中的 MMarcoReranking 任务，并通过 EvalScope 模型评测框架执行评测。

具体步骤如下：

确保 Qwen3-Reranker-0.6B 文本重排服务保持运行。首次运行评测时，容器需要能够访问 Hugging Face Hub 以下载评测数据集。
在主机上打开新的终端并进入同一容器。
```
docker exec -it moffett_test /bin/bash
```
运行一条查询的评测，将 --candidate-limit 设置为 10。
```
python test/eval_scope_test/run_evalscope.py \
  --api-base http://127.0.0.1:8000/v1 \
  --model qwen3-reranker-0.6b-s40 \
  --task MMarcoReranking \
  --limit 1 \
  --candidate-limit 10 \
  --output outputs/qwen3-reranker-s40
```
参数说明如下：
- --limit：指定参与评测的查询数量，设置为 0 时使用完整查询集。
- --candidate-limit：指定每条查询保留的候选文档数，设置为 0 时保留完整候选集。评测会保留全部已知正样本，因此实际保留的候选文档数可能超过该值。
查看评测结果。

评测结果保存在容器的以下目录：
```
/opt/llama_backend/outputs/qwen3-reranker-s40/
```
输出结果的 Main Score 表示平均精度均值（Mean Average Precision，MAP）排序指标，不是文档的相关性概率。

注意

限制查询数或候选文档数的评测用于验证部署和评测链路，结果不能与完整 MTEB 任务的标准评测成绩直接比较。

停止 RAG 服务

在运行模型服务的终端中按 Ctrl+C，停止服务进程。
在主机上停止容器。
```
docker stop moffett_test
```
可选：删除容器。

不再使用容器时，在主机上执行以下命令删除容器。删除前，请将需要保留的评测结果复制到主机；容器内 /opt/llama_backend/outputs/ 下的结果会随容器删除。
```
docker rm moffett_test
```

文本向量与重排服务

前提条件

准备环境

启动 RAG 服务容器

部署 BGE-M3 文本向量服务

可选：比较编译模型与 ONNX 模型输出

启动服务

验证文本向量服务

可选：评测语义文本相似度

部署 Qwen3-Reranker-0.6B 文本重排服务

可选：验证编译模型推理

启动服务

验证文本重排服务

可选：评测文本重排结果

停止 RAG 服务

选择文档版本