文档中心

缓存数据库 Redis 版

扩展模块

Valkey-Search

缓存数据库 Redis 版提供了基于 Valkey 模块的 Valkey-Search 扩展模块。您可以通过 Valkey-Search 高效的向量存储与检索能力，将历史对话内容转化为向量形式并持久化存储在 Redis 实例，帮助构建具备“长记忆”的 Chatbot 系统，为实现可持续、高一致性的多轮对话交互提供可靠技术支撑。本文介绍缓存数据库 Redis 版的 Valkey-Search 扩展模块相关信息，包括功能原理，适用场景，以及具体的命令语法。

前提条件

实例的版本需同时满足如下要求才可使用 Valkey-Search 扩展模块：

数据库版本需为 Redis 7.0。

Proxy 小版本需大于等于 1.511.0。

Server 小版本需大于等于 7.511.0。

说明

您可以在实例信息页签下查看实例的数据库版本和小版本信息，具体操作步骤，请参见查看实例信息。

实例状态需为运行中。关于实例状态的更多说明，请参见实例状态。

功能特性

缓存数据库 Redis 版的 Valkey-Search 提供了两种用于向量相似性搜索的索引算法：分层可导航小世界图（Hierarchical Navigable Small World，简称 HNSW）和暴力搜索（Flat Search）。下表汇总了两种索引算法的特性差异和使用场景供您参考。

特性对比	HNSW	Flat search
搜索原理	HNSW 是一种基于图论的高性能近似最近邻搜索算法。该算法的核心在于构建一个层次化的可导航小世界图结构，通过将数据点组织为多层级联稀疏图，可在显著提升搜索效率的同时保持较高的查询准确率。	Flat Search 是一种基础的向量相似性检索方法，采用无索引的暴力匹配机制。当进行搜索时，该算法会将查询向量与数据集中的每个向量进行比较，无需预构建复杂数据结构或进行近似处理。该算法会遍历所有数据点进行精确比较，能够确保 100% 的召回率。
搜索速度	通过层级图结构，搜索路径短，速度快。	线性扫描，查询时间随数据量线性增长。数据量大时，查询延迟高，资源消耗大。
结果精度	近似搜索准确率高，通常能达到 90%~99% 以上。	100% 精确，返回真正的最近邻，没有近似误差。
内存占用	内存占用高，需要额外存储图的边和层级结构。	内存占用低，只存储原始向量数据，几乎没有额外内存消耗。
实现复杂度	索引构建复杂，算法和数据结构较复杂，参数调优难度较大。	逻辑简单，易于实现和维护。
数据规模扩展	扩展性好，适合数十万甚至数亿的大规模数据集。	扩展性差，难以支持实时更新或增量添加新数据，适合小规模数据集。
使用场景	大规模、高维度、低延迟、高并发的向量搜索。需要快速响应和高召回率的在线服务。动态数据环境（频繁插入/删除）。语义搜索、推荐系统、图像检索等。	数据量较小，查询延迟要求不高。对搜索结果精度要求极高的场景。离线批量处理或实验场景。

命令语法

命令列表

Valkey-Search 支持的命令如下表所示。

说明

针对下表中的命令语法，定义如下：

大写关键字：命令关键字，如 FT.CREATE。

小写关键字：可自定义的参数。

[]：[] 内的为可选参数，不在 [] 内的为必选参数。

<可选项 1>|<可选项 2>|<可选项 n>：一组互斥的参数可选项，即仅支持从可选项中选择一个参数进行设置。

命令	语法	说明
FT.CREATE	FT.CREATE <index-name> [ON HASH \| JSON] [PREFIX <count> <prefix> [<prefix>...]] SCHEMA ( <field-identifier> [AS <field-alias>] NUMERIC \| TAG [SEPARATOR <sep>] [CASESENSITIVE] \| VECTOR [HNSW \| FLAT] <attr_count> [<attribute_name> <attribute_value>]+) )+	创建一个空的索引，支持在创建时指定索引相关属性，如允许被索引的键前缀，向量算法，向量维度等。支持 HASH 及其 JSON 数据类型索引。说明索引创建成功后会启动回填进程，即：持续扫描存量数据，并将满足条件的数据构建至索引中。新插入的数据若满足索引条件，也会被自动加入索引中。
FT.DROPINDEX	FT.DROPINDEX <index_name>	删除指定索引。说明该命令只会删除索引，不会删除原文数据。您可以通过 UNLINK 或 DEL 命令来异步或同步删除原文数据。
FT.SEARCH	FT.SEARCH <index-name> <query_string> [NOCONTENT] [TIMEOUT] [PARAMS <count> <name1> <value1>...] [RETURN <count> <field_or_jsonpath> [AS <alias>] ...] [LIMIT <offset> <count>] [DIALECT <dialect>]	在指定索引中执行搜索查询。支持使用 JSONPath 提取结果。
FT._LIST	FT._LIST	查询当前数据库中已创建的索引列表。
FT.INFO	FT.INFO <index_name>	查询指定索引的详细信息，例如索引的参数，已索引的数据量等。包括 key_type (HASH 或 JSON)。

注意事项

如需使用 Valkey-Search 功能，请提交工单联系技术支持申请使用。

申请完成后，拥有 Administrator 角色的账号默认具备 Valkey-Search 相关命令的所有权限。您也可以根据业务需要创建一个允许使用所有 Valkey-Search 类命令的新角色（即该角色的 ACL 规则需设置为 +@valkey_search），创建角色后，您需要通过拥有该角色的账号登录 Redis 后即可使用 Valkey-Search 相关命令。创建角色的具体操作步骤，请参见创建角色。

缓存数据库 Redis 版支持对 Valkey-Search 数据类型进行大、热 Key 分析，能够帮助及时发现并分析数据库中的热 Key 和大 Key 详情，为您优化热 Key 和大 Key 提供数据参考。具体操作步骤，请参见大 Key 分析和热 Key 分析。

成功申请使用 Valkey-Search 功能后，实例将不再支持任何数据恢复功能，包括：

按备份集恢复

按时间点恢复

恢复已删除实例

FT.CREATE

类别	说明
命令语法	FT.CREATE <index-name> [ON HASH \| JSON] [PREFIX <count> <prefix> [<prefix>...]] SCHEMA ( <field-identifier> [AS <field-alias>] NUMERIC \| TAG [SEPARATOR <sep>] [CASESENSITIVE] \| VECTOR [HNSW \| FLAT] <attr_count> [<attribute_name> <attribute_value>]+) )+
时间复杂度	O (N log N)，其中 N 是被索引项的数量。
命令描述	创建一个空的索引，支持在创建时指定索引相关属性，如允许被索引的键前缀，向量算法，向量维度等。说明索引创建成功后会启动回填进程，即：持续扫描存量数据，并将满足条件的数据构建至索引中。新插入的数据若满足索引条件，也会被自动加入索引中。
选项	index-name：新创建的索引名称，必填。 ON HASH \| JSON：指定被索引数据的数据类型，选填，默认值：HASH。若需索引 JSON 文档，请设置为 JSON。 PREFIX <count> <prefix>...：指定允许被索引的键前缀，选填，若不设置该参数，默认索引所有的 HASH 数据。其中 <count> 为前缀数量，<prefix> 为具体的前缀，允许同时传入多个前缀。例如，PREFIX 2 doc: user: 表示只索引以 doc: 或 user: 开头的键。 SCHEMA：索引创建命令的核心部分，用于指定索引的字段名称，字段类型，以及字段属性。其中： field-identifier：对于 HASH 为字段名；对于 JSON 为 JSONPath 表达式（如 $.user.age）。 AS field-alias：为字段设置别名，建议在 JSONPath 下使用以简化查询。 NUMERIC \| TAG \| VECTOR：指定索引字段的类型为 NUMERIC，TAG 或 VECTOR，其中： NUMERIC：指定索引数字类型的数据。 TAG：指定索引包含了目标标签的数据。您可以为 TAG 类型的索引字段设置如下属性： SEPARATOR <sep>：指定 tag 的分隔符，选填。取值范围：,.<>{}[]"':;!@#$%^&*()-+=~，默认值：,。 CASESENSITIVE：指定 tag 是否区分大小写，选填，默认不区分大小写。 VECTOR：指定索引向量类型的数据。您可以为 VECTOR 类型的索引字段选择 HNSW 或 FLAT 向量索引算法，不同索引算法支持设置的属性不同： FLAT 算法支持设置如下属性： DIM <number>：向量维度，必填。 TYPE FLOAT32：数据类型，必填。当前仅支持 FLOAT32。 DISTANCE_METRIC [L2 \| IP \| COSINE]：距离算法，必填。取值范围：L2，IP 或 COSINE。 INITIAL_CAP <size>：初始的索引大小。选填。 HNSW 算法支持设置如下属性： DIM <number>：向量维度，必填。 TYPE FLOAT32：数据类型，必填。当前仅支持 FLOAT32。 DISTANCE_METRIC [L2 \| IP \| COSINE]：距离算法，必填。取值范围：L2，IP 或 COSINE。 INITIAL_CAP <size>：初始的索引大小。选填。 M <number>：指定构建索引时每个节点的最大邻居数（即最大出边数），选填。默认值：16，最大值：512。 EF_CONSTRUCTION <number>：指定索引构建过程中检查的向量数量，选填。该参数值越高，召回率会越高，但索引创建时间也会更长。默认值：200，最大值：4096。 EF_RUNTIME <number>：指定查询操作时要检查的向量数量。选填。默认值：10，最大值：4096。您可以单独为运行的每个查询设置该参数，该参数值越高，召回率越高，但查询时间也会越长。说明关于 HNSW 和 FLAT 向量索引算法的更多信息，请参见功能特性。
返回值	OK：执行成功。其他情况返回相应的异常信息。
示例	创建一个名为 redis_doctest 的 HNSW 索引，命令示例如下。 FT.CREATE redis_doctest SCHEMA doctest VECTOR HNSW 6 TYPE FLOAT32 DIM 3 DISTANCE_METRIC L2 返回示例。 OK

FT.DROPINDEX

类别	说明
命令语法	FT.DROPINDEX <index_name>
时间复杂度	O(N)，其中 N 是被索引的数据量。
命令描述	删除指定索引。说明该命令只会删除索引，不会删除原文数据。您可以通过 UNLINK 或 DEL 命令来异步或同步删除原文数据。
选项	<index_name>：需要删除的索引名称。
返回值	OK：执行成功。其他情况返回相应的异常信息。
示例	命令示例。 FT.DROPINDEX redis_doctest 返回示例。 OK

FT.SEARCH

类别	说明
命令语法	FT.SEARCH <index-name> <query_string> [NOCONTENT] [TIMEOUT] [PARAMS <count> <name1> <value1>...] [RETURN <count> <field1>...] [LIMIT <offset> <count>] [DIALECT <dialect>]
时间复杂度	O(N)，其中 N 是被索引的数据量。
命令描述	在指定索引中执行搜索查询。
选项	index-name：需要查询的索引名称，必填。 query_string：搜索查询的表达式字符串，必填。查询表达式的具体格式为 <filtering>=>[ KNN <K> @<vector_field_name> $<vector_parameter_name> <query-modifiers>]。其中： filtering：过滤条件。支持使用星号（*）不表示不进行过滤，即会搜索索引内的所有向量。 vector_field_name：指定索引的向量字段名称。 KNN <K>：指定使用 KNN 算法，返回最相似的 <K> 个结果。 @<vector_field_name>：指定 KNN 的查询向量字段名，向量必须由 Float32 位的浮点数编码而来。 $<vector_parameter_name>：查询参数的占位符，具体的查询向量二进制数据通过 PARAMS <count> <name1> <value1>... 参数传入。 query-modifiers：指定 KNN 搜索行为的关键字，选填。支持设置如下关键字： EF_RUNTIME：后跟一个数值，该值会覆盖创建索引时指定的 EF_RUNTIME 参数值。 AS：将查询结果中的 score 字段重命名为指定字符串。 NOCONTENT：指定是否返回结果的字段内容。选填。若设置了该值，返回结果中展示搜索到的 key 名称，不会返回 score 等其他内容。 TIMEOUT：指定查询的超时时间，选填。单位：毫秒。 PARAMS <count> <name1> <value1>...：查询字符串的参数数量，选填。 RETURN <count> <field1>...：指定搜索结果需要的字段，选填，默认返回所有的字段。支持传入 JSONPath 路径，直接从 JSON 文档中提取特定子字段返回。 LIMIT <offset> <count>：限制返回结果的偏移量（offset）和数量（count），选填，默认值：LIMIT 0 10，即最多返回 10 个 key。 DIALECT <dialect>：指定查询解析器的方言，选填。在使用 JSONPath 索引或复杂提取时，必须设置为 DIALECT 2。
返回值	执行成功时，返回符合查询条件的结果。其他情况返回相应的异常信息。
示例	如下代码以向量相似度搜索为例，介绍相关命令示例：执行如下命令创建一个名为 redis_doctest 的 HNSW 索引，其中 doctest 为向量字段。 FT.CREATE redis_doctest SCHEMA doctest VECTOR HNSW 6 TYPE FLOAT32 DIM 3 DISTANCE_METRIC L2 执行如下命令插入测试数据。 HSET p1 doctest "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80?" HSET p2 doctest "\x00\x00\x00\x00\x00\x00\x80?\x00\x00\x00\x00" HSET p3 doctest "\x00\x00\x80?\x00\x00\x00\x00\x00\x00\x00\x00" HSET p4 doctest "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80?" HSET p5 doctest "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80?" 执行如下命令进行向量相似度搜索，并返回最相似的 3 条数据。 FT.SEARCH redis_doctest "*=>[KNN 3 @doctest $query_vector]" PARAMS 2 query_vector "\xcd\xccL?\x00\x00\x00\x00\x00\x00\x00\x00" DIALECT 2 查询结果示例。 1) (integer) 3 2) "p3" 3) 1) "__doctest_score" 2) "0.0399999953806" 3) "doctest" 4) "\x00\x00\x80?\x00\x00\x00\x00\x00\x00\x00\x00" 4) "p2" 5) 1) "__doctest_score" 2) "1.6400001049" 3) "doctest" 4) "\x00\x00\x00\x00\x00\x00\x80?\x00\x00\x00\x00" 6) "p1" 7) 1) "__doctest_score" 2) "1.6400001049" 3) "doctest" 4) "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80?"

FT._LIST

类别	说明
命令语法	FT._LIST
时间复杂度	O(1)。
命令描述	查询当前数据库中已创建的索引列表。
选项	无。
返回值	执行成功时，会返回当前数据库中已创建的所有索引名称。其他情况返回相应的异常信息。
示例	命令示例。 FT._LIST 返回示例。 1) redis_doctest 2) redis_doctest1

FT.INFO

类别	说明
命令语法	FT.INFO <index_name>
时间复杂度	O(1)。
命令描述	查询指定索引的详细信息，例如索引的参数，已索引的数据量等。
选项	<index_name>：需要查询的索引名称。
返回值	执行成功时，会返回指定索引的相关信息。其他情况返回相应的异常信息。
示例	命令示例。 FT.INFO redis_doctest 返回示例。 1) index_name 2) redis_doctest 3) index_options 4) (empty array) 5) index_definition 6) 1) key_type 2) HASH 3) prefixes 4) 1) 5) default_score 6) "1" 7) attributes 8) 1) 1) identifier 2) doctest 3) attribute 4) doctest 5) type 6) VECTOR 7) index 8) 1) capacity 2) (integer) 10240 3) dimensions 4) (integer) 3 5) distance_metric 6) L2 7) size 8) "2" 9) data_type 10) FLOAT32 11) algorithm 12) 1) name 2) HNSW 3) m 4) (integer) 16 5) ef_construction 6) (integer) 200 7) ef_runtime 8) (integer) 10 9) num_docs 10) "2" 11) num_terms 12) "0" 13) num_records 14) "2" 15) hash_indexing_failures 16) "0" 17) backfill_in_progress 18) "0" 19) backfill_complete_percent 20) "1.000000" 21) mutation_queue_size 22) "0" 23) recent_mutations_queue_delay 24) "0 sec" 25) state 26) ready 说明关于返回结果的参数信息详情，请参见 Response。

最近更新时间：2026.07.30 17:44:23

这个页面对您有帮助吗？

有用

无用