在现代语义搜索和 RAG 应用中文本嵌入Embedding是核心基础——它将自然语言转换成高维数值向量使得计算机能够“理解”语义相似性。RedisVL 提供了一套统一的向量化器接口让你可以使用多种主流嵌入服务OpenAI、HuggingFace、Ollama、Cohere 等轻松生成向量并直接与 Redis 的向量索引无缝集成。前置准备在开始之前请确保已安装 RedisVLpip install redisvl有运行的 Redis 实例Redis 8 或 Redis Cloud且已启用 RediSearch 模块根据你计划使用的嵌入服务准备好对应的 API 密钥或本地模型服务如 Ollama 本地运行概要使用 OpenAI、HuggingFace、Ollama、Cohere 等主流 Provider 生成文本向量同步与异步的嵌入方法以及批量嵌入的高效技巧如何构建自定义向量器适配你自己的嵌入函数如何将向量器与 RedisVL 索引结合实现语义搜索整体工作流程下图展示了使用向量化器的完整流程用户文本向量化器选择 ProviderOpenAIHuggingFaceOllamaCohere / 其他生成向量存入 Redis 索引执行向量查询返回相似结果向量化器充当了“翻译官”的角色将文本转化为数值表示这个过程通常称为嵌入Embedding。不同的 Provider 背后是不同的模型架构和训练数据但 RedisVL 提供了统一的 API使得切换 Provider 变得非常简单。示例文本为了演示一致性我们将在所有示例中使用以下三句英文That is a happy dogThat is a happy personToday is a sunny day一、OpenAI 向量化器OpenAI 提供高质量通用嵌入模型如text-embedding-ada-002。使用前需安装openai库并设置 API 密钥。安装与配置pipinstallopenaiimportosimportgetpassfromredisvl.utils.vectorizeimportOpenAITextVectorizer api_keyos.environ.get(OPENAI_API_KEY)orgetpass.getpass(Enter your OpenAI API key: )# 创建向量化器实例oaiOpenAITextVectorizer(modeltext-embedding-ada-002,api_config{api_key:api_key},)单条嵌入embeddingoai.embed(This is a test sentence.)print(len(embedding))# 输出 1536批量嵌入sentences[That is a happy dog,That is a happy person,Today is a sunny day]embeddingsoai.embed_many(sentences)# 返回列表每个元素是一个向量异步嵌入提高并发效率embeddingsawaitoai.aembed_many(sentences)原理embed_many内部可能会将多个文本拼接成一次 API 请求取决于 Provider 支持从而减少网络往返次数大幅提升吞吐量。二、Azure OpenAI 向量化器Azure OpenAI 是 OpenAI 模型的 Azure 托管版本配置稍有不同。fromredisvl.utils.vectorizeimportAzureOpenAITextVectorizer az_oaiAzureOpenAIVectorizer(modelyour-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 密钥。安装pipinstallsentence-transformers使用fromredisvl.utils.vectorizeimportHFTextVectorizer hfHFTextVectorizer(modelsentence-transformers/all-mpnet-base-v2)embeddinghf.embed(This is a test sentence.)embeddingshf.embed_many(sentences,as_bufferTrue)# as_bufferTrue 返回字节流便于存入 Redis注意本地模型会下载到缓存目录首次运行需要联网。之后完全离线运行适合对数据隐私敏感的场景。四、Ollama 向量化器Ollama 允许你在本地运行嵌入模型如nomic-embed-text完全离线且免费。你需要先安装 Ollama 并拉取模型。安装与准备pipinstallredisvl[ollama]ollama pull nomic-embed-text ollama serve# 确保后台进程运行使用fromredisvl.utils.vectorizeimportOllamaTextVectorizer ollamaOllamaTextVectorizer(modelnomic-embed-text)embeddingollama.embed(This is a test sentence.)embeddingsollama.embed_many(sentences,batch_size2)# batch_size 控制每次发送的文本数embed_many也支持异步aembed_many。五、VertexAI 向量化器Google CloudVertexAI 是 GCP 的统一 AI 平台提供多种嵌入模型。你需要启用 Vertex AI API配置服务账号并设置环境变量。安装pipinstallgoogle-cloud-aiplatform1.26环境变量GOOGLE_APPLICATION_CREDENTIALS服务账号 JSON 文件路径GCP_PROJECT_ID项目 IDGCP_LOCATION区域如us-central1使用fromredisvl.utils.vectorizeimportVertexAIVectorizer vtxVertexAIVectorizer(api_config{project_id:os.environ[GCP_PROJECT_ID],location:os.environ[GCP_LOCATION],google_application_credentials:os.environ[GOOGLE_APPLICATION_CREDENTIALS],})embeddingvtx.embed(This is a test sentence.)六、Cohere 向量化器Cohere 提供专用嵌入模型如embed-english-v3.0特别注重语义表示。与 OpenAI 类似你需要 API 密钥。安装pipinstallcohere使用fromredisvl.utils.vectorizeimportCohereTextVectorizer coCohereTextVectorizer(modelembed-english-v3.0,api_config{api_key:your-cohere-key},)# 查询时使用 input_typesearch_queryquery_vecco.embed(search query,input_typesearch_query)# 文档索引时使用 input_typesearch_documentdoc_vecco.embed(document content,input_typesearch_document)为什么需要input_typeCohere 的不同模型针对查询和文档做了优化指定类型有助于模型调整内部表示提升检索效果。七、VoyageAI 向量化器VoyageAI 提供高性能嵌入模型如voyage-law-2、voyage-2等。也支持input_type参数query/document。安装与使用pipinstallvoyageaifromredisvl.utils.vectorizeimportVoyageAIVectorizer voVoyageAIVectorizer(modelvoyage-law-2,api_config{api_key:your-voyage-key},)query_vecvo.embed(query,input_typequery)doc_vecvo.embed(document,input_typedocument)八、Mistral AI 向量化器Mistral AI 提供其嵌入模型如mistral-embed。使用方式与 OpenAI 类似。pipinstallmistralaifromredisvl.utils.vectorizeimportMistralAITextVectorizer mistralMistralAITextVectorizer()# 默认从环境变量读取 MISTRAL_API_KEYembeddingawaitmistral.aembed(This is a test sentence.)# 异步示例九、Amazon Bedrock 向量化器Bedrock 提供来自多个厂商的基础模型包括 Amazon 自研的 Titan 嵌入模型。需要配置 AWS 凭证。安装pipinstallredisvl[bedrock]配置凭证importos os.environ[AWS_ACCESS_KEY_ID]...os.environ[AWS_SECRET_ACCESS_KEY]...os.environ[AWS_REGION]us-east-1使用fromredisvl.utils.vectorizeimportBedrockVectorizer bedrockBedrockVectorizer(modelamazon.titan-embed-text-v2:0)embeddingbedrock.embed(This is a test sentence.)embeddingsbedrock.embed_many(sentences)十、自定义向量器CustomVectorizer如果你有自己的嵌入函数例如封装了某个私有模型RedisVL 提供了CustomVectorizer让你轻松接入。fromredisvl.utils.vectorizeimportCustomVectorizerdefmy_embed(text_input,**kwargs):# 你的嵌入逻辑返回一个向量列表或单个向量return[0.1]*768# 示例custom_vecCustomVectorizer(my_embed)embeddingcustom_vec.embed(test)自定义向量器可以直接用于 RedisVL 的其他组件例如语义缓存SemanticCache或索引查询。将向量器与 SearchIndex 集成生成向量后我们通常需要将它们存入 Redis 并执行相似性搜索。下面演示完整流程。1. 定义 SchemaYAML 格式# schema.yamlversion:0.1.0index:name:vectorizersprefix:docstorage_type:hashfields:-name:texttype:text-name:embeddingtype:vectorattrs:dims:768# 必须与模型输出维度一致algorithm:flatdistance_metric:cosine2. 创建索引并加载数据fromredisvl.indeximportSearchIndexfromredisvl.redis.utilsimportarray_to_buffer indexSearchIndex.from_yaml(./schema.yaml,redis_urlredis://localhost:6379)index.create(overwriteTrue)# 使用 HuggingFace 向量器生成向量hfHFTextVectorizer(modelsentence-transformers/all-mpnet-base-v2)embeddingshf.embed_many(sentences)# 准备数据向量需转换为字节格式float32data[{text:t,embedding:array_to_buffer(v,dtypefloat32)}fort,vinzip(sentences,embeddings)]index.load(data)3. 执行向量查询fromredisvl.queryimportVectorQuery query_vechf.embed(That is a happy cat)# 查询文本queryVectorQuery(vectorquery_vec,vector_field_nameembedding,return_fields[text],num_results3)resultsindex.query(query)fordocinresults: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 中定义的维度类型一致。hf_float16HFTextVectorizer(modelsentence-transformers/all-mpnet-base-v2,dtypefloat16)bytes_vechf_float16.embed(test,as_bufferTrue)# 返回 float16 编码的字节流选择较低精度如float16可节省存储空间和加速计算但可能轻微影响精度。float32是默认值兼容性最好。总结与最佳实践Provider适用场景注意点OpenAI通用、高质量需要 API Key费用较高需网络Azure OpenAI企业 Azure 环境配置复杂但合规性更好HuggingFace开源免费可离线模型较大首次需下载Ollama本地运行完全免费需安装 Ollama 并拉取模型VertexAIGCP 生态用户需要 GCP 权限和配置Cohere针对检索优化的模型注意input_type参数VoyageAI特定领域如法律模型同样需指定input_typeMistral AI欧洲 AI 供应商支持异步需 API KeyAmazon BedrockAWS 企业用户需要 AWS 凭证关键要点所有向量化器共享相同的接口embed单条、embed_many批量、aembed/aembed_many异步批量嵌入能显著提高效率尤其对于 API 类服务内部实现可能将多个文本打包成一次请求向量存储前需转换为字节流as_bufferTrue或array_to_buffer查询时使用VectorQuery并传入查询向量即可获得相似结果通过 RedisVL 的向量化器你可以轻松地在多个嵌入模型之间切换并与 Redis 的向量索引完美结合构建高性能的语义搜索、推荐系统或 RAG 应用。现在就开始尝试吧
在现代语义搜索和 RAG 应用中文本嵌入Embedding是核心基础——它将自然语言转换成高维数值向量使得计算机能够“理解”语义相似性。RedisVL 提供了一套统一的向量化器接口让你可以使用多种主流嵌入服务OpenAI、HuggingFace、Ollama、Cohere 等轻松生成向量并直接与 Redis 的向量索引无缝集成。前置准备在开始之前请确保已安装 RedisVLpip install redisvl有运行的 Redis 实例Redis 8 或 Redis Cloud且已启用 RediSearch 模块根据你计划使用的嵌入服务准备好对应的 API 密钥或本地模型服务如 Ollama 本地运行概要使用 OpenAI、HuggingFace、Ollama、Cohere 等主流 Provider 生成文本向量同步与异步的嵌入方法以及批量嵌入的高效技巧如何构建自定义向量器适配你自己的嵌入函数如何将向量器与 RedisVL 索引结合实现语义搜索整体工作流程下图展示了使用向量化器的完整流程用户文本向量化器选择 ProviderOpenAIHuggingFaceOllamaCohere / 其他生成向量存入 Redis 索引执行向量查询返回相似结果向量化器充当了“翻译官”的角色将文本转化为数值表示这个过程通常称为嵌入Embedding。不同的 Provider 背后是不同的模型架构和训练数据但 RedisVL 提供了统一的 API使得切换 Provider 变得非常简单。示例文本为了演示一致性我们将在所有示例中使用以下三句英文That is a happy dogThat is a happy personToday is a sunny day一、OpenAI 向量化器OpenAI 提供高质量通用嵌入模型如text-embedding-ada-002。使用前需安装openai库并设置 API 密钥。安装与配置pipinstallopenaiimportosimportgetpassfromredisvl.utils.vectorizeimportOpenAITextVectorizer api_keyos.environ.get(OPENAI_API_KEY)orgetpass.getpass(Enter your OpenAI API key: )# 创建向量化器实例oaiOpenAITextVectorizer(modeltext-embedding-ada-002,api_config{api_key:api_key},)单条嵌入embeddingoai.embed(This is a test sentence.)print(len(embedding))# 输出 1536批量嵌入sentences[That is a happy dog,That is a happy person,Today is a sunny day]embeddingsoai.embed_many(sentences)# 返回列表每个元素是一个向量异步嵌入提高并发效率embeddingsawaitoai.aembed_many(sentences)原理embed_many内部可能会将多个文本拼接成一次 API 请求取决于 Provider 支持从而减少网络往返次数大幅提升吞吐量。二、Azure OpenAI 向量化器Azure OpenAI 是 OpenAI 模型的 Azure 托管版本配置稍有不同。fromredisvl.utils.vectorizeimportAzureOpenAITextVectorizer az_oaiAzureOpenAIVectorizer(modelyour-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 密钥。安装pipinstallsentence-transformers使用fromredisvl.utils.vectorizeimportHFTextVectorizer hfHFTextVectorizer(modelsentence-transformers/all-mpnet-base-v2)embeddinghf.embed(This is a test sentence.)embeddingshf.embed_many(sentences,as_bufferTrue)# as_bufferTrue 返回字节流便于存入 Redis注意本地模型会下载到缓存目录首次运行需要联网。之后完全离线运行适合对数据隐私敏感的场景。四、Ollama 向量化器Ollama 允许你在本地运行嵌入模型如nomic-embed-text完全离线且免费。你需要先安装 Ollama 并拉取模型。安装与准备pipinstallredisvl[ollama]ollama pull nomic-embed-text ollama serve# 确保后台进程运行使用fromredisvl.utils.vectorizeimportOllamaTextVectorizer ollamaOllamaTextVectorizer(modelnomic-embed-text)embeddingollama.embed(This is a test sentence.)embeddingsollama.embed_many(sentences,batch_size2)# batch_size 控制每次发送的文本数embed_many也支持异步aembed_many。五、VertexAI 向量化器Google CloudVertexAI 是 GCP 的统一 AI 平台提供多种嵌入模型。你需要启用 Vertex AI API配置服务账号并设置环境变量。安装pipinstallgoogle-cloud-aiplatform1.26环境变量GOOGLE_APPLICATION_CREDENTIALS服务账号 JSON 文件路径GCP_PROJECT_ID项目 IDGCP_LOCATION区域如us-central1使用fromredisvl.utils.vectorizeimportVertexAIVectorizer vtxVertexAIVectorizer(api_config{project_id:os.environ[GCP_PROJECT_ID],location:os.environ[GCP_LOCATION],google_application_credentials:os.environ[GOOGLE_APPLICATION_CREDENTIALS],})embeddingvtx.embed(This is a test sentence.)六、Cohere 向量化器Cohere 提供专用嵌入模型如embed-english-v3.0特别注重语义表示。与 OpenAI 类似你需要 API 密钥。安装pipinstallcohere使用fromredisvl.utils.vectorizeimportCohereTextVectorizer coCohereTextVectorizer(modelembed-english-v3.0,api_config{api_key:your-cohere-key},)# 查询时使用 input_typesearch_queryquery_vecco.embed(search query,input_typesearch_query)# 文档索引时使用 input_typesearch_documentdoc_vecco.embed(document content,input_typesearch_document)为什么需要input_typeCohere 的不同模型针对查询和文档做了优化指定类型有助于模型调整内部表示提升检索效果。七、VoyageAI 向量化器VoyageAI 提供高性能嵌入模型如voyage-law-2、voyage-2等。也支持input_type参数query/document。安装与使用pipinstallvoyageaifromredisvl.utils.vectorizeimportVoyageAIVectorizer voVoyageAIVectorizer(modelvoyage-law-2,api_config{api_key:your-voyage-key},)query_vecvo.embed(query,input_typequery)doc_vecvo.embed(document,input_typedocument)八、Mistral AI 向量化器Mistral AI 提供其嵌入模型如mistral-embed。使用方式与 OpenAI 类似。pipinstallmistralaifromredisvl.utils.vectorizeimportMistralAITextVectorizer mistralMistralAITextVectorizer()# 默认从环境变量读取 MISTRAL_API_KEYembeddingawaitmistral.aembed(This is a test sentence.)# 异步示例九、Amazon Bedrock 向量化器Bedrock 提供来自多个厂商的基础模型包括 Amazon 自研的 Titan 嵌入模型。需要配置 AWS 凭证。安装pipinstallredisvl[bedrock]配置凭证importos os.environ[AWS_ACCESS_KEY_ID]...os.environ[AWS_SECRET_ACCESS_KEY]...os.environ[AWS_REGION]us-east-1使用fromredisvl.utils.vectorizeimportBedrockVectorizer bedrockBedrockVectorizer(modelamazon.titan-embed-text-v2:0)embeddingbedrock.embed(This is a test sentence.)embeddingsbedrock.embed_many(sentences)十、自定义向量器CustomVectorizer如果你有自己的嵌入函数例如封装了某个私有模型RedisVL 提供了CustomVectorizer让你轻松接入。fromredisvl.utils.vectorizeimportCustomVectorizerdefmy_embed(text_input,**kwargs):# 你的嵌入逻辑返回一个向量列表或单个向量return[0.1]*768# 示例custom_vecCustomVectorizer(my_embed)embeddingcustom_vec.embed(test)自定义向量器可以直接用于 RedisVL 的其他组件例如语义缓存SemanticCache或索引查询。将向量器与 SearchIndex 集成生成向量后我们通常需要将它们存入 Redis 并执行相似性搜索。下面演示完整流程。1. 定义 SchemaYAML 格式# schema.yamlversion:0.1.0index:name:vectorizersprefix:docstorage_type:hashfields:-name:texttype:text-name:embeddingtype:vectorattrs:dims:768# 必须与模型输出维度一致algorithm:flatdistance_metric:cosine2. 创建索引并加载数据fromredisvl.indeximportSearchIndexfromredisvl.redis.utilsimportarray_to_buffer indexSearchIndex.from_yaml(./schema.yaml,redis_urlredis://localhost:6379)index.create(overwriteTrue)# 使用 HuggingFace 向量器生成向量hfHFTextVectorizer(modelsentence-transformers/all-mpnet-base-v2)embeddingshf.embed_many(sentences)# 准备数据向量需转换为字节格式float32data[{text:t,embedding:array_to_buffer(v,dtypefloat32)}fort,vinzip(sentences,embeddings)]index.load(data)3. 执行向量查询fromredisvl.queryimportVectorQuery query_vechf.embed(That is a happy cat)# 查询文本queryVectorQuery(vectorquery_vec,vector_field_nameembedding,return_fields[text],num_results3)resultsindex.query(query)fordocinresults: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 中定义的维度类型一致。hf_float16HFTextVectorizer(modelsentence-transformers/all-mpnet-base-v2,dtypefloat16)bytes_vechf_float16.embed(test,as_bufferTrue)# 返回 float16 编码的字节流选择较低精度如float16可节省存储空间和加速计算但可能轻微影响精度。float32是默认值兼容性最好。总结与最佳实践Provider适用场景注意点OpenAI通用、高质量需要 API Key费用较高需网络Azure OpenAI企业 Azure 环境配置复杂但合规性更好HuggingFace开源免费可离线模型较大首次需下载Ollama本地运行完全免费需安装 Ollama 并拉取模型VertexAIGCP 生态用户需要 GCP 权限和配置Cohere针对检索优化的模型注意input_type参数VoyageAI特定领域如法律模型同样需指定input_typeMistral AI欧洲 AI 供应商支持异步需 API KeyAmazon BedrockAWS 企业用户需要 AWS 凭证关键要点所有向量化器共享相同的接口embed单条、embed_many批量、aembed/aembed_many异步批量嵌入能显著提高效率尤其对于 API 类服务内部实现可能将多个文本打包成一次请求向量存储前需转换为字节流as_bufferTrue或array_to_buffer查询时使用VectorQuery并传入查询向量即可获得相似结果通过 RedisVL 的向量化器你可以轻松地在多个嵌入模型之间切换并与 Redis 的向量索引完美结合构建高性能的语义搜索、推荐系统或 RAG 应用。现在就开始尝试吧
