Manage Models¶
Sign in as an administrator and open Models at /models. Make sure you have
configured the provider credentials or base URL
in .env first; catalog entries store model metadata and capabilities, never
API keys.
Add a model¶
- Click Add Model and select a provider.
- Use Find on provider to search the upstream catalog and prefill capabilities, or enter the fields manually.
- Check Display label (
label), Logical ID (id), Upstream / API model (api_model), and Wire API (wire_api). - Enable the entry and click Save.
- Open a new chat, select the model, and send a test message.
Key identity rules:
idvs.api_model:idis the stable identifier stored on chats;api_modelis the upstream model name sent to the provider API when it differs fromid. Keepidstable once chats use it.- Unique routes: Every
(provider, wire_api, api_model or id)combination in the catalog must be unique. - Provider discovery & metadata refresh: On OpenRouter, Crowbot, and
Mistral, discovery prefills reasoning support, mandatory status, and supported
effort levels (
minimal,low,medium,high,xhigh,max). You can also discover a model via OpenRouter and switch its Provider dropdown to reuse its metadata on another compatible endpoint, or click Refresh provider metadata when editing an existing entry. - Setting
context_window: To set or changecontext_windowexplicitly, export the catalog JSON, editcontext_window, and import it in Update mode (see the Model catalog reference).
Edit, disable, delete, or set the default model¶
Use the action controls on any model row to edit it, toggle it on or off, set it
as the default model, or delete it. The active default_model must stay enabled
and cannot be deleted until another enabled model is chosen as the default.
When you delete a model that existing chats still reference, Numi asks which enabled model should take over those chats (with the catalog default preselected):
- Existing chats keep their full message history and switch to the replacement model, normalizing their saved reasoning level to one the replacement supports.
- Any admin overrides for chat titles or memory that pointed to the deleted model reset to automatic, and access tiers referencing it are updated.
- A model hardcoded in
CHAT_TITLE_MODELorMEMORY_SUMMARY_MODELin.envcannot be deleted while that environment setting names it; disable the model instead or change.envfirst.
Choose a Numi Search ranking model¶
Open Models → Automation and find Numi Search ranking. Choose LLM to use an OpenRouter model from your catalog, or Decision for the built-in ranking shortlist. The initial choices for these types are DeepSeek V4.1 Flash and Drex Max Finance respectively. Existing saved choices are kept.
Decision candidates are ordered from useful alternatives to the strongest relevance candidates. The information button explains the selected model's trade-off. These models do not need entries in your conversational catalog.
Click Save override to apply a change, Cancel to discard it, or Use config to restore the environment fallback. These controls only affect Numi Search ranking; the tool-suggestion router keeps its own model.
Import, export, and reload¶
- Export: Downloads the active catalog as a portable JSON file.
- Import: Accepts a catalog JSON document in one of three modes:
- Merge: Adds only models whose
idand route do not exist yet in your catalog (ignoring OpenRouter variant suffixes such as:floorwhen matching), leaving all your existing models and default model untouched. - Update: Adds new entries, replaces existing entries that share the same
idor route, and updatesdefault_modelif specified. Include complete model objects when using Update mode, as omitted optional fields revert to their schema defaults. - Replace: Replaces the entire catalog with the imported JSON (after verifying that active chats, background model settings, and tiers have valid targets).
- Defaults: Lists models from the packaged
models.default.jsonthat are not yet in your private catalog so you can cherry-pick newly shipped default models after an upgrade. - Reload catalog: Re-reads
state/models.jsonfrom disk after manual edits. If an edited file fails validation at runtime, Numi keeps the last valid catalog snapshot active.
Catalog files on disk¶
Packaged defaults live in src/numi_chat/llm/models.default.json. As soon as
you save a change in Admin -> Models (or create state/models.json),
state/models.json acts as the complete runtime catalog (configurable via
NUMI_CHAT_MODEL_CONFIG_PATH).
In Docker deployments, always mount the parent ./state:/app/state directory
rather than mounting models.json as a single file, because Admin saves write a
temporary file and atomically replace models.json in its directory.