介绍 Qwen3-Embedding-4B 模型的本地化部署实践。该模型支持 32k 长文本，输出 2560 维向量，适用于检索和知识管理。教程提供两种方案：一是基于 llama.cpp 的轻量级部署，利用 GGUF 量化在消费级显卡运行；二是结合 vLLM 与 Open WebUI 构建可视化知识库系统，支持 RAG 检索。内容涵盖环境准备、模型下载、服务启动及接口调试，适合个人及企业构建语义搜索应用。
随着大模型在语义理解、信息检索和知识管理等场景的广泛应用，高质量的文本向量化能力成为构建智能系统的核心基础。通义千问团队于 2025 年 8 月开源了 Qwen3-Embedding-4B ——一款专为高效文本嵌入设计的中等规模双塔模型。该模型以 4B 参数量实现了对 32k 长文本的支持，输出 2560 维高精度向量，并在 MTEB 多项基准测试中超越同尺寸模型。
本文将围绕 的本地化部署实践展开，重点介绍如何结合 和 + 构建一个可交互、高性能的知识库服务系统。无论你是想在消费级显卡（如 RTX 3060）上运行语义搜索，还是希望搭建支持多语言、长文档的企业级知识引擎，本教程都能提供完整可落地的技术路径。
llama.cppvLLMOpen WebUIQwen3-Embedding-4B 是阿里云 Qwen3 系列中专注于「文本向量化」任务的专用模型，采用标准的 Dense Transformer 结构，共 36 层，基于双塔编码器架构进行训练。其核心目标是生成高质量、通用性强的句向量表示，适用于检索、聚类、分类等多种下游任务。
| 指标 | 表现 |
|---|---|
| 参数量 | 4B |
| 显存占用（FP16） | ~8 GB |
| GGUF 量化后体积（Q4_K_M） | ~3 GB |
| 向量维度 | 2560（可投影） |
| 上下文长度 | 32k tokens |
| MTEB (Eng.v2) | 74.60 |
| CMTEB (中文) | 68.09 |
| MTEB (Code) | 73.50 |
一句话总结： '4 B 参数，3 GB 显存，2560 维向量，32 k 长文，MTEB 英/中/代码三项 74+/68+/73+，可商用。'
得益于高效的结构设计和先进的训练策略，Qwen3-Embedding-4B 在 RTX 3060 这类消费级 GPU 上即可实现每秒处理 800+ 文档 的推理速度（使用 GGUF-Q4 量化版本），非常适合中小企业和个人开发者构建本地知识库系统。
llama.cpp 是一个用 C/C++ 编写的轻量级大模型推理框架，支持 CPU/GPU 混合计算，特别适合资源受限环境下的模型部署。它原生支持 GGUF 格式的量化模型，而 Qwen3-Embedding-4B 已发布官方 GGUF 镜像，可直接加载运行。
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
make clean && make LLAMA_CUBLAS=1 -j
注：
LLAMA_CUBLAS=1启用 NVIDIA GPU 加速，确保已安装 CUDA 驱动和 cuBLAS 库。
前往 Hugging Face 获取已转换的 GGUF 模型文件：
wget <model_url>
推荐使用 Q4_K_M 或 Q5_K_S 量化等级，在精度与性能之间取得良好平衡。
使用 main 可执行程序运行嵌入服务：
./main \
-m ./models/Qwen3-Embedding-4B-GGUF-Q4_K_M.gguf \
--port 8080 \
--embedding \
--n-gpu-layers 35 \
--batch-size 512 \
--threads 8
参数说明：
--embedding：启用向量输出模式--n-gpu-layers 35：尽可能多地将层卸载到 GPU（适用于 12GB 显存以上设备）--batch-size：批处理大小，影响吞吐量--port：HTTP API 端口服务启动后可通过以下接口获取向量：
POST http://localhost:8080/embedding
Content-Type: application/json
{
"content": "这是一段需要编码的中文文本"
}
响应示例：
{
"embedding": [0.123, -0.456, ..., 0.789],
"length": 2560,
"model": "Qwen3-Embedding-4B"
}
虽然 llama.cpp 提供了轻量级部署方案，但对于需要图形界面、用户交互和知识库管理的应用场景，推荐使用 vLLM + Open WebUI 组合构建完整的语义搜索平台。
docker run -d \
-p 3000:8080 \
-p 8888:8888 \
-e OPENAI_API_KEY=dummy \
-e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
-v open-webui:/app/backend/data \
--name open-webui \
ghcr.io/open-webui/open-webui:main
注意：若使用 Docker Desktop，
host.docker.internal可访问宿主机服务；Linux 用户需替换为实际 IP。
目前 vLLM 尚未内置 Qwen3-Embedding-4B 支持，但可通过自定义模型注册方式加载。
创建 embedding_model.py：
from vllm import LLM, SamplingParams
import torch
class Qwen3EmbeddingModel:
def __init__(self, model_path="Qwen/Qwen3-Embedding-4B"):
self.llm = LLM(
model=model_path,
tensor_parallel_size=1,
dtype="half",
gpu_memory_utilization=0.9,
enforce_eager=True,
max_model_len=32768
)
def encode(self, texts):
sampling_params = SamplingParams(temperature=0, max_tokens=1)
outputs = self.llm.generate(texts, sampling_params, use_tqdm=False)
embeddings = []
for output in outputs:
# 获取最后一层 [EDS] token 的隐藏状态
last_hidden_state = output.outputs[0].logprobs[-1]
embeddings.append(last_hidden_state.tolist())
return embeddings
启动 FastAPI 包装服务：
from fastapi import FastAPI
import uvicorn
app = FastAPI()
model = Qwen3EmbeddingModel()
@app.post("/v1/embeddings")
def get_embeddings(request: dict):
texts = request["input"]
vectors = model.encode(texts)
return {
"data": [
{"embedding": vec, "index": i} for i, vec in enumerate(vectors)
],
"model": "Qwen3-Embedding-4B",
"object": "list"
}
if __name__ == "__main__":
uvicorn.run(app, host="0.0.0.0", port=8000)
进入 Open WebUI 设置页面 → Model Settings → Embedding Provider：
Customhttp://<your-host-ip>:8000/v1Qwen3-Embedding-4B保存后即可在知识库上传功能中选择该模型进行文档向量化。
在 Open WebUI 中完成上述配置后，进入 Knowledge 页面，点击 'Add Knowledge Base'，选择刚刚注册的 Qwen3-Embedding-4B 模型作为编码器。
上传一份包含技术文档或多语言内容的 PDF 文件，系统会自动分块并调用 embedding 接口生成向量索引。
随后可在聊天窗口输入相关问题，例如：
'请总结这篇文档中关于气候变化的主要观点'
系统将执行 RAG 流程：
结果准确率明显优于传统 TF-IDF 或小尺寸 embedding 模型。
可通过浏览器开发者工具或代理工具（如 Charles）监控 /v1/embeddings 请求：
{
"input": [
"全球变暖是由于温室气体排放增加引起的。",
"Climate change poses risks to biodiversity."
]
}
返回的向量可用于进一步分析余弦相似度、聚类效果等。
Qwen3-Embedding-4B 凭借其 4B 参数、32k 上下文、2560 维高维向量、多语言支持和优异的 MTEB 表现，已成为当前开源社区中最值得尝试的中等规模 embedding 模型之一。无论是个人项目还是企业级应用，都可以借助其出色的性能和灵活的部署方式快速构建语义搜索系统。
本文介绍了两种主流部署路径：
llama.cpp + GGUF 模型，在 RTX 3060 等消费级显卡上实现低延迟、高吞吐的嵌入服务；vLLM + Open WebUI，打造支持知识库管理、RAG 检索和可视化交互的企业级 AI 助手。此外，模型支持 指令感知 和 在线维度压缩，极大提升了工程实用性。Apache 2.0 协议也为其商业化应用扫清了法律障碍。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
使用加密算法（如AES、TripleDES、Rabbit或RC4）加密和解密文本明文。 在线工具，加密/解密文本在线工具，online
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online