Qwen3-Embedding-4B从零开始：本地部署+接口调用完整流程

Qwen3-Embedding-4B从零开始：本地部署+接口调用完整流程

想自己搭建一个智能知识库，让电脑能“理解”你上传的文档，并精准回答你的问题吗？今天，我们就来手把手教你，如何用一台普通的游戏显卡（比如RTX 3060），把阿里最新开源的文本理解模型——Qwen3-Embedding-4B——部署到本地，并打造一个功能完整的知识库系统。

这个模型专门负责“文本向量化”，简单说，就是把一段文字（比如一篇文章、一个问题）转换成一串电脑能理解的数字（向量）。有了这个能力，电脑就能比较不同文字的相似度，从而实现智能搜索、问答和文档分类。它支持119种语言，能一口气处理长达32000个字的文档，性能在同类开源模型中名列前茅，最关键的是，个人和商业都能免费使用。

下面，我们就从零开始，带你走通整个流程。

1. 准备工作与环境搭建

在开始之前，我们先明确一下目标：我们将使用vLLM作为高性能的模型推理引擎，用Open WebUI来构建一个可视化的知识库管理界面。整个过程就像搭积木，我们把各个组件安装好，然后连接起来。

1.1 核心组件简介

• Qwen3-Embedding-4B：主角，负责将文本转化为向量的AI模型。
• vLLM：一个专门为高效运行大语言模型设计的推理引擎。它就像模型的“发动机”，能让模型跑得更快、更省资源。
• Open WebUI：一个开源的、类似ChatGPT的Web用户界面。我们将用它来管理知识库（上传文档、提问等），它背后会调用我们部署的模型。

1.2 一键部署（推荐）

为了让大家最快体验到效果，社区已经提供了预配置的镜像。这是最省心的方法。

1. 获取镜像：你可以访问模型社区页面，找到名为Qwen3-Embedding-4B的镜像。通常，页面会提供一个“一键部署”或类似的按钮。
2. 启动环境：点击部署后，系统会自动为你创建一个包含所有依赖（Python, vLLM, Open WebUI等）的云开发环境。稍等几分钟，等待初始化完成。
3. 访问服务：环境启动后，你会获得一个访问链接。通常，Open WebUI的默认端口是7860。如果你在Jupyter环境中，可能需要将地址中的端口号（如8888）手动改为7860来访问。

登录演示： 部署成功后，打开Web界面，你可以使用以下提供的演示账号登录（仅用于体验功能）：

账号：[e-mail] 密码：kakajiang

1.3 手动部署（适用于本地或自有服务器）

如果你想在自己的电脑或服务器上部署，可以按照以下步骤操作。这里假设你已有基本的Linux命令和Python环境知识。

步骤一：安装vLLM并启动模型服务首先，我们需要让模型“跑起来”。在终端中执行以下命令：

# 1. 安装vLLM (推荐使用Python虚拟环境) pip install vllm # 2. 启动Qwen3-Embedding-4B模型服务 # --model 指定模型路径或名称，vLLM支持从Hugging Face自动下载 # --served-model-name 定义服务名称，后续API会用到 # --port 指定服务端口，这里用8000 vllm serve Qwen/Qwen3-Embedding-4B \ --served-model-name qwen-embedding \ --port 8000

命令执行后，vLLM会下载模型（如果本地没有）并启动一个HTTP API服务。看到类似“Uvicorn running on http://0.0.0.0:8000”的输出，就说明模型服务启动成功了。这个服务提供了标准的OpenAI兼容的API接口。

步骤二：安装并配置Open WebUI接下来，我们安装知识库的“前台界面”。

# 1. 拉取Open WebUI的Docker镜像（这是最简单的方式） docker pull ghcr.io/open-webui/open-webui:main # 2. 运行Open WebUI容器，并将其连接到模型服务 # -e 设置环境变量，这里告诉WebUI我们的Embedding模型API地址 docker run -d \ --name open-webui \ -p 7860:8080 \ -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \ -e EMBEDDINGS_API_URL=http://host.docker.internal:8000/v1 \ -e EMBEDDINGS_MODEL_NAME=qwen-embedding \ ghcr.io/open-webui/open-webui:main

• -p 7860:8080：将容器的8080端口映射到本机的7860端口，这样你就能通过http://localhost:7860访问界面了。
• EMBEDDINGS_API_URL：这个变量至关重要，它指向了我们刚刚启动的vLLM模型服务（http://host.docker.internal:8000/v1）。host.docker.internal是一个特殊域名，让容器能访问宿主机的服务。
• EMBEDDINGS_MODEL_NAME：需要和启动vLLM时设置的--served-model-name一致。

等待容器启动后，打开浏览器访问http://localhost:7860，注册一个账号，就可以开始使用了。

2. 在Open WebUI中配置与验证

服务都跑起来后，我们进入Open WebUI界面进行关键配置，确保它正确使用了我们部署的Qwen3-Embedding模型。

2.1 设置Embedding模型

1. 登录Open WebUI后，点击左下角的用户名，进入设置（Settings）。
2. 在设置侧边栏，找到并点击模型（Models）。
3. 你会看到Embedding 模型的设置区域。将自定义 Embedding API的开关打开。
4. 在API 地址中填入：http://localhost:8000/v1（如果你按上述步骤部署）。
5. 在模型名称中填入：qwen-embedding。
6. 点击保存。

这个步骤相当于告诉Open WebUI：“别用你自带的或者网上的模型，去连接我本地8000端口那个服务，用名字叫qwen-embedding的模型来处理文本向量。”

2.2 创建知识库并验证效果

配置完成后，我们就可以测试模型的实际能力了。

1. 创建知识库：在WebUI主界面，点击左侧的知识库（Knowledge Base），然后点击+ 新建知识库，给它起个名字，比如“测试库”。
2. 上传文档：进入新建的知识库，点击上传按钮，上传一个TXT、PDF或Word文档。例如，你可以上传一篇技术文章或一份产品说明书。
3. 等待处理：上传后，Open WebUI会自动调用我们配置的Qwen3-Embedding模型，将文档切片并转换成向量，存储到向量数据库中。这个过程称为“嵌入（Embedding）”。
4. 进行问答测试：回到聊天主界面。在输入框上方，确保选择了你刚创建的“测试库”作为知识源。然后，你就可以针对上传文档的内容提问了。
   • 示例：如果你上传了一篇关于Python编程的教程，你可以问“如何定义一个函数？”。
   • 效果：系统会先从知识库中（通过向量相似度搜索）找到与问题最相关的文档片段，然后将这些片段和你的问题一起发送给对话模型（如果你也部署了的话，如Qwen2.5-7B），最终生成一个准确的答案。如果只部署了Embedding模型，WebUI也会展示它检索到的相关文档片段。

通过这个流程，你可以直观地感受到Qwen3-Embedding-4B模型的理解和检索能力。它能够从长文档中精准定位到与问题相关的部分。

3. 直接调用API接口

除了通过WebUI，我们也可以直接通过编程调用模型的API，这为集成到自己的应用程序中提供了可能。vLLM提供的API是OpenAI兼容的。

3.1 调用Embedding接口

下面是一个使用Pythonrequests库调用嵌入接口的示例。假设你的模型服务运行在http://localhost:8000。

import requests import json # API端点 url = "http://localhost:8000/v1/embeddings" # 请求头 headers = { "Content-Type": "application/json" } # 请求数据：输入你想要向量化的文本 data = { "model": "qwen-embedding", # 模型名称，与启动时一致 "input": "通义千问是阿里云推出的大语言模型" } # 发送POST请求 response = requests.post(url, headers=headers, data=json.dumps(data)) # 检查响应 if response.status_code == 200: result = response.json() # 提取生成的向量（一个包含2560个浮点数的列表） embedding_vector = result['data'][0]['embedding'] print(f"向量维度：{len(embedding_vector)}") print(f"向量前10维：{embedding_vector[:10]}") else: print(f"请求失败，状态码：{response.status_code}") print(response.text)

运行这段代码，你会得到一个长度为2560的列表，这就是句子“通义千问是阿里云推出的大语言模型”的向量表示。你可以用同样的方法处理其他文本，然后通过计算向量之间的余弦相似度，来判断它们的语义是否相近。

3.2 接口请求示例

当你通过Open WebUI进行问答时，实际上后台也是发起了类似的API调用。你可以在Open WebUI的“设置” -> “高级”中开启日志，或者在服务端的控制台，看到这些真实的请求和响应，这对于调试和理解整个工作流非常有帮助。

4. 总结

通过以上步骤，我们完成了从零部署Qwen3-Embedding-4B模型到构建可用知识库的全流程。我们来回顾一下关键点：

1. 模型选择：Qwen3-Embedding-4B是一个在精度、速度和资源消耗上取得很好平衡的文本向量化模型，特别适合个人开发者或中小团队在单卡（如RTX 3060）环境下搭建语义搜索应用。
2. 部署核心：使用vLLM部署模型能获得极佳的推理性能，而Open WebUI则提供了一个功能强大且美观的开箱即用界面，两者结合大大降低了搭建RAG（检索增强生成）应用的门槛。
3. 流程关键：成功的关键在于正确配置Open WebUI中的EMBEDDINGS_API_URL，确保前端界面能连接到后端的模型推理服务。
4. 灵活应用：你既可以通过WebUI快速体验和管理知识，也可以通过直接调用API，将模型的嵌入能力集成到你自己的Python脚本、网站或应用程序中。

现在，你可以开始上传你自己的文档资料，构建专属的智能知识助手了。无论是学习笔记、项目文档还是公司内部资料，都能通过这个系统变得可查询、可对话。

---

获取更多AI镜像

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