本文档面向需要编写Python代码以添加或增强Dify模型支持的开发者,详细指导如何创建目录结构、编写模型配置、实现模型调用逻辑、调试和发布插件的完整流程,包含了核心方法实现和错误处理的细节。
dify-official-plugins
的本地克隆)的 models/
目录下,找到或创建以模型供应商命名的文件夹(例如 models/my_new_provider
)。models
子目录: 在供应商目录下,创建 models
子目录。models/models/
目录下,为你需要支持的每种模型类型创建一个子目录。常见的类型包括:
llm
: 文本生成模型text_embedding
: 文本 Embedding 模型rerank
: Rerank 模型speech2text
: 语音转文字模型tts
: 文字转语音模型moderation
: 内容审查模型models/models/llm/
),你需要创建一个 Python 文件来实现该类型模型的调用逻辑(例如 llm.py
)。my-model-v1.yaml
)。_position.yaml
文件来控制该类型下模型在 Dify UI 中的显示顺序。my_provider
支持 LLM 和 Embedding):
models/models/llm/
),为你要添加的模型创建一个 YAML 文件,文件名通常与模型 ID 保持一致或具有描述性(例如 my-llm-model-v1.yaml
)。model
: (必需) 模型的官方 API 标识符。label
: (必需) 在 Dify UI 中显示的名称 (支持多语言)。model_type
: (必需) 必须与所在目录类型一致 (如 llm
)。features
: (可选) 声明模型支持的特殊功能 (如 vision
, tool-call
, stream-tool-call
等)。model_properties
: (必需) 定义模型固有属性,如 mode
(chat
或 completion
), context_size
。parameter_rules
: (必需) 定义用户可调参数及其规则 (名称 name
, 类型 type
, 是否必须 required
, 默认值 default
, 范围 min
/max
, 选项 options
等)。可以使用 use_template
引用预定义模板简化常见参数(如 temperature
, max_tokens
)的配置。pricing
: (可选) 定义模型的计费信息。claude-3-5-sonnet-20240620.yaml
):
llm.py
)编写代码来处理 API 调用、参数转换和结果返回。
models/models/llm/
)创建或打开相应的 Python 文件(例如 llm.py
)。
MyProviderLargeLanguageModel
。dify_plugin.provider_kits.llm.LargeLanguageModel
。_invoke(...)
: 核心调用方法。
def _invoke(self, model: str, credentials: dict, prompt_messages: List[PromptMessage], model_parameters: dict, tools: Optional[List[PromptMessageTool]] = None, stop: Optional[List[str]] = None, stream: bool = True, user: Optional[str] = None) -> Union[LLMResult, Generator[LLMResultChunk, None, None]]:
credentials
和 model_parameters
准备 API 请求。prompt_messages
格式转换为供应商 API 所需的格式。tools
参数以支持 Function Calling / Tool Use (如果模型支持)。stream
参数决定是进行流式调用还是同步调用。stream=True
,此方法必须返回一个生成器 (Generator
),通过 yield
逐块返回 LLMResultChunk
对象。每个 chunk 包含部分结果(文本、工具调用块等)和可选的用量信息。stream=False
,此方法必须返回一个完整的 LLMResult
对象,包含最终的文本结果、完整的工具调用列表以及总的用量信息 (LLMUsage
)。validate_credentials(self, model: str, credentials: dict) -> None
: (必需) 用于在用户添加或修改凭证时验证其有效性。通常通过调用一个简单的、低成本的 API 端点(如列出可用模型、检查余额等)来实现。如果验证失败,应抛出 CredentialsValidateFailedError
或其子类。
get_num_tokens(self, model: str, credentials: dict, prompt_messages: List[PromptMessage], tools: Optional[List[PromptMessageTool]] = None) -> int
: (可选但推荐) 用于预估给定输入的 Token 数量。如果无法准确计算或 API 不支持,可以返回 0。
@property _invoke_error_mapping(self) -> dict[type[InvokeError], list[type[Exception]]]
: (必需) 定义一个错误映射字典。键是 Dify 的标准 InvokeError
子类,值是供应商 SDK 可能抛出的需要被映射到该标准错误的异常类型列表。这对于 Dify 统一处理不同供应商的错误至关重要。
调试 Key
和 远程服务器地址
(例如 http://<your-dify-domain>:5003
)。.env
文件 (可从 .env.example
复制)。
.env
文件,填入调试信息:
Ctrl+C
)。
<provider_name>.difypkg
文件。
dify-official-plugins
仓库。langgenius/dify-official-plugins
主仓库发起 Pull Request。在 PR 描述中清晰说明你所做的更改、添加的模型或功能,以及任何必要的测试说明。manifest.yaml
规范)