Geração de Ativos de Conhecimento — Guia do Usuário

Um documento normativo de 80 páginas responde a qualquer dúvida — desde que alguém tenha tempo de lê-lo inteiro. A Geração de Ativos de Conhecimento transforma documentos já ingeridos em um contexto em material pronto para consulta: uma versão reescrita em linguagem simples, um FAQ e um glossário de termos e siglas. Tudo nasce como rascunho e só entra em uso depois de revisado e aprovado por uma pessoa — você ganha escala sem perder o controle.

Este guia cobre a geração e o ciclo de vida dos ativos. A revisão e a aprovação têm guia próprio: Curadoria de Conhecimento. A arquitetura da funcionalidade está em Arquitetura — Knowledge Preparation.

1. O que é cada tipo de ativo

Ao pedir a geração por integração, os tipos aceitam tanto o nome minúsculo acima quanto o nome do enum (DOCUMENTO_OTIMIZADO, FAQ, GLOSSARIO).

2. Fontes citadas — por que você pode confiar

A geração usa ancoragem estrita nas fontes: o modelo de linguagem recebe somente o texto do documento (os trechos já indexados, identificados por [chunk:<id>]) e é obrigado a citar, em cada seção, pergunta/resposta e termo, os trechos de origem (chunkIdsOrigem) que fundamentam aquele item.

Depois da geração, uma validação programática (não feita por IA) confere cada citação contra os trechos reais do documento:

• citação de trecho inexistente é removida;
• item sem nenhuma citação válida é descartado;
• se nenhum item sobrar, aquele tipo falha para aquele documento com motivo legível ("O modelo não produziu conteúdo aproveitável...") — sem derrubar o restante do lote.

Na tela de curadoria, o revisor vê o ativo lado a lado com os trechos-fonte citados, exatamente para validar essa ancoragem antes de aprovar.

3. Como disparar uma geração

A geração é disparada por integração programática — a plataforma expõe um endpoint que recebe o lote e devolve na hora um identificador de tarefa (taskId), rodando o trabalho em segundo plano. Os contratos estão na referência de API. Na tela de curadoria não há botão de geração em lote: de lá você dispara apenas a re-geração pontual de um ativo específico.

Requer a permissão KNOWLEDGE_ASSET_GENERATE (perfis admin e steward/ADVANCED_USER por padrão).

Regras do lote:

• o contexto de destino é obrigatório (campo dominio) — nunca é adivinhado;
• os documentos (documentCodes) são opcionais: em branco, entram todos os documentos do contexto que já tenham trechos indexados, com limite de 50 documentos por lote (configurável). Lote maior recebe uma mensagem em português pedindo para dividir;
• os tipos (tipos) são opcionais: em branco, os três são gerados.

Acompanhando o progresso

O acompanhamento em tempo real é um fluxo de eventos (text/event-stream, evento generation-progress) que emite o estado da tarefa a cada mudança: a fase (descobrindo-documentos, gerando), total, processados, falhas, ativosGerados, as últimas mensagens (ex.: "«Portaria X»: faq v1 gerado com 8 item(ns).") e o estado final COMPLETED ou FAILED.

O estado da tarefa fica disponível por 6 horas e sobrevive a reconexões. Depois disso, a consulta devolve NOT_FOUND com a mensagem "Tarefa não encontrada ou expirada.".

Re-geração

A re-geração cria uma nova versão (mesmo documento, mesmo tipo) — a versão anterior não é alterada. Ela também acontece automaticamente pela cascata de fontes monitoradas: quando um documento é substituído na origem, a plataforma deprecia os ativos aprovados da versão antiga e gera ativos novos para a nova versão, que voltam à fila de curadoria.

4. Exemplo prático — do documento ao FAQ aprovado

1. O contexto de normas recebeu a "Instrução Normativa 2.055" pela ingestão de URL. A ingestão terminou e os trechos estão indexados.
2. Um usuário com permissão de geração dispara um lote para esse contexto pedindo os três tipos de ativo, e recebe o identificador da tarefa.
3. Enquanto o lote roda, o acompanhamento mostra a fase e o placar: 1 documento, 3 ativos gerados, 0 falhas — até COMPLETED.
4. Na tela de Curadoria de Conhecimento, os três rascunhos aparecem na fila de revisão. O revisor confere as citações lado a lado, ajusta uma definição do glossário e aprova com Aprovar.
5. Com a aprovação, o FAQ e o glossário passam a valer para a busca do chat — se o consumo de ativos estiver ativado no contexto.

5. Consultando ativos

A listagem paginada (com filtros por contexto, tipo e status) e o detalhe de cada ativo estão disponíveis na tela de curadoria e também por integração — veja a referência de API. A listagem devolve os itens com o total, a página e o tamanho de página pedidos.

Cada ativo carrega rastreabilidade completa: documento de origem (documentCode), trechos citados por item (chunkIdsOrigem), modelo de IA (modeloLlm) e versão do prompt (promptVersao) usados, versao do ativo, geradoEm, se houve edição humana (editadoPorHumano), quem aprovou (aprovadoPor) e o motivo registrado (reason).

6. Ciclo de vida (status)

DRAFT ──> APPROVED ──> DEPRECATED
  └─────> REJECTED

Uma transição inválida é recusada com mensagem explicando as transições permitidas. Toda mudança de status gera evento de linhagem (ASSET_APPROVED / ASSET_DEPRECATED) com o ator real.

Termos de glossário: os termos gerados aparecem no catálogo como DRAFT e não afetam a expansão de consultas do chat até serem aprovados na tela de curadoria (a resolução do chat só usa termos aprovados; a mudança propaga em até 5 minutos pelo cache).

Uso no chat/busca: ao aprovar, o ativo é indexado (com vetores semânticos) no índice de conhecimento do contexto — mas o chat só consulta esse índice se o administrador ligar a opção useKnowledgeAssets na configuração do contexto (desligada por padrão). Com a opção desligada, a busca se comporta exatamente como antes da funcionalidade.

7. Permissões

Sem a permissão, a operação é negada com mensagem em português e o acesso negado fica auditado.

8. Solução de problemas