Precisando de um bom exemplo para baixar e testar o ILW no Lumina V2? Criamos um passo a passo completo que vai te ajudar a entender, na prática, como utilizar nosso framework de maneira simples e eficiente.
Neste artigo, vamos usar um exemplo real, com dados integrados, workflow configurado e resultado final funcionando. A ideia é que você consiga:
– Baixar o projeto pronto
– Rodar localmente com Docker
– Entender a estrutura básica do ILW no Lumina V2
– Personalizar e expandir com seus próprios dados e fluxos
—
## O que é o ILW no Lumina V2?
O ILW (Intelligent Learning Workflow) é o framework do Lumina V2 para criação de fluxos inteligentes que combinam:
– Fontes de dados (arquivos, bancos, APIs)
– Estratégias de chunking e indexação
– Modelos de linguagem (LLMs)
– Ferramentas auxiliares (busca, ações, automações)
– Métricas de uso e monitoramento
No Lumina V2, esses componentes são organizados em um workflow visual e declarativo, que pode ser versionado e executado em diferentes ambientes (dev, staging, produção).
—
## Cenário do exemplo
O exemplo que vamos utilizar simula um assistente interno de conhecimento para uma empresa, com:
– Base de documentos institucionais (PDFs, textos, políticas internas)
– Um índice vetorial para busca semântica
– Um modelo de linguagem configurado para responder em português
– Um fluxo de orquestração que recebe a pergunta do usuário, consulta a base e retorna a resposta contextualizada
Esse é um caso muito comum em empresas que querem:
– Centralizar conhecimento interno
– Reduzir tempo de atendimento a dúvidas recorrentes
– Dar mais autonomia para times de operações, CS, vendas e suporte
—
## Arquitetura do exemplo ILW
O projeto de exemplo segue uma arquitetura simples, mas já alinhada com boas práticas do Lumina V2:
1. **Ingestão de dados**
– Leitura de documentos de uma pasta local
– Normalização (texto limpo, metadados básicos)
– Geração de chunks configuráveis (tamanho, sobreposição)
2. **Indexação**
– Criação de embeddings
– Armazenamento em um índice vetorial
– Organização por coleções e tags
3. **Runtime (execução do workflow)**
– Recebe a pergunta do usuário via API ou interface
– Faz busca semântica no índice vetorial
– Monta o contexto
– Chama o modelo de linguagem com o prompt adequado
– Retorna a resposta e as referências utilizadas
4. **Monitoramento básico**
– Logs dos inputs/outputs
– Medição simples de latência e volume de chamadas
—
## Pré-requisitos para rodar o exemplo
Antes de baixar e rodar o projeto, verifique se você tem:
– Docker e Docker Compose instalados
– Acesso ao Lumina V2 (chave de API ou credenciais de ambiente)
– Git instalado para clonar o repositório (opcional, se você preferir baixar o .zip)
Recomendamos um ambiente com pelo menos:
– 4 GB de RAM livres
– Conexão estável com a internet (para baixar imagens e dependências)
– Acesso para rodar containers Docker
—
## Baixando o projeto de exemplo
1. Acesse o repositório oficial de exemplos do Lumina V2 (link fornecido pela equipe ou documentação).
2. Localize o projeto com o nome semelhante a:
`lumina-v2-ilw-example-knowledge-base`
3. Baixe o projeto em formato `.zip` ou use:
bash
git clone https://seu-repositorio/lumina-v2-ilw-example-knowledge-base.git
cd lumina-v2-ilw-example-knowledge-base
4. Verifique a estrutura de pastas, que deve ser próxima de:
bash
.
├── docker/
├── ilw/
│ ├── workflows/
│ ├── configs/
│ └── data/
├── src/
├── .env.example
└── README.md
—
## Configurando variáveis de ambiente
Dentro do diretório do projeto:
1. Copie o arquivo de exemplo de ambiente:
bash
cp .env.example .env
2. Edite o arquivo `.env` com suas credenciais, por exemplo:
env
LUMINA_API_KEY=xxxxxxxxxxxxxxxx
LUMINA_ENV=dev
VECTOR_DB_URL=http://vector-db:8080
3. Ajuste também valores como:
– Nome do índice vetorial
– Idioma padrão das respostas
– Modelo de linguagem a ser utilizado (ex.: `gpt-4`, `gpt-4o`, ou modelo interno)
—
## Subindo o ambiente com Docker
Com o `.env` configurado, basta subir os serviços:
bash
docker compose up -d
O `docker-compose.yml` do projeto geralmente inclui:
– Serviço do ILW (orquestrador / runtime)
– Serviço de banco vetorial (quando não gerenciado externamente)
– Serviços auxiliares (web, monitoramento, etc., dependendo do exemplo)
Para verificar se está tudo rodando:
bash
docker compose ps
Você deve ver os containers em estado `running`.
—
## Carregando os dados de exemplo
O projeto vem com uma pasta de dados pré-configurada, normalmente em algo como:
bash
ilw/data/input/
Ela inclui documentos fictícios ou anonimizados, como:
– Políticas internas
– FAQs
– Guias de uso de ferramentas
– Procedimentos operacionais
Para rodar o processo de ingestão e indexação:
bash
docker compose exec ilw-service python -m ilw.ingest
Esse comando:
– Lê os arquivos da pasta de entrada
– Gera chunks
– Cria embeddings
– Popula o índice vetorial
Você verá logs indicando quantos documentos foram processados e quantos vetores foram gravados.
—
## Executando o workflow ILW
Com os dados indexados, você já pode interagir com o workflow. Normalmente, o projeto expõe uma API HTTP, por exemplo em:
bash
http://localhost:8000
Um endpoint comum é algo como:
bash
POST /ilw/ask
Enviando um JSON:
json
{
“question”: “Quais são as diretrizes para trabalho remoto na empresa?”,
“user_id”: “usuario_teste_01”
}
O serviço executará o workflow:
1. Recebe a pergunta
2. Consulta o índice vetorial
3. Monta o contexto relevante
4. Chama o modelo de linguagem
5. Devolve uma resposta estruturada, por exemplo:
json
{
“answer”: “As diretrizes para trabalho remoto incluem horários de disponibilidade, política de equipamentos e regras de segurança de informação…”,
“sources”: [
{
“document”: “politica_trabalho_remoto.pdf”,
“page”: 3
},
{
“document”: “manual_funcionario.pdf”,
“page”: 10
}
],
“metadata”: {
“latency_ms”: 1243,
“model”: “gpt-4o”
}
}
—
## Entendendo o workflow no Lumina V2
Dentro da pasta `ilw/workflows/` você encontrará arquivos de definição do workflow, geralmente em formatos como YAML ou JSON. Neles você verá algo como:
– Nós de:
– `input` (entrada do usuário)
– `search` (consulta ao índice)
– `llm` (modelo de linguagem)
– `post-process` (tratamento final da resposta)
– Configurações de:
– Quantidade de documentos a recuperar
– Tamanho máximo do contexto
– Instruções de sistema para o modelo
Essa estrutura facilita:
– Evoluir o fluxo sem grandes refatorações
– Criar variações do mesmo workflow (por time, idioma ou produto)
– Versionar e auditar mudanças
—
## Personalizando o exemplo
Com o exemplo rodando, você pode começar a adaptá-lo para a sua realidade. Algumas sugestões:
1. **Substituir os documentos de exemplo pelos seus**
– Apague ou mova os arquivos de `ilw/data/input/`
– Adicione seus PDFs, DOCXs ou arquivos de texto
– Rode novamente o processo de ingestão
2. **Ajustar a estratégia de chunking**
– Mexa no tamanho máximo dos trechos
– Ajuste sobreposição
– Teste diferentes granularidades de contexto
3. **Personalizar o prompt do modelo**
– Defina tom de voz
– Especifique como o modelo deve citar fontes
– Inclua instruções sobre o que fazer quando não houver informação suficiente
4. **Conectar a uma interface própria**
– Criar um frontend simples em React, Vue ou outro framework
– Integrar com um chat interno (Slack, Teams, etc.)
– Expor um endpoint autenticado para outros serviços internos
—
## Boas práticas ao usar o ILW
Alguns cuidados importantes ao levar esse tipo de solução para ambientes reais:
– **Governança de dados**
Garanta que a base de conhecimento não contenha dados sensíveis ou que estejam fora da política de privacidade e segurança da empresa.
– **Avaliação contínua**
Crie um processo de revisão de respostas, especialmente nas primeiras semanas, para calibrar prompt, chunking, fontes e modelos.
– **Observabilidade**
Monitore:
– Volume de perguntas
– Temas mais buscados
– Taxa de “não sei”
– Casos em que o modelo alucina ou responde de forma imprecisa
– **Iteração rápida**
Use o próprio ILW como um espaço de experimentação: crie versões A/B, compare modelos, teste alterações de contexto e instrutivos.
—
## Debug e troubleshooting
Caso algo não funcione como esperado, verifique:
1. **Containers**
– Use `docker compose logs -f` para ver logs em tempo real.
– Verifique se o serviço de banco vetorial está acessível.
2. **Configurações de ambiente**
– Confirme se `LUMINA_API_KEY` está correta.
– Veja se não há conflito de portas (especialmente 8000, 8080, etc.).
3. **Dados de entrada**
– Confira se há arquivos na pasta de ingestão.
– Certifique-se de que o script de ingestão foi executado com sucesso.
4. **Permissões e rede**
– Em ambientes corporativos, veja se proxy ou firewall não estão bloqueando downloads ou chamadas externas.
—
## Próximos passos
Depois de dominar esse exemplo básico, você pode:
– Criar múltiplas coleções de conhecimento (por área da empresa)
– Integrar o ILW a fluxos de aprovação de conteúdo
– Adicionar ferramentas avançadas (consultas a bancos relacionais, execução de códigos, automações)
– Explorar modelos alternativos (abertos, fechados, híbridos)
O objetivo desse exemplo é servir como ponto de partida: algo simples de rodar, fácil de entender e pronto para ser expandido. Com ele funcionando, você já tem a base necessária para desenhar soluções de IA realmente úteis e alinhadas à realidade do seu negócio usando o Lumina V2 e o ILW.