Interfaces

51 min

Esta seção descreve os métodos de interface e as explicações dos parâmetros que precisam ser implementados pelos provedores e diferentes tipos de modelos.

Provedor

Herdar a classe base __base.model_provider.ModelProvider e implementar as seguintes interfaces:

def validate_provider_credentials(self, credentials: dict) -> None:
    """
    Validar credenciais do provedor
    Você pode escolher qualquer método de validação de credenciais do tipo de modelo ou implementar o método de validação você mesmo,
    por exemplo: obter a API da lista de modelos

    Se a validação falhar, lance uma exceção

    :param credentials: credenciais do provedor, o formulário das credenciais é definido em `provider_credential_schema`.
    """

credentials (objeto) Informações de credenciais

Os parâmetros das informações de credenciais são definidos pelo provider_credential_schema no arquivo de configuração YAML do provedor. Incluem entradas como api_key.

Se a verificação falhar, lance o erro errors.validate.CredentialsValidateFailedError.

Modelo

Os modelos são divididos em 5 tipos diferentes, cada um herdando de diferentes classes base e exigindo a implementação de diferentes métodos.

Todos os modelos precisam implementar uniformemente os seguintes 2 métodos:

Verificação de Credenciais do Modelo

Semelhante à verificação de credenciais do provedor, esta etapa envolve a verificação para um modelo individual.

def validate_credentials(self, model: str, credentials: dict) -> None:
    """
    Validar credenciais do modelo

    :param model: nome do modelo
    :param credentials: credenciais do modelo
    :return:
    """

Parâmetros:

model (string) Nome do modelo
credentials (objeto) Informações de credenciais

Os parâmetros das informações de credenciais são definidos pelo provider_credential_schema ou model_credential_schema no arquivo de configuração YAML do provedor. Incluem entradas como api_key.

Se a verificação falhar, lance o erro errors.validate.CredentialsValidateFailedError.

Tabela de Mapeamento de Erro de Invocação

Quando há uma exceção na invocação do modelo, ela precisa ser mapeada para o tipo de InvokeError especificado pelo Runtime. Isso facilita a capacidade do Paragraph de lidar com diferentes erros com ações de acompanhamento apropriadas.

Erros de Runtime:

InvokeConnectionError Erro de conexão de invocação
InvokeServerUnavailableError Provedor de serviço de invocação indisponível
InvokeRateLimitError Limite de taxa de invocação atingido
InvokeAuthorizationError Falha na autorização da invocação
InvokeBadRequestError Erro de parâmetro de invocação

@property
def _invoke_error_mapping(self) -> dict[type[InvokeError], list[type[Exception]]]:
    """
    Mapear erro de invocação do modelo para erro unificado
    A chave é o tipo de erro lançado para o chamador
    O valor é o tipo de erro lançado pelo modelo,
    que precisa ser convertido em um tipo de erro unificado para o chamador.

    :return: Mapeamento de erro de invocação
    """

Você pode se referir ao _invoke_error_mapping do OpenAI como exemplo.

LLM

Herdar a classe base __base.large_language_model.LargeLanguageModel e implementar as seguintes interfaces:

Invocação LLM

Implementar o método central para a invocação LLM, que pode suportar tanto retornos de streaming quanto síncronos.

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]:
    """
    Invocar modelo de linguagem grande

    :param model: nome do modelo
    :param credentials: credenciais do modelo
    :param prompt_messages: mensagens de prompt
    :param model_parameters: parâmetros do modelo
    :param tools: ferramentas para chamada de ferramentas
    :param stop: palavras de parada
    :param stream: é resposta em streaming
    :param user: id único do usuário
    :return: resposta completa ou gerador de resultados de resposta em streaming
    """

Parâmetros:

model (string) Nome do modelo
credentials (objeto) Informações de credenciais

Os parâmetros das informações de credenciais são definidos pelo provider_credential_schema ou model_credential_schema no arquivo de configuração YAML do provedor. Incluem entradas como api_key.

prompt_messages (array[PromptMessage]) Lista de prompts

Se o modelo for do tipo Completion, a lista precisa incluir apenas um elemento UserPromptMessage; se o modelo for do tipo Chat, requer uma lista de elementos como SystemPromptMessage, UserPromptMessage, AssistantPromptMessage, ToolPromptMessage, dependendo da mensagem.

model_parameters (objeto) Parâmetros do modelo

Os parâmetros do modelo são definidos pelas parameter_rules no YAML de configuração do modelo.

tools (array[PromptMessageTool]) [opcional] Lista de ferramentas, equivalente à função na chamada de ferramentas.

Ou seja, a lista de ferramentas para chamada de ferramentas.

stop (array[string]) [opcional] Sequências de parada

A saída do modelo vai parar antes da string definida pela sequência de parada.

stream (bool) Se deve ser gerado em streaming, o padrão é True

A saída em streaming retorna Generator[LLMResultChunk], a saída não em streaming retorna LLMResult.

user (string) [opcional] Identificador único do usuário

Isso pode ajudar o provedor a monitorar e detectar comportamento abusivo.

Retornos:

A saída em streaming retorna Generator[LLMResultChunk], a saída não em streaming retorna LLMResult.

Pré-calculando Tokens de Entrada

Se o modelo não fornecer uma interface de tokens pré-calculados, você pode retornar diretamente 0.

def get_num_tokens(self, model: str, credentials: dict, prompt_messages: list[PromptMessage],
                   tools: Optional[list[PromptMessageTool]] = None) -> int:
    """
    Obter número de tokens para mensagens de prompt fornecidas

    :param model: nome do modelo
    :param credentials: credenciais do modelo
    :param prompt_messages: mensagens de prompt
    :param tools: ferramentas para chamada de ferramentas
    :return:
    """

Para explicações dos parâmetros, consulte a seção acima sobre Invocação LLM.

Buscar Esquema de Modelo Personalizável [Opcional]

def get_customizable_model_schema(self, model: str, credentials: dict) -> Optional[AIModelEntity]:
    """
    Obter esquema de modelo personalizável

    :param model: nome do modelo
    :param credentials: credenciais do modelo
    :return: esquema do modelo
    """

Quando o provedor suporta a adição de LLMs personalizados, este método pode ser implementado para permitir que modelos personalizados obtenham o esquema do modelo. O retorno padrão é nulo.

TextEmbedding

Herdar a classe base __base.text_embedding_model.TextEmbeddingModel e implementar as seguintes interfaces:

Invocação de Embedding

def _invoke(self, model: str, credentials: dict,
            texts: list[str], user: Optional[str] = None) \
        -> TextEmbeddingResult:
    """
    Invocar modelo de embedding de texto

    :param model: nome do modelo
    :param credentials: credenciais do modelo
    :param texts: textos para incorporar
    :param user: id único do usuário
    :return: resultado de embeddings
    """

Parâmetros:

model (string) Nome do modelo
credentials (objeto) Informações de credenciais

Os parâmetros das informações de credenciais são definidos pelo provider_credential_schema ou model_credential_schema no arquivo de configuração YAML do provedor. Incluem entradas como api_key.

texts (array[string]) Lista de textos, capaz de processamento em lote
user (string) [opcional] Identificador único do usuário

Isso pode ajudar o provedor a monitorar e detectar comportamento abusivo.

Retornos:

Entidade TextEmbeddingResult.

Pré-calculando Tokens

def get_num_tokens(self, model: str, credentials: dict, texts: list[str]) -> int:
    """
    Obter número de tokens para textos fornecidos

    :param model: nome do modelo
    :param credentials: credenciais do modelo
    :param texts: textos para incorporar
    :return:
    """

Para explicações dos parâmetros, consulte a seção acima sobre Invocação de Embedding.

Rerank

Herdar a classe base __base.rerank_model.RerankModel e implementar as seguintes interfaces:

Invocação de 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:
    """
    Invocar modelo de rerank

    :param model: nome do modelo
    :param credentials: credenciais do modelo
    :param query: consulta para rerank
    :param docs: documentos a serem reordenados
    :param score_threshold: limiar de pontuação
    :param top_n: número máximo de documentos retornados
    :param user: id único do usuário
    :return: resultado de rerank
    """

Parâmetros:

model (string) Nome do modelo
credentials (objeto) Informações de credenciais

Os parâmetros das informações de credenciais são definidos pelo provider_credential_schema ou model_credential_schema no arquivo de configuração YAML do provedor. Incluem entradas como api_key.

query (string) Consulta de rerank
docs (array[string]) Documentos a serem reordenados
score_threshold (float) [opcional] Limiar de pontuação para filtragem
top_n (int) [opcional] Número máximo de documentos retornados
user (string) [opcional] Identificador único do usuário

Isso pode ajudar o provedor a monitorar e detectar comportamento abusivo.

Retornos:

Entidade RerankResult.

Speech2text

Herde a classe base __base.speech2text_model.Speech2TextModel e implemente as seguintes interfaces:

Invocação

def _invoke(self, model: str, credentials: dict, file: IO[bytes], user: Optional[str] = None) -> str:
    """
    Invocar modelo de linguagem grande

    :param model: nome do modelo
    :param credentials: credenciais do modelo
    :param file: arquivo de áudio
    :param user: id único do usuário
    :return: texto correspondente ao arquivo de áudio
    """

Parâmetros:

model (string): Nome do modelo
credentials (objeto): Informações de credenciais

Os parâmetros das informações de credenciais são definidos pelo provider_credential_schema ou model_credential_schema no arquivo de configuração YAML do provedor. Incluem entradas como api_key.

file (File): Fluxo do arquivo
user (string) [opcional]: Identificador único do usuário

Isso pode ajudar o provedor a monitorar e detectar comportamento abusivo.

Retorno:

String após a conversão de fala para texto.

Text2speech

Herde a classe base __base.text2speech_model.Text2SpeechModel e implemente as seguintes interfaces:

Invocação

def _invoke(self, model: str, credentials: dict, content_text: str, streaming: bool, user: Optional[str] = None):
    """
    Invocar modelo de linguagem grande

    :param model: nome do modelo
    :param credentials: credenciais do modelo
    :param content_text: texto a ser traduzido
    :param streaming: se a saída será em streaming
    :param user: id único do usuário
    :return: arquivo de áudio traduzido
    """

Parâmetros:

model (string): Nome do modelo
credentials (objeto): Informações de credenciais

Os parâmetros das informações de credenciais são definidos pelo provider_credential_schema ou model_credential_schema no arquivo de configuração YAML do provedor. Incluem entradas como api_key.

content_text (string): Texto a ser convertido
streaming (bool): Se a saída será em streaming
user (string) [opcional]: Identificador único do usuário

Isso pode ajudar o provedor a monitorar e detectar comportamento abusivo.

Retorno:

Fluxo de fala convertido a partir de texto.

Moderação

Herde a classe base __base.moderation_model.ModerationModel e implemente as seguintes interfaces:

Invocação

def _invoke(self, model: str, credentials: dict, text: str, user: Optional[str] = None) -> bool:
    """
    Invocar modelo de linguagem grande

    :param model: nome do modelo
    :param credentials: credenciais do modelo
    :param text: texto a ser moderado
    :param user: id único do usuário
    :return: false se o texto for seguro, true caso contrário
    """

Parâmetros:

model (string): Nome do modelo
credentials (objeto): Informações de credenciais

Os parâmetros das informações de credenciais são definidos pelo provider_credential_schema ou model_credential_schema no arquivo de configuração YAML do provedor. Incluem entradas como api_key.

text (string): Conteúdo do texto
user (string) [opcional]: Identificador único do usuário

Isso pode ajudar o provedor a monitorar e detectar comportamento abusivo.

Retorno:

False indica que o texto é seguro, True indica o contrário.

Entidades

PromptMessageRole

Função da mensagem

class PromptMessageRole(Enum):
    """
    Enum class para a função da mensagem no prompt.
    """
    SYSTEM = "system"
    USER = "user"
    ASSISTANT = "assistant"
    TOOL = "tool"

PromptMessageContentType

Tipos de conteúdo da mensagem, divididos em texto e imagem.

class PromptMessageContentType(Enum):
    """
    Enum class para o tipo de conteúdo da mensagem no prompt.
    """
    TEXT = 'text'
    IMAGE = 'image'

PromptMessageContent

Classe base de conteúdo da mensagem, usada apenas para declaração de parâmetros e não pode ser inicializada.

class PromptMessageContent(BaseModel):
    """
    Model class para o conteúdo da mensagem no prompt.
    """
    type: PromptMessageContentType
    data: str

Atualmente, dois tipos são suportados: texto e imagem. É possível inserir simultaneamente texto e várias imagens.

Você precisa inicializar TextPromptMessageContent e ImagePromptMessageContent separadamente para inserção.

TextPromptMessageContent

class TextPromptMessageContent(PromptMessageContent):
    """
    Model class para o conteúdo de texto da mensagem no prompt.
    """
    type: PromptMessageContentType = PromptMessageContentType.TEXT

Se inserir uma combinação de texto e imagens, o texto precisa ser construído nesta entidade como parte da lista de conteúdo.

ImagePromptMessageContent

class ImagePromptMessageContent(PromptMessageContent):
    """
    Model class para o conteúdo de imagem da mensagem no prompt.
    """
    class DETAIL(Enum):
        LOW = 'low'
        HIGH = 'high'

    type: PromptMessageContentType = PromptMessageContentType.IMAGE
    detail: DETAIL = DETAIL.LOW  # Resolução

Se inserir uma combinação de texto e imagens, as imagens precisam ser construídas nesta entidade como parte da lista de conteúdo.

Os dados podem ser uma URL ou uma string codificada em base64 da imagem.

PromptMessage Classe base para todos os corpos de mensagem de função, usada apenas para declaração de parâmetros e não pode ser inicializada.

class PromptMessage(ABC, BaseModel):
    """
    Model class para a mensagem no prompt.
    """
    role: PromptMessageRole
    content: Optional[str | list[PromptMessageContent]] = None  # Suporta dois tipos: string e lista de conteúdo. A lista de conteúdo é projetada para atender às necessidades de entradas multimodais. Para mais detalhes, consulte a explicação de PromptMessageContent.
    name: Optional[str] = None

UserPromptMessage

Corpo da mensagem do usuário, representando uma mensagem do usuário.

class UserPromptMessage(PromptMessage):
    """
    Model class para a mensagem do usuário no prompt.
    """
    role: PromptMessageRole = PromptMessageRole.USER

AssistantPromptMessage

Representa uma mensagem retornada pelo modelo, normalmente usada para few-shots ou entrada de histórico de chat.

class AssistantPromptMessage(PromptMessage):
    """
    Model class para a mensagem do assistente no prompt.
    """
    class ToolCall(BaseModel):
        """
        Model class para a chamada de ferramenta na mensagem do assistente.
        """
        class ToolCallFunction(BaseModel):
            """
            Model class para a função de chamada de ferramenta na mensagem do assistente.
            """
            name: str  # nome da ferramenta
            arguments: str  # argumentos da ferramenta

        id: str  # ID da ferramenta, eficaz apenas em chamadas de ferramentas OpenAI. É o ID exclusivo para invocação da ferramenta e a mesma ferramenta pode ser chamada várias vezes.
        type: str  # padrão: função
        function: ToolCallFunction  # informações da chamada de ferramenta

    role: PromptMessageRole = PromptMessageRole.ASSISTANT
    tool_calls: list[ToolCall] = []  # O resultado da invocação de ferramentas na resposta do modelo (retornado apenas quando as ferramentas são inseridas e o modelo considera necessário invocar uma ferramenta).

Onde tool_calls é a lista de chamadas de ferramentas retornadas pelo modelo após a invocação do modelo com as ferramentas inseridas.

SystemPromptMessage

Representa mensagens do sistema, geralmente usadas para configurar comandos do sistema dados ao modelo.

class SystemPromptMessage(PromptMessage):
    """
    Model class para a mensagem do sistema no prompt.
    """
    role: PromptMessageRole = PromptMessageRole.SYSTEM

ToolPromptMessage

Representa mensagens de ferramentas, usadas para transmitir os resultados de uma execução de ferramenta ao modelo para o próximo passo do processamento.

class ToolPromptMessage(PromptMessage):
    """
    Model class para a mensagem de ferramenta no prompt.
    """
    role: PromptMessageRole = PromptMessageRole.TOOL
    tool_call_id: str  # ID de invocação da ferramenta. Se a chamada de ferramenta OpenAI não for suportada, o nome da ferramenta também pode ser inserido.

O conteúdo da classe base recebe os resultados da execução da ferramenta.

PromptMessageTool

class PromptMessageTool(BaseModel):
    """
    Model class para a ferramenta da mensagem no prompt.
    """
    name: str
    description: str
    parameters: dict

LLMResult

class LLMResult(BaseModel):
    """
    Model class para o resultado de LLM.
    """
    model: str  # Modelo realmente utilizado
    prompt_messages: list[PromptMessage]  # mensagens do prompt
    message: AssistantPromptMessage  # mensagem de resposta
    usage: LLMUsage  # informações de uso


    system_fingerprint: Optional[str] = None  # impressão digital da solicitação, consulte a definição da OpenAI

LLMResultChunkDelta

Em retornos de streaming, cada iteração contém a entidade delta.

class LLMResultChunkDelta(BaseModel):
    """
    Model class para o delta de chunk de resultado de LLM.
    """
    index: int
    message: AssistantPromptMessage  # mensagem de resposta
    usage: Optional[LLMUsage] = None  # informações de uso
    finish_reason: Optional[str] = None  # motivo da conclusão, apenas o último é retornado

LLMResultChunk

Cada entidade de iteração em retornos de streaming.

class LLMResultChunk(BaseModel):
    """
    Model class para o chunk de resultado de LLM.
    """
    model: str  # Modelo realmente utilizado
    prompt_messages: list[PromptMessage]  # mensagens do prompt
    system_fingerprint: Optional[str] = None  # impressão digital da solicitação, consulte a definição da OpenAI
    delta: LLMResultChunkDelta

LLMUsage

class LLMUsage(ModelUsage):
    """
    Model class para uso de LLM.
    """
    prompt_tokens: int  # Tokens usados para o prompt
    prompt_unit_price: Decimal  # Preço unitário para o prompt
    prompt_price_unit: Decimal  # Unidade de preço para o prompt, ou seja, o preço unitário com base em quantos tokens
    prompt_price: Decimal  # Custo para o prompt
    completion_tokens: int  # Tokens usados para a resposta
    completion_unit_price: Decimal  # Preço unitário para a resposta
    completion_price_unit: Decimal  # Unidade de preço para a resposta, ou seja, o preço unitário com base em quantos tokens
    completion_price: Decimal  # Custo para a resposta
    total_tokens: int  # Número total de tokens usados
    total_price: Decimal  # Custo total
    currency: str  # Unidade monetária
    latency: float  # Latência da solicitação (s)

TextEmbeddingResult

class TextEmbeddingResult(BaseModel):
    """
    Model class para o resultado de incorporação de texto.
    """
    model: str  # Modelo realmente utilizado
    embeddings: list[list[float]]  # Lista de vetores de incorporação, correspondente à lista de textos de entrada
    usage: EmbeddingUsage  # Informações de uso

EmbeddingUsage

class EmbeddingUsage(ModelUsage):
    """
    Model class para uso de incorporação.
    """
    tokens: int  # Número de tokens usados
    total_tokens: int  # Número total de tokens usados
    unit_price: Decimal  # Preço unitário
    price_unit: Decimal  # Unidade de preço, ou seja, o preço unitário com base em quantos tokens
    total_price: Decimal  # Custo total
    currency: str  # Unidade monetária
    latency: float  # Latência da solicitação (s)

RerankResult

class RerankResult(BaseModel):
    """
    Model class para o resultado de rerank.
    """
    model: str  # Modelo realmente utilizado
    docs: list[RerankDocument]  # Lista de documentos rerankeados

RerankDocument

class RerankDocument(BaseModel):
    """
    Model class para o documento rerankeado.
    """
    index: int  # índice original
    text: str
    score: float