Schema设计 #
一、Schema概述 #
1.1 什么是Schema #
Schema 定义了 Collection 的结构，包括字段列表、描述信息和配置选项。
text
Schema结构：
┌─────────────────────────────────────────┐
│ Schema │
├─────────────────────────────────────────┤
│ 字段列表 (Fields) │
│ ├── 字段1: id (主键) │
│ ├── 字段2: name (标量) │
│ ├── 字段3: embedding (向量) │
│ └── ... │
├─────────────────────────────────────────┤
│ 描述信息 (Description) │
├─────────────────────────────────────────┤
│ 配置选项 │
│ ├── enable_dynamic_field │
│ └── auto_id │
└─────────────────────────────────────────┘
二、字段定义 #
2.1 FieldSchema参数 #
python
from pymilvus import FieldSchema, DataType
field = FieldSchema(
name="field_name",
dtype=DataType.INT64,
is_primary=False,
auto_id=False,
description="字段描述",
max_length=256,
dim=768,
element_type=DataType.VARCHAR,
max_capacity=10
)
2.2 参数说明 #
| 参数 | 类型 | 说明 |
|---|---|---|
| name | str | 字段名称 |
| dtype | DataType | 数据类型 |
| is_primary | bool | 是否主键 |
| auto_id | bool | 是否自动生成ID |
| description | str | 字段描述 |
| max_length | int | VARCHAR最大长度 |
| dim | int | 向量维度 |
| element_type | DataType | 数组元素类型 |
| max_capacity | int | 数组最大容量 |
2.3 主键字段 #
python
id_field = FieldSchema(
name="id",
dtype=DataType.INT64,
is_primary=True,
auto_id=False,
description="主键ID"
)
varchar_id_field = FieldSchema(
name="id",
dtype=DataType.VARCHAR,
max_length=64,
is_primary=True,
auto_id=False,
description="字符串主键"
)
2.4 向量字段 #
python
float_vector = FieldSchema(
name="embedding",
dtype=DataType.FLOAT_VECTOR,
dim=768,
description="浮点向量"
)
binary_vector = FieldSchema(
name="binary_embedding",
dtype=DataType.BINARY_VECTOR,
dim=512,
description="二进制向量"
)
float16_vector = FieldSchema(
name="float16_embedding",
dtype=DataType.FLOAT16_VECTOR,
dim=768,
description="16位浮点向量"
)
sparse_vector = FieldSchema(
name="sparse_embedding",
dtype=DataType.SPARSE_FLOAT_VECTOR,
description="稀疏向量"
)
2.5 标量字段 #
python
int_field = FieldSchema(
name="age",
dtype=DataType.INT32,
description="年龄"
)
float_field = FieldSchema(
name="price",
dtype=DataType.FLOAT,
description="价格"
)
bool_field = FieldSchema(
name="is_active",
dtype=DataType.BOOL,
description="是否激活"
)
varchar_field = FieldSchema(
name="title",
dtype=DataType.VARCHAR,
max_length=512,
description="标题"
)
2.6 复杂字段 #
python
json_field = FieldSchema(
name="metadata",
dtype=DataType.JSON,
description="JSON元数据"
)
array_field = FieldSchema(
name="tags",
dtype=DataType.ARRAY,
element_type=DataType.VARCHAR,
max_capacity=20,
max_length=64,
description="标签数组"
)
int_array_field = FieldSchema(
name="scores",
dtype=DataType.ARRAY,
element_type=DataType.INT32,
max_capacity=100,
description="分数数组"
)
三、CollectionSchema #
3.1 创建Schema #
python
from pymilvus import CollectionSchema
fields = [
FieldSchema(name="id", dtype=DataType.INT64, is_primary=True),
FieldSchema(name="title", dtype=DataType.VARCHAR, max_length=512),
FieldSchema(name="embedding", dtype=DataType.FLOAT_VECTOR, dim=768)
]
schema = CollectionSchema(
fields=fields,
description="文档集合",
enable_dynamic_field=True
)
3.2 Schema参数 #
| 参数 | 类型 | 说明 |
|---|---|---|
| fields | list | 字段列表 |
| description | str | Schema描述 |
| enable_dynamic_field | bool | 启用动态字段 |
| auto_id | bool | 自动生成ID |
3.3 动态字段 #
python
schema = CollectionSchema(
fields=fields,
description="支持动态字段的集合",
enable_dynamic_field=True
)
data = [
{
"id": 1,
"title": "文档标题",
"embedding": [0.1] * 768,
"author": "张三",
"views": 1000,
"tags": ["AI", "ML"]
}
]
collection.insert(data)
四、主键设计 #
4.1 主键类型 #
text
主键类型：
┌─────────────────────────────────────────┐
│ INT64 主键 │
├─────────────────────────────────────────┤
│ 优点: 性能高、存储小 │
│ 缺点: 需要自己生成唯一ID │
│ 适用: 自增ID场景 │
└─────────────────────────────────────────┘
┌─────────────────────────────────────────┐
│ VARCHAR 主键 │
├─────────────────────────────────────────┤
│ 优点: 可读性好、可使用业务ID │
│ 缺点: 性能略低、存储较大 │
│ 适用: UUID、业务主键场景 │
└─────────────────────────────────────────┘
4.2 INT64主键 #
python
id_field = FieldSchema(
name="id",
dtype=DataType.INT64,
is_primary=True,
auto_id=False
)
data = [
[1, 2, 3],
["文档1", "文档2", "文档3"],
[[0.1]*768, [0.2]*768, [0.3]*768]
]
4.3 VARCHAR主键 #
python
id_field = FieldSchema(
name="doc_id",
dtype=DataType.VARCHAR,
max_length=64,
is_primary=True
)
import uuid
data = [
[str(uuid.uuid4()), str(uuid.uuid4())],
["文档1", "文档2"],
[[0.1]*768, [0.2]*768]
]
4.4 自动生成ID #
python
id_field = FieldSchema(
name="id",
dtype=DataType.INT64,
is_primary=True,
auto_id=True
)
data = [
["文档1", "文档2"],
[[0.1]*768, [0.2]*768]
]
result = collection.insert(data)
print(result.primary_keys)
五、向量字段设计 #
5.1 向量维度选择 #
text
常用向量维度：
模型 维度
──────────────────────────────
OpenAI text-embedding-3-small 1536
OpenAI text-embedding-3-large 3072
Sentence-BERT 768
BERT-base 768
ResNet50 2048
VGG16 4096
CLIP 512
5.2 向量类型选择 #
python
float_vector = FieldSchema(
name="embedding",
dtype=DataType.FLOAT_VECTOR,
dim=768
)
binary_vector = FieldSchema(
name="binary_embedding",
dtype=DataType.BINARY_VECTOR,
dim=512
)
float16_vector = FieldSchema(
name="float16_embedding",
dtype=DataType.FLOAT16_VECTOR,
dim=768
)
5.3 多向量字段 #
python
fields = [
FieldSchema(name="id", dtype=DataType.INT64, is_primary=True),
FieldSchema(name="title_embedding", dtype=DataType.FLOAT_VECTOR, dim=384),
FieldSchema(name="content_embedding", dtype=DataType.FLOAT_VECTOR, dim=768),
FieldSchema(name="image_embedding", dtype=DataType.FLOAT_VECTOR, dim=512)
]
六、Schema验证 #
6.1 检查Schema #
python
collection = Collection("documents")
schema = collection.schema
print(f"描述: {schema.description}")
print(f"动态字段: {schema.enable_dynamic_field}")
for field in schema.fields:
print(f"字段: {field.name}, 类型: {field.dtype}")
if field.is_primary:
print(f" 主键: 是")
if field.auto_id:
print(f" 自动ID: 是")
6.2 验证字段 #
python
def validate_field_value(field, value):
if field.dtype == DataType.INT64:
return isinstance(value, int)
elif field.dtype == DataType.FLOAT:
return isinstance(value, (int, float))
elif field.dtype == DataType.VARCHAR:
return isinstance(value, str) and len(value) <= field.max_length
elif field.dtype == DataType.FLOAT_VECTOR:
return isinstance(value, list) and len(value) == field.dim
return True
七、Schema最佳实践 #
7.1 文档搜索Schema #
python
fields = [
FieldSchema(
name="doc_id",
dtype=DataType.VARCHAR,
max_length=64,
is_primary=True,
description="文档唯一标识"
),
FieldSchema(
name="title",
dtype=DataType.VARCHAR,
max_length=512,
description="文档标题"
),
FieldSchema(
name="content",
dtype=DataType.VARCHAR,
max_length=65535,
description="文档内容"
),
FieldSchema(
name="embedding",
dtype=DataType.FLOAT_VECTOR,
dim=1536,
description="OpenAI嵌入向量"
),
FieldSchema(
name="metadata",
dtype=DataType.JSON,
description="元数据"
),
FieldSchema(
name="created_at",
dtype=DataType.INT64,
description="创建时间戳"
)
]
schema = CollectionSchema(
fields=fields,
description="文档搜索集合",
enable_dynamic_field=True
)
7.2 推荐系统Schema #
python
fields = [
FieldSchema(
name="item_id",
dtype=DataType.INT64,
is_primary=True,
description="物品ID"
),
FieldSchema(
name="item_name",
dtype=DataType.VARCHAR,
max_length=256,
description="物品名称"
),
FieldSchema(
name="category",
dtype=DataType.VARCHAR,
max_length=64,
description="分类"
),
FieldSchema(
name="price",
dtype=DataType.FLOAT,
description="价格"
),
FieldSchema(
name="tags",
dtype=DataType.ARRAY,
element_type=DataType.VARCHAR,
max_capacity=20,
max_length=32,
description="标签"
),
FieldSchema(
name="item_embedding",
dtype=DataType.FLOAT_VECTOR,
dim=128,
description="物品嵌入向量"
)
]
7.3 图像搜索Schema #
python
fields = [
FieldSchema(
name="image_id",
dtype=DataType.INT64,
is_primary=True,
auto_id=True,
description="图像ID"
),
FieldSchema(
name="image_url",
dtype=DataType.VARCHAR,
max_length=1024,
description="图像URL"
),
FieldSchema(
name="category",
dtype=DataType.VARCHAR,
max_length=64,
description="分类"
),
FieldSchema(
name="feature_vector",
dtype=DataType.FLOAT_VECTOR,
dim=2048,
description="ResNet特征向量"
),
FieldSchema(
name="width",
dtype=DataType.INT32,
description="宽度"
),
FieldSchema(
name="height",
dtype=DataType.INT32,
description="高度"
)
]
八、Schema修改 #
8.1 查看当前Schema #
python
collection = Collection("documents")
print(collection.schema)
8.2 动态添加字段数据 #
python
collection = Collection("documents")
data = [
{
"id": 1,
"title": "文档标题",
"embedding": [0.1] * 768,
"new_field": "新字段值"
}
]
collection.insert(data)
九、总结 #
Schema设计要点：
| 要点 | 说明 |
|---|---|
| 主键选择 | INT64性能高，VARCHAR可读性好 |
| 向量维度 | 根据模型选择合适维度 |
| 动态字段 | 启用后可灵活添加字段 |
| 字段命名 | 遵循命名规范，见名知意 |
| 描述信息 | 添加描述便于维护 |
下一步，让我们学习数据类型！
最后更新：2026-04-04