モデルインターフェース

ここでは、プロバイダーと各モデルタイプが実装する必要のあるインターフェースメソッドとパラメータについて説明します。モデルプラグインを開発する前に、まずモデル設計ルールとモデルプラグイン紹介を読むことをお勧めします。

モデルプロバイダー

__base.model_provider.ModelProvider ベースクラスを継承し、以下のインターフェースを実装します：

def validate_provider_credentials(self, credentials: dict) -> None:
    """
    プロバイダーのクレデンシャルを検証します
    モデルタイプの任意の validate_credentials メソッドを選択するか、自分で検証メソッドを実装することができます（例：モデルリスト取得API）。

    検証に失敗した場合は、例外を発生させます

    :param credentials: プロバイダーのクレデンシャル。クレデンシャルの形式は `provider_credential_schema` で定義されます。
    """

credentials (object) クレデンシャル情報

クレデンシャル情報のパラメータは、プロバイダーのYAML設定ファイルの provider_credential_schema で定義され、api_key などが渡されます。検証に失敗した場合は、errors.validate.CredentialsValidateFailedError エラーをスローしてください。注：事前定義モデルはこのインターフェースを完全に実装する必要がありますが、カスタムモデルプロバイダーは以下のように簡単な実装で済みます：

class XinferenceProvider(Provider):
    def validate_provider_credentials(self, credentials: dict) -> None:
        pass

モデル

モデルは5つの異なるモデルタイプに分かれ、モデルタイプごとに継承するベースクラスや実装が必要なメソッドも異なります。

共通インターフェース

すべてのモデルは、以下の2つのメソッドを共通して実装する必要があります：

モデルクレデンシャルの検証

プロバイダーのクレデンシャル検証と同様に、ここでは個別のモデルに対して検証を行います。

def validate_credentials(self, model: str, credentials: dict) -> None:
    """
    モデルのクレデンシャルを検証します

    :param model: モデル名
    :param credentials: モデルのクレデンシャル
    :return:
    """

パラメータ：

model (string) モデル名
credentials (object) クレデンシャル情報

クレデンシャル情報のパラメータは、プロバイダーのYAML設定ファイルの provider_credential_schema または model_credential_schema で定義され、api_key などが渡されます。検証に失敗した場合は、errors.validate.CredentialsValidateFailedError エラーをスローしてください。

呼び出し例外エラーマッピングテーブル

モデル呼び出し時に例外が発生した場合、Runtime が指定する InvokeError タイプにマッピングする必要があります。これにより、Dify は異なるエラーに対して異なる後続処理を行うことができます。Runtime Errors:

InvokeConnectionError 呼び出し接続エラー
InvokeServerUnavailableError 呼び出し先サーバー利用不可
InvokeRateLimitError 呼び出しレート制限超過
InvokeAuthorizationError 呼び出し認証失敗
InvokeBadRequestError 呼び出しパラメータ不正

@property
def _invoke_error_mapping(self) -> dict[type[InvokeError], list[type[Exception]]]:
    """
    モデルの呼び出しエラーを統一エラーにマッピングします
    キーは呼び出し元にスローされるエラータイプです
    値はモデルによってスローされるエラータイプであり、呼び出し元のために統一エラータイプに変換する必要があります。

    :return: 呼び出しエラーマッピング
    """

対応するエラーを直接スローし、以下のように定義することも可能です。これにより、その後の呼び出しで InvokeConnectionError などの例外を直接スローできます。

LLM

__base.large_language_model.LargeLanguageModel ベースクラスを継承し、以下のインターフェースを実装します：

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]:
    """
    大規模言語モデルを呼び出します

    :param model: モデル名
    :param credentials: モデルのクレデンシャル
    :param prompt_messages: プロンプトメッセージ
    :param model_parameters: モデルパラメータ
    :param tools: ツール呼び出し用のツール
    :param stop: ストップワード
    :param stream: ストリーム応答かどうか
    :param user: 一意のユーザーID
    :return: 完全な応答またはストリーム応答チャンクジェネレータの結果
    """

パラメータ：
- model (string) モデル名
- credentials (object) クレデンシャル情報

クレデンシャル情報のパラメータは、プロバイダーのYAML設定ファイルの provider_credential_schema または model_credential_schema で定義され、api_key などが渡されます。

prompt_messages (array[PromptMessage]) プロンプトリスト

モデルが Completion タイプの場合、リストには UserPromptMessage 要素を1つ渡すだけで十分です。モデルが Chat タイプの場合、メッセージに応じて SystemPromptMessage、UserPromptMessage、AssistantPromptMessage、ToolPromptMessage 要素のリストを渡す必要があります。

model_parameters (object) モデルパラメータ。モデルパラメータはモデルのYAML設定の parameter_rules で定義されます。
tools (array[PromptMessageTool]) [optional] ツールリスト。function calling における function と同等です。つまり、tool calling に渡すツールリストです。
stop (array[string]) [optional] ストップシーケンス。モデルの返却は、ストップシーケンスで定義された文字列の直前で停止します。
stream (bool) ストリーミング出力かどうか、デフォルトは True。ストリーミング出力は Generator[LLMResultChunk] を返し、非ストリーミング出力は LLMResult を返します。
user (string) [optional] ユーザーの一意の識別子。プロバイダーが不正利用を監視および検出するのに役立ちます。
返り値

ストリーミング出力は Generator[LLMResultChunk] を返し、非ストリーミング出力は LLMResult を返します。

入力トークンの事前計算

モデルがトークン事前計算インターフェースを提供していない場合、直接 0 を返すことができます。

def get_num_tokens(self, model: str, credentials: dict, prompt_messages: list[PromptMessage],
                   tools: Optional[list[PromptMessageTool]] = None) -> int:
    """
    指定されたプロンプトメッセージのトークン数を取得します

    :param model: モデル名
    :param credentials: モデルのクレデンシャル
    :param prompt_messages: プロンプトメッセージ
    :param tools: ツール呼び出し用のツール
    :return:
    """

パラメータの説明は上記の LLM 呼び出し を参照してください。このインターフェースは、対応する model に基づいて適切な tokenizer を選択して計算する必要があります。対応するモデルが tokenizer を提供していない場合は、AIModel ベースクラスの _get_num_tokens_by_gpt2(text: str) メソッドを使用して計算できます。

カスタムモデルルールの取得 [オプション]

def get_customizable_model_schema(self, model: str, credentials: dict) -> Optional[AIModelEntity]:
    """
    カスタマイズ可能なモデルスキーマを取得します

    :param model: モデル名
    :param credentials: モデルのクレデンシャル
    :return: モデルスキーマ
    """

プロバイダーがカスタムLLMの追加をサポートしている場合、このメソッドを実装することで、カスタムモデルがモデルルールを取得できるようになります。デフォルトでは None を返します。

OpenAI プロバイダーのほとんどのファインチューニングモデルでは、ファインチューニングモデル名（例：gpt-3.5-turbo-1106）からベースモデルを取得し、そのベースモデルの事前定義パラメータルールを返すことができます。OpenAI の具体的な実装を参照してください。

TextEmbedding

__base.text_embedding_model.TextEmbeddingModel ベースクラスを継承し、以下のインターフェースを実装します：

Embedding 呼び出し

def _invoke(self, model: str, credentials: dict,
            texts: list[str], user: Optional[str] = None) \
        -> TextEmbeddingResult:
    """
    テキスト埋め込みモデルを呼び出します

    :param model: モデル名
    :param credentials: モデルのクレデンシャル
    :param texts: 埋め込むテキスト
    :param user: 一意のユーザーID
    :return: 埋め込み結果
    """

パラメータ：
model (string) モデル名
credentials (object) クレデンシャル情報

texts (array[string]) テキストリスト、バッチ処理可能
user (string) [optional] ユーザーの一意の識別子。プロバイダーが不正利用を監視および検出するのに役立ちます。
返り値：

TextEmbeddingResult エンティティ。

トークンの事前計算

def get_num_tokens(self, model: str, credentials: dict, texts: list[str]) -> int:
    """
    指定されたテキストのトークン数を取得します

    :param model: モデル名
    :param credentials: モデルのクレデンシャル
    :param texts: 埋め込むテキスト
    :return:
    """

パラメータの説明は上記の Embedding 呼び出し を参照してください。

上記の LargeLanguageModel と同様に、このインターフェースは対応する model に基づいて適切な tokenizer を選択して計算する必要があります。対応するモデルが tokenizer を提供していない場合は、AIModel ベースクラスの _get_num_tokens_by_gpt2(text: str) メソッドを使用して計算できます。

Rerank

__base.rerank_model.RerankModel ベースクラスを継承し、以下のインターフェースを実装します：

rerank 呼び出し

def _invoke(self, model: str, credentials: dict,
            query: str, docs: list[str], score_threshold: Optional[float] = None, top_n: Optional[int] = None,
            user: Optional[str] = None) \
        -> RerankResult:
    """
    Rerankモデルを呼び出します

    :param model: モデル名
    :param credentials: モデルのクレデンシャル
    :param query: 検索クエリ
    :param docs: リランキング対象のドキュメント
    :param score_threshold: スコアのしきい値
    :param top_n: 上位n件
    :param user: 一意のユーザーID
    :return: リランキング結果
    """

パラメータ：
model (string) モデル名
credentials (object) クレデンシャル情報クレデンシャル情報のパラメータは、プロバイダーのYAML設定ファイルの provider_credential_schema または model_credential_schema で定義され、api_key などが渡されます。
query (string) クエリリクエストの内容
docs (array[string]) リランキングが必要なドキュメント（チャンク）のリスト
score_threshold (float) [optional] スコアのしきい値
top_n (int) [optional] 上位n個のドキュメント（チャンク）を取得
user (string) [optional] ユーザーの一意の識別子。プロバイダーが不正利用を監視および検出するのに役立ちます。
返り値：

RerankResult エンティティ。

Speech2text

__base.speech2text_model.Speech2TextModel ベースクラスを継承し、以下のインターフェースを実装します：

Invoke 呼び出し

def _invoke(self, model: str, credentials: dict,
            file: IO[bytes], user: Optional[str] = None) \
        -> str:
    """
    音声テキスト変換モデルを呼び出します

    :param model: モデル名
    :param credentials: モデルのクレデンシャル
    :param file: 音声ファイル
    :param user: 一意のユーザーID
    :return: 指定された音声ファイルに対するテキスト
    """

パラメータ：
model (string) モデル名
credentials (object) クレデンシャル情報クレデンシャル情報のパラメータは、プロバイダーのYAML設定ファイルの provider_credential_schema または model_credential_schema で定義され、api_key などが渡されます。
file (File) ファイルストリーム
user (string) [optional] ユーザーの一意の識別子。プロバイダーが不正利用を監視および検出するのに役立ちます。
返り値：

音声変換された文字列。

Text2speech

__base.text2speech_model.Text2SpeechModel ベースクラスを継承し、以下のインターフェースを実装します：

Invoke 呼び出し

def _invoke(self, model: str, credentials: dict, content_text: str, streaming: bool, user: Optional[str] = None):
    """
    大規模言語モデルを呼び出します

    :param model: モデル名
    :param credentials: モデルの認証情報
    :param content_text: 変換するテキストコンテンツ
    :param streaming: 出力がストリーミングであるか
    :param user: 一意のユーザーID
    :return: 変換された音声ファイル
    """

パラメータ：
model (string) モデル名
credentials (object) 認証情報認証情報のパラメータは、プロバイダーのYAML設定ファイルの provider_credential_schema または model_credential_schema で定義され、api_key などが渡されます。
content_text (string) 変換が必要なテキストコンテンツ
streaming (bool) ストリーミング出力を行うかどうか
user (string) [optional] ユーザーの一意の識別子プロバイダーが不正利用を監視および検出するのに役立ちます。
戻り値：

テキスト変換後の音声ストリーム。

Moderation

__base.moderation_model.ModerationModel ベースクラスを継承し、以下のインターフェースを実装します：

Invoke 呼び出し

def _invoke(self, model: str, credentials: dict,
            text: str, user: Optional[str] = None) \
        -> bool:
    """
    大規模言語モデルを呼び出します

    :param model: モデル名
    :param credentials: モデルの認証情報
    :param text: モデレーションするテキスト
    :param user: 一意のユーザーID
    :return: テキストが安全な場合はfalse、それ以外の場合はtrue
    """

パラメータ：
model (string) モデル名
credentials (object) 認証情報認証情報のパラメータは、プロバイダーのYAML設定ファイルの provider_credential_schema または model_credential_schema で定義され、api_key などが渡されます。
text (string) テキストコンテンツ
user (string) [optional] ユーザーの一意の識別子プロバイダーが不正利用を監視および検出するのに役立ちます。
戻り値：

Falseは渡されたテキストが安全であることを示し、Trueはその逆を示します。

エンティティ

PromptMessageRole

メッセージロール

class PromptMessageRole(Enum):
    """
    プロンプトメッセージのEnumクラス。
    """
    SYSTEM = "system"
    USER = "user"
    ASSISTANT = "assistant"
    TOOL = "tool"

PromptMessageContentType

メッセージコンテントタイプ。プレーンテキストと画像に分かれます。

class PromptMessageContentType(Enum):
    """
    プロンプトメッセージコンテントタイプのEnumクラス。
    """
    TEXT = 'text'
    IMAGE = 'image'

PromptMessageContent

メッセージコンテントのベースクラス。パラメータ宣言専用であり、初期化できません。

class PromptMessageContent(BaseModel):
    """
    プロンプトメッセージコンテントのモデルクラス。
    """
    type: PromptMessageContentType
    data: str  # コンテンツデータ

現在、テキストと画像の2つのタイプをサポートしており、テキストと複数の画像を同時に渡すことができます。それぞれ TextPromptMessageContent と ImagePromptMessageContent を初期化して渡す必要があります。

TextPromptMessageContent

class TextPromptMessageContent(PromptMessageContent):
    """
    テキストプロンプトメッセージコンテントのモデルクラス。
    """
    type: PromptMessageContentType = PromptMessageContentType.TEXT

画像とテキストを渡す場合、その中のテキストはこのエンティティを content リストの一部として構築する必要があります。

ImagePromptMessageContent

class ImagePromptMessageContent(PromptMessageContent):
    """
    画像プロンプトメッセージコンテントのモデルクラス。
    """
    class DETAIL(Enum):
        LOW = 'low'
        HIGH = 'high'

    type: PromptMessageContentType = PromptMessageContentType.IMAGE
    detail: DETAIL = DETAIL.LOW  # 解像度

画像とテキストを渡す場合、その中の画像はこのエンティティを content リストの一部として構築する必要があります。 data は url または画像の base64 エンコードされた文字列です。

PromptMessage

すべてのRoleメッセージボディのベースクラス。パラメータ宣言専用であり、初期化できません。

class PromptMessage(ABC, BaseModel):
    """
    プロンプトメッセージのモデルクラス。
    """
    role: PromptMessageRole  # メッセージロール
    content: Optional[str | list[PromptMessageContent]] = None  # 文字列とコンテントリストの2つのタイプをサポートします。コンテントリストはマルチモーダルのニーズを満たすためのもので、詳細は `PromptMessageContent` の説明を参照してください。
    name: Optional[str] = None  # 名称、オプション。

UserPromptMessage

UserMessageメッセージボディ。ユーザーメッセージを表します。

class UserPromptMessage(PromptMessage):
    """
    ユーザープロンプトメッセージのモデルクラス。
    """
    role: PromptMessageRole = PromptMessageRole.USER

AssistantPromptMessage

モデルの返信メッセージを表します。通常、few-shots またはチャット履歴の入力に使用されます。

class AssistantPromptMessage(PromptMessage):
    """
    アシスタントプロンプトメッセージのモデルクラス。
    """
    class ToolCall(BaseModel):
        """
        アシスタントプロンプトメッセージツールコールのモデルクラス。
        """
        class ToolCallFunction(BaseModel):
            """
            アシスタントプロンプトメッセージツールコール関数のモデルクラス。
            """
            name: str  # ツール名
            arguments: str  # ツールパラメータ

        id: str  # ツールID。OpenAI の tool call のみで有効で、ツールの呼び出しの一意のIDです。同じツールを複数回呼び出すことができます。
        type: str  # デフォルトは function
        function: ToolCallFunction  # ツール呼び出し情報

    role: PromptMessageRole = PromptMessageRole.ASSISTANT
    tool_calls: list[ToolCall] = []  # モデルが応答したツール呼び出し結果（tools が渡され、かつモデルがツールの呼び出しが必要だと判断した場合にのみ返されます）

この tool_calls は、モデルを呼び出す際に tools を渡した後、モデルから返される tool call のリストです。

SystemPromptMessage

システムメッセージを表します。通常、モデルに設定するシステム指示に使用されます。

class SystemPromptMessage(PromptMessage):
    """
    システムプロンプトメッセージのモデルクラス。
    """
    role: PromptMessageRole = PromptMessageRole.SYSTEM

ToolPromptMessage

ツールメッセージを表します。ツールの実行後に結果をモデルに渡し、次のステップを計画するために使用されます。

class ToolPromptMessage(PromptMessage):
    """
    ツールプロンプトメッセージのモデルクラス。
    """
    role: PromptMessageRole = PromptMessageRole.TOOL
    tool_call_id: str  # ツール呼び出しID。OpenAI tool call をサポートしていない場合、ツール名を渡すこともできます。

ベースクラスの content にツールの実行結果を渡します。

PromptMessageTool

class PromptMessageTool(BaseModel):
    """
    プロンプトメッセージツールのモデルクラス。
    """
    name: str  # ツール名
    description: str  # ツールの説明
    parameters: dict  # ツールパラメータのdict

LLMResult

class LLMResult(BaseModel):
    """
    LLM結果のモデルクラス。
    """
    model: str  # 実際に使用されたモデル
    prompt_messages: list[PromptMessage]  # プロンプトメッセージのリスト
    message: AssistantPromptMessage  # 返信メッセージ
    usage: LLMUsage  # 使用されたトークンおよび料金情報
    system_fingerprint: Optional[str] = None  # リクエストフィンガープリント。OpenAI の当該パラメータ定義を参照できます。

LLMResultChunkDelta

ストリーミングレスポンスにおける各イテレーション内部の delta エンティティ

class LLMResultChunkDelta(BaseModel):
    """
    LLM結果チャンクデルタのモデルクラス。
    """
    index: int  # シーケンス番号
    message: AssistantPromptMessage  # 返信メッセージ
    usage: Optional[LLMUsage] = None  # 使用されたトークンおよび料金情報。最後のメッセージでのみ返されます。
    finish_reason: Optional[str] = None  # 終了理由。最後のメッセージでのみ返されます。

LLMResultChunk

ストリーミングレスポンスにおける各イテレーションのエンティティ

class LLMResultChunk(BaseModel):
    """
    LLM結果チャンクのモデルクラス。
    """
    model: str  # 実際に使用されたモデル
    prompt_messages: list[PromptMessage]  # プロンプトメッセージのリスト
    system_fingerprint: Optional[str] = None  # リクエストフィンガープリント。OpenAI の当該パラメータ定義を参照できます。
    delta: LLMResultChunkDelta  # 各イテレーションで変化のある内容

LLMUsage

class LLMUsage(ModelUsage):
    """
    LLM使用量のモデルクラス。
    """
    prompt_tokens: int  # プロンプト使用トークン数
    prompt_unit_price: Decimal  # プロンプト単価
    prompt_price_unit: Decimal  # プロンプト価格単位（単価が何トークンに基づいているか）
    prompt_price: Decimal  # プロンプト料金
    completion_tokens: int  # 返信使用トークン数
    completion_unit_price: Decimal  # 返信単価
    completion_price_unit: Decimal  # 返信価格単位（単価が何トークンに基づいているか）
    completion_price: Decimal  # 返信料金
    total_tokens: int  # 総使用トークン数
    total_price: Decimal  # 総料金
    currency: str  # 通貨単位
    latency: float  # リクエスト遅延(秒)

TextEmbeddingResult

class TextEmbeddingResult(BaseModel):
    """
    テキスト埋め込み結果のモデルクラス。
    """
    model: str  # 実際に使用されたモデル
    embeddings: list[list[float]]  # embeddingベクトルリスト。渡された texts リストに対応します。
    usage: EmbeddingUsage  # 使用情報

EmbeddingUsage

class EmbeddingUsage(ModelUsage):
    """
    埋め込み使用量のモデルクラス。
    """
    tokens: int  # 使用トークン数
    total_tokens: int  # 総使用トークン数
    unit_price: Decimal  # 単価
    price_unit: Decimal  # 価格単位（単価が何トークンに基づいているか）
    total_price: Decimal  # 総料金
    currency: str  # 通貨単位
    latency: float  # リクエスト遅延(秒)

RerankResult

class RerankResult(BaseModel):
    """
    Rerank結果のモデルクラス。
    """
    model: str  # 実際に使用されたモデル
    docs: list[RerankDocument]  # リランキング後のドキュメントリスト

RerankDocument

class RerankDocument(BaseModel):
    """
    Rerankドキュメントのモデルクラス。
    """
    index: int  # 元のシーケンス番号
    text: str  # ドキュメントのテキスト内容
    score: float  # スコア

概念と概要

開発実践

貢献と公開

実践例とユースケース

高度な開発

リファレンスと仕様

ドキュメントについて

モデルインターフェース

モデルプロバイダー

モデル

共通インターフェース

LLM

TextEmbedding

Rerank

Speech2text

Text2speech

Moderation

エンティティ

PromptMessageRole

PromptMessageContentType

PromptMessageContent

TextPromptMessageContent

ImagePromptMessageContent

PromptMessage

UserPromptMessage

AssistantPromptMessage

SystemPromptMessage

ToolPromptMessage

PromptMessageTool

LLMResult

LLMResultChunkDelta

LLMResultChunk

LLMUsage

TextEmbeddingResult

EmbeddingUsage

RerankResult

RerankDocument

関連リソース

概念と概要

開発実践

貢献と公開

実践例とユースケース

高度な開発

リファレンスと仕様

ドキュメントについて

​モデルプロバイダー

​モデル

​共通インターフェース

​LLM

​TextEmbedding

​Rerank

​Speech2text

​Text2speech

​Moderation

​エンティティ

​PromptMessageRole

​PromptMessageContentType

​PromptMessageContent

​TextPromptMessageContent

​ImagePromptMessageContent

​PromptMessage

​UserPromptMessage

​AssistantPromptMessage

​SystemPromptMessage

​ToolPromptMessage

​PromptMessageTool

​LLMResult

​LLMResultChunkDelta

​LLMResultChunk

​LLMUsage

​TextEmbeddingResult

​EmbeddingUsage

​RerankResult

​RerankDocument

​関連リソース

モデルプロバイダー

モデル

共通インターフェース

LLM

TextEmbedding

Rerank

Speech2text

Text2speech

Moderation

エンティティ

PromptMessageRole

PromptMessageContentType

PromptMessageContent

TextPromptMessageContent

ImagePromptMessageContent

PromptMessage

UserPromptMessage

AssistantPromptMessage

SystemPromptMessage

ToolPromptMessage

PromptMessageTool

LLMResult

LLMResultChunkDelta

LLMResultChunk

LLMUsage

TextEmbeddingResult

EmbeddingUsage

RerankResult

RerankDocument

関連リソース