Model Configuration

https://app.example.com is an example address. Replace it with the actual address of your environment, retaining the route path and query parameters.

1. Configuration Goal

Initialize the fixed model group and its models so that the target model passes connection testing, is billed correctly, and appears in users' model selectors within the authorized scope.

The current version has two levels of model configuration:

• Model Group: A system-provisioned configuration unit used to organize one or more models and hold shared connection settings;
• Model: The specific model under a model group that is actually called by the Agent Runtime.

In the current version, Provider is configured by the system. There is no separate Model Provider configuration or management entry; Model Provider is planned for a later version. The current version does not allow administrators to create, copy, or delete Model Groups. Administrators can only configure connections and add models in system-provisioned Model Groups. A model can belong to only one Model Group.

2. Configuration Entry

Configuration entry: System → Models in the Admin Console.

Example route: https://app.example.com/admin/settings/model

app.example.com is an example domain. During actual operation, replace it with the AOS Work access domain for the customer environment. Keep the route path /admin/settings/model unchanged.

3. Pre-configuration Checklist

Prepare the following information before starting:

1. The Base URL, API Key, and other connection fields required by the current Models page;
2. The model's actual identifier (Model ID);
3. The user-facing display name (Model Display Name);
4. Context Window, model capabilities, and whether image parsing is supported;
5. Input, output, and cached-token prices for configuring Credits Conversion;
6. The Roles whose Allowed Models should include this model.

Enter sensitive credentials such as API Key only in the Admin Console connection configuration. Do not write them in ordinary documents, configuration records, or resource files.

4. Configure the Fixed Model Group

1. In System → Models, find the system-provisioned Model Group that needs to be configured.
2. Open the Model Group settings and confirm its fixed name and identifier.
3. Fill in Base URL, API Key, and other connection information according to the fields provided on the page.
4. Click Save to save the connection configuration.
5. Use the page's enable switch to confirm that the Model Group is available.

The current version does not provide Create Model Group and does not allow multiple Groups for the same Provider. After credentials are saved, only masked values are displayed. Adding, replacing, and deleting credentials should all retain audit records.

5. Create and Edit a Model

5.1 Basic Information

In the target Model Group, click Add model or open the edit settings for an existing model, then configure:

• Model Display Name: The user-facing display name; required;
• Model ID: The model identifier sent to the provider; required;
• Model Logo: The model graphic shown to users;
• Context Window: The model's context length;
• The model's currently supported capability fields, including Supports Image Parsing.

Model Display Name and Model ID are independent. Changing Model ID changes the identifier subsequently sent to the provider, but should not by itself cause the user-facing display name to be changed.

5.2 Model Logo

Model Logo uses the current Model Group's default icon unless an administrator overrides it. To override the default, you can:

1. Select another model or provider icon from Lobe Icons;
2. Upload a custom SVG, PNG, or WebP icon;
3. Restore the current Model Group's default icon.

The model must have a valid Model Display Name and Model Logo before it meets the display conditions for appearing in the Role Allowed Models candidate list.

5.3 Credits Conversion

Configure Credits conversion ratios for input, output, and cached Tokens. The interface uses the unit credits / 1K tokens; also verify the per-token conversion preview.

For detailed price conversion and cross-model consistency requirements for monetary value, see 02 Credits Conversion Configuration.

6. Testing, Enabling, and Availability Conditions

1. Save the model's basic information and Credits Conversion.
2. Use the current Model Group connection and Model ID to run Test connection and complete a minimal model call.
3. Enable the Model only after confirming that the test succeeded.
4. Check that both the Model Group and Model are enabled.

The model is available only when all of the following are true:

• The Model Group is enabled;
• The Model is enabled;
• The most recent Test connection succeeded;
• Model Display Name and Model Logo are valid.

Disabling a Model Group or Model does not delete the model configuration or historical quota records. Do not delete a model while it is still referenced by an Agent, template, or other runtime configuration.

7. Configure Role Allowed Models

After the model is configured and meets the availability conditions, it is added only to the Role Allowed Models candidate list; it is not automatically available to all users.

Configuration entry: Account → Roles in the Admin Console.

Example route: https://app.example.com/admin/account/role?tab=roles

app.example.com is an example domain. During actual operation, replace it with the AOS Work access domain for the customer environment. Keep the route path /admin/account/role?tab=roles unchanged.

1. Create or edit the target Role.
2. Fill in the required Role name and Description.
3. In Allowed models, select a model that has been configured, tested successfully, and is currently available.
4. Click Save to save the Role.

Authorization rules:

• Allowed models may be empty, which means the Role grants no models;
• For a user bound to one Role, selectable models are the intersection of that Role's Allowed Models and currently available models;
• For a user bound to multiple Roles, take the union of the Roles' Allowed Models, then intersect it with currently available models;
• Newly added models are not automatically added to existing Roles; an administrator must explicitly configure them;
• Removing Role authorization or making a model unavailable takes effect immediately for subsequent calls. The system must not silently replace the model currently selected by the user; the user must select a valid model again before the next message.

8. User-side Verification

Use a standard user account bound to the target Role to verify:

1. Open New Chat.
2. Open the model selector and confirm that the target model appears with the correct display name and icon.
3. Send a minimal test message.
4. Confirm that the request succeeds and Credits are recorded according to the configured input, output, and cached-token conversion rules.

If the model does not appear in the selector, check in this order: whether the Model Group is enabled, whether the Model is enabled, whether Test connection succeeded, whether the display name and icon are valid, and whether the user's current Role has the model configured in Allowed Models.

9. Initialization Completion Criteria

• The Model Group name, identifier, Base URL, and connection credentials are configured;
• The Model Group connection configuration is saved and the Model Group is enabled;
• Model Display Name, Model ID, Context Window, capabilities, and Model Logo are configured;
• Input, Output, and Cached Credits Conversion are completed as described in this model configuration guide;
• Test connection succeeded and the Model is enabled;
• Allowed Models is explicitly configured for the target Role;
• A standard user can see and successfully call the target model in New Chat;
• Sensitive credentials such as API Key are not written in ordinary documents or records.