> ## Documentation Index
> Fetch the complete documentation index at: https://alterxyz-a56768d7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 实现标准的模型集成

> 本文档面向需要编写Python代码以添加或增强Dify模型支持的开发者，详细指导如何创建目录结构、编写模型配置、实现模型调用逻辑、调试和发布插件的完整流程，包含了核心方法实现和错误处理的细节。

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

**阅读本文前，建议你：**

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

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

***

## 第 1 步: 创建目录结构

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

1. **定位或创建供应商目录:** 在你的插件项目（通常是 `dify-official-plugins` 的本地克隆）的 `models/` 目录下，找到或创建以模型供应商命名的文件夹（例如 `models/my_new_provider`）。
2. **创建 `models` 子目录:** 在供应商目录下，创建 `models` 子目录。
3. **按模型类型创建子目录:** 在 `models/models/` 目录下，为你需要支持的**每种模型类型**创建一个子目录。常见的类型包括：
   * `llm`: 文本生成模型
   * `text_embedding`: 文本 Embedding 模型
   * `rerank`: Rerank 模型
   * `speech2text`: 语音转文字模型
   * `tts`: 文字转语音模型
   * `moderation`: 内容审查模型
4. **准备实现文件:**
   * 在每个模型类型目录下（例如 `models/models/llm/`），你需要创建一个 Python 文件来实现该类型模型的调用逻辑（例如 `llm.py`）。
   * 同样在该目录下，你需要为该类型下的每个具体模型创建一个 YAML 配置文件（例如 `my-model-v1.yaml`）。
   * （可选）可以创建一个 `_position.yaml` 文件来控制该类型下模型在 Dify UI 中的显示顺序。

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

```bash
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 能够正确地理解和使用它。

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

```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 调用、参数转换和结果返回。

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

2. **定义实现类:**

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

   ```python
   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):
       # ... 实现方法 ...
   ```

3. **实现关键方法:** (具体需要实现的方法取决于继承的基类，以下以 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`)。
     * **实现模式:** 强烈建议将同步和流式逻辑拆分到内部帮助方法中。

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

     ```python
     @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 实例中测试效果。

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

2. **配置本地环境:**
   * 在你的本地插件项目**根目录**下，找到或创建 `.env` 文件 (可从 `.env.example` 复制)。
   * 编辑 `.env` 文件，填入调试信息：

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

3. **启动本地插件服务:**
   * 在插件项目根目录下，确保你的 Python 环境已激活（如果使用虚拟环境）。

   * 运行主程序：

     ```bash
     python -m main
     ```

   * 观察终端输出，如果连接成功，通常会有相应的日志提示。

4. **在 Dify 中测试:**
   * 刷新 Dify 的 "插件" 或 "模型供应商" 页面，你应该能看到你的本地插件实例，可能带有 "调试中" 标识。
   * 前往 "设置" -> "模型供应商"，找到你的插件，配置有效的 API 凭证。
   * 在 Dify 应用中选择并使用你的模型进行测试。你在本地对 Python 代码的修改（保存后通常会自动重新加载服务）会直接影响 Dify 中的调用行为。使用 Dify 的调试预览功能可以帮助你检查输入输出和错误信息。

***

## 第 5 步: 打包与发布

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

1. **打包插件:**
   * 停止本地调试服务 (`Ctrl+C`)。

   * 在插件项目**根目录**下运行打包命令：

     ```bash
     # 将 <provider_name> 替换为你的供应商目录名
     dify plugin package models/<provider_name>
     ```

   * 这将在项目根目录下生成一个 `<provider_name>.difypkg` 文件。
2. **提交 Pull Request:**
   * 确保你的代码风格良好，并遵循 Dify 的[插件发布规范](https://docs.dify.ai/zh-hans/plugins/publish-plugins/publish-to-dify-marketplace)。
   * 将你的本地 Git 提交推送到你 Fork 的 `dify-official-plugins` 仓库。
   * 在 GitHub 上向 `langgenius/dify-official-plugins` 主仓库发起 Pull Request。在 PR 描述中清晰说明你所做的更改、添加的模型或功能，以及任何必要的测试说明。
   * 等待 Dify 团队审核。审核通过并合并后，你的贡献将包含在官方插件中，并在 [Dify Marketplace](https://marketplace.dify.ai/) 上可用。

***

## 探索更多

* [模型 Schema 定义](https://alterxyz-a56768d7.mintlify.site/plugin_dev_zh/0412-model-schema.zh.md) (模型 YAML 规范)
* [插件 Manifest 结构](https://alterxyz-a56768d7.mintlify.site/plugin_dev_zh/0411-general-specifications.zh.md) (`manifest.yaml` 规范)
* [Dify Plugin SDK 参考](https://github.com/langgenius/dify-plugin-sdks) (查找基类、数据结构和错误类型)
* [Dify 官方插件仓库](https://github.com/langgenius/dify-official-plugins) (查看现有插件的实现)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.