实现标准的模型集成

本文档是为需要通过编写 Python 代码来为 Dify 添加或增强模型支持的开发者准备的标准指南。当你需要添加的模型涉及新的 API 调用逻辑、特殊参数处理或 Dify 需要显式支持的新功能（如 Vision, Tool Calling）时，就需要遵循本指南的步骤。

阅读本文前，建议你：

具备 Python 编程基础和面向对象编程的基本理解。
熟悉你想要集成的模型供应商提供的 API 文档和认证方式。
已安装并配置好 Dify 插件开发工具包 (参考初始化开发工具)。
（可选）阅读模型插件介绍文档，了解模型插件的基本概念和架构。

本指南将引导你完成创建目录结构、编写模型配置 (YAML)、实现模型调用逻辑 (Python) 以及调试和发布插件的全过程。

第 1 步: 创建目录结构

一个组织良好的目录结构是开发可维护插件的基础。你需要为你的模型供应商插件创建特定的目录和文件。

定位或创建供应商目录: 在你的插件项目（通常是 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）。
- 同样在该目录下，你需要为该类型下的每个具体模型创建一个 YAML 配置文件（例如 my-model-v1.yaml）。
- （可选）可以创建一个 _position.yaml 文件来控制该类型下模型在 Dify UI 中的显示顺序。

示例结构 (假设供应商 my_provider 支持 LLM 和 Embedding):

models/my_provider/
├── models                # 模型实现和配置目录
│   ├── llm               # LLM 类型
│   │   ├── _position.yaml  (可选, 控制排序)
│   │   ├── my-llm-model-v1.yaml
│   │   ├── my-llm-model-v2.yaml
│   │   └── llm.py          # LLM 实现逻辑
│   └── text_embedding    # Embedding 类型
│       ├── _position.yaml  (可选, 控制排序)
│       ├── my-embedding-model.yaml
│       └── text_embedding.py # Embedding 实现逻辑
├── provider              # 供应商级别代码目录
│   └── my_provider.py    (用于凭证验证等, 参考“创建模型供应商”文档)
└── manifest.yaml         # 插件清单文件

第 2 步: 定义模型配置 (YAML)

对于每个具体模型，你需要创建一个 YAML 文件来描述其属性、参数和功能，以便 Dify 能够正确地理解和使用它。

创建 YAML 文件: 在对应的模型类型目录下（例如 models/models/llm/），为你要添加的模型创建一个 YAML 文件，文件名通常与模型 ID 保持一致或具有描述性（例如 my-llm-model-v1.yaml）。
编写配置内容: 遵循 AIModelEntity Schema Definition 规范编写内容。关键字段包括：
- 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):

model: claude-3-5-sonnet-20240620
label:
  en_US: claude-3-5-sonnet-20240620
model_type: llm
features:
  - agent-thought
  - vision
  - tool-call
  - stream-tool-call
  - document
model_properties:
  mode: chat
  context_size: 200000
parameter_rules:
  - name: temperature
    use_template: temperature
  - name: top_p
    use_template: top_p
  - name: max_tokens
    use_template: max_tokens
    required: true
    default: 8192
    min: 1
    max: 8192 # 注意 Dify 层面可能有限制
pricing:
  input: '3.00'
  output: '15.00'
  unit: '0.000001' # 每百万 token
  currency: USD

第 3 步: 编写模型调用代码 (Python)

这是实现模型功能的和核心步骤。你需要在对应模型类型的 Python 文件中（例如 llm.py）编写代码来处理 API 调用、参数转换和结果返回。

创建/编辑 Python 文件: 在模型类型目录下（例如 models/models/llm/）创建或打开相应的 Python 文件（例如 llm.py）。

定义实现类:

定义一个类，例如 MyProviderLargeLanguageModel。
该类必须继承自 Dify 插件 SDK 中对应的模型类型基类。例如，对于 LLM，需要继承 dify_plugin.provider_kits.llm.LargeLanguageModel。

import logging
from typing import Union, Generator, Optional, List
from dify_plugin.provider_kits.llm import LargeLanguageModel # 导入基类
from dify_plugin.provider_kits.llm import LLMResult, LLMResultChunk, LLMUsage # 导入结果和用量类
from dify_plugin.provider_kits.llm import PromptMessage, PromptMessageTool # 导入消息和工具类
from dify_plugin.errors.provider_error import InvokeError, InvokeAuthorizationError # 导入错误类
# 假设你有一个 vendor_sdk 用于调用 API
# import vendor_sdk

logger = logging.getLogger(__name__)

class MyProviderLargeLanguageModel(LargeLanguageModel):
    # ... 实现方法 ...

实现关键方法: (具体需要实现的方法取决于继承的基类，以下以 LLM 为例)

_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 请求。
- 将 Dify 的 prompt_messages 格式转换为供应商 API 所需的格式。
- 处理 tools 参数以支持 Function Calling / Tool Use (如果模型支持)。
- 根据 stream 参数决定是进行流式调用还是同步调用。
- 流式返回: 如果 stream=True，此方法必须返回一个生成器 (Generator)，通过 yield 逐块返回 LLMResultChunk 对象。每个 chunk 包含部分结果（文本、工具调用块等）和可选的用量信息。
- 同步返回: 如果 stream=False，此方法必须返回一个完整的 LLMResult 对象，包含最终的文本结果、完整的工具调用列表以及总的用量信息 (LLMUsage)。
实现模式: 强烈建议将同步和流式逻辑拆分到内部帮助方法中。

def _invoke(self, ..., stream: bool = True, ...) -> Union[LLMResult, Generator[LLMResultChunk, None, None]]:
    # 准备 API 请求参数 (认证、模型参数转换、消息格式转换等)
    api_params = self._prepare_api_params(credentials, model_parameters, prompt_messages, tools, stop)

    try:
        if stream:
            return self._invoke_stream(model, api_params, user)
        else:
            return self._invoke_sync(model, api_params, user)
    except vendor_sdk.APIError as e:
        # 处理 API 错误, 映射到 Dify 错误 (参考 _invoke_error_mapping)
        # ... raise mapped_error ...
        pass # Replace with actual error handling
    except Exception as e:
        logger.exception("Unknown error during model invocation")
        raise e # Or raise a generic InvokeError

def _invoke_stream(self, model: str, api_params: dict, user: Optional[str]) -> Generator[LLMResultChunk, None, None]:
    # 调用 vendor_sdk 的流式接口
    # for api_chunk in vendor_sdk.create_stream(...):
    #     # 将 api_chunk 转换为 LLMResultChunk
    #     dify_chunk = self._convert_api_chunk_to_llm_result_chunk(api_chunk)
    #     yield dify_chunk
    pass # Replace with actual implementation

def _invoke_sync(self, model: str, api_params: dict, user: Optional[str]) -> LLMResult:
    # 调用 vendor_sdk 的同步接口
    # api_response = vendor_sdk.create_sync(...)
    # 将 api_response 转换为 LLMResult (包括 message.content, tools, usage)
    # dify_result = self._convert_api_response_to_llm_result(api_response)
    # return dify_result
    pass # Replace with actual implementation

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 统一处理不同供应商的错误至关重要。

@property
def _invoke_error_mapping(self) -> dict[type[InvokeError], list[type[Exception]]]:
    # 示例映射
    mapping = {
        InvokeAuthorizationError: [
            vendor_sdk.AuthenticationError,
            vendor_sdk.PermissionDeniedError,
        ],
        InvokeRateLimitError: [
            vendor_sdk.RateLimitError,
        ],
        # ... 其他映射 ...
    }
    # 可以在这里加入基类的默认映射 (如果基类提供的话)
    # base_mapping = super()._invoke_error_mapping
    # mapping.update(base_mapping) # 注意合并策略
    return mapping

第 4 步: 调试插件

在将插件贡献给社区之前，充分的测试和调试是必不可少的。Dify 提供了远程调试功能，让你可以在本地修改代码并实时在 Dify 实例中测试效果。

获取调试信息:
- 在你的 Dify 实例中，进入 “插件管理” 页面 (可能需要管理员权限)。
- 点击页面右上角的 “调试插件”，获取你的 调试 Key 和 远程服务器地址 (例如 http://<your-dify-domain>:5003)。

配置本地环境:

在你的本地插件项目根目录下，找到或创建 .env 文件 (可从 .env.example 复制)。

编辑 .env 文件，填入调试信息：

INSTALL_METHOD=remote
REMOTE_INSTALL_HOST=<your-dify-domain-or-ip> # Dify 服务器地址
REMOTE_INSTALL_PORT=5003                     # 调试端口
REMOTE_INSTALL_KEY=****-****-****-****-**** # 你的调试 Key

启动本地插件服务:
- 在插件项目根目录下，确保你的 Python 环境已激活（如果使用虚拟环境）。
- 运行主程序：
  python -m main
- 观察终端输出，如果连接成功，通常会有相应的日志提示。
在 Dify 中测试:
- 刷新 Dify 的 “插件” 或 “模型供应商” 页面，你应该能看到你的本地插件实例，可能带有 “调试中” 标识。
- 前往 “设置” -> “模型供应商”，找到你的插件，配置有效的 API 凭证。
- 在 Dify 应用中选择并使用你的模型进行测试。你在本地对 Python 代码的修改（保存后通常会自动重新加载服务）会直接影响 Dify 中的调用行为。使用 Dify 的调试预览功能可以帮助你检查输入输出和错误信息。

第 5 步: 打包与发布

当你完成了开发和调试，并对插件的功能满意后，就可以将其打包并贡献给 Dify 社区了。

打包插件:
- 停止本地调试服务 (Ctrl+C)。
- 在插件项目根目录下运行打包命令：
  # 将 <provider_name> 替换为你的供应商目录名 dify plugin package models/<provider_name>
- 这将在项目根目录下生成一个 <provider_name>.difypkg 文件。
提交 Pull Request:
- 确保你的代码风格良好，并遵循 Dify 的插件发布规范。
- 将你的本地 Git 提交推送到你 Fork 的 dify-official-plugins 仓库。
- 在 GitHub 上向 langgenius/dify-official-plugins 主仓库发起 Pull Request。在 PR 描述中清晰说明你所做的更改、添加的模型或功能，以及任何必要的测试说明。
- 等待 Dify 团队审核。审核通过并合并后，你的贡献将包含在官方插件中，并在 Dify Marketplace 上可用。

探索更多

模型 Schema 定义 (模型 YAML 规范)
插件 Manifest 结构 (manifest.yaml 规范)
Dify Plugin SDK 参考 (查找基类、数据结构和错误类型)
Dify 官方插件仓库 (查看现有插件的实现)

编辑此页面 | 提交问题

概念与入门

开发实践

贡献与发布

实践案例与示例

高级开发

Reference & Specifications

关于本文档

实现标准的模型集成

第 1 步: 创建目录结构

第 2 步: 定义模型配置 (YAML)

第 3 步: 编写模型调用代码 (Python)

第 4 步: 调试插件

第 5 步: 打包与发布

探索更多

概念与入门

开发实践

贡献与发布

实践案例与示例

高级开发

Reference & Specifications

关于本文档

​第 1 步: 创建目录结构

​第 2 步: 定义模型配置 (YAML)

​第 3 步: 编写模型调用代码 (Python)

​第 4 步: 调试插件

​第 5 步: 打包与发布

​探索更多

第 1 步: 创建目录结构

第 2 步: 定义模型配置 (YAML)

第 3 步: 编写模型调用代码 (Python)

第 4 步: 调试插件

第 5 步: 打包与发布

探索更多