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:

configs:
  - modelName: <model-name>
    provider: OPENAI_COMPATIBLE
    providerEndpoint: <endpoint>

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

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/<modelId>/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.
config.credentials.apiToken	Yes for the hosted API	Hugging Face access token, sent as Authorization: Bearer <token>. 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

How to Index Fields for Vector Search