Qwen3-Embedding-4B部署教程：Jupyter与WebUI双模式切换

1. 模型简介：通义千问3-Embedding-4B向量化模型

Qwen3-Embedding-4B 是阿里云通义千问（Qwen）系列中专为文本向量化设计的中等规模双塔模型，参数量为40亿（4B），于2025年8月正式开源。该模型在语义理解、跨语言检索和长文本处理方面表现出色，适用于构建高质量的知识库系统、语义搜索服务以及多语言内容分析平台。

其核心定位是“中等体量、支持32k长上下文、输出2560维向量、覆盖119种语言”，兼顾推理效率与表达能力，特别适合单卡部署场景下的高性价比语义编码需求。

1.1 核心特性概览

• 结构设计：采用36层Dense Transformer架构，基于双塔编码器结构，通过取末尾[EDS] token的隐藏状态生成句向量。
• 向量维度：默认输出2560维向量，支持MRL（Matrix Rank Learning）机制，在运行时可动态投影至32~2560之间的任意维度，灵活平衡精度与存储开销。
• 上下文长度：最大支持32,768 token输入，能够完整编码整篇论文、法律合同或大型代码文件，避免分段截断带来的信息损失。
• 多语言能力：覆盖119种自然语言及主流编程语言，在跨语言检索、双语文本对挖掘任务中达到官方评估S级性能。
• 基准表现优异：
• MTEB (English v2)：74.60
• CMTEB (中文)：68.09
• MTEB (Code)：73.50
  在同尺寸开源embedding模型中全面领先。
• 指令感知能力：无需微调，只需在输入前添加任务描述前缀（如“为检索生成向量”），即可让同一模型自适应输出用于检索、分类或聚类的专用向量表示。
• 部署友好性：
• FP16精度下模型体积约8GB；
• 支持GGUF-Q4量化格式，压缩后仅需3GB显存；
• 在RTX 3060上可达每秒800文档的编码速度；
• 已集成vLLM、llama.cpp、Ollama等主流推理框架；
• 遵循Apache 2.0开源协议，允许商用。

1.2 适用选型建议

“单卡RTX 3060用户若需实现119语种语义搜索或长文档去重，可直接拉取Qwen3-Embedding-4B的GGUF镜像进行部署。”

该模型尤其适合以下应用场景： - 构建企业级知识库的语义索引 - 多语言内容推荐系统 - 代码片段相似度匹配 - 文档聚类与去重 - 跨语言问答系统底座

2. 部署方案设计：vLLM + Open-WebUI 架构整合

为了最大化用户体验与开发灵活性，本文提供基于vLLM 加速推理 + Open-WebUI 可视化交互的双模部署方案，支持在 Jupyter Notebook 和 Web 浏览器界面之间自由切换使用。

2.1 整体架构说明

本方案采用容器化部署方式，利用 Docker Compose 统一管理多个服务组件：

• vLLM：负责加载 Qwen3-Embedding-4B 模型并提供高性能异步推理 API
• Open-WebUI：前端可视化界面，支持知识库上传、查询测试与接口调试
• Nginx（可选）：反向代理，统一端口暴露服务
• Jupyter Lab：提供 Python 编程环境，便于开发者调试 embedding 接口

所有服务共享 GPU 资源，通过本地网络互通，形成一体化 AI 应用开发平台。

2.2 环境准备

硬件要求

软件依赖

• Ubuntu 20.04 或更高版本
• NVIDIA Driver ≥535
• CUDA Toolkit ≥12.1
• Docker & Docker Compose
• nvidia-container-toolkit

# 安装 NVIDIA 容器工具包 distribution=$(. /etc/os-release;echo $ID$VERSION_ID) curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add - curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list sudo apt-get update && sudo apt-get install -y nvidia-docker2 sudo systemctl restart docker

3. 实战部署流程：从零搭建双模式系统

3.1 获取模型文件

目前 Qwen3-Embedding-4B 已发布 GGUF 量化版本，推荐使用 Q4_K_M 级别以获得最佳性能/体积比。

# 创建模型目录 mkdir -p /opt/models/qwen3-embedding-4b # 下载 GGUF-Q4 量化模型（示例链接） wget -O /opt/models/qwen3-embedding-4b/qwen3-embedding-4b-q4.gguf \ https://huggingface.co/Qwen/Qwen3-Embedding-4B-GGUF/resolve/main/qwen3-embedding-4b-Q4_K_M.gguf

也可从 Hugging Face Hub 直接拉取原始 FP16 模型用于 vLLM：

git lfs install git clone https://huggingface.co/Qwen/Qwen3-Embedding-4B /opt/models/qwen3-embedding-4b-hf

3.2 启动 vLLM 服务

创建docker-compose.yml文件：

version: '3.8' services: vllm: image: vllm/vllm-openai:latest container_name: vllm_embedding runtime: nvidia environment: - NVIDIA_VISIBLE_DEVICES=0 ports: - "8000:8000" volumes: - /opt/models/qwen3-embedding-4b-hf:/model command: - "--model=/model" - "--dtype=half" - "--tensor-parallel-size=1" - "--enable-auto-tool-call-parsing=False" - "--disable-log-requests" deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu]

启动服务：

docker compose up -d vllm

等待数分钟，直到日志显示Uvicorn running on http://0.0.0.0:8000表示服务就绪。

3.3 部署 Open-WebUI

添加 Open-WebUI 到docker-compose.yml：

webui: image: ghcr.io/open-webui/open-webui:main container_name: open-webui ports: - "7860:8080" environment: - VLLM_ENDPOINT=http://vllm:8000 volumes: - ./webui_data:/app/backend/data depends_on: - vllm

启动 WebUI：

docker compose up -d webui

访问http://localhost:7860进入图形界面。

3.4 配置 Jupyter Notebook 开发环境

添加 Jupyter 服务：

jupyter: image: jupyter/scipy-notebook:latest container_name: jupyter_notebook ports: - "8888:8888" volumes: - ./notebooks:/home/jovyan/work environment: - JUPYTER_ENABLE_LAB=yes command: start-notebook.sh --NotebookApp.token='kakajiang' --ip=0.0.0.0

启动 Jupyter：

docker compose up -d jupyter

访问http://localhost:8888并输入 tokenkakajiang登录。

4. 使用说明：Jupyter 与 WebUI 双模式切换

系统部署完成后，用户可通过两种方式使用 Qwen3-Embedding-4B 模型。

4.1 WebUI 模式：可视化操作知识库

打开浏览器访问http://localhost:7860，首次使用需注册账号。演示账户如下：

账号：kakajiang@kakajiang.com
密码：kakajiang

设置 Embedding 模型

1. 进入「Settings」→「Embeddings」
2. 选择 Provider 为vLLM
3. 填写 API 地址：http://vllm:8000（容器内）或http://host-ip:8000（外部访问）
4. 模型名称填写：Qwen3-Embedding-4B

保存后即可启用模型进行知识库构建。

知识库验证流程

1. 创建新知识库，命名如test_kb
2. 上传 PDF、TXT 或 Markdown 文件（支持长文档）
3. 系统自动调用 vLLM 接口生成 embedding 向量并存入向量数据库
4. 提出语义问题（如“这份合同的关键条款是什么？”）
5. 查看返回的相关段落是否准确匹配

4.2 Jupyter 模式：编程调用 embedding 接口

切换至 Jupyter 环境，将 URL 中的8888修改为7860即可在 WebUI 与 Notebook 间自由跳转。

示例代码：调用 vLLM embedding API

import requests import numpy as np # vLLM OpenAI 兼容接口地址 EMBEDDING_URL = "http://localhost:8000/embeddings" # 测试文本 texts = [ "人工智能是未来科技的核心驱动力。", "Machine learning enables computers to learn from data.", "这份合同规定了双方的权利与义务。" ] def get_embeddings(texts): payload = { "model": "Qwen3-Embedding-4B", "input": texts } response = requests.post(EMBEDDING_URL, json=payload) if response.status_code == 200: result = response.json() embeddings = [item["embedding"] for item in result["data"]] return np.array(embeddings) else: raise Exception(f"Request failed: {response.status_code}, {response.text}") # 获取向量 embeddings = get_embeddings(texts) print("Embedding shape:", embeddings.shape) # 输出: (3, 2560)

计算余弦相似度示例

from sklearn.metrics.pairwise import cosine_similarity similarity_matrix = cosine_similarity(embeddings) print("Similarity Matrix:") print(similarity_matrix)

查看实际请求日志

可通过抓包工具或查看 vLLM 日志确认请求细节：

{ "model": "Qwen3-Embedding-4B", "input": ["人工智能...", "Machine learning..."], "encoding_format": "float" }

响应返回标准 OpenAI 格式 embedding 数组。

5. 总结

本文详细介绍了如何部署 Qwen3-Embedding-4B 模型，并构建一个支持Jupyter 编程调试与WebUI 可视化操作的双模式应用系统。

5.1 核心价值总结

• 高性能推理：借助 vLLM 实现低延迟、高吞吐的 embedding 生成，RTX 3060 上轻松应对每秒数百文档的编码需求。
• 灵活使用模式：
• WebUI 模式适合非技术人员快速搭建知识库；
• Jupyter 模式便于开发者集成到现有 pipeline 中。
• 多语言长文本支持：32k上下文 + 119语种覆盖，满足复杂业务场景需求。
• 商用合规：Apache 2.0 协议授权，允许企业级应用部署。

5.2 最佳实践建议

1. 优先使用 GGUF-Q4 模型：对于资源受限设备，推荐使用 llama.cpp + GGUF 方案进一步降低显存占用。
2. 合理设置 batch size：在 vLLM 中根据显存调整max_num_seqs参数，避免 OOM。
3. 启用缓存机制：对重复文本做 embedding 缓存，提升整体系统效率。
4. 定期更新模型：关注 Qwen 官方仓库，及时获取性能优化版本。

通过本教程，您已具备完整部署和使用 Qwen3-Embedding-4B 的能力，可用于构建下一代智能知识管理系统。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。