インターフェース方法

​

サプライヤー

def validate_provider_credentials(self, credentials: dict) -> None:
    """
    Validate provider credentials
    You can choose any validate_credentials method of model type or implement validate method by yourself,
    such as: get model list api

    if validate failed, raise exception

    :param credentials: provider credentials, credentials form defined in `provider_credential_schema`.
    """

• credentials (object) 資格情報 資格情報のパラメータは、サプライヤーのYAML構成ファイルの provider_credential_schema で定義され、api_keyなどが渡されます。

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

​

モデル

​

一般インターフェース

• モデルの認証情報を検証する サプライヤーの認証情報検証と同様に、ここでは個々のモデルに対して検証を行います。
  Copy

  def validate_credentials(self, model: str, credentials: dict) -> None:
      """
      Validate model credentials
  
      :param model: model name
      :param credentials: model 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 コールがRate Limitに達しました
  • InvokeAuthorizationError コール認証エラー
  • InvokeBadRequestError コールパラメータが誤っています
  Copy

  @property
  def _invoke_error_mapping(self) -> dict[type[InvokeError], list[type[Exception]]]:
      """
      Map model invoke error to unified error
      The key is the error type thrown to the caller
      The value is the error type thrown by the model,
      which needs to be converted into a unified error type for the caller.
  
      :return: Invoke error mapping
      """
  

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

  @property
  def _invoke_error_mapping(self) -> dict[type[InvokeError], list[type[Exception]]]:
      return {
          InvokeConnectionError: [
            InvokeConnectionError
          ],
          InvokeServerUnavailableError: [
            InvokeServerUnavailableError
          ],
          InvokeRateLimitError: [
            InvokeRateLimitError
          ],
          InvokeAuthorizationError: [
            InvokeAuthorizationError
          ],
          InvokeBadRequestError: [
            InvokeBadRequestError
          ],
      }
  

​

LLM

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

  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 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: is stream response
      :param user: unique user id
      :return: full response or stream response chunk generator result
      """
  

  • パラメータ：
    • model (string) モデル名
    • credentials (object) 認証情報 認証情報のパラメータは、サプライヤの YAML 構成ファイルの provider_credential_schema または model_credential_schema で定義されており、api_key などの詳細が含まれます。
    • prompt_messages (array[PromptMessage]) Prompt リスト モデルのタイプが Completion の場合、リストには1つのUserPromptMessage 要素のみを渡す必要があります； モデルのタイプが 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。
• 入力tokenの事前計算 モデルがtokenの事前計算インターフェースを提供していない場合は、直接0を返すことができます。
  Copy

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

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

  def get_customizable_model_schema(self, model: str, credentials: dict) -> Optional[AIModelEntity]:
      """
      Get customizable model schema
  
      :param model: model name
      :param credentials: model credentials
      :return: model schema
      """
  

​

TextEmbedding

• Embeddingの呼び出し
  Copy

  def _invoke(self, model: str, credentials: dict,
              texts: list[str], user: Optional[str] = None) \
          -> TextEmbeddingResult:
      """
      Invoke large language model
  
      :param model: model name
      :param credentials: model credentials
      :param texts: texts to embed
      :param user: unique user id
      :return: embeddings result
      """
  

  • パラメータ：
    • model (string) モデル名
    • credentials (object) 認証情報 認証情報のパラメータは、サプライヤの YAML 構成ファイルの provider_credential_schema または model_credential_schema で定義されており、api_key などの詳細が含まれます。
    • texts (array[string]) テキストリスト，バッチで処理できる
    • user (string) [optional] ユーザーの一意の識別子 サプライヤが不正行為を監視および検出するのに使用されます。
  • 返り値： TextEmbeddingResult エンティティ。
• tokensの事前計算
  Copy

  def get_num_tokens(self, model: str, credentials: dict, texts: list[str]) -> int:
      """
      Get number of tokens for given prompt messages
  
      :param model: model name
      :param credentials: model credentials
      :param texts: texts to embed
      :return:
      """
  

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

​

Rerank

• rerankの呼び出し
  Copy

  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:
      """
      Invoke rerank model
  
      :param model: model name
      :param credentials: model credentials
      :param query: search query
      :param docs: docs for reranking
      :param score_threshold: score threshold
      :param top_n: top n
      :param user: unique user id
      :return: rerank result
      """
  

  • パラメータ：
    • model (string) モデル名
    • credentials (object) 認証情報 認証情報のパラメータは、サプライヤの YAML 構成ファイルの provider_credential_schema または model_credential_schema で定義されており、api_key などの詳細が含まれます。
    • query (string) リクエスト内容をチェックする
    • docs (array[string]) 並べ替えが必要なセクションリスト
    • score_threshold (float) [optional] Scoreの閾値
    • top_n (int) [optional] Rerank結果のトップn件を取得します。
    • user (string) [optional] ユーザーの一意の識別子 サプライヤが不正行為を監視および検出するのに役立ちます。
  • 返り値： RerankResult エンティティ。

​

Speech2text

• Invokeの呼び出し
  Copy

  def _invoke(self, model: str, credentials: dict,
              file: IO[bytes], user: Optional[str] = None) \
          -> str:
      """
      Invoke large language model
  
      :param model: model name
      :param credentials: model credentials
      :param file: audio file
      :param user: unique user id
      :return: text for given audio file
      """	
  

  • パラメータ：
    • model (string) モデル名
    • credentials (object) 認証情報 認証情報のパラメータは、サプライヤの YAML 構成ファイルの provider_credential_schema または model_credential_schema で定義されており、api_key などの詳細が含まれます。
    • file (File) ファイルストリーム
    • user (string) [optional] ユーザーの一意の識別子 サプライヤが不正行為を監視および検出するのに使用されます。
  • 返り値： 音声をテキストに変換した結果を返します。

​

Text2speech

• Invokeの呼び出し
  Copy

  def _invoke(self, model: str, credentials: dict, content_text: str, streaming: bool, user: Optional[str] = None):
      """
      Invoke large language model
  
      :param model: model name
      :param credentials: model credentials
      :param content_text: text content to be translated
      :param streaming: output is streaming
      :param user: unique user id
      :return: translated audio file
      """	
  

  • パラメータ：
    • model (string) モデル名
    • credentials (object) 認証情報 認証情報のパラメータは、サプライヤの YAML 構成ファイルの provider_credential_schema または model_credential_schema で定義されており、api_key などの詳細が含まれます。
    • content_text (string) 変換すべきテキストコンテンツ
    • streaming (bool) ストリーミング出力かどうか
    • user (string) [optional] ユーザーの一意の識別子 サプライヤが不正行為を監視および検出するのに使用されます。
  • 返り値： テキストを音声に変換した結果を返します。

​

Moderation

• Invokeの呼び出し
  Copy

  def _invoke(self, model: str, credentials: dict,
              text: str, user: Optional[str] = None) \
          -> bool:
      """
      Invoke large language model
  
      :param model: model name
      :param credentials: model credentials
      :param text: text to moderate
      :param user: unique user id
      :return: false if text is safe, true otherwise
      """
  

  • パラメータ：
    • 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 class for prompt message.
    """
    SYSTEM = "system"
    USER = "user"
    ASSISTANT = "assistant"
    TOOL = "tool"

​

PromptMessageContentType

class PromptMessageContentType(Enum):
    """
    Enum class for prompt message content type.
    """
    TEXT = 'text'
    IMAGE = 'image'

​

PromptMessageContent

class PromptMessageContent(BaseModel):
    """
    Model class for prompt message content.
    """
    type: PromptMessageContentType
    data: str  # コンテンツデータ

​

TextPromptMessageContent

class TextPromptMessageContent(PromptMessageContent):
    """
    Model class for text prompt message content.
    """
    type: PromptMessageContentType = PromptMessageContentType.TEXT

​

ImagePromptMessageContent

class ImagePromptMessageContent(PromptMessageContent):
    """
    Model class for image prompt message content.
    """
    class DETAIL(Enum):
        LOW = 'low'
        HIGH = 'high'

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

​

PromptMessage

class PromptMessage(ABC, BaseModel):
    """
    Model class for prompt message.
    """
    role: PromptMessageRole  # メッセージロール
    content: Optional[str | list[PromptMessageContent]] = None  # 2つのタイプ、文字列とコンテンツリストをサポート。コンテンツリストはマルチモーダルのニーズを満たすために使用されます。PromptMessageContentの説明を参照してください。
    name: Optional[str] = None  # 名前、オプション

​

UserPromptMessage

class UserPromptMessage(PromptMessage):
    """
    Model class for user prompt message.
    """
    role: PromptMessageRole = PromptMessageRole.USER

​

AssistantPromptMessage

class AssistantPromptMessage(PromptMessage):
    """
    Model class for assistant prompt message.
    """
    class ToolCall(BaseModel):
        """
        Model class for assistant prompt message tool call.
        """
        class ToolCallFunction(BaseModel):
            """
            Model class for assistant prompt message tool call function.
            """
            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`を渡した場合のみ、モデルがツール呼び出しが必要と判断した場合に返されます）

​

SystemPromptMessage

class SystemPromptMessage(PromptMessage):
    """
    Model class for system prompt message.
    """
    role: PromptMessageRole = PromptMessageRole.SYSTEM

​

ToolPromptMessage

class ToolPromptMessage(PromptMessage):
    """
    Model class for tool prompt message.
    """
    role: PromptMessageRole = PromptMessageRole.TOOL
    tool_call_id: str  # ツール呼び出しID。OpenAI tool callをサポートしない場合、ツール名を渡すこともできます。

​

PromptMessageTool

class PromptMessageTool(BaseModel):
    """
    Model class for prompt message tool.
    """
    name: str  # ツール名
    description: str  # ツールの説明
    parameters: dict  # ツールパラメータ dict

​

LLMResult

class LLMResult(BaseModel):
    """
    Model class for llm result.
    """
    model: str  # 使用された実際のモデル
    prompt_messages: list[PromptMessage]  # プロンプトメッセージのリスト
    message: AssistantPromptMessage  # 返信メッセージ
    usage: LLMUsage  # 使用したtokenとコスト情報
    system_fingerprint: Optional[str] = None  # リクエスト指紋。OpenAIのこのパラメータの定義を参照。

​

LLMResultChunkDelta

class LLMResultChunkDelta(BaseModel):
    """
    Model class for llm result chunk delta.
    """
    index: int  # インデックス
    message: AssistantPromptMessage  # 返信メッセージ
    usage: Optional[LLMUsage] = None  # 使用したトークンとコスト情報（最後の1つのみ）
    finish_reason: Optional[str] = None  # 終了理由（最後の1つのみ）

​

LLMResultChunk

class LLMResultChunk(BaseModel):
    """
    Model class for llm result chunk.
    """
    model: str  # 実際に使用したモデル
    prompt_messages: list[PromptMessage]  # プロンプトメッセージのリスト
    system_fingerprint: Optional[str] = None  # リクエスト指紋。OpenAIのこのパラメータの定義を参照。
    delta: LLMResultChunkDelta  # 各イテレーションの変更が存在する内容

​

LLMUsage

class LLMUsage(ModelUsage):
    """
    Model class for llm usage.
    """
    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 class for text embedding result.
    """
    model: str  # 実際に使用したモデル
    embeddings: list[list[float]]  # テキストリストに対応するembeddingベクトルのリスト
    usage: EmbeddingUsage  # 使用した情報

​

EmbeddingUsage

class EmbeddingUsage(ModelUsage):
    """
    Model class for embedding usage.
    """
    tokens: int  # 使用した token 数
    total_tokens: int  # 総使用 token 数
    unit_price: Decimal  # 単価
    price_unit: Decimal  # 価格の単位（単価が基づいているトークンの量）
    total_price: Decimal  # 総料金
    currency: str  # 通貨単位
    latency: float  # リクエスト処理時間(s)

​

RerankResult

class RerankResult(BaseModel):
    """
    Model class for rerank result.
    """
    model: str  # 実際に使用したモデル
    docs: list[RerankDocument]  # Rerankされたセグメントリスト

​

RerankDocument

class RerankDocument(BaseModel):
    """
    Model class for rerank document.
    """
    index: int  # 元の文書の順番
    text: str  # 文書のテキスト内容
    score: float  # スコア