介绍 Qwen3-Embedding-4B 模型的本地化部署流程。涵盖环境准备、模型转换（PyTorch 转 GGUF）、llama.cpp 服务启动及 Open WebUI 知识库集成。通过量化优化显存占用，结合 vLLM 提供 API 接口，实现长文本向量化与语义搜索功能。适用于跨语言检索、文档去重等场景，支持 Apache 2.0 商用许可。
通义千问 3-Embedding-4B 是阿里云 Qwen3 系列中专为文本向量化任务设计的高性能模型，参数规模达 40 亿，支持高达 32,768 个 token 的长文本编码，并输出 2560 维高质量语义向量。该模型采用 Apache 2.0 协议，允许商用，适用于跨语言检索、知识库构建、文档去重、聚类分析等场景。
本文是一篇从零开始的实战部署指南，重点介绍如何将 Qwen/Qwen3-Embedding-4B 模型通过 进行本地化部署，并结合 和 构建完整的可视化知识库系统。读者将掌握以下技能：
llama.cppvLLMOpen WebUI本教程适合具备基础 Linux 命令和 Python 环境管理能力的开发者，前置知识包括 Docker 使用、HTTP API 调用和向量数据库基本概念。
| 项目 | 推荐配置 |
|---|---|
| GPU 显存 | ≥ 8 GB（FP16 原生）或 ≥ 6 GB（GGUF-Q4 量化） |
| CPU 核心数 | ≥ 8 核 |
| 内存 | ≥ 16 GB |
| 存储空间 | ≥ 10 GB（含模型缓存） |
| 操作系统 | Ubuntu 20.04+ / WSL2 / macOS（Apple Silicon） |
提示：RTX 3060/4060 及以上显卡可流畅运行 Q4_K_M 量化版本，推理速度可达 800 docs/s 以上。
# 更新系统
sudo apt update && sudo apt upgrade -y
# 安装 Git、CMake、Build-Essential
sudo apt install git cmake build-essential python3-pip -y
# 克隆 llama.cpp 仓库
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp && make clean && LLAMA_CUBLAS=1 make -j
注意：若使用 NVIDIA GPU，请确保已安装 CUDA 驱动（≥11.8），并通过
nvidia-smi验证可用性。
目前官方未直接发布 GGUF 格式，需自行转换 HuggingFace 模型。推荐使用 HuggingFace Hub 下载原始模型：
# 安装 Hugging Face CLI
pip install huggingface-hub
# 登录 HF 账户（如需私有模型）
huggingface-cli login
# 下载模型
huggingface-cli download Qwen/Qwen3-Embedding-4B --local-dir ./models/qwen3-embedding-4b
llama.cpp 提供了针对多种架构的转换工具。由于 Qwen3 基于 Transformer 结构且使用 RoPE 位置编码，适配性良好。
进入 llama.cpp 目录后执行：
# 创建模型输出目录
mkdir -p gguf_models
# 执行转换（示例为 Q4_K_M 量化）
python3 convert.py \
../models/qwen3-embedding-4b \
--outtype f16 \
--outfile gguf_models/qwen3-embedding-4b-f16.gguf
# 量化到 Q4_K_M（节省显存）
../quantize gguf_models/qwen3-embedding-4b-f16.gguf gguf_models/qwen3-embedding-4b-q4_k_m.gguf Q4_K_M
转换过程可能耗时 10–20 分钟，取决于 CPU 性能。最终生成的 Q4_K_M 模型约为 3.1 GB。
# 测试加载模型
./main -m gguf_models/qwen3-embedding-4b-q4_k_m.gguf -t 8 --verbose-prompt --input-prefix "query: " --text "什么是人工智能？"
预期输出包含 [EDS] token 对应的向量表示（即句向量），可通过日志查看维度是否为 2560。
llama.cpp 自带简单的 HTTP 服务器功能，可用于快速测试：
# 编译 server 组件（需开启 LLAMA_SERVER=1）
LLAMA_SERVER=1 LLAMA_CUBLAS=1 make server -j
# 启动服务
./server -m gguf_models/qwen3-embedding-4b-q4_k_m.gguf -c 4096 --port 8080 --threads 8 --gpu-layers 35
参数说明：
-c 4096：上下文长度（最大支持 32k）；--gpu-layers 35：尽可能多地卸载至 GPU（共 36 层）；--port 8080：监听端口。
发送 POST 请求获取向量：
curl http://localhost:8080/embeddings \
-H "Content-Type: application/json" \
-d '{ "content": "query: 如何在 Python 中读取 JSON 文件？" }'
响应示例：
{
"embedding": [-0.12, 0.45, ..., 0.03],
"length": 2560,
"model": "qwen3-embedding-4b",
"prefix": "query: "
}
支持前缀指令（如
query:、passage:）实现任务感知向量生成。
虽然 vLLM 主要面向大语言模型，但其也支持纯 embedding 模型部署。首先安装 vLLM：
pip install vllm==0.4.2
启动 Qwen3-Embedding-4B 服务：
python -m vllm.entrypoints.openai.api_server \
--model Qwen/Qwen3-Embedding-4B \
--task embedding \
--tensor-parallel-size 1 \
--dtype half \
--max-model-len 32768 \
--port 8000
此方式无需手动转换 GGUF，自动从 HF 加载 FP16 模型（约 8GB 显存）。适合高端 GPU 用户。
docker run -d \
-p 3000:8080 \
-e OPENAI_API_BASE=http://your-vllm-host:8000/v1 \
-e OLLAMA_BASE_URL=http://your-ollama-host:11434 \
-v open-webui-data:/app/backend/data \
--name open-webui \
ghcr.io/open-webui/open-webui:main
http://localhost:3000http://your-llama-cpp-or-vllm-host:8000/embeddings输入查询：'请解释量子计算的基本原理'，系统返回最相关的段落。
进一步点击可查看原文出处。
浏览器开发者工具中可观察到对 embedding 服务的实际调用：
POST /embeddings HTTP/1.1
Host: your-vllm-host:8000
Content-Type: application/json
{
"input": "query: 量子计算的基本原理",
"model": "Qwen3-Embedding-4B"
}
响应时间通常在 100–300ms 之间（取决于硬件和文本长度）。
| 优化项 | 推荐做法 |
|---|---|
| 量化级别 | 使用 Q4_K_M 平衡精度与显存占用 |
| GPU 卸载 | 尽可能设置 --gpu-layers 35 |
| 批处理 | 多文档同时编码提升吞吐量 |
| 缓存机制 | 对高频查询结果做 Redis 缓存 |
利用模型的指令感知能力，根据不同任务添加前缀：
| 任务类型 | 推荐前缀 |
|---|---|
| 检索 | query: / passage: |
| 分类 | classify: topic of |
| 聚类 | cluster: document about |
| 跨语言匹配 | translate query: en to zh |
示例：
query: 如何训练一个 BERT 模型？vspassage: BERT 是一种双向编码器……
本文系统介绍了 Qwen3-Embedding-4B 的本地部署全流程，涵盖从模型获取、格式转换、服务启动到前端集成的完整路径。核心要点总结如下：
对于希望在单卡环境下构建多语言、长文本语义理解系统的团队，Qwen3-Embedding-4B 是一个极具性价比的选择。结合本文提供的部署模板，开发者可在 30 分钟内完成整套系统搭建。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 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