Analisa a qualidade de um chunk específico e retorna uma nota de 0 a 10 baseada nas melhores práticas de chunks e relação com outros chunks similares. O advisor de chunks é responsável por garantir melhores práticas do uso dos blocos de conteúdo, otimizando a qualidade da busca semântica e dos resultados servidos à IA conversacional.

​
Visão Geral

Quando o usuário cria um novo chunk ou edita um existente, transformamos o conteúdo em embeddings e armazenamos no banco de dados. Quando o usuário faz uma pergunta, criamos os embeddings da pergunta e fazemos uma busca vetorial (cosine similarity) para encontrar os chunks mais relevantes.

​
O que a análise identifica

  • Qualidade do chunk baseado em melhores práticas
  • Relação com outros chunks semanticamente similares
  • Otimização para busca semântica
  • Qualidade dos embeddings gerados
  • Recomendações de melhoria (quando score < 5)

​
Endpoint

POST /api/externalAPIs/public/advisor/chunkAdvisor

​
Parâmetros

ParâmetroTipoDescriçãoObrigatório
chunkIdstringID do chunk a ser analisadoSim
hostIdstringID do hostSim
modelstringModelo LLM a ser usado (padrão: gpt-oss-120b)Não
providerstringProvider LLM a ser usado (padrão: cerebras)Não
completionTimeoutMsnumberTimeout em milissegundos para chamadas LLM (padrão: 60000)Não

​
Fluxo de Análise

  1. Buscar informações do chunk: Recupera os dados completos do chunk do banco de dados
  2. Criar perguntas semânticas: Usa IA para gerar perguntas semânticas sobre o conteúdo do chunk
  3. Buscar chunks similares: Utiliza as perguntas semânticas para encontrar chunks relacionados
  4. Avaliar qualidade: Analisa o chunk comparando com chunks similares e retorna nota 0-10
  5. Recomendar melhorias (se score < 5): Se a nota for menor que 5, executa uma análise adicional para identificar problemas específicos e gerar recomendações
  6. Salvar issues (se necessário): Se problemas forem identificados, cria registros na tabela advisor_issues para rastreamento

​
Exemplo de Requisição

curl -X POST {{BASE_URL}}/api/externalAPIs/public/advisor/chunkAdvisor \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chunkId": "bf047297-ff98-4b4d-b6b7-07f8f50ca36c",
    "hostId": "b302f8ad-991b-411c-beb3-12cd648c95cc"
  }'

​
Exemplo de Resposta

{
  "code": 200,
  "message": "Success",
  "data": {
    "score": 7.5,
    "fromCache": false,
    "cachedAt": "2024-01-15T10:30:00.000Z"
  }
}

​
Campos da Resposta

CampoTipoDescrição
scorenumberNota de qualidade do chunk (0 a 10)
fromCachebooleanIndica se o resultado foi retornado do cache (true) ou processado agora (false)
cachedAtstringData e hora em ISO 8601 de quando o resultado foi cacheado (sempre presente, mesmo quando fromCache é false)

​
Sistema de Cache

O endpoint implementa um sistema de cache com TTL de 40 segundos para evitar processamento duplicado. Isso significa que:

  • Se você fizer múltiplas requisições para o mesmo chunkId e hostId dentro de 40 segundos, apenas a primeira será processada
  • As requisições subsequentes retornarão o resultado em cache com fromCache: true
  • O campo cachedAt sempre indica quando o resultado foi cacheado, mesmo quando fromCache é false
  • Chave de cache: chunkAdvisor:{chunkId}:{hostId}

​
Recomendações de Melhoria

Quando a nota (score) retornada for menor que 5, o sistema automaticamente executa uma análise adicional para identificar problemas específicos e gerar recomendações. Essas recomendações são salvas na tabela advisor_issues para rastreamento e podem ser consultadas posteriormente através do endpoint insightByDemand.

​
Códigos de Erro

  • 400: Campos obrigatórios ausentes ou inválidos
  • 401: Token de autenticação inválido ou ausente
  • 404: Chunk não encontrado
  • 500: Erro interno do servidor

​
Exemplos de Uso

​
Análise básica

curl -X POST {{BASE_URL}}/api/externalAPIs/public/advisor/chunkAdvisor \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chunkId": "bf047297-ff98-4b4d-b6b7-07f8f50ca36c",
    "hostId": "b302f8ad-991b-411c-beb3-12cd648c95cc"
  }'

​
Análise com modelo customizado

curl -X POST {{BASE_URL}}/api/externalAPIs/public/advisor/chunkAdvisor \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chunkId": "bf047297-ff98-4b4d-b6b7-07f8f50ca36c",
    "hostId": "b302f8ad-991b-411c-beb3-12cd648c95cc",
    "model": "gpt-oss-120b",
    "provider": "cerebras",
    "completionTimeoutMs": 60000
  }'
Análise em Tempo RealInsight por Demanda