API: LLM Usage

Visão Geral

Endpoints para monitoramento de uso de LLM (tokens e custos). Permite visualizar consumo agregado por modelo, tipo de operação e período.

O tracking é feito automaticamente pelo sistema em todas as chamadas aos LLMs (Claude e OpenAI) e armazena: - Provider e modelo utilizado - Tipo de operação (Chat, Vision, Transcription, etc.) - Tokens de entrada e saída - Custo estimado (baseado na tabela de preços configurada) - Referências opcionais (MessageId, ConversationId, AgentId)

Endpoints

GET /api/admin/llm-usage/summary

Retorna um sumário agregado do uso de LLM no período especificado.

Autorização: Requer autenticação

Query Parameters:

Parâmetro	Tipo	Obrigatório	Descrição
startDate	DateTime	Não	Data inicial do período (UTC)
endDate	DateTime	Não	Data final do período (UTC)

Response (200 OK):

{
  "totalInputTokens": 1250000,
  "totalOutputTokens": 380000,
  "totalCost": 12.45,
  "totalRequests": 542,
  "byModel": [
    {
      "provider": "Anthropic",
      "model": "claude-3-5-sonnet-20241022",
      "totalRequests": 450,
      "totalInputTokens": 1000000,
      "totalOutputTokens": 300000,
      "totalCost": 9.50
    },
    {
      "provider": "OpenAI",
      "model": "gpt-4o-mini",
      "totalRequests": 92,
      "totalInputTokens": 250000,
      "totalOutputTokens": 80000,
      "totalCost": 2.95
    }
  ],
  "byOperationType": [
    {
      "operationType": "Chat",
      "totalRequests": 480,
      "totalTokens": 1500000,
      "totalCost": 11.00
    },
    {
      "operationType": "Vision",
      "totalRequests": 62,
      "totalTokens": 130000,
      "totalCost": 1.45
    }
  ],
  "startDate": "2024-01-01T00:00:00Z",
  "endDate": "2024-01-31T23:59:59Z"
}

---

GET /api/admin/llm-usage

Retorna uma lista paginada de registros individuais de uso de LLM.

Autorização: Requer autenticação

Query Parameters:

Parâmetro	Tipo	Obrigatório	Descrição
startDate	DateTime	Não	Data inicial do período (UTC)
endDate	DateTime	Não	Data final do período (UTC)
provider	string	Não	Filtrar por provider (Anthropic, OpenAI)
model	string	Não	Filtrar por modelo específico
operationType	string	Não	Filtrar por tipo de operação
agentId	Guid	Não	Filtrar por agente
page	int	Não	Página (default: 1)
pageSize	int	Não	Itens por página (default: 50, max: 100)

Response (200 OK):

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenantId": "110e8400-e29b-41d4-a716-446655440099",
      "provider": "Anthropic",
      "model": "claude-3-5-sonnet-20241022",
      "operationType": "Chat",
      "inputTokens": 2500,
      "outputTokens": 450,
      "estimatedCost": 0.0125,
      "messageId": "660e8400-e29b-41d4-a716-446655440001",
      "conversationId": "770e8400-e29b-41d4-a716-446655440002",
      "agentId": "880e8400-e29b-41d4-a716-446655440003",
      "createdAt": "2024-01-20T14:30:00Z"
    }
  ],
  "totalCount": 542,
  "page": 1,
  "pageSize": 50,
  "totalPages": 11
}

---

Tipos de Operação (LlmOperationType)

Valor	Descrição
Chat	Resposta em conversa (ProcessMessageHandler)
Vision	Descrição de imagem via Claude Vision
Transcription	Transcrição de áudio via OpenAI Whisper
Embedding	Geração de embeddings para busca semântica
Chunking	Processamento de knowledge blocks
Playground	Testes no playground do agente

---

Providers (LlmProvider)

Valor	Descrição
Anthropic	Claude API
OpenAI	OpenAI API

---

Configuração de Preços

Os preços são configurados em appsettings.json na seção LlmPricing:

{
  "LlmPricing": {
    "Models": [
      { "Model": "claude-opus-4-5-20251101", "InputPricePerMillion": 5.00, "OutputPricePerMillion": 25.00 },
      { "Model": "claude-sonnet-4-5-20251001", "InputPricePerMillion": 3.00, "OutputPricePerMillion": 15.00 },
      { "Model": "claude-haiku-4-5-20251001", "InputPricePerMillion": 1.00, "OutputPricePerMillion": 5.00 },
      { "Model": "claude-3-5-sonnet-20241022", "InputPricePerMillion": 3.00, "OutputPricePerMillion": 15.00 },
      { "Model": "gpt-4-turbo", "InputPricePerMillion": 10.00, "OutputPricePerMillion": 30.00 },
      { "Model": "gpt-4o", "InputPricePerMillion": 2.50, "OutputPricePerMillion": 10.00 },
      { "Model": "gpt-4o-mini", "InputPricePerMillion": 0.15, "OutputPricePerMillion": 0.60 },
      { "Model": "gpt-3.5-turbo", "InputPricePerMillion": 0.50, "OutputPricePerMillion": 1.50 }
    ]
  }
}

---

Cálculo de Custo

O custo é calculado automaticamente pelo LlmPricingService:

EstimatedCost = (InputTokens / 1_000_000) × InputPricePerMillion
              + (OutputTokens / 1_000_000) × OutputPricePerMillion

Se o modelo não estiver configurado na tabela de preços, EstimatedCost será null.

---

Tracking Automático

O tracking é feito automaticamente em:

1. ProcessMessageHandler - Chamadas de chat com o LLM
2. ProcessMessageHandler.DescribeImageAsync - Descrição de imagens
3. (Planejado) Playground, Embeddings, Transcriptions

---

Multi-tenancy

Os dados de LlmUsage respeitam o filtro de tenant: - Cada registro tem TenantId - Query filter global filtra automaticamente por tenant - SuperAdmins podem ver dados de todos os tenants

---

Índices

A tabela llm_usages possui índices otimizados para: - Consultas por tenant e período - Consultas por tipo de operação - Consultas por agente - Consultas por conversa