From 29eba5b7f86314fa3d99e0dc206d977cc2807949 Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Tue, 13 Oct 2026 08:10:05 +0000 Subject: [PATCH] docs(models): describe what a queued manual import adds A queued import goes through the gallery installer, so it persists recommended inference defaults and installs the backend when automatic backend installation is on, while the synchronous write stores the body as posted. Say so in the docs and the endpoint description, list the reference forms that are queued (URLs, hf:// and owner/repo, artifacts), and regenerate the swagger files. Assisted-by: Claude:claude-sonnet-5-5 Signed-off-by: Ettore Di Giacinto --- core/http/endpoints/localai/import_model.go | 6 ++++- docs/content/getting-started/models.md | 27 +++++++++++++++++---- swagger/docs.go | 2 +- swagger/swagger.json | 2 +- swagger/swagger.yaml | 6 ++++- 5 files changed, 34 insertions(+), 9 deletions(-) diff --git a/core/http/endpoints/localai/import_model.go b/core/http/endpoints/localai/import_model.go index 083fe5ef9..6539051e8 100644 --- a/core/http/endpoints/localai/import_model.go +++ b/core/http/endpoints/localai/import_model.go @@ -131,7 +131,11 @@ func ImportModelURIEndpoint(cl *config.ModelConfigLoader, appConfig *config.Appl // @Description is enqueued on the gallery job queue and answered with a job id // @Description plus status URL to poll, like a gallery install; a config with // @Description no downloads is written synchronously and answered with a -// @Description plain success response. +// @Description plain success response. A queued import runs the gallery +// @Description installer, which also adds recommended inference defaults the +// @Description config leaves unset and installs the backend when automatic +// @Description backend installation is enabled; the synchronous path stores +// @Description the body as posted. // @Tags models // @Accept json // @Produce json diff --git a/docs/content/getting-started/models.md b/docs/content/getting-started/models.md index c182ae659..3473c83e7 100644 --- a/docs/content/getting-started/models.md +++ b/docs/content/getting-started/models.md @@ -143,15 +143,32 @@ This is especially useful for: - Setting up complex model setups - Editing existing model configurations -When the configuration references remote assets — a URL in -`parameters.model` or `mmproj`, or `download_files` entries — **Create** -does not download them inside the request: the import is queued like a -gallery installation, and the page reports the job's progress until the -model is ready. The configuration file is written once every download +When the configuration references remote assets, **Create** does not +download them inside the request: the import is queued like a gallery +installation, and the page reports the job's progress until the model is +ready. These configurations are queued: + +- a URL in `parameters.model` or `mmproj`, or `download_files` entries; +- an `hf://` reference or a bare `owner/repo` in `parameters.model`, on a + backend that consumes a model directory; +- an explicit `artifacts:` block. The configuration file is written once every download has finished, so a failed download never leaves a config pointing at files that do not exist. A configuration that only references files already on disk is written immediately, as before. +A queued import runs through the same installer as a gallery +installation, so it differs from an immediate write in two ways: + +- Recommended sampling parameters for the model family (for example + `temperature` and `top_p`) are added under `parameters:` when the + configuration does not set them. The immediate write stores your + configuration exactly as posted. +- When automatic backend installation is enabled, the backend named in the + configuration is installed as part of the job. + +Set the parameters you care about explicitly if you need the same stored +file in both cases. + The same split applies to the API behind the page: `POST /models/import` answers a queued import with a job id and a status URL to poll (`/models/jobs/{id}` — the same shape gallery installs use), and a diff --git a/swagger/docs.go b/swagger/docs.go index 22c6f2864..aea1ffe60 100644 --- a/swagger/docs.go +++ b/swagger/docs.go @@ -2859,7 +2859,7 @@ const docTemplate = `{ }, "/models/import": { "post": { - "description": "Writes the posted model configuration. A config referencing\nremote assets (download_files entries, URI-valued model/mmproj)\nis enqueued on the gallery job queue and answered with a job id\nplus status URL to poll, like a gallery install; a config with\nno downloads is written synchronously and answered with a\nplain success response.", + "description": "Writes the posted model configuration. A config referencing\nremote assets (download_files entries, URI-valued model/mmproj)\nis enqueued on the gallery job queue and answered with a job id\nplus status URL to poll, like a gallery install; a config with\nno downloads is written synchronously and answered with a\nplain success response. A queued import runs the gallery\ninstaller, which also adds recommended inference defaults the\nconfig leaves unset and installs the backend when automatic\nbackend installation is enabled; the synchronous path stores\nthe body as posted.", "consumes": [ "application/json" ], diff --git a/swagger/swagger.json b/swagger/swagger.json index 63be870c7..9f3b9e9ca 100644 --- a/swagger/swagger.json +++ b/swagger/swagger.json @@ -2856,7 +2856,7 @@ }, "/models/import": { "post": { - "description": "Writes the posted model configuration. A config referencing\nremote assets (download_files entries, URI-valued model/mmproj)\nis enqueued on the gallery job queue and answered with a job id\nplus status URL to poll, like a gallery install; a config with\nno downloads is written synchronously and answered with a\nplain success response.", + "description": "Writes the posted model configuration. A config referencing\nremote assets (download_files entries, URI-valued model/mmproj)\nis enqueued on the gallery job queue and answered with a job id\nplus status URL to poll, like a gallery install; a config with\nno downloads is written synchronously and answered with a\nplain success response. A queued import runs the gallery\ninstaller, which also adds recommended inference defaults the\nconfig leaves unset and installs the backend when automatic\nbackend installation is enabled; the synchronous path stores\nthe body as posted.", "consumes": [ "application/json" ], diff --git a/swagger/swagger.yaml b/swagger/swagger.yaml index 324261d67..e2019dd69 100644 --- a/swagger/swagger.yaml +++ b/swagger/swagger.yaml @@ -5628,7 +5628,11 @@ paths: is enqueued on the gallery job queue and answered with a job id plus status URL to poll, like a gallery install; a config with no downloads is written synchronously and answered with a - plain success response. + plain success response. A queued import runs the gallery + installer, which also adds recommended inference defaults the + config leaves unset and installs the backend when automatic + backend installation is enabled; the synchronous path stores + the body as posted. parameters: - description: model configuration (YAML or JSON body) in: body