LlamaIndex em pratique

#LlamaIndex na prática: para que serve e quando adotá-lo

LlamaIndex é um framework Python que dá suporte a todo o fluxo de um RAG: carregar documentos, dividi-los em partes (nodes), transformá-los em vetores, indexá-los e depois consultar o índice com um LLM que cita suas fontes. A versão 0.14.25, publicada no PyPI em 21 de setembro de 2026, exige Python 3.10 ou superior. Um RAG mínimo cabe em cerca de dez linhas; o framework se torna útil quando é necessário variar as fontes, mudar o modo de resposta, adicionar um reranker ou integrar um agente. Localmente, ele funciona com Ollama para o LLM e um modelo de embeddings escolhido por você, desde que você desative suas configurações padrão, que fazem chamadas à OpenAI. Este guia monta um RAG totalmente local, mostra as configurações que importam e corrige vários exemplos desatualizados que ainda são encontrados na internet.

Abstrações claras

Document, Node, VectorStoreIndex, retriever, query engine: cada etapa do RAG tem um objeto dedicado, substituível.

Conectores de dados

SimpleDirectoryReader lê PDF, Word, PowerPoint, Markdown, imagens ou áudio; outros leitores abrangem Notion, Google Docs, Slack ou Discord.

Modos de consulta

Várias estratégias de síntese e mecanismos mais elaborados (subperguntas, roteamento entre índices) para ir além da simples busca vetorial.

Execução local possível

Ollama e os embeddings do Hugging Face ou Ollama são conectados por meio de pacotes de integração dedicados.

#As etapas de um RAG LlamaIndex e suas configurações padrão

Antes de escrever código, tenha em mente o pipeline e, principalmente, seus valores padrão: é aí que se esconde a maioria das surpresas ao executar localmente.

#Instalação para um RAG 100 % local

O comando pip install llama-index instala um pacote inicial que inclui llama-index-core, as integrações da OpenAI para o LLM e os embeddings, e os leitores de arquivos. Para execução local, adicione as integrações do Ollama e de embeddings (llama-index-embeddings-ollama se você preferir OllamaEmbedding); os pacotes OpenAI do conjunto permanecem instalados, mas sem uso, desde que você configure Settings.

pip install llama-index \
            llama-index-llms-ollama \
            llama-index-embeddings-huggingface

ollama pull mistral

O nome de um pacote indica o caminho de importação: llama-index-llms-ollama corresponde a llama_index.llms.ollama. Quanto à memória, leve em conta os pesos do LLM (cerca de 5 GB para um modelo de 7–8B em Q4, referência do site), o modelo de embeddings e o contexto: um computador com 16 GB de RAM é adequado para um corpus pequeno; mais memória oferece uma margem maior.

#Um RAG em dez linhas (com suas configurações padrão para OpenAI)

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader

docs = SimpleDirectoryReader("./docs").load_data()
index = VectorStoreIndex.from_documents(docs)

query = index.as_query_engine()
print(query.query("Résume les points clés du contrat X"))

Este código é válido, mas utiliza os modelos padrão da OpenAI: falha sem chave e, com chave, envia seus textos para o provedor. Serve como esqueleto. A seção seguinte adiciona as poucas linhas que o tornam local.

#Migrar para o uso local com Ollama e embeddings em francês

Três blocos de configuração são suficientes: o LLM, o modelo de embeddings e a divisão em trechos. Para o francês, BGE-M3 é uma escolha comum: sua ficha indica mais de 100 idiomas e entradas de até 8.192 tokens. O download do modelo pesa cerca de 2,3 GB (arquivo pytorch_model.bin do repositório Hugging Face) e ocorre apenas uma vez.

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings
from llama_index.llms.ollama import Ollama
from llama_index.embeddings.huggingface import HuggingFaceEmbedding

# Configuration globale : tout est local
Settings.llm = Ollama(
    model="mistral",
    base_url="http://localhost:11434",
    request_timeout=120.0,   # le défaut est de 30 s
    context_window=8000,     # transmis à Ollama comme num_ctx
)
Settings.embed_model = HuggingFaceEmbedding(model_name="BAAI/bge-m3")
Settings.chunk_size = 700
Settings.chunk_overlap = 100

# Pipeline
docs = SimpleDirectoryReader("./docs").load_data()
index = VectorStoreIndex.from_documents(docs, show_progress=True)

# Persister sur disque
index.storage_context.persist(persist_dir="./storage")

# Requêter
query_engine = index.as_query_engine(similarity_top_k=5)
reponse = query_engine.query("Quels sont les risques identifiés ?")
print(reponse)
for src in reponse.source_nodes:
    print(f"  - {src.metadata.get('file_name')} ({src.score:.2f})")

from llama_index.core import load_index_from_storage, StorageContext

storage = StorageContext.from_defaults(persist_dir="./storage")
index = load_index_from_storage(storage)

#Por que context_window e request_timeout são importantes

O código-fonte da integração do Ollama com o LlamaIndex passa o valor de context_window para o Ollama com o nome num_ctx. Sem isso, o Ollama aplica sua janela padrão, de cerca de 4.000 tokens quando há menos de 24 GiB de VRAM, segundo sua documentação. A conta é simples: cinco trechos de 700 tokens somam 3.500 tokens, antes da pergunta, das instruções do template de prompt e da resposta. Com 4.000 tokens, o prompt ultrapassa o limite e o contexto é truncado, muitas vezes sem erro visível. Com 8.000, há margem.

O tempo limite é a outra armadilha: o cliente Ollama do LlamaIndex define 30 segundos por padrão. Uma primeira chamada que carrega o modelo na memória e processa um prompt longo pode ultrapassar esse limite. Os 120 segundos do exemplo são um ponto de partida a ajustar conforme seu hardware.

#Carregar seus arquivos: configurações do SimpleDirectoryReader

SimpleDirectoryReader lê um diretório inteiro e suporta diversos formatos: PDF, Word, PowerPoint, Markdown, imagens, áudio e vídeo. Alguns parâmetros evitam indexar conteúdo indiscriminadamente.

from llama_index.core import SimpleDirectoryReader

docs = SimpleDirectoryReader(
    input_dir="./docs",
    required_exts=[".pdf", ".docx"],  # ne charger que ces formats
    num_files_limit=100,              # plafond pour un premier essai
).load_data()

Os conectores para serviços (Notion, Google Docs, Slack, Discord) buscam os dados online: isso é inevitável, pois eles estão lá. Depois que os documentos são carregados, a indexação e a consulta continuam locais, com seus embeddings e seu LLM Ollama. Faça um primeiro teste com alguns arquivos: um PDF digitalizado sem camada de texto não produzirá nada enquanto não passar por um OCR, como descrito no guia do Tesseract.

#Escolher um modo de consulta e o custo em chamadas ao LLM

O modo de síntese determina quantas vezes o LLM é chamado e, portanto, o tempo de resposta local. A tabela apresenta os modos documentados e seus custos, com um exemplo de cinco passagens de 700 tokens e uma janela de 8.000 tokens (estimativa).

Para uma pergunta factual, mantenha compact. Para resumir um documento longo, tree_summarize foi concebido para isso, ao custo de várias chamadas: em uma máquina local, reserve várias vezes o tempo de uma resposta simples. no_text é valioso para verificar o que a busca retorna, sem esperar pelo LLM.

#Adicionar um reranker local

Quando a resposta correta está nos 20 primeiros trechos, mas não nos 5 primeiros, um reranker reordena os candidatos antes de enviá-los ao LLM. A documentação do LlamaIndex recomenda o SentenceTransformerRerank como opção padrão que não exige chave de API e é executada localmente. Trata-se de um cross-encoder via sentence-transformers, e a documentação cita o Qwen3-Reranker-0.6B para uma melhor qualidade multilíngue.

from llama_index.core.postprocessor import SentenceTransformerRerank

reranker = SentenceTransformerRerank(
    model="cross-encoder/ms-marco-MiniLM-L2-v2",
    top_n=3,
)
query_engine = index.as_query_engine(
    similarity_top_k=15,             # large pour rattraper la bonne réponse
    node_postprocessors=[reranker],  # puis resserre à 3
)

O modelo apresentado aqui é o do exemplo oficial, escolhido por sua velocidade; foi projetado para o inglês: para documentos em francês, teste um reranker multilíngue. O guia dedicado detalha a escolha e a avaliação.

#Subperguntas e roteamento

SubQuestionQueryEngine

Decompõe uma pergunta complexa em subperguntas enviadas a ferramentas de consulta e depois sintetiza. "Compare as estratégias de 2024 e 2025" se torna duas pesquisas separadas.

RouterQueryEngine

Escolhe, para cada pergunta, o motor adequado entre vários (por exemplo, um índice de resumos ou um índice vetorial).

Esses dois mecanismos multiplicam as chamadas ao LLM: uma decomposição em três subperguntas acrescenta a geração das subperguntas, três respostas e a síntese final, totalizando pelo menos cinco chamadas. Em hardware local, reserve-os para as perguntas que realmente justificarem seu uso.

#Agentes: a API atual já não é a mesma dos tutoriais antigos

Muitos tutoriais usam ReActAgent.from_tools. Essa classe não existe mais no código-fonte atual: o módulo agent/react/base.py que a continha desapareceu do repositório. Os agentes agora são workflows assíncronos: FunctionAgent (um agente que chama funções ou ferramentas), ReActAgent na versão de workflow e AgentWorkflow para orquestrar vários agentes. O tutorial oficial para uso local constrói o agente com AgentWorkflow.from_tools_or_functions e o executa com await agent.run.

import asyncio
from llama_index.core import Settings
from llama_index.core.agent.workflow import AgentWorkflow

async def search_documents(query: str) -> str:
    """Répond aux questions sur les contrats clients."""
    response = await query_engine.aquery(query)
    return str(response)

agent = AgentWorkflow.from_tools_or_functions(
    [search_documents],
    llm=Settings.llm,
    system_prompt="Tu réponds uniquement à partir des contrats indexés.",
)

async def main():
    reponse = await agent.run("Y a-t-il une clause de non-concurrence chez Acme Corp ?")
    print(str(reponse))

asyncio.run(main())

O nome, a descrição e os argumentos da função (sua docstring) são enviados ao LLM, que decide se deve chamá-la: portanto, capriche nessa descrição. O funcionamento do FunctionAgent baseia-se em chamadas nativas de funções; com um modelo local, escolha um modelo que suporte ferramentas no Ollama e mantenha o RAG simples se o seu não tiver esse suporte.

#LlamaIndex, LangChain ou RAG próprio: como escolher

Regra prática: um RAG documental com fontes citadas, diversos formatos e algumas opções de consulta se constrói rapidamente com o LlamaIndex. Se você quiser entender primeiro o mecanismo, escreva uma versão própria uma vez: o guia ChromaDB mostra os passos. Para um agente que controla muitas ferramentas externas, compare o LangChain e os workflows do LlamaIndex de acordo com seus hábitos.

#As armadilhas que custam tempo

Reindexar a cada execução

Sem persist, o índice fica na memória e desaparece quando o script é encerrado. Persista o índice e depois recarregue-o com load_index_from_storage.

Trocar de modelo sem reindexar

Os vetores de dois modelos de embeddings não são comparáveis: modificar embed_model ou a divisão em trechos exige reconstruir o índice.

Contexto truncado silenciosamente

Um prompt mais longo que a janela de Ollama é truncado: verifique context_window se as respostas ignorarem as passagens finais.

Copiar um tutorial antigo

As APIs de agentes mudaram: verifique se os imports de um exemplo existem na versão instalada (0.14.25 no momento da redação).

Nunca medir

Um RAG sem avaliação se desvia sem que você perceba: o guia Ragas mostra como quantificar esse desvio.

• RAG local com ChromaDB e Ollama: tutorial em Python
• Adicionar um reranker ao seu pipeline
• Os melhores modelos de embeddings para francês
• Estratégias de chunking
• Ragas: avaliar seu RAG local com números
• Criar um agente de IA local em Python com LangChain e Ollama

• Fonte: tutorial de introdução aos modelos locais
• Fonte: instalação do LlamaIndex
• Fonte: modos de síntese de resposta
• Fonte: persistência e recarregamento de um índice
• Fonte: ficha do modelo BGE-M3