Files
librechat.ai/pages/docs/configuration/librechat_yaml/object_structure/model_specs.mdx
Danny Avila f9cd648514 feat: Config v1.2.4 Changelog (#280)
* feat: Add allowedProviders and addedEndpoints features for enhanced agent configuration

* wip: changelog 1.2.4

* feat: Enhance token balance management with auto-refill settings and detailed configuration options

* feat: Enhance balance management with new configuration options for auto-refill and user balances

* docs: Mark endpointsMenu setting as deprecated and provide migration guidance
2025-04-01 22:26:32 -04:00

757 lines
18 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Model Specs Object Structure
## **Overview**
The `modelSpecs` object helps you provide a simpler UI experience for AI models within your application.
There are 3 main fields under `modelSpecs`:
- `enforce` (optional; default: false)
- `prioritize` (optional; default: true)
- `list` (required)
- `addedEndpoints` (optional)
**Notes:**
- If `enforce` is set to true, model specifications can potentially conflict with other interface settings such as `endpointsMenu`, `modelSelect`, `presets`, and `parameters`.
- The `list` array contains detailed configurations for each model, including presets that dictate specific behaviors, appearances, and capabilities.
- If [interface](interface.mdx) fields are not specified in the configuration, having a list of model specs will disable the following interface elements:
- `endpointsMenu`
- `modelSelect`
- `parameters`
- `presets`
- If you would like to enable these interface elements along with model specs, you can set them to `true` in the `interface` object.
## Example
```yaml filename="modelSpecs"
modelSpecs:
enforce: true
prioritize: true
list:
- name: "meeting-notes-gpt4"
label: "Meeting Notes Assistant (GPT4)"
default: true
description: "Generate meeting notes by simply pasting in the transcript from a Teams recording."
iconURL: "https://example.com/icon.png"
preset:
endpoint: "azureOpenAI"
model: "gpt-4-turbo-1106-preview"
maxContextTokens: 128000 # Maximum context tokens
max_tokens: 4096 # Maximum output tokens
temperature: 0.2
modelLabel: "Meeting Summarizer"
greeting: |
This assistant creates meeting notes based on transcripts of Teams recordings.
To start, simply paste the transcript into the chat box.
promptPrefix: |
Based on the transcript, create coherent meeting minutes for a business meeting. Include the following sections:
- Date and Attendees
- Agenda
- Minutes
- Action Items
Focus on what items were discussed and/or resolved. List any open action items.
The format should be a bulleted list of high level topics in chronological order, and then one or more concise sentences explaining the details.
Each high level topic should have at least two sub topics listed, but add as many as necessary to support the high level topic.
- Do not start items with the same opening words.
Take a deep breath and be sure to think step by step.
```
---
## **Top-level Fields**
### enforce
<OptionTable
options={[
['enforce', 'Boolean', 'Determines whether the model specifications should strictly override other configuration settings.', 'Setting this to `true` can lead to conflicts with interface options if not managed carefully.'],
]}
/>
**Default:** `false`
**Example:**
```yaml filename="modelSpecs / enforce"
modelSpecs:
enforce: true
```
---
### prioritize
<OptionTable
options={[
['prioritize', 'Boolean', 'Specifies if model specifications should take priority over the default configuration when both are applicable.', 'When set to `true`, it ensures that a modelSpec is always selected in the UI. Doing this may prevent users from selecting different endpoints for the selected spec.'],
]}
/>
**Default:** `true`
**Example:**
```yaml filename="modelSpecs / prioritize"
modelSpecs:
prioritize: false
```
---
### addedEndpoints
<OptionTable
options={[
['addedEndpoints', 'Array of Strings', 'Allows specific endpoints (e.g., "openAI", "google") to be selectable in the UI alongside the defined model specs.', 'Requires `interface.modelSelect` to be `true`. If this field is used and `interface.modelSelect` is not explicitly set, `modelSelect` will default to `true`.'],
]}
/>
**Default:** `[]` (empty list)
**Note:** Must be one of the following:
- `openAI, azureOpenAI, google, anthropic, assistants, azureAssistants, bedrock`
**Example:**
```yaml filename="modelSpecs / addedEndpoints"
modelSpecs:
# ... other modelSpecs fields
addedEndpoints:
- openAI
- google
```
---
### list
**Required**
<OptionTable
options={[
['list', 'Array of Objects', 'Contains a list of individual model specifications detailing various configurations and behaviors.', 'Each object in the list details the configuration for a specific model, including its behaviors, appearance, and capabilities related to the application\'s functionality.'],
]}
/>
## **Model Spec (List Item)**
Within each **Model Spec**, or each **list** item, you can configure the following fields:
---
### name
<OptionTable
options={[
['name', 'String', 'Unique identifier for the model.', 'No default. Must be specified.'],
]}
/>
**Description:**
Unique identifier for the model.
---
### label
<OptionTable
options={[
['label', 'String', 'A user-friendly name or label for the model, shown in the header dropdown.', 'No default. Optional.'],
]}
/>
**Description:**
A user-friendly name or label for the model, shown in the header dropdown.
---
### default
<OptionTable
options={[
['default', 'Boolean', 'Specifies if this model spec is the default selection, to be auto-selected on every new chat.', ''],
]}
/>
**Description:**
Specifies if this model spec is the default selection, to be auto-selected on every new chat.
---
### iconURL
<OptionTable
options={[
['iconURL', 'String', 'URL or a predefined endpoint name for the model\'s icon.', 'No default. Optional.'],
]}
/>
**Description:**
URL or a predefined endpoint name for the model's icon.
---
### description
<OptionTable
options={[
['description', 'String', 'A brief description of the model and its intended use or role, shown in the header dropdown menu.', 'No default. Optional.'],
]}
/>
**Description:**
A brief description of the model and its intended use or role, shown in the header dropdown menu.
---
### showIconInMenu
<OptionTable
options={[
['showIconInMenu', 'Boolean', 'Controls whether the model\'s icon appears in the header dropdown menu.', ''],
]}
/>
**Description:**
Controls whether the model's icon appears in the header dropdown menu. Defaults to `true`.
---
### showIconInHeader
<OptionTable
options={[
['showIconInHeader', 'Boolean', 'Controls whether the model\'s icon appears in the header dropdown button, left of its name.', ''],
]}
/>
**Description:**
Controls whether the model's icon appears in the header dropdown button, left of its name. Defaults to `true`.
---
### preset
<OptionTable
options={[
['preset', 'Object', 'Detailed preset configurations that define the behavior and capabilities of the model.', 'See "Preset Object Structure" below.'],
]}
/>
**Description:**
Detailed preset configurations that define the behavior and capabilities of the model (see Preset Object Structure below).
---
## Preset Fields
The `preset` field for a `modelSpecs.list` item is made up of a comprehensive configuration blueprint for AI models within the system. It is designed to specify the operational settings of AI models, tailoring their behavior, outputs, and interactions with other system components and endpoints.
### System Options
#### endpoint
**Required**
**Accepted Values:**
- `openAI`
- `azureOpenAI`
- `google`
- `anthropic`
- `assistants`
- `azureAssistants`
- `bedrock`
- `agents`
**Note:** If you are using a custom endpoint, the `endpoint` value must match the defined [custom endpoint name](/docs/configuration/librechat_yaml/object_structure/custom_endpoint#name) exactly.
<OptionTable
options={[
['endpoint', 'Enum (EModelEndpoint) or String (nullable)', 'Specifies the endpoint the model communicates with to execute operations. This setting determines the external or internal service that the model interfaces with.', ''],
]}
/>
**Example:**
```yaml filename="modelSpecs / list / {spec_item} / preset / endpoint"
preset:
endpoint: "openAI"
```
---
#### modelLabel
<OptionTable
options={[
['modelLabel', 'String (nullable)', 'The label used to identify the model in user interfaces or logs. It provides a human-readable name for the model, which is displayed in the UI, as well as made aware to the AI.', 'None'],
]}
/>
**Default:** `None`
**Example:**
```yaml filename="modelSpecs / list / {spec_item} / preset / modelLabel"
preset:
modelLabel: "Customer Support Bot"
```
---
#### greeting
<OptionTable
options={[
['greeting', 'String', 'A predefined message that is visible in the UI before a new chat is started. This is a good way to provide instructions to the user, or to make the interface seem more friendly and accessible.', ''],
]}
/>
**Default:** `None`
**Example:**
```yaml filename="modelSpecs / list / {spec_item} / preset / greeting"
preset:
greeting: "This assistant creates meeting notes based on transcripts of Teams recordings. To start, simply paste the transcript into the chat box."
```
---
#### promptPrefix
<OptionTable
options={[
['promptPrefix', 'String (nullable)', 'A static text prepended to every prompt sent to the model, setting a consistent context for responses.', 'When using "assistants" as the endpoint, this becomes the OpenAI field `additional_instructions`.'],
]}
/>
**Default:** `None`
**Example 1:**
```yaml filename="modelSpecs / list / {spec_item} / preset / promptPrefix"
preset:
promptPrefix: "As a financial advisor, ..."
```
**Example 2:**
```yaml filename="modelSpecs / list / {spec_item} / preset / promptPrefix"
preset:
promptPrefix: |
Based on the transcript, create coherent meeting minutes for a business meeting. Include the following sections:
- Date and Attendees
- Agenda
- Minutes
- Action Items
Focus on what items were discussed and/or resolved. List any open action items.
The format should be a bulleted list of high level topics in chronological order, and then one or more concise sentences explaining the details.
Each high level topic should have at least two sub topics listed, but add as many as necessary to support the high level topic.
- Do not start items with the same opening words.
Take a deep breath and be sure to think step by step.
```
---
#### resendFiles
<OptionTable
options={[
['resendFiles', 'Boolean', 'Indicates whether files should be resent in scenarios where persistent sessions are not maintained.', ''],
]}
/>
**Default:** `false`
**Example:**
```yaml filename="modelSpecs / list / {spec_item} / preset / resendFiles"
preset:
resendFiles: true
```
---
#### imageDetail
**Accepted Values:**
- low
- auto
- high
<OptionTable
options={[
['imageDetail', 'Enum (eImageDetailSchema)', 'Specifies the level of detail required in image analysis tasks, applicable to models with vision capabilities (OpenAI spec).', ''],
]}
/>
**Example:**
```yaml filename="modelSpecs / list / {spec_item} / preset / imageDetail"
preset:
imageDetail: "high"
```
---
#### maxContextTokens
<OptionTable
options={[
['maxContextTokens', 'Number', 'The maximum number of context tokens to provide to the model.', 'Useful if you want to limit the maximum context for this preset.'],
]}
/>
**Example:**
```yaml filename="modelSpecs / list / {spec_item} / preset / maxContextTokens"
preset:
maxContextTokens: 4096
```
---
### Agent Options
Note that these options are only applicable when using the `agents` endpoint.
You should exclude any model options and defer to the agent's configuration as defined in the UI.
---
#### agent_id
<OptionTable
options={[
['agent_id', 'String', 'Identification of an assistant.', ''],
]}
/>
**Example:**
```yaml filename="modelSpecs / list / {spec_item} / preset / agent_id"
preset:
agent_id: "agent_someUniqueId"
```
---
### Assistant Options
Note that these options are only applicable when using the `assistants` or `azureAssistants` endpoint.
Similar to [Agents](#agent-options), you should exclude any model options and defer to the assistant's configuration.
---
#### assistant_id
<OptionTable
options={[
['assistant_id', 'String', 'Identification of an assistant.', ''],
]}
/>
**Example:**
```yaml filename="modelSpecs / list / {spec_item} / preset / assistant_id"
preset:
assistant_id: "asst_someUniqueId"
```
---
#### instructions
**Note:** this is distinct from [`promptPrefix`](#promptPrefix), as this overrides existing assistant instructions for current runs.
Only use this if you want to override the assistant's core instructions.
Use [`promptPrefix`](#promptPrefix) for `additional_instructions`.
More information:
- https://platform.openai.com/docs/api-reference/models#runs-createrun-instructions
- https://platform.openai.com/docs/api-reference/runs/createRun#runs-createrun-additional_instructions
<OptionTable
options={[
['instructions', 'String', 'Overrides the assistant\'s default instructions.', ''],
]}
/>
**Example:**
```yaml filename="modelSpecs / list / {spec_item} / preset / instructions"
preset:
instructions: "Please handle customer queries regarding order status."
```
---
#### append_current_datetime
Adds the current date and time to `additional_instructions` for each run. Does not overwrite `promptPrefix`, but adds to it.
<OptionTable
options={[
['append_current_datetime', 'Boolean', 'Adds the current date and time to `additional_instructions` as defined by `promptPrefix`', ''],
]}
/>
**Example:**
```yaml filename="modelSpecs / list / {spec_item} / preset / append_current_datetime"
preset:
append_current_datetime: true
```
---
### Model Options
> **Note:** Each parameter below includes a note on which endpoints support it.
> **OpenAI / AzureOpenAI / Custom** typically support `temperature`, `presence_penalty`, `frequency_penalty`, `stop`, `top_p`, `max_tokens`.
> **Google / Anthropic** typically support `topP`, `topK`, `maxOutputTokens`, `promptCache` (Anthropic only).
> **Bedrock** supports `region`, `maxTokens`, and a few others.
#### model
> **Supported by:** All endpoints (except `agents`)
<OptionTable
options={[
['model', 'String (nullable)', 'The model name to use for the preset, matching a configured model under the chosen endpoint.', 'None'],
]}
/>
**Default:** `None`
**Example:**
```yaml
preset:
model: "gpt-4-turbo"
```
---
#### temperature
> **Supported by:** `openAI`, `azureOpenAI`, `google` (as `temperature`), `anthropic` (as `temperature`), and custom (OpenAI-like)
<OptionTable
options={[
['temperature', 'Number', 'Controls how deterministic or “creative” the model responses are.', ''],
]}
/>
**Example:**
```yaml
preset:
temperature: 0.7
```
---
#### presence_penalty
> **Supported by:** `openAI`, `azureOpenAI`, custom (OpenAI-like)
> *Not typically used by Google/Anthropic/Bedrock*
<OptionTable
options={[
['presence_penalty', 'Number', 'Penalty for repetitive tokens, encouraging exploration of new topics.', ''],
]}
/>
**Example:**
```yaml
preset:
presence_penalty: 0.3
```
---
#### frequency_penalty
> **Supported by:** `openAI`, `azureOpenAI`, custom (OpenAI-like)
> *Not typically used by Google/Anthropic/Bedrock*
<OptionTable
options={[
['frequency_penalty', 'Number', 'Penalty for repeated tokens, reducing redundancy in responses.', ''],
]}
/>
**Example:**
```yaml
preset:
frequency_penalty: 0.5
```
---
#### stop
> **Supported by:** `openAI`, `azureOpenAI`, custom (OpenAI-like)
> *Not typically used by Google/Anthropic/Bedrock*
<OptionTable
options={[
['stop', 'Array of Strings', 'Stop tokens for the model, instructing it to end its response if encountered.', ''],
]}
/>
**Example:**
```yaml
preset:
stop:
- "END"
- "STOP"
```
---
#### top_p
> **Supported by:** `openAI`, `azureOpenAI`, custom (OpenAI-like)
> **Google/Anthropic** often use `topP` (capital “P”) instead of `top_p`.
<OptionTable
options={[
['top_p', 'Number', 'Nucleus sampling parameter (0-1), controlling the randomness of tokens.', ''],
]}
/>
**Example:**
```yaml
preset:
top_p: 0.9
```
---
#### topP
> **Supported by:** `google` & `anthropic`
> (similar purpose to `top_p`, but named differently in those APIs)
<OptionTable
options={[
['topP', 'Number', 'Nucleus sampling parameter for Google/Anthropic endpoints.', ''],
]}
/>
**Example:**
```yaml
preset:
topP: 0.8
```
---
#### topK
> **Supported by:** `google` & `anthropic`
> (k-sampling limit on the next token distribution)
<OptionTable
options={[
['topK', 'Number', 'Limits the next token selection to the top K tokens.', ''],
]}
/>
**Example:**
```yaml
preset:
topK: 40
```
---
#### max_tokens
> **Supported by:** `openAI`, `azureOpenAI`, custom (OpenAI-like)
> *For Google/Anthropic, use `maxOutputTokens` or `maxTokens` (depending on the endpoint).*
<OptionTable
options={[
['max_tokens', 'Number', 'The maximum number of tokens in the model response.', ''],
]}
/>
**Example:**
```yaml
preset:
max_tokens: 4096
```
---
#### maxOutputTokens
> **Supported by:** `google`, `anthropic`
> *Equivalent to `max_tokens` for these providers.*
<OptionTable
options={[
['maxOutputTokens', 'Number', 'The maximum number of tokens in the response (Google/Anthropic).', ''],
]}
/>
**Example:**
```yaml
preset:
maxOutputTokens: 2048
```
---
#### promptCache
> **Supported by:** `anthropic`
> (Toggle Anthropics “prompt-caching” feature)
<OptionTable
options={[
['promptCache', 'Boolean', 'Enables or disables Anthropics built-in prompt caching.', ''],
]}
/>
**Example:**
```yaml
preset:
promptCache: true
```
---
#### region
> **Supported by:** `bedrock`
> (Used to specify an AWS region for Amazon Bedrock)
<OptionTable
options={[
['region', 'String', 'AWS region for Amazon Bedrock endpoints.', ''],
]}
/>
**Example:**
```yaml
preset:
region: "us-east-1"
```
---
#### maxTokens
> **Supported by:** `bedrock`
> (Used in place of `max_tokens`)
<OptionTable
options={[
['maxTokens', 'Number', 'Maximum output tokens for Amazon Bedrock endpoints.', ''],
]}
/>
**Example:**
```yaml
preset:
maxTokens: 1024
```