Train

Clusters the index’s vectors into IVF lists so queries only scan the closest lists. train() waits until training finishes before returning.

index.train(
    n_lists=None,
    batch_size=None,
    max_iters=None,
    tolerance=None,
    max_memory=None,
)

The service also trains indexes automatically. An untrained index is trained once it holds more than AUTO_TRAIN_MIN_VECTORS vectors (default 65536), and a trained index is retrained when its size calls for more lists than it has. Set AUTO_TRAIN_DISABLED=true on the service to turn this off. Call train() yourself to train a smaller index, or to make sure training is finished before running queries or benchmarks.

Parameters

Parameter	Type	Default	Description
`n_lists`	`int`	`None` (auto)	(Optional) Number of IVF lists. `None` picks the square root of the vector count, rounded to a power of two.
`batch_size`	`int`	`None` (ignored)	(Optional) Vectors processed per training batch.
`max_iters`	`int`	`None` (ignored)	(Optional) Maximum clustering iterations.
`tolerance`	`float`	`None` (ignored)	(Optional) Convergence tolerance.
`max_memory`	`int`	`None` (ignored)	(Optional) Memory cap for training, in MB.

Only n_lists affects training today. The service accepts batch_size, max_iters, tolerance, and max_memory but doesn’t pass them to training, so they have no effect.

Parameter values aren’t range-checked: an out-of-range value such as a negative list count is accepted, and training is skipped as described in Requirements.

Requirements

Training only runs when all three hold:

The index has at least 10,000 vectors.
It has at least twice as many vectors as n_lists.
The vector dimension is a multiple of 32, such as 384, 768, or 1536.

train() doesn’t report a skipped or failed training run. If a requirement isn’t met, or training fails on the service, train() still returns normally and the index stays untrained. Check is_trained() after train() returns: an untrained index has n_lists of 1. Queries on an untrained index still work.

Returns

None. If the index is already training, train() waits for that run to finish, then trains again.

Exceptions

cyborgdb.AuthenticationError

The client isn’t using the root key, or the index_key is invalid (HTTP 401/403). Training requires the root key.

cyborgdb.NotFoundError

The index doesn’t exist (HTTP 404).

cyborgdb.ServiceError / cyborgdb.TransportError

The service returns 5xx or can’t be reached. A failed training run doesn’t raise; see Requirements.

See Errors for the full hierarchy.

Example Usage

Default settings

index.train()

# train() doesn't raise if training is skipped, so check the result
print(index.is_trained(), index.n_lists)
# Output: True 128

Custom settings

index.train(
    n_lists=128,
    batch_size=4096,
    max_iters=200,
    tolerance=1e-7,
)

Introduction

Client

Encrypted Index

Types & Helpers

Parameters

Requirements

Returns

Exceptions

Example Usage

Default settings

Custom settings

​Parameters

​Requirements

​Returns

​Exceptions

​Example Usage

​Default settings

​Custom settings

Parameters

Requirements

Returns

Exceptions

Example Usage

Default settings

Custom settings