Интеграция пользовательских моделей

Пользовательская модель — это LLM, которую вы разворачиваете или настраиваете самостоятельно. В этом документе на примере модели Xinference показано, как интегрировать пользовательскую модель в ваш плагин модели. По умолчанию пользовательская модель автоматически включает два параметра (её тип модели и имя модели) и не требует дополнительных определений в файле YAML поставщика. Реализовывать validate_provider_credential в файле конфигурации поставщика не нужно. Во время выполнения, в зависимости от выбранного пользователем типа или имени модели, Интеллос автоматически вызывает метод validate_credentials соответствующего слоя модели для проверки учётных данных.

Интеграция плагина пользовательской модели

Ниже приведены шаги для интеграции пользовательской модели:

Создайте файл поставщика модели
Определите типы моделей, которые будет включать ваша пользовательская модель.
Создайте файлы кода по типам моделей
В зависимости от типа модели (например, llm или text_embedding) создайте отдельные файлы кода. Убедитесь, что каждый тип модели организован в отдельные логические слои — это упростит сопровождение и дальнейшее расширение.
Разработайте логику вызова модели
Внутри каждого модуля типа модели создайте файл Python с именем этого типа модели (например, llm.py). Определите в файле класс, реализующий конкретную логику модели в соответствии со спецификациями интерфейса модели системы.
Отладьте плагин
Напишите модульные и интеграционные тесты для нового функционала поставщика, чтобы убедиться, что все компоненты работают как задумано.

1. Создайте файл поставщика модели

В каталоге /provider вашего плагина создайте файл xinference.yaml. Семейство моделей Xinference поддерживает типы моделей LLM, Text Embedding и Rerank, поэтому ваш файл xinference.yaml должен включать все три. Пример:

provider: xinference  # Identifies the provider
label:                # 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 Inference
icon_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.svg
icon_large:           # Large icon
  en_US: icon_l_en.svg
help:                 # Help information
  title:
    en_US: How to deploy Xinference
    zh_Hans: 如何部署 Xinference
  url:
    en_US: https://github.com/xorbitsai/inference

supported_model_types:  # Model types Xinference supports: LLM/Text Embedding/Rerank
- llm
- text-embedding
- rerank

configurate_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-model

provider_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, а затем определяете класс (например, XinferenceAILargeLanguageModel), наследующий __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]:
    """
    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 chunk

def _handle_sync_response(self, **kwargs) -> LLMResult:
    return LLMResult(**response)

Предварительный подсчёт входных токенов

Если ваша модель не предоставляет интерфейс для подсчёта токенов, просто верните 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

Также вы можете вызвать self._get_num_tokens_by_gpt2(text: str) из базового класса AIModel, который использует токенизатор 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, распознаваемым средой выполнения. Это позволяет Интеллос обрабатывать различные ошибки стандартизированным образом: Ошибки среды выполнения:

•	`InvokeConnectionError`
•	`InvokeServerUnavailableError`
•	`InvokeRateLimitError`
•	`InvokeAuthorizationError`
•	`InvokeBadRequestError`

@property
def _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 Интеллос error for consistent handling.
    """
    # return {
    #   InvokeConnectionError: [requests.exceptions.ConnectionError],
    #   ...
    # }

Подробнее о методах интерфейса см. в документации по моделям. Чтобы посмотреть полные файлы кода, рассмотренные в этом руководстве, перейдите в репозиторий на GitHub.

3. Отладьте плагин

После завершения разработки протестируйте плагин, чтобы убедиться, что он работает корректно. Подробнее см.:

Отладка плагина

4. Опубликуйте плагин

Если вы хотите разместить этот плагин в Интеллос Маркетплейс, см.: Публикация в Интеллос Маркетплейс

Изучить дополнительно

Быстрый старт:

Документация по эндпоинтам плагинов:

Edit this page | Report an issue

Начало работы

Возможности и спецификации

Руководства и примеры разработки

Интеграция пользовательских моделей

Интеграция плагина пользовательской модели

1. Создайте файл поставщика модели

2. Разработайте код модели

3. Отладьте плагин

Отладка плагина

4. Опубликуйте плагин

Изучить дополнительно

​Интеграция плагина пользовательской модели

​1. Создайте файл поставщика модели

​2. Разработайте код модели

​3. Отладьте плагин

Отладка плагина

​4. Опубликуйте плагин

​Изучить дополнительно

Интеграция плагина пользовательской модели

1. Создайте файл поставщика модели

2. Разработайте код модели

3. Отладьте плагин

4. Опубликуйте плагин

Изучить дополнительно