Estimador de Token

  # Integração do Estimador Tiktoken

Estimar a contagem de tokens para texto usando a biblioteca tiktoken, permitindo a contagem precisa de tokens para modelos OpenAI .

## Recursos

- Contagem precisa de tokens**: Usa a biblioteca oficial tiktoken para fornecer estimativas precisas de tokens
- Suporte a vários modelos**: Suporta vários modelos OpenAI (gpt-3.5-turbo, gpt-4, etc.)
- **Limites de segurança**: Verificação opcional do limite de segurança para evitar excessos de token
- Configuração zero**: Não é necessária nenhuma configuração - funciona de imediato
- **Tratamento de erros**: Tratamento gracioso de erros com mensagens descritivas

## Utilização

### Estimativa de Tokens Ação

A integração fornece uma única ação: `estimateTokens`

**Parâmetros de entrada:**
- `text` (obrigatório): O texto para estimar os tokens
- `model` (opcional): O modelo OpenAI a ser usado para tokenização (o padrão é "gpt-3.5-turbo")
- `safetyLimit` (opcional): Limite de segurança para estimativa de contagem de tokens. Se deixado vazio, nenhum limite será aplicado

**Saída:**
- `tokenCount`: O número estimado de tokens no texto
- `tokenizerName`: O nome do tokenizador utilizado
- `model`: O modelo no qual a tokenização foi baseada
- `limitExceeded`: Indica se a contagem estimada de tokens excedeu o limite de segurança (presente apenas quando safetyLimit é fornecido)

### Exemplo de uso

**Uso básico:**
```
Texto: "Olá, mundo!"
Modelo: "gpt-3.5-turbo"

Resultado:
- tokenCount: 4
- tokenizerName: "tiktoken"
- modelo: "gpt-3.5-turbo"
```

**Com limite de segurança:**
```
Texto: "Este é um texto mais longo que pode exceder o nosso limite de segurança..."
Modelo: "gpt-3.5-turbo"
Limite de segurança: 10

Resultado:
- tokenCount: 15
- tokenizerName: "tiktoken"
- modelo: "gpt-3.5-turbo"
- limitExceeded: true
```

## Modelos suportados

- `gpt-3.5-turbo`
- `gpt-4`
- `gpt-4-turbo`
- `texto-davinci-003`
- `texto-davinci-002`
- `code-davinci-002`
- E outros modelos OpenAI suportados pelo tiktoken

## Limites de segurança recomendados

Ao definir limites de segurança, considere que suas chamadas de API reais incluirão tokens adicionais para prompts do sistema, histórico de conversas e geração de respostas. Aqui estão as recomendações conservadoras:

### GPT.5-Turbo (limite de 4.096 tokens)
- **Conservador**: 2.500 tokens (deixa ~1.600 para prompts do sistema + resposta)
- Moderado**: 3.000 tokens (deixa ~1.100 para prompts do sistema + resposta)
- Agressivo**: 3.500 tokens (deixa ~600 para prompts do sistema + resposta)

### GPT(limite de 8.192 tokens)
- **Conservador**: 5.000 tokens (deixa ~3.200 para prompts do sistema + resposta)
- **Moderado**: 6.000 tokens (deixa ~2.200 para avisos do sistema + resposta)
- Agressivo**: 7.000 tokens (deixa ~1.200 para avisos do sistema + resposta)

### GPT Turbo (limite de 128.000 tokens)
- Conservador**: 100.000 tokens (deixa ~28.000 para prompts do sistema + resposta)
- **Moderado**: 110.000 tokens (deixa ~18.000 para prompts do sistema + resposta)
- Agressivo**: 120.000 tokens (deixa ~8.000 para prompts do sistema + resposta)

**Nota**: Estas recomendações assumem tamanhos típicos de prompts do sistema (200-800 tokens) e comprimentos de resposta desejados (500-2.000 tokens). Ajuste com base no seu caso de utilização específico.

## Tratamento de erros

A integração lida com vários cenários de erro:

- **Entrada inválida**: Devolve mensagens de erro claras para texto em falta ou inválido
- Texto vazio**: Devolve 0 tokens para cadeias de caracteres vazias
- Modelo não suportado**: Retorna erro para modelos não suportados pelo tiktoken
- Erros de Tokenização**: Lida com erros da biblioteca tiktoken de forma graciosa
- Avisos de limite de segurança**: Registra avisos quando a contagem de tokens excede os limites de segurança

## Benefícios

- Otimização de custos**: Estimativa de custos de token antes de fazer chamadas de API
- Limitação de taxa**: Gerir os orçamentos dos tokens e evitar excessos com limites de segurança
- Lógica de fluxo de trabalho**: Ativar a lógica condicional com base em contagens de tokens e limites de segurança
- Transparência**: Fornecer visibilidade dos padrões de utilização de tokens
- Monitorização proactiva**: Definir limites de segurança para detetar precocemente potenciais excessos de tokens