【高速缓存】RedisVL为文本生成嵌入向量实践指南

在现代语义搜索和 RAG 应用中，文本嵌入（Embedding） 是核心基础------它将自然语言转换成高维数值向量，使得计算机能够"理解"语义相似性。RedisVL 提供了一套统一的向量化器接口，让你可以使用多种主流嵌入服务（OpenAI、HuggingFace、Ollama、Cohere 等）轻松生成向量，并直接与 Redis 的向量索引无缝集成。

前置准备

在开始之前，请确保：

已安装 RedisVL：pip install redisvl
有运行的 Redis 实例（Redis 8+ 或 Redis Cloud），且已启用 RediSearch 模块
根据你计划使用的嵌入服务，准备好对应的 API 密钥或本地模型服务（如 Ollama 本地运行）

概要

使用 OpenAI、HuggingFace、Ollama、Cohere 等主流 Provider 生成文本向量
同步与异步的嵌入方法，以及批量嵌入的高效技巧
如何构建自定义向量器，适配你自己的嵌入函数
如何将向量器与 RedisVL 索引结合，实现语义搜索

整体工作流程

下图展示了使用向量化器的完整流程：
#mermaid-svg-XTegZBtwI0UMgE4i{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-XTegZBtwI0UMgE4i .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-XTegZBtwI0UMgE4i .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-XTegZBtwI0UMgE4i .error-icon{fill:#552222;}#mermaid-svg-XTegZBtwI0UMgE4i .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-XTegZBtwI0UMgE4i .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-XTegZBtwI0UMgE4i .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-XTegZBtwI0UMgE4i .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-XTegZBtwI0UMgE4i .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-XTegZBtwI0UMgE4i .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-XTegZBtwI0UMgE4i .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-XTegZBtwI0UMgE4i .marker{fill:#333333;stroke:#333333;}#mermaid-svg-XTegZBtwI0UMgE4i .marker.cross{stroke:#333333;}#mermaid-svg-XTegZBtwI0UMgE4i svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-XTegZBtwI0UMgE4i p{margin:0;}#mermaid-svg-XTegZBtwI0UMgE4i .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-XTegZBtwI0UMgE4i .cluster-label text{fill:#333;}#mermaid-svg-XTegZBtwI0UMgE4i .cluster-label span{color:#333;}#mermaid-svg-XTegZBtwI0UMgE4i .cluster-label span p{background-color:transparent;}#mermaid-svg-XTegZBtwI0UMgE4i .label text,#mermaid-svg-XTegZBtwI0UMgE4i span{fill:#333;color:#333;}#mermaid-svg-XTegZBtwI0UMgE4i .node rect,#mermaid-svg-XTegZBtwI0UMgE4i .node circle,#mermaid-svg-XTegZBtwI0UMgE4i .node ellipse,#mermaid-svg-XTegZBtwI0UMgE4i .node polygon,#mermaid-svg-XTegZBtwI0UMgE4i .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-XTegZBtwI0UMgE4i .rough-node .label text,#mermaid-svg-XTegZBtwI0UMgE4i .node .label text,#mermaid-svg-XTegZBtwI0UMgE4i .image-shape .label,#mermaid-svg-XTegZBtwI0UMgE4i .icon-shape .label{text-anchor:middle;}#mermaid-svg-XTegZBtwI0UMgE4i .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-XTegZBtwI0UMgE4i .rough-node .label,#mermaid-svg-XTegZBtwI0UMgE4i .node .label,#mermaid-svg-XTegZBtwI0UMgE4i .image-shape .label,#mermaid-svg-XTegZBtwI0UMgE4i .icon-shape .label{text-align:center;}#mermaid-svg-XTegZBtwI0UMgE4i .node.clickable{cursor:pointer;}#mermaid-svg-XTegZBtwI0UMgE4i .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-XTegZBtwI0UMgE4i .arrowheadPath{fill:#333333;}#mermaid-svg-XTegZBtwI0UMgE4i .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-XTegZBtwI0UMgE4i .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-XTegZBtwI0UMgE4i .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-XTegZBtwI0UMgE4i .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-XTegZBtwI0UMgE4i .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-XTegZBtwI0UMgE4i .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-XTegZBtwI0UMgE4i .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-XTegZBtwI0UMgE4i .cluster text{fill:#333;}#mermaid-svg-XTegZBtwI0UMgE4i .cluster span{color:#333;}#mermaid-svg-XTegZBtwI0UMgE4i div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-XTegZBtwI0UMgE4i .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-XTegZBtwI0UMgE4i rect.text{fill:none;stroke-width:0;}#mermaid-svg-XTegZBtwI0UMgE4i .icon-shape,#mermaid-svg-XTegZBtwI0UMgE4i .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-XTegZBtwI0UMgE4i .icon-shape p,#mermaid-svg-XTegZBtwI0UMgE4i .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-XTegZBtwI0UMgE4i .icon-shape .label rect,#mermaid-svg-XTegZBtwI0UMgE4i .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-XTegZBtwI0UMgE4i .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-XTegZBtwI0UMgE4i .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-XTegZBtwI0UMgE4i :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 用户文本
向量化器
选择 Provider
OpenAI
HuggingFace
Ollama
Cohere / 其他
生成向量
存入 Redis 索引
执行向量查询
返回相似结果

向量化器充当了"翻译官"的角色，将文本转化为数值表示，这个过程通常称为嵌入（Embedding）。不同的 Provider 背后是不同的模型架构和训练数据，但 RedisVL 提供了统一的 API，使得切换 Provider 变得非常简单。

示例文本

为了演示一致性，我们将在所有示例中使用以下三句英文：

"That is a happy dog"
"That is a happy person"
"Today is a sunny day"

一、OpenAI 向量化器

OpenAI 提供高质量通用嵌入模型（如 text-embedding-ada-002）。使用前需安装 openai 库并设置 API 密钥。

安装与配置

bash 复制代码

pip install openai

python 复制代码

import os
import getpass
from redisvl.utils.vectorize import OpenAITextVectorizer

api_key = os.environ.get("OPENAI_API_KEY") or getpass.getpass("Enter your OpenAI API key: ")

# 创建向量化器实例
oai = OpenAITextVectorizer(
    model="text-embedding-ada-002",
    api_config={"api_key": api_key},
)

单条嵌入

python 复制代码

embedding = oai.embed("This is a test sentence.")
print(len(embedding))  # 输出 1536

批量嵌入

python 复制代码

sentences = ["That is a happy dog", "That is a happy person", "Today is a sunny day"]
embeddings = oai.embed_many(sentences)  # 返回列表，每个元素是一个向量

异步嵌入（提高并发效率）

python 复制代码

embeddings = await oai.aembed_many(sentences)

原理：embed_many 内部可能会将多个文本拼接成一次 API 请求（取决于 Provider 支持），从而减少网络往返次数，大幅提升吞吐量。

二、Azure OpenAI 向量化器

Azure OpenAI 是 OpenAI 模型的 Azure 托管版本，配置稍有不同。

python 复制代码

from redisvl.utils.vectorize import AzureOpenAITextVectorizer

az_oai = AzureOpenAIVectorizer(
    model="your-deployment-name",  # 注意：这是你在 Azure 中的部署名称，而非模型名
    api_config={
        "api_key": "your-azure-key",
        "api_version": "2023-05-15",
        "azure_endpoint": "https://your-resource.openai.azure.com/",
    },
)

其余用法与标准 OpenAI 完全一致（embed、embed_many、aembed_many）。

三、HuggingFace 向量化器

HuggingFace 提供海量开源嵌入模型（如 all-MiniLM-L6-v2、all-mpnet-base-v2）。RedisVL 基于 sentence-transformers 库实现，模型在本地运行，无需 API 密钥。

安装

bash 复制代码

pip install sentence-transformers

使用

python 复制代码

from redisvl.utils.vectorize import HFTextVectorizer

hf = HFTextVectorizer(model="sentence-transformers/all-mpnet-base-v2")

embedding = hf.embed("This is a test sentence.")
embeddings = hf.embed_many(sentences, as_buffer=True)  # as_buffer=True 返回字节流，便于存入 Redis

注意：本地模型会下载到缓存目录，首次运行需要联网。之后完全离线运行，适合对数据隐私敏感的场景。

四、Ollama 向量化器

Ollama 允许你在本地运行嵌入模型（如 nomic-embed-text），完全离线且免费。你需要先安装 Ollama 并拉取模型。

安装与准备

bash 复制代码

pip install 'redisvl[ollama]'
ollama pull nomic-embed-text
ollama serve   # 确保后台进程运行

使用

python 复制代码

from redisvl.utils.vectorize import OllamaTextVectorizer

ollama = OllamaTextVectorizer(model="nomic-embed-text")

embedding = ollama.embed("This is a test sentence.")
embeddings = ollama.embed_many(sentences, batch_size=2)  # batch_size 控制每次发送的文本数

embed_many 也支持异步 aembed_many。

五、VertexAI 向量化器（Google Cloud）

VertexAI 是 GCP 的统一 AI 平台，提供多种嵌入模型。你需要启用 Vertex AI API，配置服务账号并设置环境变量。

安装

bash 复制代码

pip install google-cloud-aiplatform>=1.26

环境变量

GOOGLE_APPLICATION_CREDENTIALS：服务账号 JSON 文件路径
GCP_PROJECT_ID：项目 ID
GCP_LOCATION：区域（如 us-central1）

使用

python 复制代码

from redisvl.utils.vectorize import VertexAIVectorizer

vtx = VertexAIVectorizer(
    api_config={
        "project_id": os.environ["GCP_PROJECT_ID"],
        "location": os.environ["GCP_LOCATION"],
        "google_application_credentials": os.environ["GOOGLE_APPLICATION_CREDENTIALS"],
    }
)

embedding = vtx.embed("This is a test sentence.")

六、Cohere 向量化器

Cohere 提供专用嵌入模型（如 embed-english-v3.0），特别注重语义表示。与 OpenAI 类似，你需要 API 密钥。

安装

bash 复制代码

pip install cohere

使用

python 复制代码

from redisvl.utils.vectorize import CohereTextVectorizer

co = CohereTextVectorizer(
    model="embed-english-v3.0",
    api_config={"api_key": "your-cohere-key"},
)

# 查询时使用 input_type='search_query'
query_vec = co.embed("search query", input_type="search_query")

# 文档索引时使用 input_type='search_document'
doc_vec = co.embed("document content", input_type="search_document")

为什么需要 input_type？ Cohere 的不同模型针对查询和文档做了优化，指定类型有助于模型调整内部表示，提升检索效果。

七、VoyageAI 向量化器

VoyageAI 提供高性能嵌入模型，如 voyage-law-2、voyage-2 等。也支持 input_type 参数（query / document）。

安装与使用

bash 复制代码

pip install voyageai

python 复制代码

from redisvl.utils.vectorize import VoyageAIVectorizer

vo = VoyageAIVectorizer(
    model="voyage-law-2",
    api_config={"api_key": "your-voyage-key"},
)

query_vec = vo.embed("query", input_type="query")
doc_vec = vo.embed("document", input_type="document")

八、Mistral AI 向量化器

Mistral AI 提供其嵌入模型（如 mistral-embed）。使用方式与 OpenAI 类似。

bash 复制代码

pip install mistralai

python 复制代码

from redisvl.utils.vectorize import MistralAITextVectorizer

mistral = MistralAITextVectorizer()  # 默认从环境变量读取 MISTRAL_API_KEY

embedding = await mistral.aembed("This is a test sentence.")  # 异步示例

九、Amazon Bedrock 向量化器

Bedrock 提供来自多个厂商的基础模型，包括 Amazon 自研的 Titan 嵌入模型。需要配置 AWS 凭证。

安装

bash 复制代码

pip install 'redisvl[bedrock]'

配置凭证

python 复制代码

import os
os.environ["AWS_ACCESS_KEY_ID"] = "..."
os.environ["AWS_SECRET_ACCESS_KEY"] = "..."
os.environ["AWS_REGION"] = "us-east-1"

使用

python 复制代码

from redisvl.utils.vectorize import BedrockVectorizer

bedrock = BedrockVectorizer(model="amazon.titan-embed-text-v2:0")

embedding = bedrock.embed("This is a test sentence.")
embeddings = bedrock.embed_many(sentences)

十、自定义向量器（CustomVectorizer）

如果你有自己的嵌入函数（例如封装了某个私有模型），RedisVL 提供了 CustomVectorizer 让你轻松接入。

python 复制代码

from redisvl.utils.vectorize import CustomVectorizer

def my_embed(text_input, **kwargs):
    # 你的嵌入逻辑，返回一个向量列表（或单个向量）
    return [0.1] * 768  # 示例

custom_vec = CustomVectorizer(my_embed)
embedding = custom_vec.embed("test")

自定义向量器可以直接用于 RedisVL 的其他组件，例如语义缓存（SemanticCache）或索引查询。

将向量器与 SearchIndex 集成

生成向量后，我们通常需要将它们存入 Redis 并执行相似性搜索。下面演示完整流程。

1. 定义 Schema（YAML 格式）

yaml 复制代码

# schema.yaml
version: '0.1.0'
index:
    name: vectorizers
    prefix: doc
    storage_type: hash

fields:
    - name: text
      type: text
    - name: embedding
      type: vector
      attrs:
        dims: 768          # 必须与模型输出维度一致
        algorithm: flat
        distance_metric: cosine

2. 创建索引并加载数据

python 复制代码

from redisvl.index import SearchIndex
from redisvl.redis.utils import array_to_buffer

index = SearchIndex.from_yaml("./schema.yaml", redis_url="redis://localhost:6379")
index.create(overwrite=True)

# 使用 HuggingFace 向量器生成向量
hf = HFTextVectorizer(model="sentence-transformers/all-mpnet-base-v2")
embeddings = hf.embed_many(sentences)

# 准备数据，向量需转换为字节格式（float32）
data = [{"text": t, "embedding": array_to_buffer(v, dtype="float32")}
        for t, v in zip(sentences, embeddings)]

index.load(data)

3. 执行向量查询

python 复制代码

from redisvl.query import VectorQuery

query_vec = hf.embed("That is a happy cat")  # 查询文本

query = VectorQuery(
    vector=query_vec,
    vector_field_name="embedding",
    return_fields=["text"],
    num_results=3
)

results = index.query(query)
for doc in results:
    print(doc["text"], doc["vector_distance"])

输出示例：

复制代码

That is a happy dog 0.123
That is a happy person 0.145
Today is a sunny day 0.567

原理：Redis 使用 FAISS 或 HNSW 等算法在向量字段上执行近似最近邻（ANN）搜索，返回与查询向量最相似的文档，同时提供距离度量（余弦相似度/内积等）。

选择浮点数据类型

RedisVL 支持将向量存储为不同的数值类型（float16、float32、float64、bfloat16 以及整数类型 int8、uint8）。dtype 必须在向量器实例化时指定，并且必须与索引 Schema 中定义的维度类型一致。

python 复制代码

hf_float16 = HFTextVectorizer(model="sentence-transformers/all-mpnet-base-v2", dtype="float16")
bytes_vec = hf_float16.embed("test", as_buffer=True)   # 返回 float16 编码的字节流

选择较低精度（如 float16）可节省存储空间和加速计算，但可能轻微影响精度。float32 是默认值，兼容性最好。

总结与最佳实践

Provider	适用场景	注意点
OpenAI	通用、高质量，需要 API Key	费用较高，需网络
Azure OpenAI	企业 Azure 环境	配置复杂，但合规性更好
HuggingFace	开源免费，可离线	模型较大，首次需下载
Ollama	本地运行，完全免费	需安装 Ollama 并拉取模型
VertexAI	GCP 生态用户	需要 GCP 权限和配置
Cohere	针对检索优化的模型	注意 `input_type` 参数
VoyageAI	特定领域（如法律）模型	同样需指定 `input_type`
Mistral AI	欧洲 AI 供应商	支持异步，需 API Key
Amazon Bedrock	AWS 企业用户	需要 AWS 凭证

关键要点：

所有向量化器共享相同的接口：embed（单条）、embed_many（批量）、aembed / aembed_many（异步）
批量嵌入能显著提高效率（尤其对于 API 类服务），内部实现可能将多个文本打包成一次请求
向量存储前需转换为字节流（as_buffer=True 或 array_to_buffer）
查询时使用 VectorQuery 并传入查询向量即可获得相似结果

通过 RedisVL 的向量化器，你可以轻松地在多个嵌入模型之间切换，并与 Redis 的向量索引完美结合，构建高性能的语义搜索、推荐系统或 RAG 应用。现在就开始尝试吧！