> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Specs

> 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

<ParamField path="provider" type="string">
  Provider identifier, e.g.: `openai`
</ParamField>

<ParamField path="label" type="object">
  Provider display name, i18n, can set both `en_US` (English) and `zh_Hans` (Chinese) languages

  <ParamField path="zh_Hans" type="string">
    Chinese label, if not set, will default to using `en_US`
  </ParamField>

  <ParamField path="en_US" type="string" required>
    English label
  </ParamField>
</ParamField>

<ParamField path="description" type="object">
  Provider description, i18n

  <ParamField path="zh_Hans" type="string">
    Chinese description
  </ParamField>

  <ParamField path="en_US" type="string" required>
    English description
  </ParamField>
</ParamField>

<ParamField path="icon_small" type="object">
  Provider small icon, stored in the `_assets` directory under the corresponding provider implementation directory

  <ParamField path="zh_Hans" type="string">
    Chinese icon
  </ParamField>

  <ParamField path="en_US" type="string" required>
    English icon
  </ParamField>
</ParamField>

<ParamField path="icon_large" type="object">
  Provider large icon, stored in the `_assets` directory under the corresponding provider implementation directory

  <ParamField path="zh_Hans" type="string">
    Chinese icon
  </ParamField>

  <ParamField path="en_US" type="string" required>
    English icon
  </ParamField>
</ParamField>

<ParamField path="background" type="string">
  Background color value, e.g.: #FFFFFF, if empty, will display the frontend default color value
</ParamField>

<ParamField path="help" type="object">
  Help information

  <ParamField path="title" type="object">
    Help title, i18n

    <ParamField path="zh_Hans" type="string">
      Chinese title
    </ParamField>

    <ParamField path="en_US" type="string" required>
      English title
    </ParamField>
  </ParamField>

  <ParamField path="url" type="object">
    Help link, i18n

    <ParamField path="zh_Hans" type="string">
      Chinese link
    </ParamField>

    <ParamField path="en_US" type="string" required>
      English link
    </ParamField>
  </ParamField>
</ParamField>

<ParamField path="supported_model_types" type="array[ModelType]" required>
  Supported model types
</ParamField>

<ParamField path="configurate_methods" type="array[ConfigurateMethod]" required>
  Configuration methods
</ParamField>

<ParamField path="provider_credential_schema" type="ProviderCredentialSchema" required>
  Provider credential specifications
</ParamField>

<ParamField path="model_credential_schema" type="ModelCredentialSchema">
  Model credential specifications
</ParamField>

### AIModelEntity

<ParamField path="model" type="string" required>
  Model identifier, e.g.: `gpt-3.5-turbo`
</ParamField>

<ParamField path="label" type="object">
  Model display name, i18n, can set both `en_US` (English) and `zh_Hans` (Chinese) languages

  <ParamField path="zh_Hans" type="string">
    Chinese label
  </ParamField>

  <ParamField path="en_US" type="string" required>
    English label
  </ParamField>
</ParamField>

<ParamField path="model_type" type="ModelType" required>
  Model type
</ParamField>

<ParamField path="features" type="array[ModelFeature]">
  List of supported features
</ParamField>

<ParamField path="model_properties" type="object" required>
  Model properties

  <ParamField path="mode" type="LLMMode">
    Mode (available for model type `llm`)
  </ParamField>

  <ParamField path="context_size" type="integer">
    Context size (available for model types `llm` and `text-embedding`)
  </ParamField>

  <ParamField path="max_chunks" type="integer">
    Maximum number of chunks (available for model types `text-embedding` and `moderation`)
  </ParamField>

  <ParamField path="file_upload_limit" type="integer">
    Maximum file upload limit, unit: MB. (available for model type `speech2text`)
  </ParamField>

  <ParamField path="supported_file_extensions" type="string">
    Supported file extension formats, e.g.: mp3,mp4 (available for model type `speech2text`)
  </ParamField>

  <ParamField path="default_voice" type="string">
    Default voice, required: alloy,echo,fable,onyx,nova,shimmer (available for model type `tts`)
  </ParamField>

  <ParamField path="voices" type="array">
    List of available voices (available for model type `tts`)

    <ParamField path="mode" type="string">
      Voice model
    </ParamField>

    <ParamField path="name" type="string">
      Voice model display name
    </ParamField>

    <ParamField path="language" type="string">
      Supported languages for voice model
    </ParamField>
  </ParamField>

  <ParamField path="word_limit" type="integer">
    Word limit for single conversion, defaults to paragraph segmentation (available for model type `tts`)
  </ParamField>

  <ParamField path="audio_type" type="string">
    Supported audio file extension formats, e.g.: mp3,wav (available for model type `tts`)
  </ParamField>

  <ParamField path="max_workers" type="integer">
    Number of concurrent tasks supported for text-to-audio conversion (available for model type `tts`)
  </ParamField>

  <ParamField path="max_characters_per_chunk" type="integer">
    Maximum characters per chunk (available for model type `moderation`)
  </ParamField>
</ParamField>

<ParamField path="parameter_rules" type="array[ParameterRule]">
  Model call parameter rules
</ParamField>

<ParamField path="pricing" type="PriceConfig">
  Pricing information
</ParamField>

<ParamField path="deprecated" type="boolean">
  Whether deprecated. If deprecated, the model list will no longer display it, but those already configured can continue to be used. Default is False.
</ParamField>

### ModelType

<ParamField path="llm" type="string">
  Text generation model
</ParamField>

<ParamField path="text-embedding" type="string">
  Text embedding model
</ParamField>

<ParamField path="rerank" type="string">
  Rerank model
</ParamField>

<ParamField path="speech2text" type="string">
  Speech to text
</ParamField>

<ParamField path="tts" type="string">
  Text to speech
</ParamField>

<ParamField path="moderation" type="string">
  Content moderation
</ParamField>

### ConfigurateMethod

<ParamField path="predefined-model" type="string">
  Predefined model - Indicates that the user only needs to configure unified provider credentials to use predefined models under the provider.
</ParamField>

<ParamField path="customizable-model" type="string">
  Customizable model - The user needs to add credential configuration for each model.
</ParamField>

<ParamField path="fetch-from-remote" type="string">
  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.
</ParamField>

### ModelFeature

<ParamField path="agent-thought" type="string">
  Agent reasoning, generally models over 70B have chain-of-thought capabilities.
</ParamField>

<ParamField path="vision" type="string">
  Vision, i.e.: image understanding.
</ParamField>

<ParamField path="tool-call" type="string">
  Tool calling
</ParamField>

<ParamField path="multi-tool-call" type="string">
  Multiple tool calling
</ParamField>

<ParamField path="stream-tool-call" type="string">
  Streaming tool calling
</ParamField>

### FetchFrom

<ParamField path="predefined-model" type="string">
  Predefined model
</ParamField>

<ParamField path="fetch-from-remote" type="string">
  Remote model
</ParamField>

### LLMMode

<ParamField path="completion" type="string">
  Text completion
</ParamField>

<ParamField path="chat" type="string">
  Chat
</ParamField>

### ParameterRule

<ParamField path="name" type="string" required>
  Actual parameter name for model call
</ParamField>

<ParamField path="use_template" type="string">
  Use template
</ParamField>

> For details on using templates, you can refer to the examples in [Creating a New Model Provider](/en/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider).

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.

<ParamField path="label" type="object">
  Label, i18n

  <ParamField path="zh_Hans" type="string">
    Chinese label
  </ParamField>

  <ParamField path="en_US" type="string" required>
    English label
  </ParamField>
</ParamField>

<ParamField path="type" type="string">
  Parameter type

  <ParamField path="int" type="string">
    Integer
  </ParamField>

  <ParamField path="float" type="string">
    Floating point
  </ParamField>

  <ParamField path="string" type="string">
    String
  </ParamField>

  <ParamField path="boolean" type="string">
    Boolean
  </ParamField>
</ParamField>

<ParamField path="help" type="object">
  Help information

  <ParamField path="zh_Hans" type="string">
    Chinese help information
  </ParamField>

  <ParamField path="en_US" type="string" required>
    English help information
  </ParamField>
</ParamField>

<ParamField path="required" type="boolean">
  Whether required, default is False
</ParamField>

<ParamField path="default" type="int/float/string/boolean">
  Default value
</ParamField>

<ParamField path="min" type="int/float">
  Minimum value, only applicable to numeric types
</ParamField>

<ParamField path="max" type="int/float">
  Maximum value, only applicable to numeric types
</ParamField>

<ParamField path="precision" type="integer">
  Precision, decimal places to retain, only applicable to numeric types
</ParamField>

<ParamField path="options" type="array[string]">
  Dropdown option values, only applicable when `type` is `string`, if not set or is null, then option values are not restricted
</ParamField>

### PriceConfig

<ParamField path="input" type="float">
  Input unit price, i.e., Prompt unit price
</ParamField>

<ParamField path="output" type="float">
  Output unit price, i.e., returned content unit price
</ParamField>

<ParamField path="unit" type="float">
  Price unit, e.g., if priced per 1M tokens, then the unit token number corresponding to the unit price is `0.000001`
</ParamField>

<ParamField path="currency" type="string">
  Currency unit
</ParamField>

### ProviderCredentialSchema

<ParamField path="credential_form_schemas" type="array[CredentialFormSchema]" required>
  Credential form specifications
</ParamField>

### ModelCredentialSchema

<ParamField path="model" type="object" required>
  Model identifier, default variable name is `model`

  <ParamField path="label" type="object" required>
    Model form item display name

    <ParamField path="en_US" type="string" required>
      English
    </ParamField>

    <ParamField path="zh_Hans" type="string">
      Chinese
    </ParamField>
  </ParamField>

  <ParamField path="placeholder" type="object" required>
    Model prompt content

    <ParamField path="en_US" type="string" required>
      English
    </ParamField>

    <ParamField path="zh_Hans" type="string">
      Chinese
    </ParamField>
  </ParamField>
</ParamField>

<ParamField path="credential_form_schemas" type="array[CredentialFormSchema]" required>
  Credential form specifications
</ParamField>

### CredentialFormSchema

<ParamField path="variable" type="string" required>
  Form item variable name
</ParamField>

<ParamField path="label" type="object" required>
  Form item label

  <ParamField path="en_US" type="string" required>
    English
  </ParamField>

  <ParamField path="zh_Hans" type="string">
    Chinese
  </ParamField>
</ParamField>

<ParamField path="type" type="FormType" required>
  Form item type
</ParamField>

<ParamField path="required" type="boolean">
  Whether required
</ParamField>

<ParamField path="default" type="string">
  Default value
</ParamField>

<ParamField path="options" type="array[FormOption]">
  Form item attribute specific to `select` or `radio`, defines dropdown content
</ParamField>

<ParamField path="placeholder" type="object">
  Form item attribute specific to `text-input`, form item placeholder

  <ParamField path="en_US" type="string" required>
    English
  </ParamField>

  <ParamField path="zh_Hans" type="string">
    Chinese
  </ParamField>
</ParamField>

<ParamField path="max_length" type="integer">
  Form item attribute specific to `text-input`, defines maximum input length, 0 means no limit
</ParamField>

<ParamField path="show_on" type="array[FormShowOnObject]">
  Display when other form item values meet conditions, empty means always display
</ParamField>

#### FormType

<ParamField path="text-input" type="string">
  Text input component
</ParamField>

<ParamField path="secret-input" type="string">
  Password input component
</ParamField>

<ParamField path="select" type="string">
  Single-select dropdown
</ParamField>

<ParamField path="radio" type="string">
  Radio component
</ParamField>

<ParamField path="switch" type="string">
  Switch component, only supports `true` and `false`
</ParamField>

#### FormOption

<ParamField path="label" type="object" required>
  Label

  <ParamField path="en_US" type="string" required>
    English
  </ParamField>

  <ParamField path="zh_Hans" type="string">
    Chinese
  </ParamField>
</ParamField>

<ParamField path="value" type="string" required>
  Dropdown option value
</ParamField>

<ParamField path="show_on" type="array[FormShowOnObject]">
  Display when other form item values meet conditions, empty means always display
</ParamField>

#### FormShowOnObject

<ParamField path="variable" type="string" required>
  Other form item variable name
</ParamField>

<ParamField path="value" type="string" required>
  Other form item variable value
</ParamField>

## Related Resources

* [Model Architecture Details](/en/develop-plugin/features-and-specs/plugin-types/model-schema) - Deep dive into the architecture specifications of model plugins
* [Quickly Integrate a New Model](/en/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider) - Learn how to apply these rules to add new models
* [General Specifications](/en/develop-plugin/features-and-specs/plugin-types/general-specifications) - Understand the configuration of plugin manifest files
* [Create a New Model Provider](/en/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider) - Develop brand new model provider plugins

***

[Edit this page](https://github.com/langgenius/dify-docs/edit/main/en/develop-plugin/features-and-specs/plugin-types/model-designing-rules.mdx) | [Report an issue](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml)
