news 2026/4/18 10:51:45

通义千问3-Embedding-4B教程：API接口调用完整示例

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
通义千问3-Embedding-4B教程：API接口调用完整示例

通义千问3-Embedding-4B教程：API接口调用完整示例

1. Qwen3-Embedding-4B 模型简介

Qwen3-Embedding-4B 是阿里通义千问（Qwen）系列中专为文本向量化任务设计的 40 亿参数双塔模型，于 2025 年 8 月正式开源。该模型在保持中等体量的同时，具备强大的多语言语义理解能力，适用于构建高效的知识库、语义搜索系统和长文档处理场景。

其核心定位是“中等规模、支持 32k 长文本输入、输出 2560 维高维向量、覆盖 119 种语言”，兼顾性能与实用性，特别适合部署在消费级显卡上运行的大规模语义应用。

1.1 核心特性概览

  • 模型结构：基于 36 层 Dense Transformer 构建的双塔编码器架构，通过末尾[EDS]token 的隐藏状态生成句向量。
  • 向量维度：默认输出 2560 维向量，支持通过 MRL（Matrix Rank Learning）技术在线投影至任意维度（32–2560），灵活平衡精度与存储开销。
  • 上下文长度：最大支持 32,768 token 的输入长度，可一次性编码整篇论文、法律合同或大型代码文件，避免分段截断带来的语义损失。
  • 多语言能力：覆盖 119 种自然语言及主流编程语言，在跨语言检索、bitext 挖掘等任务中表现优异，官方评测达 S 级水平。
  • 性能指标：
    • MTEB (English v2)：74.60
    • CMTEB (Chinese)：68.09
    • MTEB (Code)：73.50
      在同尺寸开源 embedding 模型中全面领先。
  • 指令感知能力：无需微调，仅需在输入前添加任务描述前缀（如“为检索生成向量”），即可动态调整输出向量空间，适配检索、分类、聚类等不同下游任务。
  • 部署友好性：
    • FP16 全精度模型约 8 GB 显存占用
    • GGUF-Q4 量化版本压缩至 3 GB，可在 RTX 3060 等消费级 GPU 上流畅运行
    • 支持 vLLM、llama.cpp、Ollama 等主流推理框架，Apache 2.0 协议允许商用

1.2 适用选型建议

“单卡 RTX 3060 想做 119 语种语义搜索或长文档去重？直接拉取 Qwen3-Embedding-4B 的 GGUF 镜像即可。”

该模型非常适合以下应用场景：

  • 多语言知识库构建
  • 长文本语义匹配与去重
  • 代码片段相似度分析
  • 跨语言信息检索
  • 向量数据库预处理 pipeline

2. 基于 vLLM + Open-WebUI 的本地化部署实践

本节将详细介绍如何使用vLLM高效加载 Qwen3-Embedding-4B 模型，并结合Open-WebUI构建可视化知识库交互界面，实现完整的 embedding 应用闭环。

2.1 环境准备与服务启动

确保本地环境已安装 Docker 和 NVIDIA 驱动（CUDA ≥ 12.1）。推荐配置：RTX 3060 / 3090 / 4090，至少 12GB 显存。

启动 vLLM Embedding 服务

使用如下命令启动 vLLM 服务，加载 Qwen3-Embedding-4B 模型：

docker run -d \ --gpus all \ --shm-size 1g \ -p 8000:8000 \ --env CUDA_VISIBLE_DEVICES=0 \ vllm/vllm-openai:latest \ --model Qwen/Qwen3-Embedding-4B \ --dtype half \ --max-model-len 32768 \ --enable-chunked-prefill \ --gpu-memory-utilization 0.9

⚠️ 注意：若显存有限，可考虑使用qwen/qwen3-embedding-4b-gguf-q4_k_m版本配合 llama.cpp 替代方案。

启动 Open-WebUI 服务
docker run -d \ -p 7860:8080 \ -e OPENAI_API_BASE=http://<your-host-ip>:8000/v1 \ -e OLLAMA_BASE_URL=http://<your-host-ip>:11434 \ --name open-webui \ ghcr.io/open-webui/open-webui:main

等待数分钟后，服务初始化完成。可通过浏览器访问http://localhost:7860进入 Web UI 界面。

2.2 登录与模型配置

演示账号信息如下：

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

登录后进入设置页面，选择Embedding Model并配置为Qwen/Qwen3-Embedding-4B，确认 API 地址指向本地 vLLM 服务（http://<host>:8000/v1）。

2.3 知识库验证 embedding 效果

上传包含多语言文本、技术文档和代码片段的知识库文件（PDF、TXT、Markdown 等格式），系统会自动调用 Qwen3-Embedding-4B 对内容进行向量化并存入向量数据库。

随后进行语义查询测试，例如输入：“找出所有关于 Python 异步编程的内容”。

系统返回相关段落，准确命中异步函数定义、事件循环说明及协程示例代码，表明模型具备良好的代码语义理解和跨模态关联能力。

2.4 查看 API 请求日志

打开开发者工具，观察前端对/embeddings接口的实际调用请求：

POST http://localhost:8000/v1/embeddings Content-Type: application/json { "model": "Qwen/Qwen3-Embedding-4B", "input": "为检索生成向量：Python 中的 asyncio 如何实现并发？", "encoding_format": "float" }

响应返回 2560 维浮点数组，总耗时约 320ms（RTX 3060 测试数据），吞吐可达 800 documents/s（批量推理优化后）。

3. API 接口调用完整代码示例

本节提供 Python 客户端调用 Qwen3-Embedding-4B 的完整实现，涵盖同步、异步和批处理三种模式。

3.1 安装依赖库

pip install openai aiohttp numpy pandas

3.2 同步调用示例

import openai import numpy as np # 初始化 OpenAI 兼容客户端 client = openai.OpenAI( base_url="http://localhost:8000/v1", api_key="none" # vLLM 不需要真实密钥 ) def get_embedding(text: str) -> np.ndarray: response = client.embeddings.create( model="Qwen/Qwen3-Embedding-4B", input=text, encoding_format="float" ) return np.array(response.data[0].embedding) # 示例调用 text = "机器学习中的梯度下降算法原理" vec = get_embedding(text) print(f"向量维度: {vec.shape}") # 输出: (2560,) print(f"L2 norm: {np.linalg.norm(vec):.4f}")

3.3 异步批量调用（高性能场景）

import asyncio import aiohttp import json async def async_get_embeddings(texts: list): url = "http://localhost:8000/v1/embeddings" headers = {"Content-Type": "application/json"} async with aiohttp.ClientSession() as session: tasks = [] for text in texts: data = { "model": "Qwen/Qwen3-Embedding-4B", "input": text, "encoding_format": "float" } task = session.post(url, headers=headers, json=data) tasks.append(task) responses = await asyncio.gather(*tasks) results = [] for resp in responses: js = await resp.json() results.append(js['data'][0]['embedding']) return results # 批量调用示例 texts = [ "什么是量子计算？", "Python 中的装饰器有什么作用？", "区块链是如何保证数据不可篡改的？" ] vectors = asyncio.run(async_get_embeddings(texts)) print(f"批量获取 {len(vectors)} 个向量，每个维度 {len(vectors[0])}")

3.4 向量归一化与余弦相似度计算

from sklearn.metrics.pairwise import cosine_similarity def normalize(vectors): return vectors / np.linalg.norm(vectors, axis=1, keepdims=True) # 获取两个句子的向量 sent_a = get_embedding("人工智能的发展趋势") sent_b = get_embedding("AI 技术未来方向预测") # 归一化后计算余弦相似度 vec_a = sent_a.reshape(1, -1) vec_b = sent_b.reshape(1, -1) similarity = cosine_similarity(normalize(vec_a), normalize(vec_b))[0][0] print(f"语义相似度: {similarity:.4f}")

4. 总结

Qwen3-Embedding-4B 凭借其4B 参数、32k 上下文、2560 维高维输出、119 语种支持和出色的 MTEB 系列基准表现，已成为当前最具竞争力的开源 embedding 模型之一。其指令感知能力和MRL 动态降维特性极大提升了工程灵活性，而GGUF-Q4 仅需 3GB 显存的轻量化部署方案，使得消费级 GPU 也能轻松承载生产级语义搜索系统。

通过vLLM + Open-WebUI的组合，开发者可以快速搭建一个功能完备、可视化操作的知识库平台，并通过标准 OpenAI 兼容 API 实现无缝集成。

本文提供了从本地部署、界面配置到 API 调用的全流程实践指南，包含可运行的同步/异步代码示例，帮助开发者快速落地基于 Qwen3-Embedding-4B 的语义理解系统。

获取更多AI镜像

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

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/4/18 5:39:26

DeepSeek-OCR-WEBUI核心优势揭秘｜附详细Docker部署流程

DeepSeek-OCR-WEBUI核心优势揭秘&#xff5c;附详细Docker部署流程 1. 背景与应用场景 随着数字化转型的加速&#xff0c;企业对非结构化文档的自动化处理需求日益增长。在金融、物流、教育和政务等领域&#xff0c;大量纸质单据、发票、合同和档案需要转化为可编辑、可检索的…

作者头像 李华
网站建设 2026/4/17 18:31:46

wxappUnpacker终极指南：如何快速解密微信小程序源码

wxappUnpacker终极指南&#xff1a;如何快速解密微信小程序源码 【免费下载链接】wxappUnpacker 项目地址: https://gitcode.com/gh_mirrors/wxappu/wxappUnpacker 想要深入了解微信小程序的内部机制吗&#xff1f;wxappUnpacker作为专业的微信小程序解包工具&#xff…

作者头像 李华
网站建设 2026/4/18 7:33:33

高效图文匹配分割新体验｜sam3大模型镜像应用全解析

高效图文匹配分割新体验&#xff5c;sam3大模型镜像应用全解析 1. 技术背景与核心价值 近年来&#xff0c;视觉基础模型的发展正从“任务专用”向“通用感知”演进。Meta 推出的 SAM 系列模型持续引领这一趋势&#xff1a;从 SAM1 的零样本图像分割&#xff0c;到 SAM2 的视频…

作者头像 李华
网站建设 2026/4/16 15:00:30

Qwen3-Embedding-4B一键部署：开箱即用向量数据库方案

Qwen3-Embedding-4B一键部署&#xff1a;开箱即用向量数据库方案 1. 引言 随着大模型在检索增强生成&#xff08;RAG&#xff09;、语义搜索、多语言信息处理等场景中的广泛应用&#xff0c;高质量文本嵌入模型成为构建智能系统的核心组件。Qwen3-Embedding-4B 作为通义千问系…

作者头像 李华
网站建设 2026/3/4 2:52:08

Youtu-2B GPU利用率优化：提升并发处理能力实战

Youtu-2B GPU利用率优化&#xff1a;提升并发处理能力实战 1. 背景与挑战 随着大语言模型&#xff08;LLM&#xff09;在实际业务场景中的广泛应用&#xff0c;如何在有限的硬件资源下最大化模型服务的吞吐能力和响应效率&#xff0c;成为工程落地的关键问题。Youtu-LLM-2B 作…

作者头像 李华
网站建设 2026/4/18 3:56:10

MinerU部署常见错误汇总：从Permission Denied到OOM

MinerU部署常见错误汇总&#xff1a;从Permission Denied到OOM 1. 引言 1.1 场景背景 MinerU 2.5-1.2B 是当前在 PDF 文档结构解析与多模态内容提取领域表现优异的开源工具&#xff0c;尤其擅长处理包含复杂排版、数学公式、表格和图像的学术文档。CSDN 星图平台提供的 Mine…

作者头像 李华