> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Rerank e Moderations

> Reordene documentos por relevância para uma consulta e modere textos com base em categorias de segurança pelos endpoints de rerank e moderations do AI Gateway.

Consulte [URLs e autenticação HTTP](/docs/pt-BR/reference/base-urls.md) e a referência da API para os formatos completos de solicitação e resposta.

**Casos de uso**

* Reordenar os resultados de uma busca inicial para que os documentos mais relevantes apareçam primeiro.
* Melhorar a qualidade das respostas de RAG pontuando cada documento diretamente em relação à consulta.
* Verificar a entrada do usuário ou a saída gerada em busca de conteúdo nocivo antes de exibi-la.

***

## Rerank

### Visão geral

O **AI Gateway** expõe `POST /rerank` na base URL da [API compatível com a OpenAI](/docs/pt-BR/ai-gateway/features/openai-compatible-api.md) (`https://router.toqan.ai/eu/v3/router`). Envie uma `query` e uma lista de `documents` e receba os documentos ordenados por relevância em relação à consulta. O reranking reordena os resultados de uma recuperação inicial (por exemplo, uma busca vetorial ou por palavras-chave) com um modelo cross-encoder, um modelo que lê a consulta e cada documento em conjunto. Isso é mais lento, porém mais preciso do que comparar apenas embeddings.

A solicitação exige três campos: `query`, `documents` e `model`. Envie no máximo 1,000 documentos em uma única solicitação.

### Início rápido

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/rerank \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cohere/rerank-v4.0-pro",
    "query": "What is the capital of France?",
    "documents": [
      "Paris is the capital of France.",
      "Berlin is the capital of Germany.",
      "London is the capital of the United Kingdom."
    ]
  }'
```

Consulte [Modelos compatíveis](/docs/pt-BR/ai-gateway/supported-models.md) para ver os modelos de rerank disponíveis pelo gateway.

### Resposta

Cada entrada do array `results` contém:

| Campo | Descrição |
| - | - |
| `index` | Posição do documento no array `documents` original |
| `relevance_score` | Relevância do documento em relação à consulta, normalizada no intervalo `[0, 1]`. Pontuações próximas de 1 indicam alta relevância. |
| `document` | Opcional. O texto original do documento, contendo um campo `text`. Retornado apenas quando `return_documents` é `true`. |

Os resultados são ordenados por `relevance_score` em ordem decrescente, de modo que o documento mais relevante vem primeiro. Passe `top_n` para limitar o número de resultados retornados; o padrão é o tamanho total de `documents`. Passe `return_documents: true` para incluir o texto original do documento em cada resultado.

### Rerank e busca em Knowledge Base

A [busca em Knowledge Base](/docs/pt-BR/ai-gateway/features/knowledge-bases.md) já oferece reranking: o endpoint `search-knowledge-base` aceita um objeto `rerank_config` e retorna um `rerank_score` junto com o `search_score` para cada chunk recuperado.

Campos de `rerank_config`:

* **`model`**: o modelo de rerank a ser usado
* **`top_k`**: número de resultados principais a retornar após o reranking; o padrão é o `top_k` da Knowledge Base
* **`threshold`**: retorna apenas documentos com pontuação de relevância acima desse valor; o padrão é `0`

Onde o reranking é executado:

* **Dentro de uma Knowledge Base**: passe `rerank_config` quando a recuperação permanecer dentro do gateway.
* **Diretamente via `POST /rerank`**: chame o endpoint quando os candidatos iniciais vierem de um armazenamento externo, por exemplo, um banco de dados vetorial de terceiros, e apenas a ordenação final deva ocorrer no gateway.

## Moderations

### Visão geral

O **AI Gateway** expõe `POST /moderations` na base URL da [API compatível com a OpenAI](/docs/pt-BR/ai-gateway/features/openai-compatible-api.md) (`https://router.toqan.ai/eu/v3/router`). Envie um texto e receba classificações de segurança: para cada entrada, a resposta informa se ela foi `flagged` e, por categoria, um veredito booleano em `categories` e uma pontuação de confiança em `category_scores`.

A solicitação exige `input`; o padrão de `model` é `openai/omni-moderation-latest`. Outros modelos disponíveis incluem `mistral/mistral-moderation-2603`.

### Início rápido

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/moderations \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/omni-moderation-latest",
    "input": "I want to hurt someone"
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const moderation = await client.moderations.create({
  model: "openai/omni-moderation-latest",
  input: "I want to hurt someone",
});

console.log(moderation.results[0]);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

moderation = client.moderations.create(
    model="openai/omni-moderation-latest",
    input="I want to hurt someone",
)

print(moderation.results[0])
```

### Resposta

Cada entrada do array `results` corresponde a uma entrada e contém:

| Campo | Descrição |
| - | - |
| `flagged` | `true` quando qualquer categoria é sinalizada |
| `categories` | Veredito booleano por categoria |
| `category_scores` | Pontuação de confiança por categoria |

As categorias incluem `hate`, `harassment`, `illicit`, `self-harm`, `sexual`, `violence` e suas subcategorias, como `hate/threatening` e `self-harm/intent`. Use `flagged` ou as pontuações de cada categoria para decidir o que a aplicação faz, por exemplo, bloquear saídas acima de um limite de pontuação de `violence`.

> [!NOTE]
>
> Os nomes e as pontuações das categorias variam conforme o modelo. Os modelos compatíveis com a OpenAI retornam o conjunto de 13 categorias acima. Os modelos da Mistral (`mistral/mistral-moderation-*`) retornam um conjunto próprio: `sexual`, `hate_and_discrimination`, `violence_and_threats`, `dangerous_and_criminal_content`, `selfharm`, `health`, `financial`, `law`, `pii`.

### Moderations vs. Guardrails

Moderations é um **endpoint de pontuação**: ele classifica textos e retorna pontuações. Ele não bloqueia nada, e o chamador decide o que fazer com o resultado.

Os [Guardrails](/docs/pt-BR/ai-gateway/configuration/guardrails.md) são a camada de **aplicação**: evaluators do tipo LLM-as-a-Judge ou Python associados a [Guardrail Rules](/docs/pt-BR/ai-gateway/configuration/guardrail-rules.md) que bloqueiam automaticamente solicitações e respostas não conformes antes que cheguem ao chamador. Use moderations quando a própria aplicação inspecionar ou agir com base nas pontuações, e guardrails quando o gateway precisar aplicar a política sem código na aplicação.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.