> ## Documentation Index
> Fetch the complete documentation index at: https://alterxyz-a56768d7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Design Rules

> This document defines in detail the core concepts and structures for Dify model plugin development, including model providers (Provider), AI model entities (AIModelEntity), model types (ModelType), configuration methods (ConfigurateMethod), model features (ModelFeature), parameter rules (ParameterRule), price configuration (PriceConfig), and detailed data structure specifications for various credential modes.

* Model provider rules are based on the [Provider](#provider) entity.
* Model rules are based on the [AIModelEntity](#aimodelentity) entity.

> All entities below are based on `Pydantic BaseModel`, and can be found in the `entities` module.

### Provider

* `provider` (string) Provider identifier, e.g.: `openai`
* `label` (object) Provider display name, i18n, can set both `en_US` (English) and `zh_Hans` (Chinese) languages
  * `zh_Hans` (string) \[optional] Chinese label, if not set, will default to using `en_US`
  * `en_US` (string) English label
* `description` (object) \[optional] Provider description, i18n
  * `zh_Hans` (string) \[optional] Chinese description
  * `en_US` (string) English description
* `icon_small` (string) \[optional] Provider small icon, stored in the `_assets` directory under the corresponding provider implementation directory, same language strategy as `label`
  * `zh_Hans` (string) \[optional] Chinese icon
  * `en_US` (string) English icon
* `icon_large` (string) \[optional] Provider large icon, stored in the `_assets` directory under the corresponding provider implementation directory, same language strategy as label
  * `zh_Hans` (string) \[optional] Chinese icon
  * `en_US` (string) English icon
* `background` (string) \[optional] Background color value, e.g.: #FFFFFF, if empty, will display the frontend default color value
* `help` (object) \[optional] Help information
  * `title` (object) Help title, i18n
    * `zh_Hans` (string) \[optional] Chinese title
    * `en_US` (string) English title
  * `url` (object) Help link, i18n
    * `zh_Hans` (string) \[optional] Chinese link
    * `en_US` (string) English link
* `supported_model_types` (array\[[ModelType](#modeltype)]) Supported model types
* `configurate_methods` (array\[[ConfigurateMethod](#configuratemethod)]) Configuration methods
* `provider_credential_schema` (\[[ProviderCredentialSchema](#providercredentialschema)]) Provider credential specifications
* `model_credential_schema` (\[[ModelCredentialSchema](#modelcredentialschema)]) Model credential specifications

### AIModelEntity

* `model` (string) Model identifier, e.g.: `gpt-3.5-turbo`
* `label` (object) \[optional] Model display name, i18n, can set both `en_US` (English) and `zh_Hans` (Chinese) languages
  * `zh_Hans` (string) \[optional] Chinese label
  * `en_US` (string) English label
* `model_type` ([ModelType](#modeltype)) Model type
* `features` (array\[[ModelFeature](#modelfeature)]) \[optional] List of supported features
* `model_properties` (object) Model properties
  * `mode` ([LLMMode](#llmmode)) Mode (available for model type `llm`)
  * `context_size` (int) Context size (available for model types `llm` and `text-embedding`)
  * `max_chunks` (int) Maximum number of chunks (available for model types `text-embedding moderation`)
  * `file_upload_limit` (int) Maximum file upload limit, unit: MB. (available for model type `speech2text`)
  * `supported_file_extensions` (string) Supported file extension formats, e.g.: mp3,mp4 (available for model type `speech2text`)
  * `default_voice` (string) Default voice, required: alloy,echo,fable,onyx,nova,shimmer (available for model type `tts`)
  * `voices` (list) List of available voices.
    * `mode` (string) Voice model. (available for model type `tts`)
    * `name` (string) Voice model display name. (available for model type `tts`)
    * `language` (string) Supported languages for voice model. (available for model type `tts`)
  * `word_limit` (int) Word limit for single conversion, defaults to paragraph segmentation (available for model type `tts`)
  * `audio_type` (string) Supported audio file extension formats, e.g.: mp3,wav (available for model type `tts`)
  * `max_workers` (int) Number of concurrent tasks supported for text-to-audio conversion (available for model type `tts`)
  * `max_characters_per_chunk` (int) Maximum characters per chunk (available for model type `moderation`)
* `parameter_rules` (array\[[ParameterRule](#parameterrule)]) \[optional] Model call parameter rules
* `pricing` (\[[PriceConfig](#priceconfig)]) \[optional] Pricing information
* `deprecated` (bool) Whether deprecated. If deprecated, the model list will no longer display it, but those already configured can continue to be used. Default is False.

### ModelType

* `llm` Text generation model
* `text-embedding` Text embedding model
* `rerank` Rerank model
* `speech2text` Speech to text
* `tts` Text to speech
* `moderation` Content moderation

### ConfigurateMethod

* `predefined-model` Predefined model

Indicates that the user only needs to configure unified provider credentials to use predefined models under the provider.

* `customizable-model` Customizable model

The user needs to add credential configuration for each model.

* `fetch-from-remote` Fetch from remote

Similar to the `predefined-model` configuration method, only unified provider credentials are needed, but the models are fetched from the provider using the credential information.

### ModelFeature

* `agent-thought` Agent reasoning, generally models over 70B have chain-of-thought capabilities.
* `vision` Vision, i.e.: image understanding.
* `tool-call` Tool calling
* `multi-tool-call` Multiple tool calling
* `stream-tool-call` Streaming tool calling

### FetchFrom

* `predefined-model` Predefined model
* `fetch-from-remote` Remote model

### LLMMode

* `completion` Text completion
* `chat` Chat

### ParameterRule

* `name` (string) Actual parameter name for model call
* `use_template` (string) \[optional] Use template

> For details on using templates, you can refer to the examples in [Creating a New Model Provider](https://alterxyz-a56768d7.mintlify.site/plugin_dev_en/0222-creating-new-model-provider.en.md).

There are 5 pre-configured variable content templates by default:

* `temperature`
* `top_p`
* `frequency_penalty`
* `presence_penalty`
* `max_tokens`

You can directly set the template variable name in `use_template`, which will use the default configuration from entities.defaults.PARAMETER\_RULE\_TEMPLATE without needing to set any parameters other than `name` and `use_template`. If additional configuration parameters are set, they will override the default configuration. You can refer to `openai/llm/gpt-3.5-turbo.yaml` for examples.

* `label` (object) \[optional] Label, i18n
* `zh_Hans`(string) \[optional] Chinese label
* `en_US` (string) English label
* `type`(string) \[optional] Parameter type
  * `int` Integer
  * `float` Floating point
  * `string` String
  * `boolean` Boolean
* `help` (string) \[optional] Help information
* `zh_Hans` (string) \[optional] Chinese help information
* `en_US` (string) English help information
* `required` (bool) Whether required, default is False.
* `default`(int/float/string/bool) \[optional] Default value
* `min`(int/float) \[optional] Minimum value, only applicable to numeric types
* `max`(int/float) \[optional] Maximum value, only applicable to numeric types
* `precision`(int) \[optional] Precision, decimal places to retain, only applicable to numeric types
* `options` (array\[string]) \[optional] Dropdown option values, only applicable when `type` is `string`, if not set or is null, then option values are not restricted

### PriceConfig

* `input` (float) Input unit price, i.e., Prompt unit price
* `output` (float) Output unit price, i.e., returned content unit price
* `unit` (float) Price unit, e.g., if priced per 1M tokens, then the unit token number corresponding to the unit price is `0.000001`
* `currency` (string) Currency unit

### ProviderCredentialSchema

* `credential_form_schemas` (array\[[CredentialFormSchema](#credentialformschema)]) Credential form specifications

### ModelCredentialSchema

* `model` (object) Model identifier, default variable name is `model`
  * `label` (object) Model form item display name
    * `en_US` (string) English
    * `zh_Hans`(string) \[optional] Chinese
  * `placeholder` (object) Model prompt content
    * `en_US`(string) English
    * `zh_Hans`(string) \[optional] Chinese
* `credential_form_schemas` (array\[[CredentialFormSchema](#credentialformschema)]) Credential form specifications

### CredentialFormSchema

* `variable` (string) Form item variable name
* `label` (object) Form item label
  * `en_US`(string) English
  * `zh_Hans` (string) \[optional] Chinese
* `type` ([FormType](#formtype)) Form item type
* `required` (bool) Whether required
* `default`(string) Default value
* `options` (array\[[FormOption](#formoption)]) Form item attribute specific to `select` or `radio`, defines dropdown content
* `placeholder`(object) Form item attribute specific to `text-input`, form item placeholder
  * `en_US`(string) English
  * `zh_Hans` (string) \[optional] Chinese
* `max_length` (int) Form item attribute specific to `text-input`, defines maximum input length, 0 means no limit.
* `show_on` (array\[[FormShowOnObject](#formshowonobject)]) Display when other form item values meet conditions, empty means always display.

#### FormType

* `text-input` Text input component
* `secret-input` Password input component
* `select` Single-select dropdown
* `radio` Radio component
* `switch` Switch component, only supports `true` and `false`

#### FormOption

* `label` (object) Label
  * `en_US`(string) English
  * `zh_Hans`(string) \[optional] Chinese
* `value` (string) Dropdown option value
* `show_on` (array\[[FormShowOnObject](#formshowonobject)]) Display when other form item values meet conditions, empty means always display.

#### FormShowOnObject

* `variable` (string) Other form item variable name
* `value` (string) Other form item variable value

## Related Resources

* [Model Architecture Details](https://alterxyz-a56768d7.mintlify.site/plugin_dev_en/0412-model-schema.en.md) - Deep dive into the architecture specifications of model plugins
* [Quickly Integrate a New Model](https://alterxyz-a56768d7.mintlify.site/plugin_dev_en/0211-getting-started-new-model.en.md) - Learn how to apply these rules to add new models
* [General Specifications](https://alterxyz-a56768d7.mintlify.site/plugin_dev_en/0411-general-specifications.en.md) - Understand the configuration of plugin manifest files
* [Create a New Model Provider](https://alterxyz-a56768d7.mintlify.site/plugin_dev_en/0222-creating-new-model-provider.en.md) - Develop brand new model provider plugins


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.