カスタムモデルの統合

Xinference を例に、カスタムモデルを Dify に統合する

このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、英語版 を参照してください。

カスタムモデル とは、自分でデプロイまたは設定する LLM を指します。このガイドでは、Xinference を例に、カスタムモデルを モデルプラグイン に統合する方法を説明します。

デフォルトでは、カスタムモデルは モデルタイプ と モデル名 の 2 つのパラメータを自動的に含むため、プロバイダー YAML ファイルで追加の定義は必要ありません。

プロバイダー設定ファイルに validate_provider_credential を実装する必要はありません。実行時、Dify はユーザーが選択したモデルタイプとモデル名に基づいて、対応するモデルレイヤーの validate_credentials メソッドを呼び出します。

カスタムモデルプラグインの統合

カスタムモデルの統合は 4 つのステップに分かれます。

1. モデルプロバイダーファイルの作成：カスタムモデルに含めるモデルタイプを特定します。
2. モデルタイプごとのコードファイルの作成：モデルタイプ（例：llm や text_embedding）ごとに別々のコードファイルを作成します。各モデルタイプをそれぞれの論理レイヤーに保つことで、保守と今後の拡張が容易になります。
3. モデル呼び出しロジックの開発：各モデルタイプモジュール内で、そのモデルタイプの名前を付けた Python ファイル（例：llm.py）を作成します。ファイル内に、システムのモデルインターフェース仕様に準拠したモデルロジックを実装するクラスを定義します。
4. プラグインのデバッグ：新しいプロバイダー機能のユニットテストと統合テストを作成し、すべてのコンポーネントが意図どおりに動作することを確認します。

1. モデルプロバイダーファイルの作成

プラグインの /provider ディレクトリに、xinference.yaml ファイルを作成します。

Xinference ファミリーのモデルは LLM、Text Embedding、Rerank モデルタイプをサポートしているため、xinference.yaml にはこれら 3 つすべてを含める必要があります。

例：

provider: xinference  # Identifies the provider
label:                # Display name; can set both en_US (English) and zh_Hans (Chinese). If zh_Hans is not set, en_US is used by default.
  en_US: Xorbits Inference
icon_small:           # Small icon; store in the _assets folder of this provider's directory. The same multi-language logic applies as with label.
  en_US: icon_s_en.svg
icon_large:           # Large icon
  en_US: icon_l_en.svg
help:                 # Help information
  title:
    en_US: How to deploy Xinference
    zh_Hans: 如何部署 Xinference
  url:
    en_US: https://github.com/xorbitsai/inference

supported_model_types:  # Model types Xinference supports: LLM/Text Embedding/Rerank
- llm
- text-embedding
- rerank

configurate_methods:     # Xinference is locally deployed and does not offer predefined models. Refer to its documentation to learn which model to use. Thus, we choose a customizable-model approach.
- customizable-model

provider_credential_schema:
  credential_form_schemas:

次に、provider_credential_schema を定義します。Xinference はテキスト生成、エンベディング、リランキングモデルをサポートしているため、以下のように設定できます。

provider_credential_schema:
  credential_form_schemas:
  - variable: model_type
    type: select
    label:
      en_US: Model type
      zh_Hans: 模型类型
    required: true
    options:
    - value: text-generation
      label:
        en_US: Language Model
        zh_Hans: 语言模型
    - value: embeddings
      label:
        en_US: Text Embedding
    - value: reranking
      label:
        en_US: Rerank

Xinference のすべてのモデルには model_name が必要です。

  - variable: model_name
    type: text-input
    label:
      en_US: Model name
      zh_Hans: 模型名称
    required: true
    placeholder:
      zh_Hans: 填写模型名称
      en_US: Input model name

Xinference はローカルでデプロイされるため、ユーザーはサーバーアドレス（server_url）とモデル UID も指定する必要があります。

  - variable: server_url
    label:
      zh_Hans: 服务器 URL
      en_US: Server url
    type: text-input
    required: true
    placeholder:
      zh_Hans: 在此输入 Xinference 的服务器地址，如 https://example.com/xxx
      en_US: Enter the url of your Xinference, for example https://example.com/xxx

  - variable: model_uid
    label:
      zh_Hans: 模型 UID
      en_US: Model uid
    type: text-input
    required: true
    placeholder:
      zh_Hans: 在此输入你的 Model UID
      en_US: Enter the model uid

これでカスタムモデルプロバイダーの YAML 設定は完了です。次に、設定で定義した各モデルのコードファイルを作成します。

2. モデルコードの開発

Xinference は llm、rerank、speech2text、tts をサポートしているため、/models 下に各タイプのディレクトリを作成し、それぞれに機能コードを含めます。

以下は llm タイプのモデルの例です。llm.py という名前のファイルを作成し、__base.large_language_model.LargeLanguageModel を拡張するクラス（例：XinferenceAILargeLanguageModel）を定義します。このクラスは以下のメソッドを実装する必要があります。

LLM 呼び出し

LLM を呼び出すためのコアメソッドで、ストリーミングと同期応答の両方をサポートします。

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]:
    """
    Invoke the large language model.

    :param model: model name
    :param credentials: model credentials
    :param prompt_messages: prompt messages
    :param model_parameters: model parameters
    :param tools: tools for tool calling
    :param stop: stop words
    :param stream: determines if response is streamed
    :param user: unique user id
    :return: full response or a chunk generator
    """

ストリーミングと同期応答は、それぞれ別々の関数として実装します。Python は yield を含む関数を Generator を返すジェネレータとして扱うため、分離することで戻り値の型が明確になります。

def _invoke(self, stream: bool, **kwargs) -> Union[LLMResult, Generator]:
    if stream:
        return self._handle_stream_response(**kwargs)
    return self._handle_sync_response(**kwargs)

def _handle_stream_response(self, **kwargs) -> Generator:
    for chunk in response:
        yield chunk

def _handle_sync_response(self, **kwargs) -> LLMResult:
    return LLMResult(**response)

入力 token の事前計算

モデルが token カウントインターフェースを提供していない場合は、0 を返します。

def get_num_tokens(
    self,
    model: str,
    credentials: dict,
    prompt_messages: list[PromptMessage],
    tools: Optional[list[PromptMessageTool]] = None
) -> int:
    """
    Get the number of tokens for the given prompt messages.
    """
    return 0

または、AIModel 基底クラスから self._get_num_tokens_by_gpt2(text: str) を呼び出すこともできます。これは GPT-2 トークナイザーを使用します。これは近似値であり、モデルと正確に一致しない場合がある点に注意してください。

モデル認証情報の検証

プロバイダーレベルの認証情報チェックと似ていますが、対象は単一のモデルに限定されます。

def validate_credentials(self, model: str, credentials: dict) -> None:
    """
    Validate model credentials.
    """

動的モデルパラメータスキーマ

事前定義モデル とは異なり、モデルがサポートするパラメータを定義する YAML ファイルはないため、パラメータスキーマを動的に生成する必要があります。

例えば、Xinference は max_tokens、temperature、top_p をサポートしています。他のプロバイダー（例：OpenLLM）は、特定のモデルでのみ top_k などのパラメータをサポートする場合があるため、スキーマは各モデルの機能に合わせて適応させる必要があります。

def get_customizable_model_schema(self, model: str, credentials: dict) -> AIModelEntity | None:
    """
        used to define customizable model schema
    """
    rules = [
        ParameterRule(
            name='temperature', type=ParameterType.FLOAT,
            use_template='temperature',
            label=I18nObject(
                zh_Hans='温度', en_US='Temperature'
            )
        ),
        ParameterRule(
            name='top_p', type=ParameterType.FLOAT,
            use_template='top_p',
            label=I18nObject(
                zh_Hans='Top P', en_US='Top P'
            )
        ),
        ParameterRule(
            name='max_tokens', type=ParameterType.INT,
            use_template='max_tokens',
            min=1,
            default=512,
            label=I18nObject(
                zh_Hans='最大生成长度', en_US='Max Tokens'
            )
        )
    ]

    # if model is A, add top_k to rules
    if model == 'A':
        rules.append(
            ParameterRule(
                name='top_k', type=ParameterType.INT,
                use_template='top_k',
                min=1,
                default=50,
                label=I18nObject(
                    zh_Hans='Top K', en_US='Top K'
                )
            )
        )

    # ... additional ParameterRule entries omitted for brevity ...

    entity = AIModelEntity(
        model=model,
        label=I18nObject(
            en_US=model
        ),
        fetch_from=FetchFrom.CUSTOMIZABLE_MODEL,
        model_type=model_type,
        model_properties={ 
            ModelPropertyKey.MODE:  ModelType.LLM,
        },
        parameter_rules=rules
    )

    return entity

エラーマッピング

モデル呼び出し中にエラーが発生した場合、ランタイムの InvokeError タイプのいずれかにマッピングすることで、Dify が異なるエラーを統一的に処理できるようにします。

• InvokeConnectionError
• InvokeServerUnavailableError
• InvokeRateLimitError
• InvokeAuthorizationError
• InvokeBadRequestError

@property
def _invoke_error_mapping(self) -> dict[type[InvokeError], list[type[Exception]]]:
    """
    Map model invocation errors to unified error types.
    The key is the error type thrown to the caller.
    The value is the error type thrown by the model, which needs to be mapped to a
    unified Dify error for consistent handling.
    """
    # return {
    #   InvokeConnectionError: [requests.exceptions.ConnectionError],
    #   ...
    # }

インターフェースメソッドの詳細については、モデルドキュメント を参照してください。

このガイドで説明した完全なコードファイルは、GitHub リポジトリ を参照してください。

3. プラグインのデバッグ

開発が完了したら、プラグインをテストして正しく動作することを確認します。詳細は以下を参照してください。

プラグインのデバッグ

4. プラグインの公開

プラグインを Dify マーケットプレイスに掲載するには、「Dify マーケットプレイスへの公開」を参照してください。

さらに探索

クイックスタート：

• 拡張プラグインの開発
• ツールプラグインの開発
• バンドルプラグイン：複数のプラグインをパッケージ化

プラグインエンドポイントドキュメント：

• マニフェスト 構造
• エンドポイント 定義
• Dify サービスの逆呼び出し
• ツール
• モデル