インタフェース
ここでは、サプライヤーと各モデルタイプが実装する必要があるインターフェース方法とそのパラメータについて説明します。
サプライヤー
__base.model_provider.ModelProvider
基本クラスを継承し、以下のインターフェースを実装する必要があります:
credentials
(object) 資格情報資格情報のパラメータは、サプライヤーのYAML構成ファイルの
provider_credential_schema
で定義され、api_key
などが渡されます。
検証に失敗した場合は、errors.validate.CredentialsValidateFailedError
エラーをスローします。
注:事前定義されたモデルはこのインターフェースを完全に実装する必要がありますが、カスタムモデルサプライヤーは以下の簡単な実装のみが必要です
モデル
モデルには5つの異なるモデルタイプがあり、異なる基底クラスを継承し、実装する必要があるメソッドも異なります。
一般インターフェース
すべてのモデルには以下の2つのメソッドを実装する必要があります:
モデルの資格情報を検証する
サプライヤーの資格情報検証と同様に、ここでは個々のモデルに対して検証を行います。
パラメータ:
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
コールパラメータが誤っています
または、対応するエラーを直接スローし、以下のように定義することもできます。これにより、後続の呼び出しで
InvokeConnectionError
などの例外を直接スローできます。
OpenAIの _invoke_error_mapping
をご参照ください。
LLM
__base.large_language_model.LargeLanguageModel
基本クラスを継承し、以下のインターフェースを実装します:
LLMの呼び出し
LLM呼び出しの核心メソッドを実装し、ストリーミングと同期応答の両方をサポートします。
パラメータ:
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を返すことができます。
パラメータの説明は上記の
LLMの呼び出し
を参照してください。このインターフェースは、対応する
model
に基づいて適切なtokenizer
を選択して計算する必要があります。対応するモデルがtokenizer
を提供していない場合は、AIModel
ベースクラスの_get_num_tokens_by_gpt2(text: str)
メソッドを使用して計算できます。カスタムモデルスキーマの取得 [オプション]
供給業者がカスタムLLMを追加することをサポートしている場合、このメソッドを実装してカスタムモデルがモデル規則を取得できるようにすることができます。デフォルトではNoneを返します。
ほとんどの微調整モデルはOpenAI
供給業者の下で、微調整モデル名を使用してベースモデルを取得できます。例えば、gpt-3.5-turbo-1106
のような微調整モデル名を使用して、基本モデルの事前定義されたパラメータルールを取得できます。具体的な実装については、openaiを参照してください。
TextEmbedding
__base.text_embedding_model.TextEmbeddingModel
ベースクラスを継承し、次のインターフェースを実装します:
Embeddingの呼び出し
パラメータ:
model
(string) モデル名credentials
(object) 資格情報資格情報のパラメータは、供給業者の YAML 構成ファイルの provider_credential_schema または model_credential_schema で定義されており、api_key などの詳細が含まれます。
texts
(array[string]) テキストリスト,バッチで処理できるuser
(string) [optional] ユーザーの一意の識別子供給業者が不正行為を監視および検出するのに役立ちます。
返り値:
TextEmbeddingResult エンティティ。
tokensの事前計算
パラメータの説明は上記の
Embeddingの呼び出し
を参照してください。上記の
LargeLanguageModel
と同様に、このインターフェースは、対応するmodel
に基づいて適切なtokenizer
を選択して計算する必要があります。対応するモデルがtokenizer
を提供していない場合は、AIModel
ベースクラスの_get_num_tokens_by_gpt2(text: str)
メソッドを使用して計算できます。
Rerank
`__base.rerank_model.RerankModelベースクラスを継承し、次のインターフェースを実装します:
rerankの呼び出し
パラメータ:
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] トップのnセクションを取得しますuser
(string) [optional] ユーザーの一意の識別子供給業者が不正行為を監視および検出するのに役立ちます。
返り値:
RerankResult エンティティ。
Speech2text
__base.speech2text_model.Speech2TextModel
基底クラスを継承し、以下のインターフェースを実装します:
Invokeの呼び出し
パラメータ:
model
(string) モデル名credentials
(object) 資格情報資格情報のパラメータは、供給業者の YAML 構成ファイルの provider_credential_schema または model_credential_schema で定義されており、api_key などの詳細が含まれます。
file
(File) ファイルストリームuser
(string) [optional] ユーザーの一意の識別子供給業者が不正行為を監視および検出するのに役立ちます。
返り値:
音声をテキストに変換した結果を返します。
Text2speech
__base.text2speech_model.Text2SpeechModel
基底クラスを継承し、以下のインターフェースを実装します:
Invokeの呼び出し
パラメータ:
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の呼び出し
パラメータ:
model
(string) モデル名credentials
(object) 資格情報資格情報のパラメータは、供給業者の YAML 構成ファイルの provider_credential_schema または model_credential_schema で定義されており、api_key などの詳細が含まれます。
text
(string) テキスト内容user
(string) [optional] ユーザーの一意の識別子供給業者が不正行為を監視および検出するのに役立ちます。
返り値:
False の場合は入力したテキストは安全であり、True の場合はその逆。
エンティティ
PromptMessageRole
メッセージロールを定義する列挙型。
PromptMessageContentType
メッセージコンテンツのタイプを定義し、テキストと画像の2種類がある。
PromptMessageContent
メッセージコンテンツの基底クラスであり、パラメータのみを宣言するため初期化は行えない。
現在、テキストと画像の2つのタイプがサポートされており、テキストと複数の画像を同時に渡すことができる。
テキストと画像を同時に渡す場合は、TextPromptMessageContent
と ImagePromptMessageContent
をそれぞれ初期化する必要がある。
TextPromptMessageContent
画像とテキストを一緒に渡す場合、テキストは content
リストの一部としてこのエンティティを構築する必要がある。
ImagePromptMessageContent
画像とテキストを一緒に渡す場合、画像は content
リストの一部としてこのエンティティを構築する必要がある。
data
には url
または画像の base64
でエンコードされた文字列を指定することができる。
PromptMessage
すべてのロールメッセージの基底クラスであり、パラメータのみを宣言するため初期化はできません。
UserPromptMessage
UserMessage ユーザーメッセージを表すクラス。
AssistantPromptMessage
モデルの返信メッセージを表し、通常は few-shots
やチャット履歴が入力として使用されます。
tool_calls
は、モデルに tools
を渡した後、モデルが返す tool call
のリストです。
SystemPromptMessage
システムメッセージを表し、通常はモデルに与えられるシステム命令に使用されます。
ToolPromptMessage
ツールメッセージを表し、ツールの実行結果をモデルに渡して次のステップの計画を行います。
基类的 content
传入工具执行结果。
PromptMessageTool
LLMResult
LLMResultChunkDelta
ストリーム化された各イテレーション内の delta
エンティティ。
LLMResultChunk
ストリーム化された各イテレーションのエンティティ。
LLMUsage
TextEmbeddingResult
EmbeddingUsage
RerankResult
RerankDocument
interfaces:
credentials
(object) Credential informationThe parameters of credential information are defined by the
provider_credential_schema
in the provider's YAML configuration file. Inputs such asapi_key
are included.
If verification fails, throw the errors.validate.CredentialsValidateFailedError
error.
Model
Models are divided into 5 different types, each inheriting from different base classes and requiring the implementation of different methods.
All models need to uniformly implement the following 2 methods:
Model Credential Verification
Similar to provider credential verification, this step involves verification for an individual model.
Parameters:
model
(string) Model namecredentials
(object) Credential informationThe parameters of credential information are defined by either the
provider_credential_schema
ormodel_credential_schema
in the provider's YAML configuration file. Inputs such asapi_key
are included.
If verification fails, throw the
errors.validate.CredentialsValidateFailedError
error.Invocation Error Mapping Table
When there is an exception in model invocation, it needs to be mapped to the
InvokeError
type specified by Runtime. This facilitates Dify's ability to handle different errors with appropriate follow-up actions.Runtime Errors:
InvokeConnectionError
Invocation connection errorInvokeServerUnavailableError
Invocation service provider unavailableInvokeRateLimitError
Invocation reached rate limitInvokeAuthorizationError
Invocation authorization failureInvokeBadRequestError
Invocation parameter error
You can refer to OpenAI's _invoke_error_mapping
for an example.
LLM
Inherit the __base.large_language_model.LargeLanguageModel
base class and implement the following interfaces:
LLM Invocation
Implement the core method for LLM invocation, which can support both streaming and synchronous returns.
Parameters:
model
(string) Model namecredentials
(object) Credential informationThe parameters of credential information are defined by either the
provider_credential_schema
ormodel_credential_schema
in the provider's YAML configuration file. Inputs such asapi_key
are included.prompt_messages
(array[PromptMessage]) List of promptsIf the model is of the
Completion
type, the list only needs to include one UserPromptMessage element;If the model is of the
Chat
type, it requires a list of elements such as SystemPromptMessage, UserPromptMessage, AssistantPromptMessage, ToolPromptMessage depending on the message.model_parameters
(object) Model parametersThe model parameters are defined by the
parameter_rules
in the model's YAML configuration.tools
(array[PromptMessageTool]) [optional] List of tools, equivalent to thefunction
infunction calling
.That is, the tool list for tool calling.
stop
(array[string]) [optional] Stop sequencesThe model output will stop before the string defined by the stop sequence.
stream
(bool) Whether to output in a streaming manner, default is TrueStreaming output returns Generator[LLMResultChunk], non-streaming output returns LLMResult.
user
(string) [optional] Unique identifier of the userThis can help the provider monitor and detect abusive behavior.
Returns
Streaming output returns Generator[LLMResultChunk], non-streaming output returns LLMResult.
Pre-calculating Input Tokens
If the model does not provide a pre-calculated tokens interface, you can directly return 0.
For parameter explanations, refer to the above section on
LLM Invocation
.Fetch Custom Model Schema [Optional]
When the provider supports adding custom LLMs, this method can be implemented to allow custom models to fetch model schema. The default return null.
TextEmbedding
Inherit the __base.text_embedding_model.TextEmbeddingModel
base class and implement the following interfaces:
Embedding Invocation
Parameters:
model
(string) Model namecredentials
(object) Credential informationThe parameters of credential information are defined by either the
provider_credential_schema
ormodel_credential_schema
in the provider's YAML configuration file. Inputs such asapi_key
are included.texts
(array[string]) List of texts, capable of batch processinguser
(string) [optional] Unique identifier of the userThis can help the provider monitor and detect abusive behavior.
Returns:
TextEmbeddingResult entity.
Pre-calculating Tokens
For parameter explanations, refer to the above section on
Embedding Invocation
.
Rerank
Inherit the __base.rerank_model.RerankModel
base class and implement the following interfaces:
Rerank Invocation
Parameters:
model
(string) Model namecredentials
(object) Credential informationThe parameters of credential information are defined by either the
provider_credential_schema
ormodel_credential_schema
in the provider's YAML configuration file. Inputs such asapi_key
are included.query
(string) Query request contentdocs
(array[string]) List of segments to be rerankedscore_threshold
(float) [optional] Score thresholdtop_n
(int) [optional] Select the top n segmentsuser
(string) [optional] Unique identifier of the userThis can help the provider monitor and detect abusive behavior.
Returns:
RerankResult entity.
Speech2text
Inherit the __base.speech2text_model.Speech2TextModel
base class and implement the following interfaces:
Invoke Invocation
Parameters:
model
(string) Model namecredentials
(object) Credential informationThe parameters of credential information are defined by either the
provider_credential_schema
ormodel_credential_schema
in the provider's YAML configuration file. Inputs such asapi_key
are included.file
(File) File streamuser
(string) [optional] Unique identifier of the userThis can help the provider monitor and detect abusive behavior.
Returns:
The string after speech-to-text conversion.
Text2speech
Inherit the __base.text2speech_model.Text2SpeechModel
base class and implement the following interfaces:
Invoke Invocation
Parameters:
model
(string) Model namecredentials
(object) Credential informationThe parameters of credential information are defined by either the
provider_credential_schema
ormodel_credential_schema
in the provider's YAML configuration file. Inputs such asapi_key
are included.content_text
(string) The text content that needs to be convertedstreaming
(bool) Whether to stream outputuser
(string) [optional] Unique identifier of the userThis can help the provider monitor and detect abusive behavior.
Returns:
Text converted speech stream。
Moderation
Inherit the __base.moderation_model.ModerationModel
base class and implement the following interfaces:
Invoke Invocation
Parameters:
model
(string) Model namecredentials
(object) Credential informationThe parameters of credential information are defined by either the
provider_credential_schema
ormodel_credential_schema
in the provider's YAML configuration file. Inputs such asapi_key
are included.text
(string) Text contentuser
(string) [optional] Unique identifier of the userThis can help the provider monitor and detect abusive behavior.
Returns:
False indicates that the input text is safe, True indicates otherwise.
Entities
PromptMessageRole
Message role
PromptMessageContentType
Message content types, divided into text and image.
PromptMessageContent
Message content base class, used only for parameter declaration and cannot be initialized.
Currently, two types are supported: text and image. It's possible to simultaneously input text and multiple images.
You need to initialize TextPromptMessageContent
and ImagePromptMessageContent
separately for input.
TextPromptMessageContent
If inputting a combination of text and images, the text needs to be constructed into this entity as part of the content
list.
ImagePromptMessageContent
If inputting a combination of text and images, the images need to be constructed into this entity as part of the content
list.
data
can be either a url
or a base64
encoded string of the image.
PromptMessage
The base class for all Role message bodies, used only for parameter declaration and cannot be initialized.
UserPromptMessage
UserMessage message body, representing a user's message.
AssistantPromptMessage
Represents a message returned by the model, typically used for few-shots
or inputting chat history.
Where tool_calls
are the list of tool calls
returned by the model after invoking the model with the tools
input.
SystemPromptMessage
Represents system messages, usually used for setting system commands given to the model.
ToolPromptMessage
Represents tool messages, used for conveying the results of a tool execution to the model for the next step of processing.
The base class's content
takes in the results of tool execution.
PromptMessageTool
LLMResult
LLMResultChunkDelta
In streaming returns, each iteration contains the delta
entity.
LLMResultChunk
Each iteration entity in streaming returns.