Create an embedding model
POST/embedding-models
Creates an embedding model: a configured instance of an embedding provider, with a model name and provider parameters. Before storing the embedding model, Foundation4 embeds a test string with the provider, so the request fails when the provider cannot load the model. A size of 0 stores the measured number of dimensions, and a nonzero size must equal the measured number. The number of dimensions, requested or measured, must be at most 2,000, the largest number that the vector search indexes support; OpenAIEmbeddings accepts a dimensions parameter that asks the model for shorter vectors. An endpoint parameter, and a model name that is a URL, must be an http or https URL with a host and without credentials. Private endpoints are accepted by default; when the API server configuration sets app.allow_private_endpoints to false, the host must resolve to public addresses only. Foundation4 encrypts credential parameters, such as api_key, before storage and returns them as <redacted>. After creation, only name and description can change.
Permissions. Write on the embedding-models object type and write on the embedding provider that provider names. The key that creates the embedding model receives read, write and execute permission on the new embedding model.
Embedding models and text splitters shows example requests, and Providers and models lists the models and parameters of each provider.
Request
Responses
- 201
- 400
- 401
- 403
- 404
- 409
- 422
- 500
The embedding model was created. The body is the new embedding model, with size set to the measured number of dimensions.
The request is invalid (Invalid parameter), and details.error names the cause: a model or settings that the provider does not accept (Embedding provider '<provider>' or model '<model>' not found with the provided parameters: <reason>), a size that differs from the measured number of dimensions (Failed to create embedding model: expected embedding size <size>, got <measured>), more than 2,000 dimensions (Embedding size <size> is above the 2000 dimensions the vector search indexes support; ...), a data_files parameter for FastEmbedEmbeddings (data_files is not supported: ...), or an endpoint that is not permitted: a URL that cannot be parsed (Invalid endpoint URL: <reason>), a scheme other than http or https (Endpoint must use the http or https scheme), a URL with credentials (Endpoint must not contain credentials) or, when app.allow_private_endpoints is false, an address on a private network (Endpoint host '<host>' is not a public address; ...) or a host that does not resolve (Endpoint host could not be resolved: <reason>). The same status reports a body that is not valid JSON.
The authentication headers are missing or invalid, or the API key is inactive or expired. Errors lists the messages.
The key lacks write permission on the embedding-models object type (Unauthorized: write access to Embedding Model required) or on the embedding provider (Unauthorized: write access to Embedding Provider required, with Creating an embedding model needs write access on the provider <provider> in details.error). The same status reports a license that is not valid (Invalid license: <reason>) and a reached license limit (License limits exceeded for Embedding Model).
No embedding provider has the name in provider (Embedding Provider not found, with the name in details.provider).
An embedding model with this name already exists (Conflict unique error).
The body does not match the request schema, for example a missing model or an unknown field.
The provider failed while embedding the test string (Internal server error, without details), for example because the gRPC service or the model server is unreachable, or because the gRPC service lacks the Python package or the model files of a GPT4All or Hugging Face provider. The API server log records the cause.