训练模型
更新时间：2025-08-20
使用ivf、ivf_pq算法需要提前训练模型，训练模型相关API如下：
训练模型
用户需要提前创建索引并设定字段类型为"bpack_vector"，写入训练样本数据后，方可对样本数据进行训练，训练模型API如下：
request
JSON
1POST /_bpack/_knn/models/_train
2POST /_bpack/_knn/models/{model_id}/_train
3{
4 "training_index": "train-index-name",
5 "training_field": "train-field-name",
6 "dims": 16,
7 "max_training_vector_count": 1200,
8 "search_size": 100,
9 "description": "My model",
10 "index_type": "ivf_pq",
11 "space_type": "l2",
12 "parameters":{
13 "nlist":128,
14 "nprobes":8,
15 "m":8,
16 "code_size":8
17 }
18}response
JSON
1{
2 "model_id": "model_x"
3}path参数：
| 参数 | 说明 |
|---|---|
model_id |
模型 ID。 |
body参数：
| 参数 | 说明 |
|---|---|
training_index |
选择需要训练的索引。 |
training_field |
选择需要训练的字段，需要在索引中的knn vector字段并且维度相符。 |
dims |
维度。 |
max_training_vector_count |
（可选）索引中用于训练的最大向量数。默认为索引中的所有向量。 |
search_size |
（可选）训练数据是通过scroll查询从索引中查询到的，这个参数是定义每次scroll查询的size。默认为 10,000。 |
description |
（可选）用户提供的模型文字描述简介。 |
index_type |
（可选）索引类型，可选择ivf和ivf_pq，默认为ivf。 |
space_type |
（可选）向量距离算法，支持l2, innerproduct。 |
parameters |
（可选）具体算法参数。 |
index_type：
name |
是否需要训练 | 支持的距离算法 | 说明 |
|---|---|---|---|
ivf |
true | l2, innerproduct | ivf算法，原理是基于聚类算法对向量进行分桶，搜索时候仅搜索部分桶，从而提升搜索效率。 |
ivf_pq |
true | l2, innerproduct | 配合将ivf算法与PQ算法进行了结合，通过PQ降低原始向量的存储开销。 |
IVF parameters
| 参数 | 是否必填 | 默认值 | 是否可修改 | 说明 |
|---|---|---|---|---|
nlist |
false | 4 | false | 向量划分的桶数。较高的值可能会以内存和训练延迟为代价换取更准确的搜索准确性。 |
nprobes |
false | 1 | false | 查询期间要搜索的桶数。较高的值导致更准确但更慢的搜索。 |
IVF_PQ parameters
| 参数 | 是否必填 | 默认值 | 是否可修改 | 说明 |
|---|---|---|---|---|
nlist |
false | 4 | false | 向量划分的桶数。较高的值可能会以内存和训练延迟为代价换取更准确的搜索准确性。 |
nprobes |
false | 1 | false | 查询期间要搜索的桶数。较高的值导致更准确但更慢的搜索。 |
m |
false | 1 | false | 代表将向量分成子向量的个数，子向量彼此独立编码。向量的维度必须能被 m 整除。最大值为 1024。 |
code_size |
false | 8 | false | 代表将子向量编码的位数。推荐值为 8，不建议改为其他值。 |
查询模型
执行训练API后，可以对模型进行查询，查询到模型状态（state）为"created"后，方可正常使用。
request
JSON
1GET /_bpack/_knn/models/{model_id}?prettyresponse
JSON
1{
2 "model_id" : "test-model",
3 "model_blob" : "SXdGbIAAAAAAAAAAAA...",
4 "state": "created",
5 "timestamp": "2023-06-14T03:02:15.246736Z",
6 "description": "My model ivf_pq",
7 "error": "",
8 "index_type": "IVF",
9 "parameters": {},
10 "space_type": "innerproduct",
11 "dimension": 128
12}说明
| 参数 | 说明 |
|---|---|
| model_id | 模型 ID。 |
| model_blob | 模型序列化后具体内容。 |
| state | 状态有"training"、"created"、"failed"，在模型状态为"created"后，才可以正常使用。 |
| timestamp | 代表将子向量编码的位数。推荐值为 8，不建议改为其他值。 |
| description | 用户提供的模型文字描述简介。 |
| error | 错误详情。 |
| index_type | 索引类型。 |
| parameters | 具体算法参数。 |
| space_type | 向量距离算法。 |
| dimension | 维度。 |
删除模型
request
JSON
1DELETE /_bpack/_knn/models/{model_id}response
JSON
1{
2 "model_id": {model_id},
3 "acknowledged": true
4}使用示例
1、创建一个linear的索引，写入数据
JSON
1PUT my_index
2{
3 "mappings": {
4 "properties": {
5 "field": {
6 "type": "bpack_vector",
7 "dims": 4
8 }
9 }
10 }
11}
12
13POST my_index/_bulk
14{"index":{}}
15{"field":[3.5,4.5,6.5,6.5]}
16{"index":{}}
17{"field":[3.5,4.5,6.5,6.5]}
18{"index":{}}
19{"field":[5.5,6.5,6.5,6.5]}
20...2、训练模型，这里以ivf_pq为示例。
JSON
1POST /_bpack/_knn/models/model_ivfpq/_train
2{
3 "training_index": "my_index",
4 "training_field": "field",
5 "dims": 4,
6 "max_training_vector_count": 100000,
7 "search_size": 1000,
8 "description": "My model，ivf_pq",
9 "index_type": "ivf_pq",
10 "space_type": "l2",
11 "parameters":{
12 "nlist":128,
13 "nprobes":8,
14 "m":8,
15 "code_size":8
16 }
17}
18
19{
20 "model_id": "model_ivfpq"
21}3、查询模型状态，待到状态为created。
JSON
1GET /_bpack/_knn/models/model_ivfpq?pretty
2
3{
4 "model_id" : "model_ivfpq",
5 "model_blob" : "SXdGbIAAAAAAAAAAAA...",
6 "state": "created",
7 "timestamp": "2023-06-14T03:02:15.246736Z",
8 "description": "My model，ivf_pq",
9 "error": "",
10 "index_type": "IVF_PQ",
11 "parameters": {},
12 "space_type": "l2",
13 "dimension": 128
14}4、使用model_id创建 ivf\ivf_pq索引，之后即可正常使用索引和写入数据。
JSON
1PUT my_ivfpq_index
2{
3 "settings": {
4 "index": {
5 "knn": true
6 }
7 },
8 "mappings": {
9 "properties": {
10 "field_ivf_pq": {
11 "type": "bpack_vector",
12 "model_id": "model_ivfpq"
13 }
14 }
15 }
16}