> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyborg.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Train

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

```python theme={null}
index.train(
    n_lists=None,
    batch_size=None,
    max_iters=None,
    tolerance=None,
    max_memory=None,
)
```

<Tip>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.</Tip>

### 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. |

<Warning>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.</Warning>

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).

### 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.

<Warning>`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()`](../getters#is_trained) after `train()` returns: an untrained index has `n_lists` of `1`. Queries on an untrained index still work.</Warning>

### Returns

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

### Exceptions

<AccordionGroup>
  <Accordion title="cyborgdb.AuthenticationError">
    The client isn't using the root key, or the `index_key` is invalid (HTTP `401`/`403`). Training requires the root key.
  </Accordion>

  <Accordion title="cyborgdb.NotFoundError">
    The index doesn't exist (HTTP `404`).
  </Accordion>

  <Accordion title="cyborgdb.ServiceError / cyborgdb.TransportError">
    The service returns `5xx` or can't be reached. A failed training run doesn't raise; see [Requirements](#requirements).
  </Accordion>
</AccordionGroup>

See [Errors](../errors) for the full hierarchy.

### Example Usage

#### Default settings

```python theme={null}
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

```python theme={null}
index.train(
    n_lists=128,
    batch_size=4096,
    max_iters=200,
    tolerance=1e-7,
)
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.