RedisVL Schema 官方手册详读-拓冰建站

1 Schema 三大组件

组件	说明
version	Schema 规范版本，当前仅支持 `0.1.0`
index	索引级配置：`name / prefix / key_separator / storage_type`
fields	需要写入索引的字段集合及其自定义属性

2 `IndexSchema` 类总览

class IndexSchema(*, index: IndexInfo,                     # 基础索引信息fields: Dict[str, BaseField] = {},    # 字段集合version: Literal["0.1.0"] = "0.1.0",  # 规范版本
)

2.1 主要用途

声明式管理 倒排 + 向量 混合索引
支持 YAML / Dict 双格式创建
提供动态增删字段、序列化、验证等操作

2.2 创建方式

from redisvl.schema import IndexSchema# YAML
schema = IndexSchema.from_yaml("schema.yaml")# Dict
schema = IndexSchema.from_dict({"index": { ... },"fields": [ ... ]
})

2.3 关键方法 & 属性

方法 / 属性	作用	抛出
`add_field(field_inputs)`	追加单字段	`ValueError`（重名 / 缺必填）
`add_fields(fields)`	批量追加字段列表	`ValueError`（重名）
`remove_field(name)`	删除指定字段	—
`from_dict(data)` / `from_yaml(path)`	构建 Schema	—
`to_dict()` / `to_yaml(path, overwrite=True)`	序列化为 Dict / 写入 YAML	`FileExistsError`（overwrite=False 且已存在）
`field_names` (property)	所有字段名列表	—
`fields` (attr)	`Dict[str, BaseField]` 字段映射	—
`index` (attr)	`IndexInfo` 索引信息	—
`version` (attr)	`'0.1.0'`	—

3 Schema 示例

3.1 YAML

version: '0.1.0'index:name: user-indexprefix: userkey_separator: ":"storage_type: jsonfields:- name: usertype: tag- name: credit_scoretype: tag- name: embeddingtype: vectorattrs:algorithm: flatdims: 3distance_metric: cosinedatatype: float32

3.2 Python Dict

index_schema_dict = {"index": {"name": "user-index","prefix": "user","key_separator": ":","storage_type": "json",},"fields": [{"name": "user", "type": "tag"},{"name": "credit_score", "type": "tag"},{"name": "embedding","type": "vector","attrs": {"algorithm": "flat","dims": 3,"distance_metric": "cosine","datatype": "float32"}}]
}
schema = IndexSchema.from_dict(index_schema_dict)

注意：fields 中 字段名必须唯一，否则会触发 ValueError。

4 动态增删字段示例

# 新增单个 TAG 字段
schema.add_field({"name": "user", "type": "tag"})# 新增向量字段
schema.add_field({"name": "user-embedding","type": "vector","attrs": {"dims": 1024, "algorithm": "flat", "datatype": "float32"}
})# 批量追加
schema.add_fields([{"name": "bio", "type": "text"},{"name": "age-vec","type": "vector","attrs": {"dims": 256, "algorithm": "flat", "datatype": "float32"}}
])# 删除字段
schema.remove_field("credit_score")

5 字段定义速查

字段类型	必填键	可选键 (`attrs`)
text	`name`, `type=text`	`weight` \| `no_stem` \| `withsuffixtrie` \| `phonetic_matcher` \| `sortable`
tag	`name`, `type=tag`	`separator` \| `case_sensitive` \| `withsuffixtrie` \| `sortable`
numeric	`name`, `type=numeric`	`sortable`
geo	`name`, `type=geo`	`sortable`
vector (通用)	`name`, `type=vector`	`dims` · `algorithm(flat/hnsw)` · `datatype(bfloat16/float16/float32/float64)` · `distance_metric(COSINE/L2/IP)`
vector (HNSW 追加)	—	`m` · `ef_construction` · `ef_runtime` · `epsilon`

路径与排序示例

- name: titletype: textpath: $.document.titleattrs:weight: 1.0withsuffixtrie: true- name: locationtype: geoattrs:sortable: true

6 序列化 / 反序列化

# 保存为 YAML
schema.to_yaml("schema_out.yaml")# 读取再转 Dict
reloaded = IndexSchema.from_yaml("schema_out.yaml")
print(reloaded.to_dict())

7 常见报错对照

报错信息	常见原因
`ValueError: name already exists`	字段重名
`ValidationError` (pydantic)	字段缺必填 / 类型不符
`FileExistsError`	`to_yaml(..., overwrite=False)` 且文件已存在
`dims missing` / `datatype not supported`	VECTOR `attrs` 参数不完整或非法