Qwen3-Embedding-4B部署教程：llama.cpp集成详细步骤

Ne0inhk

— 8 min read

Qwen3-Embedding-4B部署教程：llama.cpp集成详细步骤

1. 技术背景与学习目标

通义千问3-Embedding-4B是阿里云Qwen3系列中专为文本向量化任务设计的高性能模型，参数规模达40亿，支持高达32,768个token的长文本编码，并输出2560维高质量语义向量。该模型于2025年8月开源，采用Apache 2.0协议，允许商用，适用于跨语言检索、知识库构建、文档去重、聚类分析等场景。

本文是一篇从零开始的实战部署指南，重点介绍如何将 Qwen/Qwen3-Embedding-4B 模型通过 llama.cpp 进行本地化部署，并结合 vLLM 和 Open WebUI 构建完整的可视化知识库系统。读者将掌握以下技能：

  • 下载并转换Qwen3-Embedding-4B为GGUF格式
  • 使用llama.cpp运行嵌入模型
  • 部署vLLM服务以提供API接口
  • 配置Open WebUI实现交互式知识库体验
  • 验证embedding效果及性能指标

本教程适合具备基础Linux命令和Python环境管理能力的开发者，前置知识包括Docker使用、HTTP API调用和向量数据库基本概念。

2. 环境准备与依赖安装

2.1 硬件与软件要求

项目推荐配置
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以上。

2.2 安装必要工具链

# 更新系统包 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 验证可用性。

2.3 获取Qwen3-Embedding-4B模型文件

目前官方未直接发布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

3. 模型转换：PyTorch → GGUF

3.1 准备转换脚本

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。

3.2 验证模型完整性

# 测试加载模型 ./main -m gguf_models/qwen3-embedding-4b-q4_k_m.gguf -t 8 --verbose-prompt --input-prefix "query: " --text "什么是人工智能？"

预期输出包含 [EDS] token对应的向量表示（即句向量），可通过日志查看维度是否为2560。

4. 使用llama.cpp运行嵌入服务

4.1 启动本地嵌入服务器

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：监听端口

4.2 调用embedding API

发送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:）实现任务感知向量生成。

5. 集成vLLM + Open WebUI打造知识库系统

5.1 部署vLLM Embedding服务

虽然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用户。

5.2 配置Open WebUI连接embedding服务

安装Open WebUI（Docker方式）
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
设置embedding模型
  1. 访问 http://localhost:3000
  2. 登录账号（演示信息见下文）
  3. 进入「Settings」→「Vectorization」
  4. 填写Embedding API地址：http://your-llama-cpp-or-vllm-host:8000/embeddings
  5. 选择模型类型为“Custom HuggingFace”或“OpenAI Compatible”
设置embedding模型

6. 知识库功能验证与接口调试

6.1 构建本地知识库

  1. 在Open WebUI中创建新知识库
  2. 上传PDF、TXT或Markdown文档（支持长文本切分）
  3. 系统自动调用embedding服务生成向量并存入内置ChromaDB
上传文档

6.2 执行语义搜索

输入查询：“请解释量子计算的基本原理”，系统返回最相关的段落：

语义搜索结果

进一步点击可查看原文出处：

查看原文

6.3 查看API请求日志

浏览器开发者工具中可观察到对embedding服务的实际调用：

POST /embeddings HTTP/1.1 Host: your-vllm-host:8000 Content-Type: application/json { "input": "query: 量子计算的基本原理", "model": "Qwen3-Embedding-4B" }

响应时间通常在100–300ms之间（取决于硬件和文本长度）。

接口请求截图

7. 性能优化与最佳实践

7.1 显存与速度优化建议

优化项推荐做法
量化级别使用Q4_K_M平衡精度与显存占用
GPU卸载尽可能设置--gpu-layers 35
批处理多文档同时编码提升吞吐量
缓存机制对高频查询结果做Redis缓存

7.2 长文本处理技巧

  • 切分策略：按句子或段落分割，避免截断关键信息
  • 重叠窗口：相邻块保留10%重叠防止语义断裂
  • 元数据标注：记录来源文件、页码等便于溯源

7.3 指令前缀使用规范

利用模型的指令感知能力，根据不同任务添加前缀：

任务类型推荐前缀
检索query: / passage:
分类classify: topic of
聚类cluster: document about
跨语言匹配translate query: en to zh
示例：query: 如何训练一个BERT模型？ vs passage: BERT是一种双向编码器……

8. 总结

本文系统介绍了 Qwen3-Embedding-4B 的本地部署全流程，涵盖从模型获取、格式转换、服务启动到前端集成的完整路径。核心要点总结如下：

  1. 高效部署方案：通过llama.cpp + GGUF量化可在RTX 3060级别显卡上实现低延迟、高吞吐的嵌入服务。
  2. 灵活集成能力：兼容vLLM、Open WebUI等主流生态工具，轻松构建企业级知识库。
  3. 卓越性能表现：2560维向量、32k上下文、119语种支持，在MTEB多项榜单领先同尺寸模型。
  4. 商用友好许可：Apache 2.0协议允许自由用于商业产品，降低合规风险。

对于希望在单卡环境下构建多语言、长文本语义理解系统的团队，Qwen3-Embedding-4B是一个极具性价比的选择。结合本文提供的部署模板，开发者可在30分钟内完成整套系统搭建。

获取更多AI镜像

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

Read more

Continue插件实现本地部署一个“cursor”或“github copilot”

Continue插件实现本地部署一个“cursor”或“github copilot”

本地部署 AI 代码助手，制作一个 Cursor/GitHub Copilot 的替代版本 一 需求分析 * 本地部署的定义与优势（数据隐私、离线使用、定制化）。 * Cursor 与 GitHub Copilot 的功能（代码补全、对话交互、模型差异）。 * 本地部署的AI 代码助手适用场景：企业内网开发、敏感数据环境。 二 环境准备与工具选择 * 硬件要求：GPU 要对应上你所部署的模型大小 * 模型选择：qwen2.5-14b-instruct （这里选择千问的大模型） 三 部署开源模型 这里不详细介绍具体的大模型部署的具体过程，部署完成之后，你应该得到对应的模型的以下信息 model: "qwen2.5-14b-instruct" apiBase: "http://你的ip地址（自己的本机就写localhost）

By Ne0inhk
AIGC实战测评：蓝耘元生代通义万相2.1图生视频的完美部署~

AIGC实战测评：蓝耘元生代通义万相2.1图生视频的完美部署~

文章目录 * 👏什么是图生视频？ * 👏通义万相2.1图生视频 * 👏开源仓库代码 * 👏蓝耘元生代部署通义万相2.1图生视频 * 👏平台注册 * 👏部署通义万相2.1图生视频 * 👏使用通义万相2.1图生视频 * 👏总结 👏什么是图生视频？ 图生视频是一种通过图像生成技术，结合文本信息生成视频的创新方式。通过输入一张图像和相关的描述文本，系统能够根据这些输入生成一个符合描述的视频。该技术利用深度学习和计算机视觉技术，将静态图像转化为动态视频，实现视觉内容的快速生成。这种技术的应用广泛，涵盖了内容创作、影视制作、广告生成等多个领域。 👏通义万相2.1图生视频 阿里巴巴旗下“通义”品牌宣布，其AI视频生成模型“通义万相Wan”正式推出独立网站，标志着其生成式AI技术的重大进展。新网站现已开放（网址：wan.video），用户可直接登录体验“文本生成视频”和“图像生成视频”功能，无需本地部署，极大降低了使用门槛。此外，每天登录网站还可获赠积分，激励用户持续探索。 文章链接：https:

By Ne0inhk

GitHub Copilot 使用笔记

GitHub Copilot 是 VSCode 自带的 AI Agent 插件，需要登录 GitHub 账号使用，分为免费版和付费版。 关于个人额度，可以在 Github 的 Copilot 菜单里查看 支持模型 添加第三方模型 通过 Manage Models 选中对应厂商。 可以通过 OpenRouter 来导入免费的模型，需要先到 OpenRouter 注册 API Key，输入后即可使用，也可以使用兼容 OpenAI 接口的三方 API，比如 硅基流动 SiliconFlow 使用帮助信息 切换到 Ask 模式，输入 /help 即可获取帮助命令，可以查看当前有什么可用命令和使用方法。 翻译后的内容，方便查看，

By Ne0inhk