LangChain vs LlamaIndex: qual framework de IA usar?

Índice

1. O que são frameworks de LLM
2. LangChain: o canivete suíço
3. LlamaIndex: o especialista em dados
4. Comparação direta
5. Quando usar LangChain
6. Quando usar LlamaIndex
7. Exemplo de código: RAG com LangChain
8. Exemplo de código: RAG com LlamaIndex
9. E os agentes?
10. Erros comuns

O que são frameworks de LLM {#o-que-sao}

Antes de comparar, vamos ao conceito básico. Um LLM (Large Language Model) é um modelo de IA treinado para entender e gerar texto — o ChatGPT é o exemplo mais famoso. Sozinho, um LLM faz uma coisa: recebe texto e devolve texto. Para virar um produto (um chatbot, um assistente que usa seus dados, um agente que executa tarefas), você precisa de código ao redor que:

• Conecta ao modelo via API
• Formata a pergunta do usuário (prompt)
• Busca dados relevantes e injeta no prompt
• Mantém o histórico da conversa
• Decide quando chamar ferramentas externas
• Trata erros e limita custos

Esse "código ao redor" é repetitivo. Da mesma forma que você não escreve um servidor HTTP do zero a cada projeto (usa Express, FastAPI, Django), você não escreve a orquestração de LLM do zero: usa um framework.

LangChain e LlamaIndex são os dois frameworks Python mais populares para isso. Ambos são open source, ambos rodam em qualquer LLM (OpenAI, Anthropic, open source hospedado por você), ambos têm versão em TypeScript. Mas têm filosofias diferentes — e entender essa diferença economiza semanas de dor de cabeça.

Analogia: LangChain é um canivete suíço — tem ferramenta para tudo, mas cada uma é "boa o suficiente". LlamaIndex é uma caixa de chaves de boca precisa — menos peças, mas cada uma é especializada e bem ajustada.

LangChain: o canivete suíço {#langchain}

LangChain nasceu em 2022 com uma proposta ampla: ser a camada de abstração para qualquer aplicação com LLM. Ele não assume que você vai fazer RAG (Recall-Augmented Generation, técnica que explicamos adiante). Ele assume que você pode fazer qualquer coisa: RAG, agentes, chains de raciocínio, sumarização, extração, chat com memória, etc.

O que o LangChain oferece

• Chains: sequências de chamadas encadeadas (prompt → modelo → parser)
• Agents: LLMs que decidem sozinhos quais ferramentas usar
• Memory: gerenciar histórico de conversa
• Retrievers: integração com vector stores (pgvector, Pinecone, Chroma)
• Document loaders: ler PDF, HTML, Notion, GitHub, etc.
• Callbacks: hooks para logging, streaming, monitoramento
• LangServe: publicar chains como API REST
• LangSmith: plataforma de observabilidade (paga)

Estilo de uso

LangChain é componível e flexível. Você monta peças pequenas e encaixa:

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

# Cada peça é um objeto que pode ser encadeado com o operador |
prompt = ChatPromptTemplate.from_template("Resuma: {texto}")
modelo = ChatOpenAI(model="gpt-4o-mini", temperature=0.2)
parser = StrOutputParser()

# O operador | encadeia: saída de um vira entrada do próximo
chain = prompt | modelo | parser

# Executa
resumo = chain.invoke({"texto": "Contrudo longo aqui..."})

Comentários explicam: cada peça é um objeto; o operador | (pipe) liga a saída de um na entrada do próximo, como uma linha de montagem. Isso é o coração do LangChain — componibilidade.

LlamaIndex: o especialista em dados {#llamaindex}

LlamaIndex nasceu em 2022 com o nome GPT Index, e o nome original já entrega o foco: conectar LLMs aos seus dados. Enquanto LangChain quer ser geral, LlamaIndex quer ser o melhor do mundo em RAG (Retrieval-Augmented Generation), a técnica onde o LLM responde com base nos seus documentos.

RAG, em uma frase: antes de o LLM responder, você busca no seu acervo os trechos mais relevantes e os entrega como contexto. O LLM então responde "olhando" para os seus dados, em vez de depender só do que memorizou no treino.

O que o LlamaIndex oferece

• Data connectors: conectores especializados para 100+ fontes (Notion, Salesforce, GitHub, Slack, bancos SQL, etc.)
• Index structures: índices otimizados (vetorial, hierárquico, em árvore, em grafo de conhecimento)
• Advanced retrieval: estratégias sofisticadas (reranking, hybrid search, sub-questões, roteamento)
• Response synthesis: modos de geração de resposta (refine, compact, tree-summarize)
• Agents: agentes com ferramentas de consulta (mais focado em dados)
• LlamaCloud: plataforma de ingestão e parsing (paga)
• Workflows: orquestração de fluxos multi-etapa (mais novo)

Estilo de uso

LlamaIndex é declarativo e alto nível. Você descreve o que quer, ele cuida dos detalhes:

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader

# Carrega documentos de uma pasta
documentos = SimpleDirectoryReader("./meus_docs").load_data()

# Constrói o índice vetorial automaticamente
# (gera embeddings, armazena, configura retriever)
indice = VectorStoreIndex.from_documents(documentos)

# Cria um "query engine" - a interface para fazer perguntas
motor = indice.as_query_engine(similarity_top_k=3)

# Pergunta
resposta = motor.query("Qual a política de reembolso?")
print(resposta)

Veja a diferença: em LlamaIndex, três linhas construíram um RAG completo. Em LangChain, você teria que escolher o vector store, configurar o retriever, montar a chain de QA, definir o prompt manualmente. Mais controle — também mais trabalho.

Comparação direta {#comparacao}

Quando usar LangChain {#quando-langchain}

• Quando o problema não é RAG: classificação de textos, extração estruturada, sumarização em pipeline, geração de código.
• Quando você quer agentes complexos: LangGraph (subprojeto do LangChain) é hoje a ferramenta mais madura para agentes com estado, loops e múltiplos papéis.
• Quando você quer controle fino: montar cada etapa do pipeline do jeito que faz sentido para o seu caso.
• Quando você precisa de muitas integrações: conectores para tudo que existe (vector stores, ferramentas, fontes de dados).
• Quando vai publicar como API: LangServe gera endpoints REST automaticamente a partir de chains.

Caso típico: "Quero um agente que recebe um e-mail do cliente, decide se encaminha para vendas ou suporte, busca o histórico no CRM, e responde. Tudo automático." Esse é um problema de agente com várias ferramentas — LangChain

• LangGraph brilha aqui.

Quando usar LlamaIndex {#quando-llamaindex}

• Quando o problema é RAG: chatbot que responde com base na sua base de conhecimento, assistente que consulta seus documentos internos.
• Quando você tem dados heterogêneos: PDFs, Notion, Salesforce, banco SQL — LlamaIndex tem conectores prontos e otimizados.
• Quando você precisa de RAG avançado: reranking, hybrid search, sub-questões, consulta multi-documento.
• Quando você quer velocidade de protótipo: o caminho do "documento → RAG funcionando" é o mais rápido do mercado.
• Quando você quer qualidade de recuperação: as estratégias padrão do LlamaIndex costumam acertar mais que as do LangChain out-of-the-box.

Caso típico: "Tenho 500 PDFs de manuais técnicos e quero um chatbot que responda perguntas dos clientes só com base nesses manuais." LlamaIndex resolve isso em 30 linhas de código e com qualidade alta.

Exemplo de código: RAG com LangChain {#codigo-langchain}

# pip install langchain langchain-openai langchain-community \
#             langchain-postgres tiktoken

from langchain_openai import ChatOpenAI, OpenAIEmbeddings
from langchain_community.document_loaders import DirectoryLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_postgres.vectorstores import PGVector
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough

# 1. Carregar documentos (PDFs, MDs, TXTs da pasta)
loader = DirectoryLoader("./docs", glob="**/*.md")
docs = loader.load()

# 2. Quebrar em pedaços menores (chunks) - o LLM não lê tudo de uma vez
#    chunk_size: tamanho de cada pedaço em caracteres
#    chunk_overlap: sobreposição para não cortar ideias no meio
splitter = RecursiveCharacterTextSplitter(
    chunk_size=1000, chunk_overlap=200
)
chunks = splitter.split_documents(docs)

# 3. Gerar embeddings e salvar no Postgres com pgvector
#    embeddings: vetores numéricos que representam o sentido do texto
embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
vectorstore = PGVector.from_documents(
    documents=chunks,
    embedding=embeddings,
    connection_string="postgresql://user:pass@localhost:5432/ia",
    collection_name="meus_docs",
)

# 4. Criar o retriever - a parte que busca chunks relevantes
retriever = vectorstore.as_retriever(search_kwargs={"k": 4})

# 5. Montar o prompt - como falar com o LLM
prompt = ChatPromptTemplate.from_template("""
Você é um assistente que responde SÓ com base no contexto abaixo.
Se não souber, diga que não tem informação.

Contexto:
{contexto}

Pergunta: {pergunta}
""")

# 6. Modelo
modelo = ChatOpenAI(model="gpt-4o-mini", temperature=0.2)

# 7. Montar a chain: busca contexto -> formata prompt -> chama LLM
def formatar_docs(docs):
    return "\n\n".join(d.page_content for d in docs)

chain = (
    {"contexto": retriever | formatar_docs, "pergunta": RunnablePassthrough()}
    | prompt
    | modelo
)

# 8. Usar
resposta = chain.invoke("Qual a política de reembolso?")
print(resposta.content)

Cada bloco numerado é uma etapa do RAG. LangChain te faz explicitar todas — mais código, mais controle. Note como você escolhe splitter, retriever, prompt e modelo separadamente.

Exemplo de código: RAG com LlamaIndex {#codigo-llamaindex}

# pip install llama-index llama-index-vector-stores-postgres \
#             llama-index-embeddings-openai llama-index-llms-openai

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.core import Settings
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding
from llama_index.vector_stores.postgres import PGVectorStore
from sqlalchemy import create_engine

# 1. Configurar modelos globais (LLM e embeddings)
Settings.llm = OpenAI(model="gpt-4o-mini", temperature=0.2)
Settings.embed_model = OpenAIEmbedding(model="text-embedding-3-small")

# 2. Carregar documentos - LlamaIndex cuida da leitura e parsing
documentos = SimpleDirectoryReader("./docs").load_data()

# 3. Conectar ao Postgres com pgvector
engine = create_engine("postgresql://user:pass@localhost:5432/ia")
vector_store = PGVectorStore.from_params(
    database="ia",
    host="localhost",
    password="pass",
    port=5432,
    user="user",
    table_name="meus_docs",
    embed_dim=1536,  # tamanho do vetor do text-embedding-3-small
)

# 4. Construir índice (chunking + embeddings + armazenamento automáticos)
indice = VectorStoreIndex.from_documents(
    documentos,
    vector_store=vector_store,
    chunk_size=1000,
    chunk_overlap=200,
)

# 5. Criar o query engine - interface de pergunta
#    similarity_top_k: quantos chunks relevantes recuperar
motor = indice.as_query_engine(similarity_top_k=4)

# 6. Perguntar
resposta = motor.query("Qual a política de reembolso?")
print(resposta)

Veja: mesmo resultado, bem menos código. LlamaIndex assume defaults sensatos e expõe só o que importa. Você troca 8 etapas explícitas por 6 declarativas — e ganha estratégias de reranking "de graça" quando precisar.

E os agentes? {#agentes}

Agente de IA é um LLM que recebe ferramentas e decide sozinho qual usar para resolver uma tarefa — em vez de seguir um fluxo fixo. Exemplo: um agente que recebe "agende uma reunião com o João" pode decidir chamar a ferramenta buscar_email(joao), depois verificar_agenda(quinta), depois criar_evento(...).

Recomendação prática: para agentes complexos com estado e fluxos elaborados, LangGraph (do ecossistema LangChain) é hoje a escolha mais madura. Para agentes cujo trabalho principal é consultar documentos e bancos, LlamaIndex Agents é mais direto.

Importante: agente não é bala de prata. Antes de adotar um agente, avalie se uma chain simples (fluxo fixo) não resolve. Agentes são mais flexíveis, mas mais lentos, mais caros e mais difíceis de debugar. Use só quando a decisão "qual ferramenta usar" realmente varia entre chamadas.

Erros comuns {#erros}

1. Escolher framework antes do problema: "vou usar LangChain porque é o mais famoso". Comece pelo problema, depois escolha a ferramenta.
2. Misturar os dois sem motivo: usar LangChain pra agents e LlamaIndex pra RAG no mesmo projeto, sem necessidade. Dá pra fazer, mas você paga duas curvas de aprendizado. Escolha um e vá fundo.
3. Achar que framework resolve tudo: framework orquestra, mas a qualidade vem dos dados, do prompt e do modelo. Sem curadoria, nem LlamaIndex salva.
4. Usar defaults sem entender: LlamaIndex tem chunk_size=1024 default. Para manuais técnicos curtos, isso corta seções no meio. Entenda os parâmetros antes de aceitar.
5. Subestimar a instabilidade do LangChain: a API mudou muito entre 2022 e 2024. Travou em uma versão no requirements.txt para não quebrar.
6. Ignorar observabilidade: sem LangSmith ou equivalente, você não sabe o que o agente está decidindo. Em produção, isso vira caixa-preta.
7. Construir agente logo no primeiro projeto: agentes são tentadores, mas começar com uma chain simples evita 80% dos problemas de custo e imprevisibilidade.
8. Não isolar o framework do seu código: importar langchain em todo arquivo do sistema. Crie uma camada de abstração para poder trocar de framework (ou versão) sem reescrever tudo.

Não sabe qual framework escolher para o seu caso? A Inicialize Tec avalia sua necessidade e implementa com a ferramenta certa — sem viés de modinha. Entre em contato e conversamos sobre seu projeto.