# Automatic embedding configuration reference This page lists the settings for automatic embedding. They are split across two files: - `mongot.conf` activates the subsystem and holds the values that apply across all models. Automatic embedding turns on as soon as this file has an embedding section. - The model catalog, `embedding-service-configs.yml`, defines the models themselves. ## Embedding section in `mongot.conf` | **Setting** | **Required** | **Description** | |---|---|---| | `isAutoEmbeddingViewWriter` | No | Controls whether this `mongot` instance writes generated embedding data. Default is `false`. Configure one writer for the relevant deployment. | | `modelConfigFile` | No | Path to a custom embedding model catalog. | | `queryKeyFile` | Voyage only | File containing the Voyage API key used for queries. | | `indexingKeyFile` | Voyage only | File containing the Voyage API key used during indexing. | | `providerEndpoint` | No | Overrides the endpoint for `VOYAGE` models only. It doesn't affect `OPENAI_COMPATIBLE` or `HUGGINGFACE_INFERENCE` models. | ## OPENAI_COMPATIBLE model settings Define each `OPENAI_COMPATIBLE` model under the `configs` key in the model catalog. By default, the model catalog is `embedding-service-configs.yml`. For example: ```sh configs: - modelName: provider: OPENAI_COMPATIBLE providerEndpoint: ``` The following settings apply to each model entry under `configs`: | **Setting** | **Required** | **Description** | | --- | --- | --- | | `modelName` | Yes | Name of the embedding model. `mongot` sends this value in the request `model` field and uses it to match the model referenced in an `autoEmbed` index definition. | | `config.providerEndpoint` | No. Default: `https://api.openai.com/v1/embeddings` | Full URL of the OpenAI-compatible `/v1/embeddings` endpoint. Configure this value for local engines or hosted providers that use a different endpoint. | | `config.modelConfig.outputDimensions` | Yes | Number of dimensions in the vectors returned by the model. This value determines the vector dimensions used by the index. It is sent to the provider only when `forwardDimensions` is set to `true`. | | `config.modelConfig.batchSize` | No. Default: `96` | Maximum number of inputs that `mongot` can include in a single embedding request. | | `config.modelConfig.batchTokenLimit` | No. Default: `120000` | Approximate maximum number of input tokens that `mongot` can include in one embedding request batch. | | `config.modelConfig.quantization` | No. Default: `float` | Vector output format. Only `float` is currently supported for `OPENAI_COMPATIBLE` models. | | `config.modelConfig.queryPrefix` | No | Text added before query input for models that use different instructions for queries and documents. Include any required separator, such as `"search_query: "`, in the value. | | `config.modelConfig.documentPrefix` | No | Text added before document input for asymmetric embedding models. Include any required separator, such as `"search_document: "`, in the value. | | `config.modelConfig.forwardDimensions` | No. Default: `false` | When set to `true`, sends the resolved vector dimension to the provider using the OpenAI `dimensions` request field. Use this only with models that support configurable dimensions, such as OpenAI and Azure OpenAI `text-embedding-3` models. | | `config.errorHandlingConfig` | Yes | Defines how `mongot` handles transient embedding request failures. Configure `maxRetries`, `initialRetryWaitMs`, `maxRetryWaitMs`, and `jitter`. | | `config.credentials.apiKey` | No | API key used to authenticate with the embedding provider. Omit this setting, or use `credentials: {}`, for local engines that don't require authentication. | | `config.credentials.authHeaderName` | No. Default: `Authorization` | HTTP header used to send the API key. With the default `Authorization` header, `mongot` uses the `Bearer ` scheme. Set this to `api-key` for Azure OpenAI. | ## HUGGINGFACE_INFERENCE model settings Define each `HUGGINGFACE_INFERENCE` model under the `configs` key in the model catalog. For a setup walkthrough, see [Configure automatic embedding with the Hugging Face Inference API](configure-automatic-embedding-huggingface.md). | **Setting** | **Required** | **Description** | | --- | --- | --- | | `modelName` | Yes | Name that `autoEmbed` index definitions reference. `mongot` converts it to lowercase. | | `config.providerEndpoint` | No. Default: `https://router.huggingface.co/hf-inference/models//pipeline/feature-extraction` | Replaces the Hugging Face router URL exactly as specified. Use it for a dedicated Inference Endpoint or the `/embed` route of a self-hosted TEI server. | | `config.modelConfig.modelId` | No. Default: `modelName` | Exact, case-sensitive Hugging Face Hub repository ID, for example `BAAI/bge-small-en-v1.5`. Set it whenever the repository ID has an organization prefix or uppercase letters. | | `config.modelConfig.outputDimensions` | Yes | Native dimension of the model's vectors. It sizes the index and must match what the model returns. | | `config.modelConfig.batchSize` | No. Default: `32` | Maximum number of inputs in a single request. Lower it if you receive `HTTP 413`. | | `config.modelConfig.batchTokenLimit` | No. Default: `120000` | Approximate maximum number of input tokens in one request batch. | | `config.modelConfig.truncate` | No. Default: `true` | Truncates inputs longer than the model's maximum sequence length instead of failing the batch. | | `config.modelConfig.normalize` | No | Sent only when set. Otherwise, the server default applies. | | `config.modelConfig.queryPrefix` | No | Text added before query input for asymmetric models. Include the separator in the value. | | `config.modelConfig.documentPrefix` | No | Text added before document input for asymmetric models. Include the separator in the value. | | `config.modelConfig.quantization` | No. Default: `float` | Vector output format. Only `float` is supported. | | `config.errorHandlingConfig` | Yes | Defines how `mongot` retries transient failures, such as `HTTP 429` and `HTTP 503`. See [Retry settings](#retry-settings). | | `config.credentials.apiToken` | Yes for the hosted API | Hugging Face access token, sent as `Authorization: Bearer `. Optional when `providerEndpoint` points at a server that doesn't require authentication. | ## Retry settings `config.errorHandlingConfig` accepts the following: | **Setting** | **Description** | |---|---| | `maxRetries` | Maximum number of retry attempts for a transient failure. | | `initialRetryWaitMs` | Wait before the first retry, in milliseconds. | | `maxRetryWaitMs` | Upper bound on the wait between retries, in milliseconds. | | `jitter` | Randomization applied to the retry wait, to avoid synchronized retries. | Authentication failures aren't treated as transient and aren't retried. ## Learn more [Automated Embedding overview :octicons-link-external-16:](https://www.mongodb.com/docs/vector-search/crud-embeddings/automated-embedding/){:target="_blank"} [How to Index Fields for Vector Search :octicons-link-external-16:](https://www.mongodb.com/docs/vector-search/index/vector-search-type/){:target="_blank"}