カスタムモデルの統合

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

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

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

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

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

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

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

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

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

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

例：

provider: xinference  # Identifies the providerlabel:                # 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 Inferenceicon_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.svgicon_large:           # Large icon  en_US: icon_l_en.svghelp:                 # Help information  title:    en_US: How to deploy Xinference    zh_Hans: 如何部署 Xinference  url:    en_US: https://github.com/xorbitsai/inferencesupported_model_types:  # Model types Xinference supports: LLM/Text Embedding/Rerank- llm- text-embedding- rerankconfigurate_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-modelprovider_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 chunkdef _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

@propertydef _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 マーケットプレイスへの公開」を参照してください。

さらに探索#

クイックスタート：

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