# 启动推理服务（Embedding\&Rerank）
本章节主要介绍大语言模型的推理服务Embedding\&Rerank启动方式，包括离线推理和在线推理2种方式。
无论是离线推理还是在线推理方式，以下的框架通用环境变量都需要设置。
框架通用环境变量如下：
```
# VPC网段
# 需用户手动修改，修改方式见下方注意事项
VPC_CIDR="7.150.0.0/16" #7.150.0.0是Snt9b23的网段，Snt9b机型需要替换为7.242.0.0
VPC_PREFIX=$(echo "$VPC_CIDR" | cut -d'/' -f1 | cut -d'.' -f1-2)
POD_INET_IP=$(ifconfig | grep -oP "(?<=inet\s)$VPC_PREFIX\.\d+\.\d+" | head -n 1)
POD_NETWORK_IFNAME=$(ifconfig | grep -B 1 "$POD_INET_IP" | head -n 1 | awk '{print $1}' | sed 's/://')
echo "POD_INET_IP: $POD_INET_IP"
echo "POD_NETWORK_IFNAME: $POD_NETWORK_IFNAME"
# 指定通信网卡
export GLOO_SOCKET_IFNAME=$POD_NETWORK_IFNAME
export TP_SOCKET_IFNAME=$POD_NETWORK_IFNAME
export HCCL_SOCKET_IFNAME=$POD_NETWORK_IFNAME
# 多机场景下配置
export RAY_EXPERIMENTAL_NOSET_ASCEND_RT_VISIBLE_DEVICES=1
# 开启显存优化
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
# 配置通信算法的编排展开位置在Device侧的AI Vector Core计算单元
export HCCL_OP_EXPANSION_MODE=AIV
# 指定可使用的卡，按需指定
export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3
# 指定绑核，按需指定
export CPU_AFFINITY_CONF=1
export LD_PRELOAD=/usr/local/lib/libjemalloc.so.2:${LD_PRELOAD}
# 默认启用ACLGRAPH模式，指定启动插件ascend
export VLLM_PLUGINS=ascend_vllm
# 是否是使用 ACLGRAPH模式，如果启用ACLGRAPH模式，值为1；否则为0
export USE_ACLGRAPH=0
# 指定vllm后端 v0
export VLLM_USE_V1=0
# 指定vllm版本
export VLLM_VERSION=0.9.0
```
#### 离线推理
编辑一个embeddings python脚本embeddings_offline_inference.py，脚本内容如下，运行该脚本使用ascend-vllm进行模型离线推理。
```
from vllm import LLM, SamplingParams
def main():
# 用户可以改
prompts = [
"Hello, my name is",
"The president of the United States is",
"The capital of France is",
"The future of AI is",
]
# ${model_path}用户必须改，具体参考【启动在线推理服务】章节推理服务基础参数说明--model
model_path = "${model_path}"
llm = LLM(
model=model_path,
# tensor_parallel_size用户根据实际情况可以改，具体参考【启动在线推理服务】章节推理服务基础参数说明--tensor-parallel-size
tensor_parallel_size=2,
# block_size用户根据实际情况可以改，具体参考【启动在线推理服务】章节推理服务基础参数说明--block-size
block_size=128,
# max_num_seqs用户根据实际情况可以改，具体参考【启动在线推理服务】章节推理服务基础参数说明--max-num-seqs
max_num_seqs=256,
# max_model_len用户根据实际情况可以改，具体参考【启动在线推理服务】章节推理服务基础参数说明--max-model-len
max_model_len=8192,
# distributed_executor_backend用户根据实际情况可以改，具体参考【启动在线推理服务】章节推理服务基础参数说明--distributed-executor-backend
distributed_executor_backend='ray'
)
outputs = llm.encode(prompts)
# Print the outputs.
for output in outputs:
print(output.outputs.embedding)
if __name__=="__main__":
main()
```
脚本中，未标注释部分，请勿更改。
参数说明：
${model_path}：替换成能访问的实际环境模型权重路径。
执行如下命令运行推理脚本：
```
python embeddings_offline_inference.py
```
编辑一个rerank python脚本rerank_offline_inference.py，脚本内容如下，运行该脚本使用ascend-vllm进行模型离线推理。
```
from vllm import LLM
# ${model_path}用户必须改，具体参考【启动在线推理服务】章节推理服务基础参数说明--model
path = "${model_path}"
def get_llm() -> LLM:
"""Initializes and returns the LLM model for Qwen3-Reranker."""
return LLM(
model=path,
task="score",
hf_overrides={
"architectures": ["Qwen3ForSequenceClassification"],
"classifier_from_token": ["no", "yes"],
"is_original_qwen3_reranker": True,
},
tensor_parallel_size=1
)
prefix = '<|im_start|>system\nJudge whether the Document meets the requirements based on the Query and the Instruct provided. Note that the answer can only be "yes" or "no".<|im_end|>\n<|im_start|>user\n'
suffix = "<|im_end|>\n<|im_start|>assistant\n\n\n\n\n"
query_template = "{prefix}: {instruction}\n: {query}\n"
document_template = ": {doc}{suffix}"
def main() -> None:
instruction = (
"Given a web search query, retrieve relevant passages that answer the query"
)
queries = [
"What is the capital of Beijing?",
]
documents = [
"The capital of China is Beijing.",
"Gravity is a force that attracts two bodies towards each other. It gives weight to physical objects and is responsible for the movement of planets around the sun.",
]
queries = [
query_template.format(prefix=prefix, instruction=instruction, query=query)
for query in queries
]
documents = [document_template.format(doc=doc, suffix=suffix) for doc in documents]
llm = get_llm()
outputs = llm.score(queries, documents)
print("-" * 30)
print([output.outputs.score for output in outputs])
print("-" * 30)
if __name__ == "__main__":
main()
```
脚本中，未标注释部分，请勿更改。
参数说明：
${model_path}：替换成能访问的实际环境模型权重路径。
执行如下命令运行推理脚本：
```
python rerank_offline_inference.py
```
#### 启动在线推理服务
此处提供OpenAI服务API接口启动方式。详细启动服务与请求方式参考：。
**推荐通过OpenAI服务的API接口启动推理，单机单卡和单机多卡场景下的具体操作命令如下，可以根据参数说明修改配置**。
**推理服务启动参数：** (以Qwen3-Reranker-8B为例)
```
source /home/ma-user/AscendCloud/AscendTurbo/set_env.bash
python -m vllm.entrypoints.openai.api_server \
--model /model/Qwen3-Reranker-8B \
--served-model-name Qwen3-Reranker-8B \
--max-num-seqs=256 \
--max-model-len=32768 \
--max-num-batched-tokens=32768 \
--tensor-parallel-size=1 \
--block-size=128 \
--host=0.0.0.0 \
--port=9001 \
--gpu-memory-utilization=0.95 \
--disable-log-requests \
--trust-remote-code
# 只有 Qwen3 rerank 需要设置 hf_overrides
# --hf_overrides '{"architectures": ["Qwen3ForSequenceClassification"],"classifier_from_token": ["no", "yes"],"is_original_qwen3_reranker": true}'
```
**推理服务基础参数说明如下：**
- --model ${container_model_path}：容器内模型权重文件所在的地址路径，即上传的HuggingFace权重文件存放目录。
- --served-model-name：API 中使用的模型名称。如果提供了多个名称，服务器将响应其中任意一个名称。响应中 model 字段里的模型名称将使用此列表中的第一个名称。如果未指定，模型名称将与 --model 参数的值相同。
- --max-num-seqs：最大同时处理的请求数，超过后在等待池等候处理。
- --max-model-len：推理时最大输入+最大输出tokens数量，输入超过该数量会直接返回。max-model-len的值必须小于config.json文件中的"max_position_embeddings"的值，否则推理预测会报错。config.json存在模型对应的路径下，例如：${container_model_path}/chatglm3-6b/config.json。不同模型推理支持的max-model-len长度不同，具体差异请参见[表1](https://support.huaweicloud.com/bestpractice-modelarts/modelarts_llm_infer_5908003.html#ZH-CN_TOPIC_0000002484417925__table598419217347)。
- --max-num-batched-tokens：prefill阶段，最多会使用多少token，必须大于或等于--max-model-len。
- --dtype：模型推理的数据类型。支持FP16和BF16数据类型推理。float16表示FP16，bfloat16表示BF16。如果不指定，则根据输入数据自动匹配数据类型。使用不同的dtype会影响模型精度。如果使用开源权重，建议不指定dtype，使用开源权重默认的dtype。
- --tensor-parallel-size：模型并行数。模型并行与流水线并行的乘积取值需要和启动的NPU卡数保持一致，可以参考[表1](https://support.huaweicloud.com/bestpractice-modelarts/modelarts_llm_infer_5908003.html#ZH-CN_TOPIC_0000002484417925__table598419217347)。此处举例为1，表示使用单卡启动服务。
- --pipeline-parallel-size：流水线并行数。模型并行与流水线并行的乘积取值需要和启动的NPU卡数保持一致，默认为1。当前仅支持pipeline-parallel-size为1。
- --block-size：kv-cache的block大小，推荐设置为128。
- --host=${docker_ip}：服务部署的IP，${docker_ip}替换为宿主机实际的IP地址，默认为None，举例：参数可以设置为0.0.0.0。
- --port：服务部署的端口。
- --gpu-memory-utilization：NPU使用的显存比例，复用原vLLM的入参名称，推荐值为0.95。
- --trust-remote-code：是否信任远程代码。添加该参数表示信任，不添加该参数表示不信任。
- --distributed-executor-backend：多卡推理启动后端，可选值为"ray"或者"mp"，其中"ray"表示使用ray进行启动多卡推理，"mp"表示使用python多进程进行启动多卡推理。默认使用"mp"后端启动多卡推理。
- --disable-async-output-proc：关闭异步后处理特性，关闭后性能会下降。
- --no-enable-prefix-caching：关闭prefix-caching，需要打开请参照[Prefix Caching](https://support.huaweicloud.com/bestpractice-modelarts/modelarts_llm_infer_5908014.html)
- --enforce-eager：未设置INFER_MODE环境变量时，部分模型会默认使用AclGraph图模式启动来提升性能，设置该参数后将关闭图模式。推荐Meta-Llama系列等非Qwen系列开启。
- --hf_overrides: vLLM推理引擎中用于覆盖Hugging Face模型默认配置的参数。当前只有Qwen3 Rerank类需要覆盖部分参数(见启动说明)。
#### 推理请求测试
使用命令测试推理服务是否正常启动。服务启动命令中的参数设置请参见[启动在线推理服务]。
通过OpenAI服务API接口启动服务使用以下推理测试命令。${docker_ip}替换为实际宿主机的IP地址。model参数必须填写。如果服务提供了served_model_name参数，取值与其保持一致。如果服务未提供served_model_name, 取值和服务的model参数，即模型在容器内的权重地址保持一致。端口9001和启动推理服务时的port参数保持一致。
rerank接口示例如下:
```
curl -X POST http://${docker_ip}:9001/v1/rerank \
-H "Content-Type: application/json" \
-d '{
"model": "/container_model/qwen3-reranker-8b",
"query": "What is the capital of France?",
"documents": [
"The capital of France is Paris",
"Reranking is fun!",
"vLLM is an open-source framework for fast AI serving"
]
}'
```
表1Rerank服务请求参数说明
| 参数 | 是否必选 | 默认值 | 参数类型 | 描述 |
|:---|:---|:---|:---|:---|
| model | 是 | 无 | Str | 如果服务提供了served_model_name参数，取值与其保持一致。如果服务未提供served_model_name, 取值和服务的model参数保持一致。 |
| query | 是 | 无 | Str | 用户查询文本 |
| documents | 是 | 无 | Str | 待排序文档列表（通常为Embedding召回的Top-K结果） |
使用OpenAI启动服务（仅支持V0启动），embeddings接口示例如下:
```
curl -X POST http://${docker_ip}:9001/v1/embeddings \
-H "Content-Type: application/json" \
-d '{
"model": "/container_model/qwen3-embedding-8b",
"input":"I love shanghai"
}'
```
表2Embedding服务请求参数说明
| 参数 | 是否必选 | 默认值 | 参数类型 | 描述 |
|:---|:---|:---|:---|:---|
| model | 是 | 无 | Str | 如果服务提供了served_model_name参数，取值与其保持一致。如果服务未提供served_model_name, 取值和服务的model参数保持一致。 |
| input | 是 | 无 | Str | 支持字符串或字符串列表 |