实现标准的模型集成

本文档是为需要通过编写 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 步: 打包与发布

探索更多