企业官网建设流程全解析

Zvec Embedding Function 全家桶：内置 Embedding Function 完整指南

【免费下载链接】zvecA lightweight, lightning-fast, in-process vector database项目地址: https://gitcode.com/GitHub_Trending/zve/zvec

如果你正在用Zvec（一个轻量、极速、进程内的向量数据库）做语义检索，一定会遇到第一个问题：文字怎么变成向量？好消息是，Zvec 的 Python SDK 自带了一个开箱即用的Embedding Function（嵌入函数）全家桶——本地模型、云端 API、本地推理服务全覆盖，装好 SDK 就能直接用，无需自己搭模型管道。

本文带你 10 分钟摸清 Zvec 内置的全部 8 个 Embedding Function：每个是干什么的、需要什么依赖、适合什么场景，并给出新手最易上手的配置建议。

先搞懂：Zvec 的 Embedding Function 分两类

Zvec 用两个协议类定义所有嵌入函数，接口极其简单——只要实现一个embed()方法即可：

💡 两者组合就是业界推崇的混合检索（Hybrid Search）：稠密管"意思像不像"，稀疏管"词对不对"。

协议定义位于 embedding_function.py，这也是你自己写自定义嵌入函数的起点。

一张表看懂 Zvec 内置的 8 个 Embedding Function

所有实现都集中在python/zvec/extension/目录下，统一从zvec.extension导入：

最快上手：3 个本地 Embedding Function（无需 API Key）

1. DefaultLocalDenseEmbedding：零门槛语义向量

from zvec.extension import DefaultLocalDenseEmbedding emb = DefaultLocalDenseEmbedding() vector = emb.embed("什么是向量数据库？") print(len(vector)) # 384

• 首次运行会自动下载约 50~80MB 的模型，之后完全离线可用；
• 国内用户推荐指定 ModelScope 源，会自动切换为中文优化的 GTE 模型：DefaultLocalDenseEmbedding(model_source="modelscope")；
• 支持 CPU/GPU 自动选择，CPU 上约 1000 句/秒，GPU 可达 10000 句/秒。

实现见 sentence_transformer_embedding_function.py。

2. DefaultLocalSparseEmbedding：本地 SPLADE 稀疏向量

from zvec.extension import DefaultLocalSparseEmbedding query_emb = DefaultLocalSparseEmbedding(encoding_type="query") query_vec = query_emb.embed("机器学习 算法") # {12: 0.8, 45: 1.2, ...}

• 基于 SPLADE 模型，输出可解释的"词权重"字典；
• 内置类级模型缓存：query 和 document 两个实例共享同一份模型内存，避免重复加载。

3. BM25EmbeddingFunction：经典 BM25 也能变向量

from zvec.extension import BM25EmbeddingFunction bm25 = BM25EmbeddingFunction(language="zh", encoding_type="query") vec = bm25.embed("什么是机器学习") # {1169440797: 0.29, 2045788977: 0.70, ...}

• 内置中文（zh）与英文（en）两种预训练编码器，开箱即用；
• 也支持传入自己的语料库训练专属编码器：BM25EmbeddingFunction(corpus=docs, b=0.75, k1=1.2)。

云端 Embedding：OpenAI、Qwen、Jina 三家通吃

OpenAIDenseEmbedding

from zvec.extension import OpenAIDenseEmbedding emb = OpenAIDenseEmbedding(model="text-embedding-3-small") # 读取 OPENAI_API_KEY vector = emb.embed("vector database in-process")

• 支持自定义维度（如 256、512、1024）和base_url指向任何 OpenAI 兼容服务。

QwenDenseEmbedding / QwenSparseEmbedding

from zvec.extension import QwenDenseEmbedding emb = QwenDenseEmbedding(dimension=1024, text_type="document") # 读取 DASHSCOPE_API_KEY

• 默认模型text-embedding-v4，稠密、稀疏两个函数共用一个 API；
• 稀疏版输出按维度索引升序排列的字典，天然适合做混合检索。

JinaDenseEmbedding：支持任务优化

from zvec.extension import JinaDenseEmbedding query_emb = JinaDenseEmbedding(task="retrieval.query") doc_emb = JinaDenseEmbedding(task="retrieval.passage")

• v5 模型支持task参数区分"查询"与"文档"的编码策略，还支持 Matryoshka 可变维度。

🔑 三个云端函数都支持环境变量自动读取 Key（OPENAI_API_KEY/DASHSCOPE_API_KEY/JINA_API_KEY），且embed()自带 LRU 缓存，重复文本不会重复扣费。

本地模型也能白嫖：HTTPDenseEmbedding 对接 LM Studio / Ollama

如果你用 LM Studio 或 Ollama 在本地跑着嵌入模型，Zvec 直接连上即可，连第三方库都不需要装（纯标准库实现 HTTP 调用）：

from zvec.extension import HTTPDenseEmbedding emb = HTTPDenseEmbedding(base_url="http://localhost:11434", model="nomic-embed-text") vector = emb.embed("hello zvec")

维度会自动从首次响应中探测，无需手动配置。实现见 http_embedding_function.py。

新手选型：6 个场景直接对号入座

使用 Embedding Function 的 5 条最佳实践

1. 查询和文档分开编码：Qwen 用text_type、Jina 用task、本地稀疏用encoding_type区分query/document，能显著提升非对称检索的召回率。
2. 维度提前规划：创建集合时直接用emb.dimension声明向量维度，保证 Schema 与模型严格一致（所有实现都暴露该属性）。
3. 利用内置缓存：云端embed()默认 LRU 缓存（HTTP 版为 256 条），批量导入时相同文本不会重复请求。
4. API Key 走环境变量：不要把 Key 硬编码进代码，Zvec 会自动回退读取环境变量。
5. 想接自家模型？：继承DenseEmbeddingFunction/SparseEmbeddingFunction协议，只写一个embed()方法即可无缝替换，无需改动 Zvec 任何代码。

核心模块路径速查

总结

Zvec 的 Embedding Function 全家桶把"文本变向量"这件事做到了真正的开箱即用：8 个内置实现覆盖本地、云端、本地推理服务三类部署形态，稠密与稀疏双通道让混合检索触手可及。新手建议从DefaultLocalDenseEmbedding起步跑通全链路，再按数据规模和精度需求平滑升级到云端或私有化方案——而这一切，只需要换一个类的名字。

【免费下载链接】zvecA lightweight, lightning-fast, in-process vector database项目地址: https://gitcode.com/GitHub_Trending/zve/zvec