diff --git a/zh_CN/.gitbook/assets/Feb 4,2.png b/zh_CN/.gitbook/assets/Feb 4,2.png new file mode 100644 index 0000000..d2bd2db Binary files /dev/null and b/zh_CN/.gitbook/assets/Feb 4,2.png differ diff --git a/zh_CN/SUMMARY.md b/zh_CN/SUMMARY.md index 09293f1..6e70436 100644 --- a/zh_CN/SUMMARY.md +++ b/zh_CN/SUMMARY.md @@ -40,6 +40,9 @@ * [基于 APIs 开发](guides/application-publishing/developing-with-apis.md) * [基于前端组件再开发](guides/application-publishing/based-on-frontend-templates.md) * [模型配置](guides/model-configuration/README.md) + * [增加新供应商](guides/model-configuration/new-provider.md) + * [预定义模型接入](guides/model-configuration/predefined-model.md) + * [自定义预定义模型接入](guides/model-configuration/customizable-model.md) * [接入 Hugging Face 上的开源模型](guides/model-configuration/hugging-face.md) * [接入 Replicate 上的开源模型](guides/model-configuration/replicate.md) * [接入 Xinference 部署的本地模型](guides/model-configuration/xinference.md) diff --git a/zh_CN/guides/model-configuration/customizable-model.md b/zh_CN/guides/model-configuration/customizable-model.md new file mode 100644 index 0000000..f8f1322 --- /dev/null +++ b/zh_CN/guides/model-configuration/customizable-model.md @@ -0,0 +1,300 @@ +# 自定义预定义模型接入 + +### 介绍 + +供应商集成完成后,接下来为供应商下模型的接入,为了帮助理解整个接入过程,我们以`Xinference`为例,逐步完成一个完整的供应商接入。 + +需要注意的是,对于自定义模型,每一个模型的接入都需要填写一个完整的供应商凭据。 + +而不同于预定义模型,自定义供应商接入时永远会拥有如下两个参数,不需要在供应商yaml中定义。 + +
+ +在前文中,我们已经知道了供应商无需实现`validate_provider_credential`,Runtime会自行根据用户在此选择的模型类型和模型名称调用对应的模型层的`validate_credentials`来进行验证。 + +#### 编写供应商yaml + +我们首先要确定,接入的这个供应商支持哪些类型的模型。 + +当前支持模型类型如下: + +* `llm` 文本生成模型 +* `text_embedding` 文本 Embedding 模型 +* `rerank` Rerank 模型 +* `speech2text` 语音转文字 +* `tts` 文字转语音 +* `moderation` 审查 + +`Xinference`支持`LLM`和`Text Embedding`和Rerank,那么我们开始编写`xinference.yaml`。 + +```yaml +provider: xinference #确定供应商标识 +label: # 供应商展示名称,可设置 en_US 英文、zh_Hans 中文两种语言,zh_Hans 不设置将默认使用 en_US。 + en_US: Xorbits Inference +icon_small: # 小图标,可以参考其他供应商的图标,存储在对应供应商实现目录下的 _assets 目录,中英文策略同 label + en_US: icon_s_en.svg +icon_large: # 大图标 + en_US: icon_l_en.svg +help: # 帮助 + title: + en_US: How to deploy Xinference + zh_Hans: 如何部署 Xinference + url: + en_US: https://github.com/xorbitsai/inference +supported_model_types: # 支持的模型类型,Xinference同时支持LLM/Text Embedding/Rerank +- llm +- text-embedding +- rerank +configurate_methods: # 因为Xinference为本地部署的供应商,并且没有预定义模型,需要用什么模型需要根据Xinference的文档自己部署,所以这里只支持自定义模型 +- customizable-model +provider_credential_schema: + credential_form_schemas: +``` + +随后,我们需要思考在Xinference中定义一个模型需要哪些凭据 + +* 它支持三种不同的模型,因此,我们需要有`model_type`来指定这个模型的类型,它有三种类型,所以我们这么编写 + +```yaml +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 +``` + +* 每一个模型都有自己的名称`model_name`,因此需要在这里定义 + +```yaml + - variable: model_name + type: text-input + label: + en_US: Model name + zh_Hans: 模型名称 + required: true + placeholder: + zh_Hans: 填写模型名称 + en_US: Input model name +``` + +* 填写Xinference本地部署的地址 + +```yaml + - 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 +``` + +* 每个模型都有唯一的model\_uid,因此需要在这里定义 + +```yaml + - 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 +``` + +现在,我们就完成了供应商的基础定义。 + +#### 编写模型代码 + +然后我们以`llm`类型为例,编写`xinference.llm.llm.py` + +在 `llm.py` 中创建一个 Xinference LLM 类,我们取名为 `XinferenceAILargeLanguageModel`(随意),继承 `__base.large_language_model.LargeLanguageModel` 基类,实现以下几个方法: + +* LLM 调用 + + 实现 LLM 调用的核心方法,可同时支持流式和同步返回。 + + ```python + 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 + """ + ``` + + 在实现时,需要注意使用两个函数来返回数据,分别用于处理同步返回和流式返回,因为Python会将函数中包含 `yield` 关键字的函数识别为生成器函数,返回的数据类型固定为 `Generator`,因此同步和流式返回需要分别实现,就像下面这样(注意下面例子使用了简化参数,实际实现时需要按照上面的参数列表进行实现): + + ```python + 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) + ``` +* 预计算输入 tokens + + 若模型未提供预计算 tokens 接口,可直接返回 0。 + + ```python + 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: + """ + ``` + + 有时候,也许你不需要直接返回0,所以你可以使用`self._get_num_tokens_by_gpt2(text: str)`来获取预计算的tokens,这个方法位于`AIModel`基类中,它会使用GPT2的Tokenizer进行计算,但是只能作为替代方法,并不完全准确。 +* 模型凭据校验 + + 与供应商凭据校验类似,这里针对单个模型进行校验。 + + ```python + def validate_credentials(self, model: str, credentials: dict) -> None: + """ + Validate model credentials + + :param model: model name + :param credentials: model credentials + :return: + """ + ``` +* 模型参数Schema + + 与自定义类型不同,由于没有在yaml文件中定义一个模型支持哪些参数,因此,我们需要动态时间模型参数的Schema。 + + 如Xinference支持`max_tokens` `temperature` `top_p` 这三个模型参数。 + + 但是有的供应商根据不同的模型支持不同的参数,如供应商`OpenLLM`支持`top_k`,但是并不是这个供应商提供的所有模型都支持`top_k`,我们这里举例A模型支持`top_k`,B模型不支持`top_k`,那么我们需要在这里动态生成模型参数的Schema,如下所示: + + ```python + 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' + ) + ) + ) + + """ + some NOT IMPORTANT code here + """ + + 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 + ``` +* 调用异常错误映射表 + + 当模型调用异常时需要映射到 Runtime 指定的 `InvokeError` 类型,方便 Dify 针对不同错误做不同后续处理。 + + Runtime Errors: + + * `InvokeConnectionError` 调用连接错误 + * `InvokeServerUnavailableError` 调用服务方不可用 + * `InvokeRateLimitError` 调用达到限额 + * `InvokeAuthorizationError` 调用鉴权失败 + * `InvokeBadRequestError` 调用传参有误 + + ```python + @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 + """ + ``` + +接口方法说明见:Interfaces,具体实现可参考:[llm.py](https://github.com/langgenius/dify-runtime/blob/main/lib/model\_providers/anthropic/llm/llm.py)。 diff --git a/zh_CN/guides/model-configuration/new-provider.md b/zh_CN/guides/model-configuration/new-provider.md new file mode 100644 index 0000000..b1c3e5a --- /dev/null +++ b/zh_CN/guides/model-configuration/new-provider.md @@ -0,0 +1,588 @@ +# 增加新供应商 + +供应商支持三种模型配置方式: + +* `predefined-model`预定义模型 + + 表示用户只需要配置统一的供应商凭据即可使用供应商下的预定义模型。 +* `customizable-model`自定义模型 + + 用户需要新增每个模型的凭据配置,如 Xinference,它同时支持 LLM 和 Text Embedding,但是每个模型都有唯一的 **model\_uid**,如果想要将两者同时接入,就需要为每个模型配置一个 **model\_uid**。 +* `fetch-from-remote`从远程获取 + + 与 `predefined-model`配置方式一致,只需要配置统一的供应商凭据即可,模型通过凭据信息从供应商获取。 + + 如OpenAI,我们可以基于 gpt-turbo-3.5 来 Fine Tune 多个模型,而他们都位于同一个 **api\_key** 下,当配置为`fetch-from-remote`时,开发者只需要配置统一的 **api\_key** 即可让 Dify Runtime 获取到开发者所有的微调模型并接入 Dify。 + +这三种配置方式**支持共存**,即存在供应商支持`predefined-model` + `customizable-model` 或 `predefined-model` + `fetch-from-remote`等,也就是配置了供应商统一凭据可以使用预定义模型和从远程获取的模型,若新增了模型,则可以在此基础上额外使用自定义的模型。 + +### 开始 + +#### 介绍 + +**名词解释** + +* `module`: 一个`module`即为一个Python Package,或者通俗一点,称为一个文件夹,里面包含了一个`__init__.py`文件,以及其他的`.py`文件。 + +**步骤** + +新增一个供应商主要分为几步,这里简单列出,帮助大家有一个大概的认识,具体的步骤会在下面详细介绍。 + +* 创建供应商 yaml 文件,根据 [Provider Schema](#user-content-fn-1)[^1] 编写。 +* 创建供应商代码,实现一个`class`。 +* 根据模型类型,在供应商`module`下创建对应的模型类型 `module`,如`llm`或`text_embedding`。 +* 根据模型类型,在对应的模型`module`下创建同名的代码文件,如`llm.py`,并实现一个`class`。 +* 如果有预定义模型,根据模型名称创建同名的yaml文件在模型`module`下,如`claude-2.1.yaml`,根据 [AI Model Entity](#user-content-fn-2)[^2] 编写。 +* 编写测试代码,确保功能可用。 + +#### 开始吧 + +增加一个新的供应商需要先确定供应商的英文标识,如 `anthropic`,使用该标识在 `model_providers` 创建以此为名称的 `module`。 + +在此 `module` 下,我们需要先准备供应商的 YAML 配置。 + +**准备供应商 YAML** + +此处以 `Anthropic` 为例,预设了供应商基础信息、支持的模型类型、配置方式、凭据规则。 + +```YAML +provider: anthropic # 供应商标识 +label: # 供应商展示名称,可设置 en_US 英文、zh_Hans 中文两种语言,zh_Hans 不设置将默认使用 en_US。 + en_US: Anthropic +icon_small: # 供应商小图标,存储在对应供应商实现目录下的 _assets 目录,中英文策略同 label + en_US: icon_s_en.png +icon_large: # 供应商大图标,存储在对应供应商实现目录下的 _assets 目录,中英文策略同 label + en_US: icon_l_en.png +supported_model_types: # 支持的模型类型,Anthropic 仅支持 LLM +- llm +configurate_methods: # 支持的配置方式,Anthropic 仅支持预定义模型 +- predefined-model +provider_credential_schema: # 供应商凭据规则,由于 Anthropic 仅支持预定义模型,则需要定义统一供应商凭据规则 + credential_form_schemas: # 凭据表单项列表 + - variable: anthropic_api_key # 凭据参数变量名 + label: # 展示名称 + en_US: API Key + type: secret-input # 表单类型,此处 secret-input 代表加密信息输入框,编辑时只展示屏蔽后的信息。 + required: true # 是否必填 + placeholder: # PlaceHolder 信息 + zh_Hans: 在此输入您的 API Key + en_US: Enter your API Key + - variable: anthropic_api_url + label: + en_US: API URL + type: text-input # 表单类型,此处 text-input 代表文本输入框 + required: false + placeholder: + zh_Hans: 在此输入您的 API URL + en_US: Enter your API URL +``` + +如果接入的供应商提供自定义模型,比如`OpenAI`提供微调模型,那么我们就需要添加`model_credential_schema`,以`OpenAI`为例: + +```yaml +model_credential_schema: + model: # 微调模型名称 + label: + en_US: Model Name + zh_Hans: 模型名称 + placeholder: + en_US: Enter your model name + zh_Hans: 输入模型名称 + credential_form_schemas: + - variable: openai_api_key + label: + en_US: API Key + type: secret-input + required: true + placeholder: + zh_Hans: 在此输入您的 API Key + en_US: Enter your API Key + - variable: openai_organization + label: + zh_Hans: 组织 ID + en_US: Organization + type: text-input + required: false + placeholder: + zh_Hans: 在此输入您的组织 ID + en_US: Enter your Organization ID + - variable: openai_api_base + label: + zh_Hans: API Base + en_US: API Base + type: text-input + required: false + placeholder: + zh_Hans: 在此输入您的 API Base + en_US: Enter your API Base +``` + +也可以参考`model_providers`目录下其他供应商目录下的[ YAML ](#user-content-fn-3)[^3]配置信息。 + +**实现供应商代码** + +我们需要在`model_providers`下创建一个同名的python文件,如`anthropic.py`,并实现一个`class`,继承`__base.provider.Provider`基类,如`AnthropicProvider`。 + +**自定义模型供应商** + +当供应商为Xinference等自定义模型供应商时,可跳过该步骤,仅创建一个空的`XinferenceProvider`类即可,并实现一个空的`validate_provider_credentials`方法,该方法并不会被实际使用,仅用作避免抽象类无法实例化。 + +```python +class XinferenceProvider(Provider): + def validate_provider_credentials(self, credentials: dict) -> None: + pass +``` + +**预定义模型供应商** + +供应商需要继承 `__base.model_provider.ModelProvider` 基类,实现 `validate_provider_credentials` 供应商统一凭据校验方法即可,可参考 [AnthropicProvider](https://github.com/langgenius/dify-runtime/blob/main/lib/model\_providers/anthropic/anthropic.py)。 + +```python +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`. + """ +``` + +当然也可以先预留 `validate_provider_credentials` 实现,在模型凭据校验方法实现后直接复用。 + +**增加模型** + +**增加预定义模型 👈🏻** + +对于预定义模型,我们可以通过简单定义一个 yaml,并通过实现调用代码来接入。 + +**增加自定义模型 👈🏻** + +对于自定义模型,我们只需要实现调用代码即可接入,但是它需要处理的参数可能会更加复杂。 + +*** + +#### 测试 + +为了保证接入供应商/模型的可用性,编写后的每个方法均需要在 `tests` 目录中编写对应的集成测试代码。 + +依旧以 `Anthropic` 为例。 + +在编写测试代码前,需要先在 `.env.example` 新增测试供应商所需要的凭据环境变量,如:`ANTHROPIC_API_KEY`。 + +在执行前需要将 `.env.example` 复制为 `.env` 再执行。 + +**编写测试代码** + +在 `tests` 目录下创建供应商同名的 `module`: `anthropic`,继续在此模块中创建 `test_provider.py` 以及对应模型类型的 test py 文件,如下所示: + +```shell +. +├── __init__.py +├── anthropic +│   ├── __init__.py +│   ├── test_llm.py # LLM 测试 +│   └── test_provider.py # 供应商测试 +``` + +针对上面实现的代码的各种情况进行测试代码编写,并测试通过后提交代码。 + +[^1]: ## 配置规则 + + * 供应商规则基于 Provider 实体。 + * 模型规则基于 AIModelEntity 实体。 + + 以下所有实体均基于 `Pydantic BaseModel`,可在 `entities` 模块中找到对应实体。 + + #### Provider + + * `provider` (string) 供应商标识,如:`openai` + * `label` (object) 供应商展示名称,i18n,可设置 `en_US` 英文、`zh_Hans` 中文两种语言 + * `zh_Hans` (string) \[optional] 中文标签名,`zh_Hans` 不设置将默认使用 `en_US`。 + * `en_US` (string) 英文标签名 + * `description` (object) \[optional] 供应商描述,i18n + * `zh_Hans` (string) \[optional] 中文描述 + * `en_US` (string) 英文描述 + * `icon_small` (string) \[optional] 供应商小 ICON,存储在对应供应商实现目录下的 `_assets` 目录,中英文策略同 `label` + * `zh_Hans` (string) \[optional] 中文 ICON + * `en_US` (string) 英文 ICON + * `icon_large` (string) \[optional] 供应商大 ICON,存储在对应供应商实现目录下的 \_assets 目录,中英文策略同 label + * `zh_Hans` (string) \[optional] 中文 ICON + * `en_US` (string) 英文 ICON + * `background` (string) \[optional] 背景颜色色值,例:#FFFFFF,为空则展示前端默认色值。 + * `help` (object) \[optional] 帮助信息 + * `title` (object) 帮助标题,i18n + * `zh_Hans` (string) \[optional] 中文标题 + * `en_US` (string) 英文标题 + * `url` (object) 帮助链接,i18n + * `zh_Hans` (string) \[optional] 中文链接 + * `en_US` (string) 英文链接 + * `supported_model_types` (array\[ModelType]) 支持的模型类型 + * `configurate_methods` (array\[ConfigurateMethod]) 配置方式 + * `provider_credential_schema` (ProviderCredentialSchema) 供应商凭据规格 + * `model_credential_schema` (ModelCredentialSchema) 模型凭据规格 + + #### AIModelEntity + + * `model` (string) 模型标识,如:`gpt-3.5-turbo` + * `label` (object) \[optional] 模型展示名称,i18n,可设置 `en_US` 英文、`zh_Hans` 中文两种语言 + * `zh_Hans` (string) \[optional] 中文标签名 + * `en_US` (string) 英文标签名 + * `model_type` (ModelType) 模型类型 + * `features` (array\[ModelFeature]) \[optional] 支持功能列表 + * `model_properties` (object) 模型属性 + * `mode` (LLMMode) 模式 (模型类型 `llm` 可用) + * `context_size` (int) 上下文大小 (模型类型 `llm` `text-embedding` 可用) + * `max_chunks` (int) 最大分块数量 (模型类型 `text-embedding moderation` 可用) + * `file_upload_limit` (int) 文件最大上传限制,单位:MB。(模型类型 `speech2text` 可用) + * `supported_file_extensions` (string) 支持文件扩展格式,如:mp3,mp4(模型类型 `speech2text` 可用) + * `default_voice` (string) 缺省音色,可选:alloy,echo,fable,onyx,nova,shimmer(模型类型 `tts` 可用) + * `word_limit` (int) 单次转换字数限制,默认按段落分段(模型类型 `tts` 可用) + * `audio_type` (string) 支持音频文件扩展格式,如:mp3,wav(模型类型 `tts` 可用) + * `max_workers` (int) 支持文字音频转换并发任务数(模型类型 `tts` 可用) + * `max_characters_per_chunk` (int) 每块最大字符数 (模型类型 `moderation` 可用) + * `parameter_rules` (array\[ParameterRule]) \[optional] 模型调用参数规则 + * `pricing` (PriceConfig) \[optional] 价格信息 + * `deprecated` (bool) 是否废弃。若废弃,模型列表将不再展示,但已经配置的可以继续使用,默认 False。 + + #### ModelType + + * `llm` 文本生成模型 + * `text-embedding` 文本 Embedding 模型 + * `rerank` Rerank 模型 + * `speech2text` 语音转文字 + * `tts` 文字转语音 + * `moderation` 审查 + + #### ConfigurateMethod + + * `predefined-model` 预定义模型 + + 表示用户只需要配置统一的供应商凭据即可使用供应商下的预定义模型。 + * `customizable-model` 自定义模型 + + 用户需要新增每个模型的凭据配置。 + * `fetch-from-remote` 从远程获取 + + 与 `predefined-model` 配置方式一致,只需要配置统一的供应商凭据即可,模型通过凭据信息从供应商获取。 + + #### ModelFeature + + * `agent-thought` Agent 推理,一般超过 70B 有思维链能力。 + * `vision` 视觉,即:图像理解。 + + #### FetchFrom + + * `predefined-model` 预定义模型 + * `fetch-from-remote` 远程模型 + + #### LLMMode + + * `completion` 文本补全 + * `chat` 对话 + + #### ParameterRule + + * `name` (string) 调用模型实际参数名 + * `use_template` (string) \[optional] 使用模板 + + 默认预置了 5 种变量内容配置模板: + + * `temperature` + * `top_p` + * `frequency_penalty` + * `presence_penalty` + * `max_tokens` + + 可在 use\_template 中直接设置模板变量名,将会使用 entities.defaults.PARAMETER\_RULE\_TEMPLATE 中的默认配置 不用设置除 `name` 和 `use_template` 之外的所有参数,若设置了额外的配置参数,将覆盖默认配置。 可参考 `openai/llm/gpt-3.5-turbo.yaml`。 + * `label` (object) \[optional] 标签,i18n + * `zh_Hans`(string) \[optional] 中文标签名 + * `en_US` (string) 英文标签名 + * `type`(string) \[optional] 参数类型 + * `int` 整数 + * `float` 浮点数 + * `string` 字符串 + * `boolean` 布尔型 + * `help` (string) \[optional] 帮助信息 + * `zh_Hans` (string) \[optional] 中文帮助信息 + * `en_US` (string) 英文帮助信息 + * `required` (bool) 是否必填,默认 False。 + * `default`(int/float/string/bool) \[optional] 默认值 + * `min`(int/float) \[optional] 最小值,仅数字类型适用 + * `max`(int/float) \[optional] 最大值,仅数字类型适用 + * `precision`(int) \[optional] 精度,保留小数位数,仅数字类型适用 + * `options` (array\[string]) \[optional] 下拉选项值,仅当 `type` 为 `string` 时适用,若不设置或为 null 则不限制选项值 + + #### PriceConfig + + * `input` (float) 输入单价,即 Prompt 单价 + * `output` (float) 输出单价,即返回内容单价 + * `unit` (float) 价格单位,如:每 100K 的单价为 `0.000001` + * `currency` (string) 货币单位 + + #### ProviderCredentialSchema + + * `credential_form_schemas` (array\[CredentialFormSchema]) 凭据表单规范 + + #### ModelCredentialSchema + + * `model` (object) 模型标识,变量名默认 `model` + * `label` (object) 模型表单项展示名称 + * `en_US` (string) 英文 + * `zh_Hans`(string) \[optional] 中文 + * `placeholder` (object) 模型提示内容 + * `en_US`(string) 英文 + * `zh_Hans`(string) \[optional] 中文 + * `credential_form_schemas` (array\[CredentialFormSchema]) 凭据表单规范 + + #### CredentialFormSchema + + * `variable` (string) 表单项变量名 + * `label` (object) 表单项标签名 + * `en_US`(string) 英文 + * `zh_Hans` (string) \[optional] 中文 + * `type` (FormType) 表单项类型 + * `required` (bool) 是否必填 + * `default`(string) 默认值 + * `options` (array\[FormOption]) 表单项为 `select` 或 `radio` 专有属性,定义下拉内容 + * `placeholder`(object) 表单项为 `text-input` 专有属性,表单项 PlaceHolder + * `en_US`(string) 英文 + * `zh_Hans` (string) \[optional] 中文 + * `max_length` (int) 表单项为`text-input`专有属性,定义输入最大长度,0 为不限制。 + * `show_on` (array\[FormShowOnObject]) 当其他表单项值符合条件时显示,为空则始终显示。 + + #### FormType + + * `text-input` 文本输入组件 + * `secret-input` 密码输入组件 + * `select` 单选下拉 + * `radio` Radio 组件 + * `switch` 开关组件,仅支持 `true` 和 `false` + + #### FormOption + + * `label` (object) 标签 + * `en_US`(string) 英文 + * `zh_Hans`(string) \[optional] 中文 + * `value` (string) 下拉选项值 + * `show_on` (array\[FormShowOnObject]) 当其他表单项值符合条件时显示,为空则始终显示。 + + #### FormShowOnObject + + * `variable` (string) 其他表单项变量名 + * `value` (string) 其他表单项变量值 + +[^2]: ## 配置规则 + + * 供应商规则基于 Provider 实体。 + * 模型规则基于 AIModelEntity 实体。 + + 以下所有实体均基于 `Pydantic BaseModel`,可在 `entities` 模块中找到对应实体。 + + #### Provider + + * `provider` (string) 供应商标识,如:`openai` + * `label` (object) 供应商展示名称,i18n,可设置 `en_US` 英文、`zh_Hans` 中文两种语言 + * `zh_Hans` (string) \[optional] 中文标签名,`zh_Hans` 不设置将默认使用 `en_US`。 + * `en_US` (string) 英文标签名 + * `description` (object) \[optional] 供应商描述,i18n + * `zh_Hans` (string) \[optional] 中文描述 + * `en_US` (string) 英文描述 + * `icon_small` (string) \[optional] 供应商小 ICON,存储在对应供应商实现目录下的 `_assets` 目录,中英文策略同 `label` + * `zh_Hans` (string) \[optional] 中文 ICON + * `en_US` (string) 英文 ICON + * `icon_large` (string) \[optional] 供应商大 ICON,存储在对应供应商实现目录下的 \_assets 目录,中英文策略同 label + * `zh_Hans` (string) \[optional] 中文 ICON + * `en_US` (string) 英文 ICON + * `background` (string) \[optional] 背景颜色色值,例:#FFFFFF,为空则展示前端默认色值。 + * `help` (object) \[optional] 帮助信息 + * `title` (object) 帮助标题,i18n + * `zh_Hans` (string) \[optional] 中文标题 + * `en_US` (string) 英文标题 + * `url` (object) 帮助链接,i18n + * `zh_Hans` (string) \[optional] 中文链接 + * `en_US` (string) 英文链接 + * `supported_model_types` (array\[ModelType]) 支持的模型类型 + * `configurate_methods` (array\[ConfigurateMethod]) 配置方式 + * `provider_credential_schema` (ProviderCredentialSchema) 供应商凭据规格 + * `model_credential_schema` (ModelCredentialSchema) 模型凭据规格 + + #### AIModelEntity + + * `model` (string) 模型标识,如:`gpt-3.5-turbo` + * `label` (object) \[optional] 模型展示名称,i18n,可设置 `en_US` 英文、`zh_Hans` 中文两种语言 + * `zh_Hans` (string) \[optional] 中文标签名 + * `en_US` (string) 英文标签名 + * `model_type` (ModelType) 模型类型 + * `features` (array\[ModelFeature]) \[optional] 支持功能列表 + * `model_properties` (object) 模型属性 + * `mode` (LLMMode) 模式 (模型类型 `llm` 可用) + * `context_size` (int) 上下文大小 (模型类型 `llm` `text-embedding` 可用) + * `max_chunks` (int) 最大分块数量 (模型类型 `text-embedding moderation` 可用) + * `file_upload_limit` (int) 文件最大上传限制,单位:MB。(模型类型 `speech2text` 可用) + * `supported_file_extensions` (string) 支持文件扩展格式,如:mp3,mp4(模型类型 `speech2text` 可用) + * `default_voice` (string) 缺省音色,可选:alloy,echo,fable,onyx,nova,shimmer(模型类型 `tts` 可用) + * `word_limit` (int) 单次转换字数限制,默认按段落分段(模型类型 `tts` 可用) + * `audio_type` (string) 支持音频文件扩展格式,如:mp3,wav(模型类型 `tts` 可用) + * `max_workers` (int) 支持文字音频转换并发任务数(模型类型 `tts` 可用) + * `max_characters_per_chunk` (int) 每块最大字符数 (模型类型 `moderation` 可用) + * `parameter_rules` (array\[ParameterRule]) \[optional] 模型调用参数规则 + * `pricing` (PriceConfig) \[optional] 价格信息 + * `deprecated` (bool) 是否废弃。若废弃,模型列表将不再展示,但已经配置的可以继续使用,默认 False。 + + #### ModelType + + * `llm` 文本生成模型 + * `text-embedding` 文本 Embedding 模型 + * `rerank` Rerank 模型 + * `speech2text` 语音转文字 + * `tts` 文字转语音 + * `moderation` 审查 + + #### ConfigurateMethod + + * `predefined-model` 预定义模型 + + 表示用户只需要配置统一的供应商凭据即可使用供应商下的预定义模型。 + * `customizable-model` 自定义模型 + + 用户需要新增每个模型的凭据配置。 + * `fetch-from-remote` 从远程获取 + + 与 `predefined-model` 配置方式一致,只需要配置统一的供应商凭据即可,模型通过凭据信息从供应商获取。 + + #### ModelFeature + + * `agent-thought` Agent 推理,一般超过 70B 有思维链能力。 + * `vision` 视觉,即:图像理解。 + + #### FetchFrom + + * `predefined-model` 预定义模型 + * `fetch-from-remote` 远程模型 + + #### LLMMode + + * `completion` 文本补全 + * `chat` 对话 + + #### ParameterRule + + * `name` (string) 调用模型实际参数名 + * `use_template` (string) \[optional] 使用模板 + + 默认预置了 5 种变量内容配置模板: + + * `temperature` + * `top_p` + * `frequency_penalty` + * `presence_penalty` + * `max_tokens` + + 可在 use\_template 中直接设置模板变量名,将会使用 entities.defaults.PARAMETER\_RULE\_TEMPLATE 中的默认配置 不用设置除 `name` 和 `use_template` 之外的所有参数,若设置了额外的配置参数,将覆盖默认配置。 可参考 `openai/llm/gpt-3.5-turbo.yaml`。 + * `label` (object) \[optional] 标签,i18n + * `zh_Hans`(string) \[optional] 中文标签名 + * `en_US` (string) 英文标签名 + * `type`(string) \[optional] 参数类型 + * `int` 整数 + * `float` 浮点数 + * `string` 字符串 + * `boolean` 布尔型 + * `help` (string) \[optional] 帮助信息 + * `zh_Hans` (string) \[optional] 中文帮助信息 + * `en_US` (string) 英文帮助信息 + * `required` (bool) 是否必填,默认 False。 + * `default`(int/float/string/bool) \[optional] 默认值 + * `min`(int/float) \[optional] 最小值,仅数字类型适用 + * `max`(int/float) \[optional] 最大值,仅数字类型适用 + * `precision`(int) \[optional] 精度,保留小数位数,仅数字类型适用 + * `options` (array\[string]) \[optional] 下拉选项值,仅当 `type` 为 `string` 时适用,若不设置或为 null 则不限制选项值 + + #### PriceConfig + + * `input` (float) 输入单价,即 Prompt 单价 + * `output` (float) 输出单价,即返回内容单价 + * `unit` (float) 价格单位,如:每 100K 的单价为 `0.000001` + * `currency` (string) 货币单位 + + #### ProviderCredentialSchema + + * `credential_form_schemas` (array\[CredentialFormSchema]) 凭据表单规范 + + #### ModelCredentialSchema + + * `model` (object) 模型标识,变量名默认 `model` + * `label` (object) 模型表单项展示名称 + * `en_US` (string) 英文 + * `zh_Hans`(string) \[optional] 中文 + * `placeholder` (object) 模型提示内容 + * `en_US`(string) 英文 + * `zh_Hans`(string) \[optional] 中文 + * `credential_form_schemas` (array\[CredentialFormSchema]) 凭据表单规范 + + #### CredentialFormSchema + + * `variable` (string) 表单项变量名 + * `label` (object) 表单项标签名 + * `en_US`(string) 英文 + * `zh_Hans` (string) \[optional] 中文 + * `type` (FormType) 表单项类型 + * `required` (bool) 是否必填 + * `default`(string) 默认值 + * `options` (array\[FormOption]) 表单项为 `select` 或 `radio` 专有属性,定义下拉内容 + * `placeholder`(object) 表单项为 `text-input` 专有属性,表单项 PlaceHolder + * `en_US`(string) 英文 + * `zh_Hans` (string) \[optional] 中文 + * `max_length` (int) 表单项为`text-input`专有属性,定义输入最大长度,0 为不限制。 + * `show_on` (array\[FormShowOnObject]) 当其他表单项值符合条件时显示,为空则始终显示。 + + #### FormType + + * `text-input` 文本输入组件 + * `secret-input` 密码输入组件 + * `select` 单选下拉 + * `radio` Radio 组件 + * `switch` 开关组件,仅支持 `true` 和 `false` + + #### FormOption + + * `label` (object) 标签 + * `en_US`(string) 英文 + * `zh_Hans`(string) \[optional] 中文 + * `value` (string) 下拉选项值 + * `show_on` (array\[FormShowOnObject]) 当其他表单项值符合条件时显示,为空则始终显示。 + + #### FormShowOnObject + + * `variable` (string) 其他表单项变量名 + * `value` (string) 其他表单项变量值 + +[^3]: Provider + + * `provider` (string) 供应商标识,如:`openai` + * `label` (object) 供应商展示名称,i18n,可设置 `en_US` 英文、`zh_Hans` 中文两种语言 + * `zh_Hans` (string) \[optional] 中文标签名,`zh_Hans` 不设置将默认使用 `en_US`。 + * `en_US` (string) 英文标签名 + * `description` (object) \[optional] 供应商描述,i18n + * `zh_Hans` (string) \[optional] 中文描述 + * `en_US` (string) 英文描述 + * `icon_small` (string) \[optional] 供应商小 ICON,存储在对应供应商实现目录下的 `_assets` 目录,中英文策略同 `label` + * `zh_Hans` (string) \[optional] 中文 ICON + * `en_US` (string) 英文 ICON + * `icon_large` (string) \[optional] 供应商大 ICON,存储在对应供应商实现目录下的 \_assets 目录,中英文策略同 label + * `zh_Hans` (string) \[optional] 中文 ICON + * `en_US` (string) 英文 ICON + * `background` (string) \[optional] 背景颜色色值,例:#FFFFFF,为空则展示前端默认色值。 + * `help` (object) \[optional] 帮助信息 + * `title` (object) 帮助标题,i18n + * `zh_Hans` (string) \[optional] 中文标题 + * `en_US` (string) 英文标题 + * `url` (object) 帮助链接,i18n + * `zh_Hans` (string) \[optional] 中文链接 + * `en_US` (string) 英文链接 + * `supported_model_types` (array\[ModelType]) 支持的模型类型 + * `configurate_methods` (array\[ConfigurateMethod]) 配置方式 + * `provider_credential_schema` (ProviderCredentialSchema) 供应商凭据规格 + * `model_credential_schema` (ModelCredentialSchema) 模型凭据规格 diff --git a/zh_CN/guides/model-configuration/predefined-model.md b/zh_CN/guides/model-configuration/predefined-model.md new file mode 100644 index 0000000..6dfa60e --- /dev/null +++ b/zh_CN/guides/model-configuration/predefined-model.md @@ -0,0 +1,197 @@ +# 预定义模型接入 + +供应商集成完成后,接下来为供应商下模型的接入。 + +我们首先需要确定接入模型的类型,并在对应供应商的目录下创建对应模型类型的 `module`。 + +当前支持模型类型如下: + +* `llm` 文本生成模型 +* `text_embedding` 文本 Embedding 模型 +* `rerank` Rerank 模型 +* `speech2text` 语音转文字 +* `tts` 文字转语音 +* `moderation` 审查 + +依旧以 `Anthropic` 为例,`Anthropic` 仅支持 LLM,因此在 `model_providers.anthropic` 创建一个 `llm` 为名称的 `module`。 + +对于预定义的模型,我们首先需要在 `llm` `module` 下创建以模型名为文件名称的 YAML 文件,如:`claude-2.1.yaml`。 + +#### 准备模型 YAML + +```yaml +model: claude-2.1 # 模型标识 +# 模型展示名称,可设置 en_US 英文、zh_Hans 中文两种语言,zh_Hans 不设置将默认使用 en_US。 +# 也可不设置 label,则使用 model 标识内容。 +label: + en_US: claude-2.1 +model_type: llm # 模型类型,claude-2.1 为 LLM +features: # 支持功能,agent-thought 为支持 Agent 推理,vision 为支持图片理解 +- agent-thought +model_properties: # 模型属性 + mode: chat # LLM 模式,complete 文本补全模型,chat 对话模型 + context_size: 200000 # 支持最大上下文大小 +parameter_rules: # 模型调用参数规则,仅 LLM 需要提供 +- name: temperature # 调用参数变量名 + # 默认预置了 5 种变量内容配置模板,temperature/top_p/max_tokens/presence_penalty/frequency_penalty + # 可在 use_template 中直接设置模板变量名,将会使用 entities.defaults.PARAMETER_RULE_TEMPLATE 中的默认配置 + # 若设置了额外的配置参数,将覆盖默认配置 + use_template: temperature +- name: top_p + use_template: top_p +- name: top_k + label: # 调用参数展示名称 + zh_Hans: 取样数量 + en_US: Top k + type: int # 参数类型,支持 float/int/string/boolean + help: # 帮助信息,描述参数作用 + zh_Hans: 仅从每个后续标记的前 K 个选项中采样。 + en_US: Only sample from the top K options for each subsequent token. + required: false # 是否必填,可不设置 +- name: max_tokens_to_sample + use_template: max_tokens + default: 4096 # 参数默认值 + min: 1 # 参数最小值,仅 float/int 可用 + max: 4096 # 参数最大值,仅 float/int 可用 +pricing: # 价格信息 + input: '8.00' # 输入单价,即 Prompt 单价 + output: '24.00' # 输出单价,即返回内容单价 + unit: '0.000001' # 价格单位,即上述价格为每 100K 的单价 + currency: USD # 价格货币 +``` + +建议将所有模型配置都准备完毕后再开始模型代码的实现。 + +同样,也可以参考 `model_providers` 目录下其他供应商对应模型类型目录下的 YAML 配置信息,完整的 YAML 规则见:Schema[^1]。 + +#### 实现模型调用代码 + +接下来需要在 `llm` `module` 下创建一个同名的 python 文件 `llm.py` 来编写代码实现。 + +在 `llm.py` 中创建一个 Anthropic LLM 类,我们取名为 `AnthropicLargeLanguageModel`(随意),继承 `__base.large_language_model.LargeLanguageModel` 基类,实现以下几个方法: + +* LLM 调用 + + 实现 LLM 调用的核心方法,可同时支持流式和同步返回。 + + ```python + 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 + """ + ``` + + 在实现时,需要注意使用两个函数来返回数据,分别用于处理同步返回和流式返回,因为Python会将函数中包含 `yield` 关键字的函数识别为生成器函数,返回的数据类型固定为 `Generator`,因此同步和流式返回需要分别实现,就像下面这样(注意下面例子使用了简化参数,实际实现时需要按照上面的参数列表进行实现): + + ```python + 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) + ``` +* 预计算输入 tokens + + 若模型未提供预计算 tokens 接口,可直接返回 0。 + + ```python + 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: + """ + ``` +* 模型凭据校验 + + 与供应商凭据校验类似,这里针对单个模型进行校验。 + + ```python + def validate_credentials(self, model: str, credentials: dict) -> None: + """ + Validate model credentials + + :param model: model name + :param credentials: model credentials + :return: + """ + ``` +* 调用异常错误映射表 + + 当模型调用异常时需要映射到 Runtime 指定的 `InvokeError` 类型,方便 Dify 针对不同错误做不同后续处理。 + + Runtime Errors: + + * `InvokeConnectionError` 调用连接错误 + * `InvokeServerUnavailableError` 调用服务方不可用 + * `InvokeRateLimitError` 调用达到限额 + * `InvokeAuthorizationError` 调用鉴权失败 + * `InvokeBadRequestError` 调用传参有误 + + ```python + @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 + """ + ``` + +接口方法说明见:[Interfaces](https://github.com/langgenius/dify/blob/main/api/core/model\_runtime/docs/zh\_Hans/interfaces.md),具体实现可参考:[llm.py](https://github.com/langgenius/dify-runtime/blob/main/lib/model\_providers/anthropic/llm/llm.py)。 + +[^1]: #### Provider + + * `provider` (string) 供应商标识,如:`openai` + * `label` (object) 供应商展示名称,i18n,可设置 `en_US` 英文、`zh_Hans` 中文两种语言 + * `zh_Hans` (string) \[optional] 中文标签名,`zh_Hans` 不设置将默认使用 `en_US`。 + * `en_US` (string) 英文标签名 + * `description` (object) \[optional] 供应商描述,i18n + * `zh_Hans` (string) \[optional] 中文描述 + * `en_US` (string) 英文描述 + * `icon_small` (string) \[optional] 供应商小 ICON,存储在对应供应商实现目录下的 `_assets` 目录,中英文策略同 `label` + * `zh_Hans` (string) \[optional] 中文 ICON + * `en_US` (string) 英文 ICON + * `icon_large` (string) \[optional] 供应商大 ICON,存储在对应供应商实现目录下的 \_assets 目录,中英文策略同 label + * `zh_Hans` (string) \[optional] 中文 ICON + * `en_US` (string) 英文 ICON + * `background` (string) \[optional] 背景颜色色值,例:#FFFFFF,为空则展示前端默认色值。 + * `help` (object) \[optional] 帮助信息 + * `title` (object) 帮助标题,i18n + * `zh_Hans` (string) \[optional] 中文标题 + * `en_US` (string) 英文标题 + * `url` (object) 帮助链接,i18n + * `zh_Hans` (string) \[optional] 中文链接 + * `en_US` (string) 英文链接 + * `supported_model_types` (array\[ModelType]) 支持的模型类型 + * `configurate_methods` (array\[ConfigurateMethod]) 配置方式 + * `provider_credential_schema` (ProviderCredentialSchema) 供应商凭据规格 + * `model_credential_schema` (ModelCredentialSchema) 模型凭据规格