---
title: Interfaces
slug: interfaces
createdAt: 2024-09-02T18:49:00.521Z
---

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:

```python
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.

```python
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

```python
@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.

```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]:
    """
    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.

```python
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]**

```python
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**

```python
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**

```python
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**

```python
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**

```python
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**

```python
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**

```python
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

```python
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.

```python
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.

```python
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

```python
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

```python
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.

```python
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.

```python
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.

```python
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.

```python
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.

```python
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

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

***

### LLMResult

```python
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`.

```python
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.

```python
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

```python
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

```python
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

```python
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

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

***

### RerankDocument

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