Qwen3-Embedding-4B部署教程：JupyterLab调用验证步骤-开发者社区

Qwen3-Embedding-4B部署教程：JupyterLab调用验证步骤

1. Qwen3-Embedding-4B介绍

Qwen3 Embedding 模型系列是 Qwen 家族中专为文本嵌入和排序任务设计的最新成员，基于强大的 Qwen3 系列基础模型构建。该系列涵盖多种参数规模（0.6B、4B 和 8B），适用于不同性能与效率需求的场景。其中，Qwen3-Embedding-4B 是一个在功能与资源消耗之间取得良好平衡的中等规模模型，特别适合需要高质量语义表示但又受限于计算资源的应用。

这一系列模型继承了 Qwen3 在多语言理解、长文本处理以及逻辑推理方面的优势，广泛适用于文本检索、代码搜索、分类聚类、双语对齐等多种下游任务。无论你是做信息检索系统、智能客服知识库，还是跨语言内容分析，Qwen3 Embedding 都能提供强有力的向量支持。

1.1 核心优势一览

卓越的多功能性：Qwen3-Embedding-8B 在 MTEB 多语言排行榜上位列第一（截至2025年6月5日，得分为70.58），而整个系列在各类文本嵌入和重排序任务中均表现优异。
全面的灵活性：支持从0.6B到8B的全尺寸选择，开发者可根据实际需求灵活搭配嵌入与重排序模块。同时允许自定义输出维度（32~2560）和任务指令，提升特定场景下的表现力。
强大的多语言能力：覆盖超过100种自然语言及主流编程语言，具备出色的跨语言检索和代码语义匹配能力，非常适合国际化产品或技术文档处理场景。

这些特性使得 Qwen3-Embedding 成为企业级AI应用中不可或缺的一环，尤其适合希望快速集成高质量语义向量服务的技术团队。

2. Qwen3-Embedding-4B模型概述

作为该系列中的主力型号之一，Qwen3-Embedding-4B 在保持高性能的同时兼顾了推理效率，是许多生产环境的理想选择。

2.1 关键参数说明

属性	值
模型类型	文本嵌入（Text Embedding）
参数量	40亿（4B）
支持语言	超过100种自然语言 + 编程语言
上下文长度	最高支持32,768 tokens
嵌入维度	可配置范围：32 ~ 2560，默认为2560

这个模型不仅能处理超长文本（如整篇论文或技术文档），还允许用户根据下游任务的需求调整输出向量的维度。例如，在内存敏感的移动端应用中，可以将维度设置为较低值（如128或256）以减少存储开销；而在高精度检索系统中，则可使用完整2560维向量来最大化语义表达能力。

此外，它支持通过指令（instruction）引导嵌入方向，比如指定“请将这段文字用于问答匹配”或“这是中文到英文的翻译任务”，从而让生成的向量更贴合具体应用场景。

3. 基于SGLang部署Qwen3-Embedding-4B向量服务

要使用 Qwen3-Embedding-4B 提供本地化的向量服务，推荐使用 SGLang 进行快速部署。SGLang 是一个高效的大模型推理框架，支持 OpenAI 兼容接口，便于集成到现有系统中。

3.1 部署准备

确保你的运行环境满足以下条件：

Python >= 3.10
GPU 显存 ≥ 16GB（建议使用 A10/A100 或同级别显卡）
已安装sglang和相关依赖

你可以通过 pip 安装 SGLang：

pip install sglang

3.2 启动本地向量服务

使用 SGLang 快速启动 Qwen3-Embedding-4B 的嵌入服务，执行如下命令：

python -m sglang.launch_server \ --model-path Qwen/Qwen3-Embedding-4B \ --port 30000 \ --api-key EMPTY \ --host 0.0.0.0

注意：
--model-path指定 Hugging Face 上的模型路径，需提前下载或自动拉取。
--port 30000表示服务将在本地 30000 端口开放。
--api-key EMPTY表示无需认证，适合内网测试环境。
若你已将模型缓存至本地，可替换为绝对路径。

启动成功后，你会看到类似以下的日志输出：

INFO: Started server process [PID] INFO: Waiting for model to load... INFO: Model loaded successfully. Embedding server is ready.

此时，服务已准备好接收来自客户端的嵌入请求。

4. 打开 JupyterLab 进行模型调用验证

接下来我们进入 JupyterLab 环境，编写 Python 脚本调用本地部署的 Qwen3-Embedding-4B 模型，完成一次完整的嵌入测试。

4.1 安装 OpenAI 客户端

虽然我们不是在调用 OpenAI 的 API，但由于 SGLang 提供了兼容 OpenAI 接口的服务，因此可以直接使用openai包进行交互。

pip install openai

4.2 编写调用代码

在 Jupyter Notebook 中新建一个 cell，输入以下代码：

import openai # 创建客户端，连接本地服务 client = openai.Client( base_url="http://localhost:30000/v1", api_key="EMPTY" # 因为没有真实密钥，设为空 ) # 发起嵌入请求 response = client.embeddings.create( model="Qwen3-Embedding-4B", input="How are you today" ) # 查看返回结果 print(response)

4.3 输出解析

执行上述代码后，你应该会看到类似如下的响应结构：

EmbeddingResponse( data=[ { 'object': 'embedding', 'embedding': [-0.023, 0.041, ..., 0.018], # 长度为指定维度的浮点数列表 'index': 0 } ], model='Qwen3-Embedding-4B', usage={'prompt_tokens': 5, 'total_tokens': 5} )

这表明模型已经成功将输入文本"How are you today"转换成了一个高维语义向量。你可以提取response.data[0].embedding得到具体的向量数组，用于后续的相似度计算、聚类或检索任务。

4.4 多语言与长文本测试建议

为了进一步验证模型能力，建议尝试以下几种扩展测试：

多语言输入：传入中文、法语、日语等句子，观察是否都能正常生成向量。

input_texts = [ "今天天气真好", "Le ciel est bleu aujourd'hui", "今日の天気はとても良いです" ] response = client.embeddings.create(model="Qwen3-Embedding-4B", input=input_texts)