跳到正文
LEo的网络日志
返回

在 kubernetes 上运行 qwen3 embedding:从文本到向量服务

搜索一篇文章时,我们输入的词可能和文章原文不完全一样。例如,搜索“怎么让机器理解文字”,也许希望找到介绍“文本向量化”的文章。

怎样让计算机判断这两句话在意思上接近?一种做法是把文字交给 embedding 模型,转换为一组数字,再比较数字的方向。这组数字就是向量。

本文结合一次昇腾单卡实践,介绍如何使用 Qwen3-Embedding-0.6B 提供向量接口,并整理一个通用的 kubernetes 部署示例。读完后,你应该能看懂模型和运行镜像分别是什么、需要哪些条件,以及如何验证服务有没有真正返回向量。

先说清楚范围:实际实践完成了容器内和集群内 Service 的基础推理验证。下面的 kubernetes 清单是根据实际参数整理的示例,没有逐字在相同环境中验证;镜像、存储、设备插件与权限必须按自己的集群调整。

1 embedding 做什么

Qwen3-Embedding-0.6B 将文本转为向量,可供相似度比较和检索。它不是向量数据库,也不负责生成回答。模型默认输出 1024 维向量,原生支持最长 32K 上下文;服务允许的长度由启动参数决定。模型卡介绍了多语言与检索指令。

2 一次运行需要哪些东西

模型文件提供权重、分词器和池化配置,vllm ascend 负责加载和推理,kubernetes 负责设备、存储与服务管理。更多基础概念见 vllm 入门。

本次实践使用一张昇腾 910B 系列卡、ARM64 节点、vllm 0.23.0 和 vllm ascend 0.23.0.post1 相关运行环境。给服务分配了 4 核 CPU、16 GiB 内存和 1 张卡;这是一组实测配置,不是官方公布的最低资源要求。

实际使用的镜像是在对应运行环境上做过普通用户身份适配的镜像。它不是可以直接公开拉取的官方原版。本次没有用官方原版镜像完成该模型的端到端验证,不能把两者说成完全相同。

对于 A2 系列设备,vllm ascend 0.23.0 的模型教程给出的官方镜像示例是:

quay.io/ascend/vllm-ascend:v0.23.0.post1

它可以作为选择镜像的起点,不能保证直接适配任何环境。芯片系列、CPU 架构、驱动、cann、容器运行时和镜像版本都要核对;最好固定镜像摘要。尤其是在非 root 环境,要检查运行身份、文件权限、日志和缓存目录是否可写。版本配套说明可用于核对软件组合。

维护状态也要单独看。 写作时,0.23.0 的支持矩阵将该模型在 A2/A3 上标为实验性;另有更新的支持矩阵将其标为不再维护。版本不同,结论也不能混在一起。正式使用前应重新查证所选版本的支持状态并评估维护风险。

3 部署前先准备什么

先确认以下条件:

  1. kubernetes 集群已经可用,目标节点的驱动能识别昇腾设备。
  2. 已安装并配置对应设备插件和容器运行时;节点能报告可分配的 NPU 资源。资源名称和 runtimeclass 名称以自己的集群为准。
  3. 已选择与节点架构、驱动及 cann 匹配的镜像,并核实容器运行用户可以读取模型、写入临时目录。
  4. 模型文件已准备在集群可读取的存储上,创建好指向模型目录的 PVC;所有将运行服务的节点都要能访问该存储。

可以先查看节点和资源。例如,下面的资源名只是本实践使用的名称,其他设备插件可能不同:

kubectl get nodes -o wide
NODE_NAME=your-npu-node  # 替换为实际节点名
kubectl describe node "$NODE_NAME"
kubectl get runtimeclass

在节点详情中查看 huawei.com/Ascend910 的容量和可分配量。能看到资源,只说明 kubernetes 已登记该资源;还要确认设备健康、容器运行时和业务调度策略。

模型可以从 ModelScope 模型页面或 Hugging Face 模型页面获取。下载时保留完整目录,包括权重、分词器、配置和池化配置;不要只复制一个权重文件。选择并记录具体模型版本,再按来源校验文件。

例如,已有 hf 工具且可以访问模型仓库时,可用下面的方式下载至准备好的目录;下载和向共享存储复制文件需要按自己环境的流程执行。工具文档说明了 --local-dir 和 --revision 的用法。

MODEL_REVISION=your-model-revision  # 替换为已核对的提交号或版本
hf download Qwen/Qwen3-Embedding-0.6B \
  --revision "$MODEL_REVISION" \
  --local-dir ./qwen3-embedding-0.6b

本次验证对实际挂载的 model.safetensors 做了 SHA-256 核对,与当时的官方权重一致;其他文件没有逐一校验。因此,这只能证明该权重文件一致,不能代表整套模型文件都已核验。

4 先看服务启动命令

假设模型完整目录已经只读挂载到容器 /models,核心命令是:

vllm serve /models \
  --served-model-name Qwen/Qwen3-Embedding-0.6B \
  --runner pooling \
  --port 8000 \
  --max-model-len 1024

这里的 /models 是容器内路径,不是模型在每台机器上的固定路径。--runner pooling 让服务按向量任务运行;--served-model-name 是调用接口时使用的名称;端口为 8000。

--max-model-len 1024 参考了官方 A2/A3 示例。它限制的是这个服务单次请求可处理的长度,指令和特殊 token 也会占用长度;不能把它理解为模型最多只支持 1024 token。需要更长输入时,应评估内存、显存和性能,再调整并重新验证。

5 一个 kubernetes 部署示例

下面示例的目标是让读者看清组成关系。不要直接把它当成已经验证的生产清单。 使用前需要:

将下面内容保存为 embedding.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: qwen3-embedding
spec:
  replicas: 1
  strategy:
    type: Recreate
  selector:
    matchLabels:
      app: qwen3-embedding
  template:
    metadata:
      labels:
        app: qwen3-embedding
    spec:
      runtimeClassName: ascend
      containers:
        - name: embedding
          image: REPLACE_WITH_VALIDATED_ARM64_IMAGE
          command: ["vllm", "serve"]
          args:
            - /models
            - --served-model-name
            - Qwen/Qwen3-Embedding-0.6B
            - --runner
            - pooling
            - --port
            - "8000"
            - --max-model-len
            - "1024"
          env:
            - name: HOME
              value: /tmp
            - name: XDG_CACHE_HOME
              value: /tmp/.cache
            - name: XDG_CONFIG_HOME
              value: /tmp/.config
            - name: HF_HOME
              value: /tmp/huggingface
          ports:
            - name: http
              containerPort: 8000
          resources:
            requests:
              cpu: "4"
              memory: 16Gi
            limits:
              cpu: "4"
              memory: 16Gi
              huawei.com/Ascend910: 1
          startupProbe:
            httpGet:
              path: /health
              port: http
            periodSeconds: 10
            failureThreshold: 60
          readinessProbe:
            httpGet:
              path: /health
              port: http
            periodSeconds: 10
            failureThreshold: 3
          volumeMounts:
            - name: model
              mountPath: /models
              readOnly: true
      volumes:
        - name: model
          persistentVolumeClaim:
            claimName: model-pvc
            readOnly: true
---
apiVersion: v1
kind: Service
metadata:
  name: qwen3-embedding
spec:
  type: ClusterIP
  selector:
    app: qwen3-embedding
  ports:
    - name: http
      port: 8000
      targetPort: http

runtimeClassName 选择容器运行时;NPU 的资源限制申请一张卡;PVC 将模型文件只读交给容器;Service 在集群内部提供稳定入口。Recreate 避免更新时默认同时创建两个副本,但更新期间会有服务中断。

示例增加了启动探针和就绪探针,这是对实际验证配置的改进,不是对当时配置的原样复述。启动探针给模型加载和编译留时间;就绪探针在健康接口可用前不把流量交给容器。示例最多等待约 10 分钟,具体值要根据实测调整;超时会导致容器重启。kubernetes 探针说明解释了这两种探针的区别。

调整并审查清单后,在自己的测试集群中执行:

kubectl apply -f embedding.yaml
kubectl rollout status deployment/qwen3-embedding --timeout=15m
kubectl get pods -l app=qwen3-embedding -o wide
kubectl logs -l app=qwen3-embedding --tail=100
kubectl get service qwen3-embedding

首次启动可能需要加载权重、编译和预热。如果长时间没有就绪,先看 pod 的事件和日志,不要只看列表上的运行状态。这个清单没有配置外部访问入口或认证;要对集群外提供服务,需要另行设计访问控制和安全连接。

6 调用接口,确认真的有向量

在本机另开一个终端,建立临时端口转发并保持运行:

kubectl port-forward service/qwen3-embedding 8000:8000

回到原终端,先检查健康和模型列表:

curl -fsS http://127.0.0.1:8000/health
curl -fsS http://127.0.0.1:8000/v1/models

再提交一条文本。下面的 model 要与启动参数中的服务名一致:

curl -fsS http://127.0.0.1:8000/v1/embeddings \
  -H 'Content-Type: application/json' \
  -d '{"model":"Qwen/Qwen3-Embedding-0.6B","input":"怎样部署文本向量服务?"}'

成功时,返回的 JSON 中 data 包含 embedding 数组。向量很长,不必人工逐个查看;可以用下面的 Python 示例发送批量请求,检查数量、维度、有限数值和向量长度,并比较两组相似度:

import json
import math
import urllib.request

texts = ["怎样部署文本向量服务?", "如何运行文字向量模型?", "今天晚餐吃什么?"]
body = json.dumps({"model": "Qwen/Qwen3-Embedding-0.6B", "input": texts}).encode("utf-8")
request = urllib.request.Request(
    "http://127.0.0.1:8000/v1/embeddings",
    data=body,
    headers={"Content-Type": "application/json"},
    method="POST",
)
with urllib.request.urlopen(request, timeout=120) as response:
    result = json.load(response)

items = sorted(result["data"], key=lambda item: item["index"])
vectors = [item["embedding"] for item in items]
assert len(vectors) == len(texts)
assert all(len(v) == 1024 and all(math.isfinite(x) for x in v) for v in vectors)

def norm(vector):
    return math.sqrt(sum(x * x for x in vector))

def cosine(a, b):
    return sum(x * y for x, y in zip(a, b)) / (norm(a) * norm(b))

print("向量数量:", len(vectors))
print("每个向量的维度:", [len(v) for v in vectors])
print("向量长度:", [round(norm(v), 4) for v in vectors])
print("相近文本相似度:", round(cosine(vectors[0], vectors[1]), 4))
print("另一文本相似度:", round(cosine(vectors[0], vectors[2]), 4))

保存为 check-embedding.py 后运行 python3 check-embedding.py。上面是演示输入,不保证在所有版本上得到相同排序;业务检索效果需要用自己的数据评估。测试结束后,在端口转发终端按 Ctrl+C 即可关闭转发。

模型方建议检索任务按场景为查询侧加入任务指令,文档侧通常不加。指令本身也会占用输入长度;具体提示和效果应结合实际检索数据验证,而不是把一次示例结果当成普遍结论。

7 实际验证得到了什么

本次实践使用上述核心启动参数和单卡资源,模型权重以只读方式挂载。服务日志确认 BF16、单卡和 last-token pooling;健康检查返回 HTTP 200。

在容器内,单条请求和三条批量请求均返回 HTTP 200,每条输出 1024 个有限数值,向量长度约为 1;相同输入在单条与批量中的输出逐值一致。一组测试中,相近文本的余弦相似度约为 0.845,另一条不相关文本约为 0.182。通过集群内 Service 再调用健康检查、模型列表和单条向量接口,也得到 HTTP 200。

这些结果说明:在本次选定的硬件、镜像、模型和参数组合下,基础向量推理跑通了。 它不证明其他镜像或集群也一定可用,更不等同于并发、吞吐、长文本、长期稳定性和生产验收。

8 两个容易忽略的问题

运行用户没有可写目录

本次普通用户因默认主目录不可写而启动失败,将 HOME、XDG_CACHE_HOME、XDG_CONFIG_HOME 和 HF_HOME 指向可写的 /tmp 后恢复。应检查当前镜像的运行身份和缓存路径;临时目录不保证持久化,避免直接放宽宿主机权限。普通用户身份解析和算子访问问题另见故障排查,它们与缓存不可写是不同问题。

权重很小,显存不一定只占一点

本次权重文件约 1.1 GiB,但服务启动后,整张 64 GiB 卡观测到约 61 GiB 显存占用。模型权重只是显存的一部分;运行时还可能为缓存和计算预留空间。这个数字是本次配置下的观测,不是模型的最低显存要求,也不是所有部署的固定占用。

如果要降低占用,应先了解所选版本的内存配置、输入长度与并发参数,再通过实际负载验证;不要只凭权重大小决定能否部署。模型换版本、改变服务参数或设备后,也应重新测量。



上一篇
从模型文件到推理服务:一篇文章认识 vllm
下一篇
在 kubernetes 上运行 qwen3 reranker:让检索结果重新排序