“`html
Introdução ao LangChain.js: Construindo Aplicações Práticas com LLM
Por Jake Morrison, LangChain.js é uma dessas ferramentas. Ele fornece uma forma estruturada de construir aplicações impulsionadas por modelos de linguagem grandes (LLMs) usando JavaScript ou TypeScript. Se você está trabalhando com LLMs no ecossistema JavaScript, entender o LangChain.js é essencial. Este guia irá guiá-lo através de passos práticos e acionáveis para começar e construir aplicações reais.
O que é LangChain.js e Por Que Usá-lo?
LangChain.js é uma biblioteca projetada para ajudar desenvolvedores a criar aplicações impulsionadas por LLM. Ele não substitui os próprios LLMs, mas fornece uma camada de abstração e um conjunto de ferramentas para encadear diferentes chamadas de LLM, integrar com outras fontes de dados e gerenciar interações complexas.
Pense assim: chamar diretamente uma API de LLM é como usar uma consulta de banco de dados bruta. LangChain.js fornece um ORM (Mapeador Objeto-Relacional) para LLMs. Ele lida com padrões comuns como:
* **Cadeias:** Combinando múltiplas chamadas de LLM ou outras etapas em uma sequência.
* **Prompts:** Gerenciando e formatando a entrada para LLMs.
* **Agentes:** Permitir que LLMs tomem decisões e usem ferramentas.
* **Recuperação:** Integrando dados externos (seus documentos, bancos de dados) com LLMs.
* **Memória:** Dando aos LLMs uma forma de lembrar interações passadas.
O principal benefício de usar LangChain.js é o aumento da produtividade e da manutenibilidade. Você escreve menos código repetitivo, a lógica da sua aplicação se torna mais clara e é mais fácil trocar provedores de LLM ou adicionar novas funcionalidades. Para qualquer um que esteja construindo com LLMs em JavaScript, LangChain.js oferece vantagens significativas.
Configurando Seu Projeto LangChain.js
Antes de escrever qualquer código, vamos preparar nosso ambiente. Você precisará ter o Node.js instalado.
1. **Crie um novo diretório de projeto:**
“`bash
mkdir langchain-js-project
cd langchain-js-project
“`
2. **Inicialize um projeto Node.js:**
“`bash
npm init -y
“`
3. **Instale LangChain.js e um provedor de LLM:**
Começaremos com OpenAI para nossos exemplos, mas LangChain.js suporta muitos outros (Hugging Face, Google, etc.).
“`bash
npm install langchain @openai/openai
“`
Se preferir TypeScript:
“`bash
npm install langchain @openai/openai typescript @types/node ts-node
npx tsc –init
“`
Então, atualize `tsconfig.json` para incluir `“moduleResolution”: “node”` e `“esModuleInterop”: true`.
4. **Configure sua chave API:**
Você precisará de uma chave API da OpenAI. Nunca coloque chaves API diretamente no seu código. Use variáveis de ambiente.
Crie um arquivo `.env` na raiz do seu projeto:
“`
OPENAI_API_KEY=YOUR_OPENAI_API_KEY
“`
Para carregar variáveis de ambiente, instale `dotenv`:
“`bash
npm install dotenv
“`
Então, no topo do seu arquivo principal de script (por exemplo, `index.js` ou `src/index.ts`):
“`javascript
require(‘dotenv’).config();
“`
ou para TypeScript/ESM:
“`typescript
import ‘dotenv/config’;
“`
Agora você está pronto para começar a construir com LangChain.js.
Sua Primeira Chamada LLM com LangChain.js
Vamos fazer uma chamada simples para um LLM.
“`javascript
// index.js
require(‘dotenv’).config();
const { OpenAI } = require(‘langchain/llms/openai’);
async function simpleLLMCall() {
const model = new OpenAI({ temperature: 0.7 }); // temperature controla a aleatoriedade
const prompt = “Qual é a capital da França?”;
const result = await model.call(prompt);
console.log(result);
}
simpleLLMCall();
“`
Para executar isso: `node index.js`.
Você deve ver “Paris.” ou saída semelhante. Esta é a interação mais básica. LangChain.js encapsula a chamada da API OpenAI, tornando-a consistente com outros provedores de LLM.
Trabalhando com Prompts: Modelos e Variáveis
Incorporar prompts diretamente no seu código pode se tornar confuso. LangChain.js fornece `PromptTemplate` para gerenciar prompts de forma efetiva.
“`javascript
// promptExample.js
require(‘dotenv’).config();
const { OpenAI } = require(‘langchain/llms/openai’);
const { PromptTemplate } = require(‘langchain/prompts’);
async function templatedPrompt() {
const model = new OpenAI({ temperature: 0.7 });
const template = “Qual é um bom nome para uma empresa que fabrica {product}?“;
const prompt = new PromptTemplate({
template: template,
inputVariables: [“product”],
});
“`
const formattedPrompt = await prompt.format({ product: “meias coloridas” });
console.log(“Prompt Formatado:”, formattedPrompt);
const result = await model.call(formattedPrompt);
console.log(“Resultado LLM:”, result);
}
templatedPrompt();
“`
Execute isso com `node promptExample.js`.
Isso demonstra como `PromptTemplate` permite que você defina prompts com espaços reservados (`{product}`) que você pode preencher dinamicamente. Isso é crucial para construir aplicativos flexíveis.
Cadeias: Conectando Chamadas LLM e Lógica
Cadeias são onde LangChain.js realmente brilha. Elas permitem que você combine múltiplos passos, incluindo chamadas LLM, em um único fluxo de trabalho coerente.
Cadeia LLM Simples
A `LLMChain` é a cadeia mais básica. Ela pega um `PromptTemplate` e um LLM, formata o prompt e o passa para o LLM.
“`javascript
// llmChainExample.js
require(‘dotenv’).config();
const { OpenAI } = require(‘langchain/llms/openai’);
const { PromptTemplate } = require(‘langchain/prompts’);
const { LLMChain } = require(‘langchain/chains’);
async function simpleLLMChain() {
const model = new OpenAI({ temperature: 0.7 });
const template = “Qual é a melhor {activity} para fazer em {city}?”;
const prompt = new PromptTemplate({
template: template,
inputVariables: [“activity”, “city”],
});
const chain = new LLMChain({ llm: model, prompt: prompt });
const result = await chain.call({ activity: “comida”, city: “Roma” });
console.log(“Resultado da Cadeia:”, result);
// O objeto de resultado conterá uma propriedade ‘text’ com a saída do LLM.
}
simpleLLMChain();
“`
Execute com `node llmChainExample.js`.
Observe como `chain.call()` aceita um objeto com as variáveis de entrada e lida com a formatação do prompt e a chamada do LLM. Esta é uma maneira mais limpa de interagir com seu LLM.
Cadeias Lineares: Fluxos de Trabalho em Múltiplas Etapas
Às vezes, você precisa realizar várias chamadas LLM em sequência, onde a saída de uma chamada se torna a entrada para a próxima. É aqui que o `SimpleSequentialChain` se torna útil.
“`javascript
// sequentialChainExample.js
require(‘dotenv’).config();
const { OpenAI } = require(‘langchain/llms/openai’);
const { PromptTemplate } = require(‘langchain/prompts’);
const { LLMChain, SimpleSequentialChain } = require(‘langchain/chains’);
async function multiStepChain() {
const model = new OpenAI({ temperature: 0.7 });
// Cadeia 1: Gerar um nome de empresa
const nameTemplate = “Qual é um bom nome para uma empresa que faz {product}?”;
const namePrompt = new PromptTemplate({
template: nameTemplate,
inputVariables: [“product”],
});
const nameChain = new LLMChain({ llm: model, prompt: namePrompt });
// Cadeia 2: Descrever a empresa
const descriptionTemplate = “Escreva um slogan de marketing curto e envolvente para uma empresa chamada {companyName}.”;
const descriptionPrompt = new PromptTemplate({
template: descriptionTemplate,
inputVariables: [“companyName”],
});
const descriptionChain = new LLMChain({ llm: model, prompt: descriptionPrompt });
// Combine-as em uma cadeia sequencial
const overallChain = new SimpleSequentialChain({
chains: [nameChain, descriptionChain],
verbose: true, // Defina como verdadeiro para ver etapas intermediárias
});
const result = await overallChain.run(“sapatos ecológicos”);
console.log(“Resultado Geral:”, result);
}
multiStepChain();
“`
Execute com `node sequentialChainExample.js`.
O `SimpleSequentialChain` pega a saída do `nameChain` e automaticamente a usa como a entrada (`companyName`) para o `descriptionChain`. Este padrão é extremamente poderoso para desmembrar tarefas complexas. LangChain.js facilita isso.
Geração Aumentada por Recuperação (RAG): Usando Seus Próprios Dados
LLMs são poderosos, mas seu conhecimento é limitado aos seus dados de treinamento. Para aplicativos que requerem informações atuais ou conhecimento de domínio específico (os documentos da sua empresa, por exemplo), você precisa aumentar o conhecimento do LLM com dados externos. Isso é chamado de Geração Aumentada por Recuperação (RAG).
A ideia central do RAG é:
1. **Carregar Dados:** Obtenha seus documentos (PDFs, arquivos de texto, páginas da web).
2. **Dividir Dados:** Quebre grandes documentos em partes menores e gerenciáveis.
3. **Incorporar Dados:** Converta essas partes em representações numéricas (embeddings) usando um modelo de embeddings.
4. **Armazenar Dados:** Armazene esses embeddings em um banco de dados vetorial.
5. **Recuperar:** Quando um usuário faz uma pergunta, incorpore a pergunta, busque no banco de dados vetorial por partes de documentos semelhantes.
6. **Aumentar Prompt:** Adicione essas partes recuperadas ao prompt do LLM.
7. **Gerar:** O LLM usa esse prompt aumentado para gerar uma resposta mais informada.
LangChain.js fornece componentes para cada um desses passos.
Passo 1: Carregando Documentos
LangChain.js tem vários carregadores de documentos. Vamos usar um `TextLoader`.
“`javascript
// ragExample.js – Parte 1: Carregamento de Documentos
require(‘dotenv’).config();
const { TextLoader } = require(‘langchain/document_loaders/fs/text’);
async function loadDocuments() {
// Crie um arquivo de texto fictício para demonstração
const fs = require(‘fs’);
fs.writeFileSync(‘my_document.txt’, `
A rápida raposa marrom salta sobre o cachorro preguiçoso.
Este documento fala sobre vários animais e seus comportamentos.
Os cães são conhecidos por sua lealdade e brincadeira.
As raposas são criaturas astutas e solitárias.
Os gatos gostam de cochilar e perseguir ratos.
`);
const loader = new TextLoader(“my_document.txt”);
const docs = await loader.load();
console.log(“Documentos Carregados:”, docs);
// Cada doc terá pageContent e metadata
}
loadDocuments();
“`
Passo 2: Dividindo Documentos
Grandes documentos precisam ser divididos em partes menores para que se encaixem dentro da janela de contexto do LLM e para melhorar a relevância da recuperação.
“`javascript
// ragExample.js – Parte 2: Divisão
require(‘dotenv’).config();
const { TextLoader } = require(‘langchain/document_loaders/fs/text’);
const { RecursiveCharacterTextSplitter } = require(‘langchain/text_splitter’);
async function splitDocuments() {
// (Assuma que my_document.txt já foi criado na Parte 1)
const loader = new TextLoader(“my_document.txt”);
const docs = await loader.load();
const splitter = new RecursiveCharacterTextSplitter({
chunkSize: 100, // Máximo de caracteres por parte
chunkOverlap: 20, // Sobreposição entre partes para manter o contexto
});
const splitDocs = await splitter.splitDocuments(docs);
console.log(“Documentos Divididos:”, splitDocs);
}
splitDocuments();
“`
Passos 3 & 4: Incorporando e Armazenando Documentos (Armazenamento Vetorial)
É aqui que entram os embeddings e os bancos de dados vetoriais. Usaremos embeddings da OpenAI e `HNSWLib` (um armazenamento vetorial local na memória) por simplicidade. Para produção, você usaria um banco de dados vetorial dedicado como Pinecone, Chroma, Weaviate, etc.
“`javascript
// ragExample.js – Parte 3: Embeddings e Armazenamento Vetorial
require(‘dotenv’).config();
const { OpenAIEmbeddings } = require(‘langchain/embeddings/openai’);
const { HNSWLib } = require(‘langchain/vectorstores/hnswlib’);
const { RecursiveCharacterTextSplitter } = require(‘langchain/text_splitter’);
const { TextLoader } = require(‘langchain/document_loaders/fs/text’);
const { OpenAI } = require(‘langchain/llms/openai’);
const { RetrievalQAChain } = require(‘langchain/chains’);
async function ragApplication() {
// 1. Carregar e Dividir Documentos
const fs = require(‘fs’);
fs.writeFileSync(‘my_document.txt’, `
A rápida raposa marrom salta sobre o cachorro preguiçoso.
Este documento fala sobre vários animais e seus comportamentos.
Os cães são conhecidos por sua lealdade e brincadeira.
As raposas são criaturas astutas e solitárias.
Os gatos gostam de cochilar e perseguir ratos.
Um grupo de gatos é chamado de clowder.
`);
const loader = new TextLoader(“my_document.txt”);
const rawDocs = await loader.load();
const splitter = new RecursiveCharacterTextSplitter({
chunkSize: 100,
chunkOverlap: 20,
});
const docs = await splitter.splitDocuments(rawDocs);
// 2. Criar Embeddings e Armazenar no Armazenamento Vetorial
const embeddings = new OpenAIEmbeddings();
const vectorStore = await HNSWLib.fromDocuments(docs, embeddings);
// 3. Criar um Recuperador
const retriever = vectorStore.asRetriever();
“`html
// 4. Crie o Cadeia QA de Recuperação
const model = new OpenAI({ temperature: 0 });
const chain = RetrievalQAChain.fromLLM(model, retriever);
// 5. Faça uma pergunta
const question = “Como é chamado um grupo de gatos?”;
const result = await chain.call({ query: question });
console.log(“Resposta RAG:”, result.text);
const anotherQuestion = “Me fale sobre raposas.”;
const anotherResult = await chain.call({ query: anotherQuestion });
console.log(“Outra Resposta RAG:”, anotherResult.text);
}
ragApplication();
“`
Execute com `node ragExample.js`.
Este exemplo junta todas as peças do RAG. O `RetrievalQAChain` abstrai o processo de recuperação de documentos relevantes e usá-los para responder a uma pergunta. Esta é uma maneira prática de construir chatbots ou sistemas de perguntas e respostas sobre seus dados específicos usando LangChain.js.
Agentes: LLMs Usando Ferramentas
Agentes permitem que LLMs tomem decisões sobre quais ferramentas usar e em que ordem, com base na entrada do usuário. Isso possibilita interações mais dinâmicas e complexas. As ferramentas podem ser qualquer coisa: um motor de busca, uma calculadora, uma chamada de API para seus sistemas internos, ou até mesmo outra cadeia LLM.
Vamos criar um agente simples que pode realizar cálculos usando uma ferramenta `Calculator`.
“`javascript
// agentExample.js
require(‘dotenv’).config();
const { OpenAI } = require(‘langchain/llms/openai’);
const { initializeAgentExecutorWithOptions } = require(‘langchain/agents’);
const { Calculator } = require(‘langchain/tools/calculator’);
async function runAgent() {
const model = new OpenAI({ temperature: 0 });
const tools = [new Calculator()];
// Inicializar o executor do agente
const executor = await initializeAgentExecutorWithOptions(tools, model, {
agentType: “openai-functions”, // Use o recurso de chamada de funções da OpenAI
verbose: true, // Veja o processo de pensamento do agente
});
console.log(“Chamando o agente com uma pergunta matemática simples…”);
const result1 = await executor.call({ input: “Qual é 123 mais 456?” });
console.log(“Resultado do Agente 1:”, result1.output);
console.log(“\nChamando o agente com uma pergunta mais complexa…”);
const result2 = await executor.call({ input: “Qual é a raiz quadrada de 625 multiplicada por 3?” });
console.log(“Resultado do Agente 2:”, result2.output);
}
runAgent();
“`
Execute com `node agentExample.js`.
Com `verbose: true`, você verá os “pensamentos” do agente: ele identifica que um cálculo é necessário, usa a ferramenta `Calculator` e, em seguida, fornece a resposta. Este é um padrão poderoso para construir aplicações que vão além da simples geração de texto. LangChain.js simplifica a configuração desses agentes.
Memória: Mantendo o Contexto da Conversa
Por padrão, LLMs são sem estado. Cada chamada de API é independente. Para aplicações conversacionais, o LLM precisa lembrar interações passadas. LangChain.js fornece vários tipos de memória para alcançar isso.
`ConversationBufferMemory` é uma escolha comum, armazenando o histórico bruto da conversa.
“`javascript
// memoryExample.js
require(‘dotenv’).config();
const { OpenAI } = require(‘langchain/llms/openai’);
const { ConversationChain } = require(‘langchain/chains’);
const { ConversationBufferMemory } = require(‘langchain/memory’);
async function conversationalApp() {
const model = new OpenAI({ temperature: 0.7 });
const memory = new ConversationBufferMemory();
const chain = new ConversationChain({ llm: model, memory: memory });
console.log(“Iniciando a conversa…”);
let result1 = await chain.call({ input: “Oi, meu nome é Jake.” });
console.log(“Usuário: Oi, meu nome é Jake.”);
console.log(“IA:”, result1.response);
let result2 = await chain.call({ input: “Qual é o meu nome?” });
console.log(“Usuário: Qual é o meu nome?”);
console.log(“IA:”, result2.response);
let result3 = await chain.call({ input: “Me conte um fato interessante sobre JavaScript.” });
console.log(“Usuário: Me conte um fato interessante sobre JavaScript.”);
console.log(“IA:”, result3.response);
}
conversationalApp();
“`
Execute com `node memoryExample.js`.
“““html
O `ConversationBufferMemory` mantém o histórico de chat, permitindo que o LLM responda corretamente à pergunta “Qual é o meu nome?” com base na interação anterior. LangChain.js oferece outros tipos de memória para casos de uso mais avançados, como resumir conversas ou armazenar apenas partes específicas.
Dicas Práticas para o Desenvolvimento com LangChain.js
1. **Comece Simples:** Não tente construir um agente complexo com várias ferramentas e memória imediatamente. Comece com chamadas simples de LLM e `LLMChain`.
2. **Use `verbose: true`:** Ao depurar cadeias ou agentes, definir `verbose: true` é inestimável. Isso mostra as etapas intermediárias, os prompts enviados e as respostas recebidas, ajudando você a entender por que sua cadeia pode não estar se comportando como esperado.
3. **Gerencie Chaves de API de Forma Segura:** Use sempre variáveis de ambiente para suas chaves de API. Nunca as coloque sob controle de versão.
4. **Entenda Janelas de Contexto:** Esteja ciente dos limites de tokens do LLM escolhido. Prompts longos, extensos históricos de conversa ou muitos documentos recuperados podem rapidamente exceder esses limites. LangChain.js tem ferramentas para ajudar a gerenciar isso, mas é importante estar ciente.
5. **Experimente com `temperatura`:** O parâmetro `temperatura` controla a aleatoriedade da saída do LLM. Valores mais altos (por exemplo, 0.7-1.0) levam a respostas mais criativas e menos determinísticas. Valores mais baixos (por exemplo, 0.0-0.3) são mais factuais e consistentes. Ajuste isso com base nas necessidades da sua aplicação.
6. **Explore a Documentação:** A documentação do LangChain.js é completa. Se você está procurando um carregador, cadeia, ou ferramenta específica, é provável que esteja coberta lá.
7. **Considere Armazenamentos Vetoriais em Produção:** Para aplicações RAG do mundo real, substitua `HNSWLib` por um banco de dados vetorial persistente como Pinecone, Chroma ou Weaviate. Isso permitirá que você escale e armazene grandes quantidades de dados.
8. **Tratamento de Erros:** Implemente um tratamento de erros sólido para chamadas de API, especialmente em ambientes de produção. Problemas de rede, limites de taxa ou entradas inválidas podem causar falhas.
Perguntas Frequentes sobre LangChain.js
Q1: O LangChain.js é apenas para modelos da OpenAI?
Não, o LangChain.js suporta uma ampla gama de provedores de LLM, incluindo OpenAI, modelos da Hugging Face (via `HuggingFaceHub` ou `HuggingFaceInference`), Google (por exemplo, `GoogleGenerativeAI`), Anthropic e muitos mais. As abstrações principais do LangChain.js permitem que você troque provedores de LLM com alterações mínimas de código.
Q2: Qual é a diferença entre `model.call()` e `chain.call()` ou `chain.run()`?
`model.call()` é a forma mais direta de interagir com uma única instância de LLM, passando um prompt de string bruta. `chain.call()` é usado para cadeias e aceita um objeto que contém variáveis de entrada (que são formatadas por um `PromptTemplate` se usadas dentro da cadeia). `chain.run()` é um método de conveniência para cadeias que têm apenas uma variável de entrada e retorna diretamente o texto de saída. Para cadeias mais complexas com várias entradas/saídas, `chain.call()` é preferido.
Q3: Como posso integrar o LangChain.js ao meu banco de dados ou API existente?
Você pode integrar o LangChain.js com seus sistemas existentes criando ferramentas personalizadas para agentes. Uma ferramenta é essencialmente uma função que aceita uma string de entrada e retorna uma string de saída. Você pode definir uma ferramenta que consulta seu banco de dados, chama uma API interna ou realiza qualquer outra lógica personalizada, e então disponibilizar essa ferramenta para seu agente LangChain.js. Para RAG, você pode criar implementações personalizadas de `DocumentLoader` para carregar dados de suas fontes de dados específicas.
Q4: Quando devo usar o LangChain.js em vez de chamar diretamente as APIs de LLM?
Use o LangChain.js quando precisar construir aplicações que envolvam mais do que uma única chamada isolada de LLM. Se sua aplicação exigir:
* Raciocínio em várias etapas (cadeias).
* Integração de dados externos (RAG).
* Dar ao LLM acesso a ferramentas externas (agentes).
* Gerenciar o histórico de conversação (memória).
* Trocar facilmente provedores de LLM.
* Código mais estruturado e de fácil manutenção.
Se você está apenas fazendo um prompt único para teste, chamadas diretas de API podem ser mais simples, mas para qualquer aplicação prática, LangChain.js rapidamente se torna indispensável.
Conclusão
LangChain.js é um framework poderoso para construir aplicações sofisticadas de LLM em JavaScript e TypeScript. Ao entender seus componentes principais—LLMs, Prompts, Cadeias, Recuperação, Agentes e Memória—você pode construir sistemas inteligentes que vão além da simples geração de texto. Este guia forneceu um ponto de partida prático e acionável. Desde chamadas simples de LLM até pipelines e agentes RAG complexos, LangChain.js oferece as ferramentas para dar vida às suas ideias de automação de IA. Comece a experimentar, construa pequenos projetos, e você rapidamente descobrirá o potencial do LangChain.js em seu fluxo de desenvolvimento.
“`
🕒 Published: