Models catalog | SoAI Documentation

The Models page is SoAI's model catalog. Use it to add local models or external providers, change model settings, test inference, and control which models users can select. Virtual models appear in the same list.

Add models

A fresh SoAI installation does not include any models. SoAI setup in the first-run wizard can add one for you. To add one yourself, choose how:

If you want	What to do in the SoAI WebUI
A model that runs on this machine	Open Plugins, choose a plugin that runs the type of model you want, and select Install backend. When the backend is ready, return to Models, select Add model, and download a model for it.
A model hosted by a remote service	Open Models, select Add model, then select Add provider. Choose the bundled External plugin and enter the provider details. External connects to an OpenAI-compatible API and does not need a local backend installation.

See Install and manage plugins for the backend installation workflow and Bundled plugins reference if you need help choosing a local backend.

Download a local model

Open Models and select Add model.
On the Download model tab, choose the plugin that will run the model.
Enter at least two characters under Model search, then select Search. Choose a result, or enter the exact Model download ID when you already know it.
Select a quantization or variant when the plugin offers more than one. Select Check to review whether the model fits in memory, VRAM, and local storage. The report also gives size and timing estimates.
Select Download model. The modal shows progress while the plugin downloads the files.

SoAI discovers the model after the download and adds it to the catalog. The plugin selector includes plugins that support model downloads. A plugin can be selected only when it is enabled, available, compatible, and not blocked by its backend or runtime state.

Add model files that are already on the machine

The Add model manually tab appears only for an Administrator account. Open it to see the configured models folder. Copy copies that path. Open Files opens the Files page, but it does not open the models folder or extend the account's workspace access. If the models folder is inside your assigned workspace, use Files to create the plugin's required directories and upload the model files. Otherwise, an administrator must copy them through the host's normal file transfer workflow or the WebUI Terminal. Check the backend's documentation for its directory layout and supported model files, then return to Add model manually and select Discover models. SoAI refreshes the catalog without a restart.

Add models from an external provider

The Add provider tab appears when the catalog includes a plugin that supports user-managed providers. A choice in Plugin becomes usable only when it is enabled, available, compatible, and in a usable runtime state. If the tab is missing, open Plugins and add or enable a plugin that supports user-managed providers.

Open Models, select Add model, then select Add provider.
Select External under Plugin.
Enter a Provider name you will recognize later.
Enter the provider's OpenAI-compatible API URL, including its /v1 base path when required by that service, and enter the API key.
To import only part of a large catalog, enter comma-separated terms under Models filter. Leave it empty to import every model returned by the provider.
Select Add provider.

SoAI checks the provider and reads its model list. The Models page then lists each matching model beside your local models. To remove or correct a provider, select the page-header Providers control, select Delete beside its name, and confirm the deletion. SoAI removes every model imported from that provider. Select Add model and Add provider to add it again with a new URL, API key, or model filter.

Find and manage models

Search matches a model's display name, alias, source ID, plugin, provider, or description. Sort the results by name, type, provider, plugin, status, or size. Use All plugins to show one plugin, and use the view button to switch between cards and a compact table.

The summary above the catalog shows model counts, loaded models, external providers, requests, the last-used model, and the total size reported for the catalog. Each model entry identifies its source, type, status, and parameter state. Models imported from an external provider use the Cloud type. Entries also show model size and request or token totals when SoAI has those values.

Manage a model

Control	What it does
Availability	Turn availability off to block requests and remove the model from model pickers. This control does not unload the backend.
Delete model	Deletes a local model through its plugin. You cannot undo this action. SoAI shows it only when the plugin supports model deletion. Remove external-provider models through Providers instead.
Edit model	Opens shortcuts for Model information, Rename, Test model, Edit parameters, Copy, and Delete. The same dialog has the model's availability and capability controls. Virtual models use an Edit virtual model control instead.
Edit parameters	Opens the model detail page. On Parameters, search the settings or use the category list. Customized shows saved custom values, and Unsaved changes shows your current edits. An empty number field shows Backend default and uses that value. Change the settings you need and select Save. A REQUIRES RELOAD badge marks settings that need the plugin to reload before they apply. Revert change undoes one unsaved edit; Reset discards all unsaved edits and restores the values loaded when you opened the page. If parameters fail to load, follow the reported cause and select Retry. After a disconnect, check the last-update time and refresh before relying on the displayed values. If the plugin's parameter definitions change while you have unsaved edits, select Discard changes to load the current definitions.
Rename	Sets a display alias while keeping the source model ID unchanged. Leave the alias empty to return to the source name.
Stop model	Appears only for a non-virtual model with READY or PROCESSING status whose plugin is not persistent. It stops the whole plugin, including access to any other models it serves. SoAI starts the plugin again when a later request needs one of those models. If model discovery prevents stopping or disabling the plugin, wait for discovery to finish and retry.
Test model	Opens a short or long inference test and shows the model state, plugin state, elapsed time, response, and plugin activity. Use this after a download or configuration change to confirm that the model runs.

Override model capabilities

Select Edit model to open Capabilities. Auto (on) and Auto (off) follow model and plugin capability evidence. Enabled forces a capability on, and Disabled forces it off. Unverified means no explicit capability report is available; SoAI keeps its compatibility behavior until you choose an override. Select Save to apply.

When another session changes the same model's capabilities first, SoAI discards your edits and shows the latest values. Review them and apply your changes again. The model detail page also has an Inference row that shows when a request to the model last succeeded, or Not verified yet until one does.

Load and use a model

Unloaded means SoAI has not loaded the local model into backend memory. It does not mean the model is missing, and the Models page has no separate load button. Open Chat, choose the model, and send a message. SoAI starts the plugin and loads the model for that request. SoAI may unload an idle backend later, and the next request starts it again. A disabled model stays out of model pickers until you enable it.

Routing, permissions, and troubleshooting

Select Virtual models to put two or more eligible catalog models behind one client-facing name. Virtual models, routing, and failover covers constituent validation, load-balanced ordering, ordered failover, cooldowns, editing, and routing permissions.

Permissions

You need Model read access (MODEL_READ) to view the catalog and model details. You need Model administration (MODEL_ADMIN) to download, delete, enable, rename, or configure a model. Adding or removing an external provider requires Plugin administration (PLUGIN_ADMIN). Viewing virtual-model and routing configuration requires Routing read access (MODEL_ROUTING_READ). Creating or changing a virtual model requires Model routing (MODEL_ROUTING_ADMIN). The manual model tab also requires an Administrator account. If a control is missing, ask an administrator to check your permissions and the plugin's current state.

When no models appear

What you see	What to check
A blank catalog after installation	A fresh installation starts with no models. Follow Install and manage plugins to install a local backend, then return to Models and download a model. You can also add an external provider instead.
A model is missing from Chat	Chat omits models recognized as embedding-only. Other catalog models can appear, but the selector disables one unless it is loaded or available. Select Edit model and check Availability, then check its runtime state.
An external provider reports an error	Select Providers and check the status. If the URL, API key, or model filter is wrong, select Delete, confirm the deletion, and add the provider again. Check the provider's own documentation if SoAI still cannot connect.
No Add provider choice	The tab is hidden when no catalog plugin supports user-managed providers. Open Plugins and add or enable a provider-capable plugin. A choice in Plugin becomes usable only when it is enabled, available, compatible, and in a usable runtime state. You also need Plugin administration (`PLUGIN_ADMIN`) to add the provider.
No plugin under Download model	Open Plugins, enable the plugin, and select Install backend. If SoAI still leaves it out of the list, check whether the plugin supports model downloads and whether its card reports an error or compatibility problem.