> ## Documentation Index
> Fetch the complete documentation index at: https://dify-6c0370d8-add-new-agent.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 模型规范

> 本文档详细定义了 Dify 模型插件开发的核心概念和结构，包括模型供应商（Provider）、AI 模型实体（AIModelEntity）、模型类型（ModelType）、配置方法（ConfigurateMethod）、模型特性（ModelFeature）、参数规则（ParameterRule）、价格配置（PriceConfig）以及各种凭据模式的详细数据结构规范。

<Note> ⚠️ 本文档由 AI 自动翻译。如有任何不准确之处，请参考[英文原版](/en/develop-plugin/features-and-specs/plugin-types/model-designing-rules)。</Note>

* 模型供应商规则基于 [Provider](#provider) 实体。
* 模型规则基于 [AIModelEntity](#aimodelentity) 实体。

> 以下所有实体均基于 `Pydantic BaseModel`，可在 `entities` 模块中找到。

### Provider

<ParamField path="provider" type="string">
  供应商标识符，例如：`openai`
</ParamField>

<ParamField path="label" type="object">
  供应商显示名称，i18n，可设置 `en_US`（英文）和 `zh_Hans`（中文）两种语言

  <ParamField path="zh_Hans" type="string">
    中文标签，若未设置，将默认使用 `en_US`
  </ParamField>

  <ParamField path="en_US" type="string" required>
    英文标签
  </ParamField>
</ParamField>

<ParamField path="description" type="object">
  供应商描述，i18n

  <ParamField path="zh_Hans" type="string">
    中文描述
  </ParamField>

  <ParamField path="en_US" type="string" required>
    英文描述
  </ParamField>
</ParamField>

<ParamField path="icon_small" type="object">
  供应商小图标，存储在相应供应商实现目录下的 `_assets` 目录中

  <ParamField path="zh_Hans" type="string">
    中文图标
  </ParamField>

  <ParamField path="en_US" type="string" required>
    英文图标
  </ParamField>
</ParamField>

<ParamField path="icon_large" type="object">
  供应商大图标，存储在相应供应商实现目录下的 `_assets` 目录中

  <ParamField path="zh_Hans" type="string">
    中文图标
  </ParamField>

  <ParamField path="en_US" type="string" required>
    英文图标
  </ParamField>
</ParamField>

<ParamField path="background" type="string">
  背景颜色值，例如：#FFFFFF，若为空，将显示前端默认颜色值
</ParamField>

<ParamField path="help" type="object">
  帮助信息

  <ParamField path="title" type="object">
    帮助标题，i18n

    <ParamField path="zh_Hans" type="string">
      中文标题
    </ParamField>

    <ParamField path="en_US" type="string" required>
      英文标题
    </ParamField>
  </ParamField>

  <ParamField path="url" type="object">
    帮助链接，i18n

    <ParamField path="zh_Hans" type="string">
      中文链接
    </ParamField>

    <ParamField path="en_US" type="string" required>
      英文链接
    </ParamField>
  </ParamField>
</ParamField>

<ParamField path="supported_model_types" type="array[ModelType]" required>
  支持的模型类型
</ParamField>

<ParamField path="configurate_methods" type="array[ConfigurateMethod]" required>
  配置方法
</ParamField>

<ParamField path="provider_credential_schema" type="ProviderCredentialSchema" required>
  供应商凭据规范
</ParamField>

<ParamField path="model_credential_schema" type="ModelCredentialSchema">
  模型凭据规范
</ParamField>

### AIModelEntity

<ParamField path="model" type="string" required>
  模型标识符，例如：`gpt-3.5-turbo`
</ParamField>

<ParamField path="label" type="object">
  模型显示名称，i18n，可设置 `en_US`（英文）和 `zh_Hans`（中文）两种语言

  <ParamField path="zh_Hans" type="string">
    中文标签
  </ParamField>

  <ParamField path="en_US" type="string" required>
    英文标签
  </ParamField>
</ParamField>

<ParamField path="model_type" type="ModelType" required>
  模型类型
</ParamField>

<ParamField path="features" type="array[ModelFeature]">
  支持的特性列表
</ParamField>

<ParamField path="model_properties" type="object" required>
  模型属性

  <ParamField path="mode" type="LLMMode">
    模式（适用于模型类型 `llm`）
  </ParamField>

  <ParamField path="context_size" type="integer">
    上下文大小（适用于模型类型 `llm` 和 `text-embedding`）
  </ParamField>

  <ParamField path="max_chunks" type="integer">
    最大分块数（适用于模型类型 `text-embedding` 和 `moderation`）
  </ParamField>

  <ParamField path="file_upload_limit" type="integer">
    最大文件上传限制，单位：MB（适用于模型类型 `speech2text`）
  </ParamField>

  <ParamField path="supported_file_extensions" type="string">
    支持的文件扩展名格式，例如：mp3,mp4（适用于模型类型 `speech2text`）
  </ParamField>

  <ParamField path="default_voice" type="string">
    默认语音，必填项：alloy,echo,fable,onyx,nova,shimmer（适用于模型类型 `tts`）
  </ParamField>

  <ParamField path="voices" type="array">
    可用语音列表（适用于模型类型 `tts`）

    <ParamField path="mode" type="string">
      语音模型
    </ParamField>

    <ParamField path="name" type="string">
      语音模型显示名称
    </ParamField>

    <ParamField path="language" type="string">
      语音模型支持的语言
    </ParamField>
  </ParamField>

  <ParamField path="word_limit" type="integer">
    单次转换的字数限制，默认按段落分割（适用于模型类型 `tts`）
  </ParamField>

  <ParamField path="audio_type" type="string">
    支持的音频文件扩展名格式，例如：mp3,wav（适用于模型类型 `tts`）
  </ParamField>

  <ParamField path="max_workers" type="integer">
    文字转音频转换支持的并发任务数（适用于模型类型 `tts`）
  </ParamField>

  <ParamField path="max_characters_per_chunk" type="integer">
    每个分块的最大字符数（适用于模型类型 `moderation`）
  </ParamField>
</ParamField>

<ParamField path="parameter_rules" type="array[ParameterRule]">
  模型调用参数规则
</ParamField>

<ParamField path="pricing" type="PriceConfig">
  价格信息
</ParamField>

<ParamField path="deprecated" type="boolean">
  是否已弃用。若已弃用，模型列表将不再显示该模型，但已配置的仍可继续使用。默认为 False。
</ParamField>

### ModelType

<ParamField path="llm" type="string">
  文本生成模型
</ParamField>

<ParamField path="text-embedding" type="string">
  文本嵌入模型
</ParamField>

<ParamField path="rerank" type="string">
  重排序模型
</ParamField>

<ParamField path="speech2text" type="string">
  语音转文字
</ParamField>

<ParamField path="tts" type="string">
  文字转语音
</ParamField>

<ParamField path="moderation" type="string">
  内容审核
</ParamField>

### ConfigurateMethod

<ParamField path="predefined-model" type="string">
  预定义模型 - 表示用户只需配置统一的供应商凭据即可使用该供应商下的预定义模型。
</ParamField>

<ParamField path="customizable-model" type="string">
  自定义模型 - 用户需要为每个模型添加凭据配置。
</ParamField>

<ParamField path="fetch-from-remote" type="string">
  从远程获取 - 与 `predefined-model` 配置方法类似，只需统一的供应商凭据，但模型是使用凭据信息从供应商获取的。
</ParamField>

### ModelFeature

<ParamField path="agent-thought" type="string">
  智能体推理，通常 70B 以上的模型具有思维链能力。
</ParamField>

<ParamField path="vision" type="string">
  视觉，即：图像理解。
</ParamField>

<ParamField path="tool-call" type="string">
  工具调用
</ParamField>

<ParamField path="multi-tool-call" type="string">
  多工具调用
</ParamField>

<ParamField path="stream-tool-call" type="string">
  流式工具调用
</ParamField>

### FetchFrom

<ParamField path="predefined-model" type="string">
  预定义模型
</ParamField>

<ParamField path="fetch-from-remote" type="string">
  远程模型
</ParamField>

### LLMMode

<ParamField path="completion" type="string">
  文本补全
</ParamField>

<ParamField path="chat" type="string">
  对话
</ParamField>

### ParameterRule

<ParamField path="name" type="string" required>
  模型调用的实际参数名称
</ParamField>

<ParamField path="use_template" type="string">
  使用模板
</ParamField>

> 有关使用模板的详细信息，可参考[创建新模型供应商](/zh/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider)中的示例。

默认有 5 个预配置的变量内容模板：

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

可以直接在 `use_template` 中设置模板变量名，这将使用 entities.defaults.PARAMETER\_RULE\_TEMPLATE 中的默认配置，无需设置除 `name` 和 `use_template` 之外的任何参数。如果设置了额外的配置参数，它们将覆盖默认配置。可参考 `openai/llm/gpt-3.5-turbo.yaml` 中的示例。

<ParamField path="label" type="object">
  标签，i18n

  <ParamField path="zh_Hans" type="string">
    中文标签
  </ParamField>

  <ParamField path="en_US" type="string" required>
    英文标签
  </ParamField>
</ParamField>

<ParamField path="type" type="string">
  参数类型

  <ParamField path="int" type="string">
    整数
  </ParamField>

  <ParamField path="float" type="string">
    浮点数
  </ParamField>

  <ParamField path="string" type="string">
    字符串
  </ParamField>

  <ParamField path="boolean" type="string">
    布尔值
  </ParamField>
</ParamField>

<ParamField path="help" type="object">
  帮助信息

  <ParamField path="zh_Hans" type="string">
    中文帮助信息
  </ParamField>

  <ParamField path="en_US" type="string" required>
    英文帮助信息
  </ParamField>
</ParamField>

<ParamField path="required" type="boolean">
  是否必填，默认为 False
</ParamField>

<ParamField path="default" type="int/float/string/boolean">
  默认值
</ParamField>

<ParamField path="min" type="int/float">
  最小值，仅适用于数值类型
</ParamField>

<ParamField path="max" type="int/float">
  最大值，仅适用于数值类型
</ParamField>

<ParamField path="precision" type="integer">
  精度，保留的小数位数，仅适用于数值类型
</ParamField>

<ParamField path="options" type="array[string]">
  下拉选项值，仅当 `type` 为 `string` 时适用，若未设置或为 null，则不限制选项值
</ParamField>

### PriceConfig

<ParamField path="input" type="float">
  输入单价，即提示词单价
</ParamField>

<ParamField path="output" type="float">
  输出单价，即返回内容单价
</ParamField>

<ParamField path="unit" type="float">
  价格单位，例如，若按每 1M 令牌计价，则单价对应的单位令牌数为 `0.000001`
</ParamField>

<ParamField path="currency" type="string">
  货币单位
</ParamField>

### ProviderCredentialSchema

<ParamField path="credential_form_schemas" type="array[CredentialFormSchema]" required>
  凭据表单规范
</ParamField>

### ModelCredentialSchema

<ParamField path="model" type="object" required>
  模型标识符，默认变量名为 `model`

  <ParamField path="label" type="object" required>
    模型表单项显示名称

    <ParamField path="en_US" type="string" required>
      英文
    </ParamField>

    <ParamField path="zh_Hans" type="string">
      中文
    </ParamField>
  </ParamField>

  <ParamField path="placeholder" type="object" required>
    模型提示内容

    <ParamField path="en_US" type="string" required>
      英文
    </ParamField>

    <ParamField path="zh_Hans" type="string">
      中文
    </ParamField>
  </ParamField>
</ParamField>

<ParamField path="credential_form_schemas" type="array[CredentialFormSchema]" required>
  凭据表单规范
</ParamField>

### CredentialFormSchema

<ParamField path="variable" type="string" required>
  表单项变量名
</ParamField>

<ParamField path="label" type="object" required>
  表单项标签

  <ParamField path="en_US" type="string" required>
    英文
  </ParamField>

  <ParamField path="zh_Hans" type="string">
    中文
  </ParamField>
</ParamField>

<ParamField path="type" type="FormType" required>
  表单项类型
</ParamField>

<ParamField path="required" type="boolean">
  是否必填
</ParamField>

<ParamField path="default" type="string">
  默认值
</ParamField>

<ParamField path="options" type="array[FormOption]">
  `select` 或 `radio` 特有的表单项属性，定义下拉内容
</ParamField>

<ParamField path="placeholder" type="object">
  `text-input` 特有的表单项属性，表单项占位符

  <ParamField path="en_US" type="string" required>
    英文
  </ParamField>

  <ParamField path="zh_Hans" type="string">
    中文
  </ParamField>
</ParamField>

<ParamField path="max_length" type="integer">
  `text-input` 特有的表单项属性，定义最大输入长度，0 表示无限制
</ParamField>

<ParamField path="show_on" type="array[FormShowOnObject]">
  当其他表单项值满足条件时显示，为空表示始终显示
</ParamField>

#### FormType

<ParamField path="text-input" type="string">
  文本输入组件
</ParamField>

<ParamField path="secret-input" type="string">
  密码输入组件
</ParamField>

<ParamField path="select" type="string">
  单选下拉框
</ParamField>

<ParamField path="radio" type="string">
  单选按钮组件
</ParamField>

<ParamField path="switch" type="string">
  开关组件，仅支持 `true` 和 `false`
</ParamField>

#### FormOption

<ParamField path="label" type="object" required>
  标签

  <ParamField path="en_US" type="string" required>
    英文
  </ParamField>

  <ParamField path="zh_Hans" type="string">
    中文
  </ParamField>
</ParamField>

<ParamField path="value" type="string" required>
  下拉选项值
</ParamField>

<ParamField path="show_on" type="array[FormShowOnObject]">
  当其他表单项值满足条件时显示，为空表示始终显示
</ParamField>

#### FormShowOnObject

<ParamField path="variable" type="string" required>
  其他表单项变量名
</ParamField>

<ParamField path="value" type="string" required>
  其他表单项变量值
</ParamField>

## 相关资源

* [模型架构详解](/zh/develop-plugin/features-and-specs/plugin-types/model-schema) - 深入了解模型插件的架构规范
* [快速集成新模型](/zh/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider) - 学习如何应用这些规则来添加新模型
* [通用规范](/zh/develop-plugin/features-and-specs/plugin-types/general-specifications) - 了解插件清单文件的配置
* [创建新模型供应商](/zh/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider) - 开发全新的模型供应商插件

***

[编辑此页面](https://github.com/langgenius/dify-docs/edit/main/en/develop-plugin/features-and-specs/plugin-types/model-designing-rules.mdx) | [报告问题](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml)