Formatando Arquivos para Base de Conhecimento com Open WebUI

Introdução

Compartilhando boas práticas de formatação e estruturação de arquivos PDF, Markdown e texto puro para a criação de bases de conhecimento textuais otimizadas para embeddings e sistemas de QA (Question Answering) no Open WebUI. Os achados a seguir consideram cenários com e sem backend específico, focando na eficiência de parsing, qualidade semântica e organização por projeto.

Abordam-se recomendações detalhadas sobre o tipo de arquivo ideal, estrutura de conteúdo, presença ou não de imagens, tamanho recomendado e diretrizes para manutenção contínua da base.

Formato de Arquivo Recomendado #

Formatos leves e estruturados são ideais. O Markdown (.md, .mdx) é o preferido por sua leveza e estrutura clara. Texto puro (.txt) também é suportado, mas perde hierarquia.

PDFs e DOCX devem ser evitados como fontes primárias: foram feitos para impressão, possuem artefatos de layout. Caso usados, devem ser convertidos via ferramentas como PyMuPDF4LLM.

• Markdown (.md, .mdx) – Recomendado. Mantém estrutura semântica e hierarquia de títulos.
• Texto simples (.txt) – Leve e direto, mas sem formatação estruturada.
• PDF/DOCX – Exigem pré-processamento para evitar perda semântica.
• HTML/CSV – Úteis em contextos específicos como documentação técnica ou dados tabulares.

Estrutura Interna dos Arquivos #

Use títulos, listas e parágrafos curtos para facilitar o parsing semântico e o chunking. Markdown, por exemplo, é interpretado por ferramentas como o LlamaIndex para criar “nós” com base nos cabeçalhos.

• Cabeçalhos claros – Facilitam a segmentação em seções coerentes.
• Listas e marcadores – Aumentam a separação visual e lógica entre itens.
• Parágrafos curtos – Melhoram a qualidade do embedding e legibilidade.
• Consistência – Padronize títulos, sintaxe e organização interna.

Ilustrações, Tabelas e Elementos Multimídia #

Elementos não textuais devem ser removidos ou descritos textualmente. A maioria dos modelos de embedding lida apenas com texto natural.

• Imagens – Remover. Alt text raramente é suficiente para QA.
• Tabelas – Converter para .csv ou Markdown. Ferramentas como PyMuPDF4LLM extraem tabelas automaticamente.
• Equações/Diagramas – Devem ser descritos ou resumidos textualmente.

Tamanho Ideal por Arquivo/Lote #

Evite arquivos excessivamente grandes. Idealmente, divida em partes menores e mantenha cada chunk com ~300–1024 tokens.

• Arquivos moderados – Limite de algumas dezenas de páginas por arquivo.
• Chunking automático – Padrões: 300 tokens (Bedrock), 1024 tokens (LlamaIndex).
• Organização por lote – Agrupe por tema, projeto ou tipo de conteúdo.
• Granularidade e nomeação – Nomeie arquivos com prefixos claros, como projeto_topico.md.

Manutenção e Organização por Projeto #

Use diretórios por projeto e adicione metadados como title, tags e lastUpdated. Integre controle de versão via Git sempre que possível.

• Monitoramento – Sincronize mudanças com a base (manual ou via automação com Git/CI).
• Batch vs. contínuo – Reconstrua esporadicamente ou use ingestão incremental em pipelines dinâmicos.
• Revisão periódica – Remova conteúdo desatualizado e documente as diretrizes de ingestão.

Considerações para LangChain e LlamaIndex #

Frameworks como LangChain e LlamaIndex permitem controle refinado sobre ingestão e chunking. Aproveite recursos como MarkdownNodeParser, chunk_overlap e metadados personalizados.

• Loaders específicos – Utilize SimpleDirectoryReader, PDFReader etc.
• Chunking ajustável – Personalize tamanho e sobreposição (e.g. 1024 tokens com 20 de overlap).
• Hierarquia semântica – Markdown bem estruturado facilita paths de cabeçalho em nodes.
• Metadados – Enriquecem os vetores e auxiliam na filtragem e rastreamento.
• Conversão e limpeza – Use PyMuPDF4LLM e postprocessors para remover ruídos antes da vetorização.

Recursos recomendados #

• PyMuPDF4LLM – Conversão precisa de PDFs com chunking estruturado.
• LlamaIndex Docs – Guia completo sobre parsing, chunking e metadados.
• Open WebUI (GitHub) – Interface aberta para LLMs com suporte a RAG e ingestão de documentos.
• LangChain Docs – Framework para construção de agentes e pipelines de QA.