UltraGXNarrativa com IA
O pipeline documenta a KB com regras determinísticas. A narrativa é uma etapa opcional que adiciona, a cada documento, prosa escrita por um modelo de linguagem: o propósito do objeto, um resumo, a intenção de cada evento, as regras explicadas em termos de negócio, notas para a migração e um glossário.
O que a diferencia de colar o código em um chat é a validação: o modelo recebe o documento já analisado (não o GeneXus bruto) e o UltraGX verifica se cada atributo, tabela, variável ou objeto citado existe realmente nesse objeto. Se o modelo inventar um nome, ele é solicitado a corrigir; se insistir, a prosa não é publicada.
A narrativa é executada sobre um projeto já gerado pelo pipeline.
Conexões
Uma conexão é um provedor, um modelo e suas credenciais, guardados com um nome. Você pode ter várias (por exemplo, uma conta da empresa e um modelo local) e escolher qual usar em cada execução.
- Em Conexão, clique em + Nova e digite um nome.
- Escolha o Provedor. O Modelo e a URL base são preenchidos com valores padrão que você pode alterar.
- Cole a API key desta conexão, ou marque Roda local se você usa um modelo no seu computador ou na sua rede.
- As alterações são salvas ao executar. Excluir remove a conexão selecionada.
| Provedor | Modelo padrão | Observações |
|---|---|---|
| Anthropic (Claude) | claude-sonnet-5 | Ótima qualidade de prosa e de respeito aos nomes |
| OpenAI (GPT) | gpt-4o-mini | |
| Google (Gemini) | gemini-3.8-flash | Contexto amplo e rápido; boa opção para KBs grandes |
| DeepSeek, Zhipu (GLM), Moonshot (Kimi), Alibaba (Qwen) | conforme o provedor | Aceitam Roda local se o modelo estiver na sua própria infraestrutura |
| Google (Gemma) | gemma3:latest | Pensado para rodar localmente |
| OpenRouter | um modelo do seu catálogo | Uma única chave para muitos modelos |
| mock (sem modelo) | — | Gera texto de teste, sem custo; serve para verificar o fluxo |
Modelos locais
Com Roda local, a API key fica oculta e a URL base aponta para o seu servidor compatível com OpenAI: http://localhost:11434/v1 para Ollama, http://localhost:1234/v1 para LM Studio, ou o endereço de outra máquina da sua rede. Instale e baixe o modelo nesse servidor antes de executar (por exemplo ollama pull qwen3.6).
Com um modelo local nenhum documento sai da sua rede. A contrapartida é a velocidade e o tamanho do contexto: se o modelo tiver uma janela de contexto pequena, reduza Caracteres do documento enviados ao modelo para 16.000 ou menos.
Onde as chaves ficam guardadas
As API keys ficam guardadas no arquivo de configurações do UltraGX (%APPDATA%\UltraGX\settings.json no Windows, ~/.config/UltraGX/settings.json no Linux e no macOS), dentro do seu perfil de usuário. Elas não são gravadas na pasta de saída nem enviadas ao UltraGX. Trate esse arquivo como um segredo.
Opções da execução
| Opção | O que faz |
|---|---|
| Projeto | o projeto a narrar |
| Idioma | idioma da prosa (convém usar o mesmo do projeto) |
| Concorrência | objetos em paralelo. Com provedores na nuvem, 4 a 8 acelera bastante; com um modelo local, 1 |
| Tipos | tipos de objeto a narrar, separados por vírgula (por exemplo procedure,transaction,webpanel). Vazio = todos os tipos com lógica |
| Limite | quantidade máxima de objetos nesta execução (0 = todos). Útil para testar com 10 objetos antes de lançar a KB inteira |
| Caracteres do documento enviados ao modelo | tamanho máximo de cada documento enviado (60.000 por padrão). Documentos mais longos são cortados |
Com Tipos vazio, o UltraGX não narra as declarações: atributos, domínios, SDTs, grupos de subtipos, objetos externos, data views e configurações de padrões. O documento determinístico delas já diz tudo o que há a dizer, e narrá-las só gasta tokens. Se mesmo assim quiser narrar alguma, escreva-a em Tipos.
Executar, acompanhar e retomar
Clique em Executar / retomar. O log mostra cada objeto com seu resultado. Cada resposta é incorporada ao seu documento na hora: você pode abrir o objeto no Visualizador (com Recarregar) enquanto a execução continua, e o visualizador completo é regenerado periodicamente e ao final.
Se você parar a execução ou ela for interrompida, clique de novo em Executar / retomar: os objetos já narrados não são enviados novamente.
Resultados por objeto
| Status | O que significa | É publicado |
|---|---|---|
ok | a prosa passou na validação | sim, na seção Significado de negócio e nas seções correspondentes |
degraded | depois das novas tentativas, o modelo continuou citando nomes que não existem no objeto | não; o documento mostra um aviso com os nomes inventados |
error | o provedor falhou (chave inválida, cota esgotada, resposta inválida, tempo esgotado) | não |
Repetir degradados / erros processa novamente só esses objetos. Os erros transitórios do provedor (limites de taxa, erros 5xx, quedas de rede) já são repetidos automaticamente com espera progressiva durante a execução.
O status de todos os objetos está na página Narrativa do visualizador e na coluna Narrativa da lista de objetos.
Custos e privacidade
- Cada objeto é uma chamada ao modelo com o seu documento completo (até o limite de caracteres). Para estimar o custo, execute com Limite 20, veja os tokens que o log informa no final e extrapole para a quantidade de objetos com lógica da sua KB.
- Com provedores na nuvem, o documento de cada objeto (incluindo o seu código GeneXus) é enviado a esse provedor com a sua conta e sob as condições dele. Se a KB tiver restrições de confidencialidade, use um modelo local ou um provedor aprovado pela sua organização.
- Na edição demo, só os objetos da amostra são narrados.