Preparação de Conhecimento — Administração

A geração de ativos de conhecimento funciona sozinha — mas é o administrador quem define o tom, quem pode aprovar, quanta capacidade de IA o lote consome e o momento em que o conteúdo aprovado passa a valer para os usuários do chat. Este guia reúne tudo o que você controla: permissões, prompts por contexto, limites de geração, prioridade em relação ao chat interativo, liga/desliga do consumo, recursos de instalação e o que fazer quando algo trava.

Arquitetura: Arquitetura — Knowledge Preparation. API de exportação externa: API de Exportação de Conhecimento. Guia do usuário: Geração de Ativos de Conhecimento — Guia do Usuário.

1. Permissões

As permissões da funcionalidade ficam no catálogo central de permissões da plataforma, na categoria KNOWLEDGE, e vêm mapeadas assim nas roles padrão:

A regra vale no servidor, em duas camadas: a cadeia de filtros exige a autoridade correspondente antes de a requisição chegar ao código, e uma segunda verificação de permissão roda no próprio serviço. A interface apenas espelha o que o servidor já decide.

Integrações internas da plataforma — como a cascata disparada quando um documento é substituído por versão mais nova — autenticam-se com o token interno de serviço e recebem um subconjunto seguro: visualizar, gerar e aprovar, nunca excluir nem exportar.

2. Prompts de conhecimento por contexto

Cada contexto tem quatro prompts próprios que governam a geração:

• Semeadura automática: ao criar um contexto, os quatro prompts nascem com o texto padrão. A semeadura é idempotente e nunca sobrescreve uma customização existente.
• Onde ficam: no índice datta_prompts, com cache em datta:prompts:{dominio}:{tipo} e TTL de 30 minutos.
• Customização: os prompts são lidos com PROMPT_VIEW e editados com PROMPT_EDIT pela interface de prompts do contexto, sempre com a opção de restaurar o padrão. Os três endpoints correspondentes (ler, customizar, restaurar) estão na referência de API.
• Defaults: vêm dos textos padrão embarcados na plataforma. Não existem arquivos de prompt de conhecimento por domínio no repositório — todo contexto usa o padrão genérico até você customizá-lo pela tela.

Cuidado ao customizar: os prompts exigem que o modelo devolva JSON com as citações de trecho por item (chunkIdsOrigem) — é isso que permite a validação de fontes. Remover essa exigência faz a validação descartar todo o conteúdo, e o tipo falha com "nenhum item com citações válidas".

3. Capacidade e limites de geração

Os padrões equilibram velocidade e consumo de IA. Todos são ajustáveis na instalação, sob o prefixo datta.knowledge.*:

E, do lado da exportação para sistemas externos:

Prioridade: o chat interativo nunca espera

As gerações em lote rodam em uma pista de baixa prioridade de acesso à IA, separada do chat: a chamada só entra nessa pista quando marcada como lote — sem a marcação, ela é tratada como interativa e passa direto, sem fila.

Quando a pista satura — fila cheia ou espera acima do limite — a chamada recebe HTTP 429 com Retry-After e um corpo indicando o motivo (queue_full ou wait_timeout) e quantos segundos esperar. O acompanhamento fica nas métricas llm_lane_wait_ms{lane=batch}, llm_lane_inflight{lane} e llm_lane_rejected_total{lane,reason}.

Dimensionamento na prática: com 2 chamadas simultâneas na pista, 3 documentos em paralelo e até 3 tipos por documento, a preparação de conhecimento enfileira no máximo ~9 chamadas — a fila de 100 absorve com folga. O gargalo é intencional: ele está no semáforo de concorrência, e existe justamente para que o usuário do chat nunca espere atrás de um lote.

4. Consumo pelo chat (liga/desliga por contexto)

Aprovar um ativo o torna elegível para a busca do chat, mas o chat só passa a consultá-lo quando o contexto tem o consumo de ativos de conhecimento ligado na configuração de domínio (useKnowledgeAssets, desligado por padrão; o endpoint de atualização do contexto está na referência de API).

• A publicação no índice de retrieval acontece em toda aprovação, item a item, com identificador determinístico por ativo e ordem; depreciar um ativo remove todos os seus itens.
• Com a opção desligada, a lista de índices consultada pela busca é byte-idêntica ao comportamento anterior à funcionalidade — nada muda para os usuários.
• Com a opção ligada, os ativos aprovados entram no retrieval daquele contexto; a mudança propaga em até 5 minutos (cache datta:chat:knowledge-optin:{dominio}).
• Buscas que cruzam vários contextos por curinga sempre excluem os índices de conhecimento — um contexto nunca herda o conhecimento de outro sem ter optado por ele.

Interruptor geral: a publicação vem ligada por padrão (datta.knowledge.retrieval.enabled=true); em false, ela é suspensa sem bloquear as aprovações (elas passam apenas a registrar a intenção no log). A publicação é best-effort: falha de vetorização ou de indexação não desfaz a aprovação. Acompanhe knowledge_retrieval_publish_total{outcome=error} e reaprove ou republique quando o gerador de vetores voltar — republicar sobrescreve, não duplica.

5. Onde o conhecimento fica armazenado

O sufixo do índice de retrieval (conhecimento) e o nome do índice-mestre são configuráveis na instalação.

6. Instalação e recursos

Memória mínima de 1Gi, sem exceção: a subida da aplicação com o agente de telemetria leva cerca de 190 segundos e não cabe em 512Mi — o serviço morre no boot. As sondas de readiness e liveness ficam nos caminhos padrão de saúde da plataforma.

Pré-requisito de cache: a preparação de conhecimento usa o banco lógico 17 do cache da plataforma (o primeiro livre — de 1 a 16 já estão alocados). A instalação já configura 32 bancos lógicos; instalações antigas, limitadas a 16, fazem o serviço falhar ao conectar. Para conferir quantos bancos o cache expõe, consulte CONFIG GET databases no próprio cache.

Variáveis de ambiente relevantes:

Atenção: a configuração de instalação exporta OPENSEARCH_URI, mas a preparação de conhecimento lê OPENSEARCH_URL. Na prática vale o padrão http://opensearch:9200; para apontar para outro OpenSearch, defina OPENSEARCH_URL explicitamente.

As chamadas da funcionalidade chegam pela borda da plataforma e são roteadas para a preparação de conhecimento; os prompts de conhecimento têm rota própria, atendida pelo repositório de prompts. Todos os endpoints estão na referência de API.

7. Observabilidade

Os eventos de auditoria saem em log estruturado (índices otel-logs-*): KNOWLEDGE.EXPORTED, KNOWLEDGE.EXPORT_DENIED, KNOWLEDGE.ASSET_EDITED e KNOWLEDGE.ASSET_STATUS_LOTE. A linhagem dos ativos (ASSET_*) é publicada no fluxo lineage:events e consumida pelo catálogo da plataforma.

8. Solução de problemas

Erros 429 em cadeia na geração

1. Distinga a origem. O 429 da pista de lote traz no corpo o motivo (queue_full ou wait_timeout). O 429 do provedor de IA (cota do Gemini por minuto) aparece nos logs da camada de acesso aos modelos e é re-tentado automaticamente — primeiro pela própria pista, depois pela preparação de conhecimento, com espera progressiva de 2s a 30s.
2. Se persistir: reduza KNOWLEDGE_MAX_CONCURRENT_GENERATIONS de 3 para 1 ou diminua o tamanho do lote; confira a cota da chave Gemini; em ambientes isolados, use o provedor local (datta.llm.provider=vllm).
3. Confirme pelo dado: crescimento de llm_lane_rejected_total em queue_full indica lote grande demais para 2 chamadas simultâneas.

Lote de geração "preso"

• O estado vive na instância que criou o lote, com uma cópia no banco lógico 17 do cache (datta:knowledge:task:{taskId}, TTL de 6 horas). Um reinício do serviço no meio do lote interrompe a geração: a cópia para de avançar, mas o acompanhamento continua devolvendo o último estado até o TTL expirar.
• Diagnóstico: procure nos logs da preparação de conhecimento por "Lote de geracao" e liste as chaves datta:knowledge:task:* no banco lógico 17 do cache.
• Recuperação: dispare um novo lote apenas com os documentos faltantes. A gravação é idempotente por versão — nada é corrompido, e a nova execução cria versões novas somente do que rodar.

Índice datta-knowledge-assets ausente ou com mapping errado

• O índice é criado na subida do serviço; se o OpenSearch estiver fora do ar, a criação é tentada de novo no primeiro acesso. Confirme no log a linha "Indice datta-knowledge-assets criado com mapping explicito".
• Nunca deixe o índice nascer por indexação dinâmica: os campos viram tipo textual e os filtros exatos param de casar, silenciosamente. Se já aconteceu, apague o índice vazio e reinicie o serviço, ou recrie-o com o mapping correto e reindexe.

Geração devolve aviso em vez de conteúdo

• Quando a IA está indisponível (chave Gemini ausente, provedor local desligado), a camada de modelos devolve a indisponibilidade como conteúdo amigável, não como erro HTTP. A preparação de conhecimento reconhece as mensagens de autenticação e falha o item com o texto original — confira a chave em Sistema›Data Layer›LLM / vLLM, que é a fonte efetiva.

Listagens ou indicadores desatualizados

• Caches: listagem com 60 segundos em memória mais 5 minutos no cache da plataforma; indicadores com 30 segundos em memória mais 60 segundos no cache. Ambos são invalidados em qualquer mutação.
• Se um valor ficar defasado além disso, inspecione as chaves datta:knowledge:* no banco lógico 17 e apague seletivamente as do domínio — nunca limpe o banco inteiro sem selecionar explicitamente o 17.