Pular para o conteúdo principal

LangChain.js e Oracle AI Database: guia de busca vetorial

Conecte o LangChain.js ao Oracle AI Database com o OracleVS, armazene embeddings com metadados e compare busca por similaridade, filtros por metadados e MMR em TypeScript.
· 10 min leer

Explore com IA

Um modelo de linguagem responde a perguntas gerais, mas não consegue consultar com confiança uma base de conhecimento privada sem que o app recupere primeiro as informações certas. Para desenvolvedores JavaScript, o LangChain.js oferece abstrações conhecidas para documentos, embeddings e recuperação. O que faltava era um local persistente para armazenar e pesquisar os vetores gerados.

O Oracle AI Database cobre essa necessidade por meio da integração @oracle/langchain-oracledb. Neste guia, você vai conectar um pequeno fluxo em TypeScript ao Oracle, armazenar texto com metadados, executar busca por similaridade e melhorar a recuperação com filtros e maximal marginal relevance (MMR). O tutorial foca no fluxo de retrieval; o app em TypeScript que acompanha adiciona a mesma integração a uma interface interativa no navegador.

Para detalhes da integração, veja o guia oficial de integração do Oracle LangChain JavaScript.

O que é a integração entre LangChain.js e Oracle AI Database?

O LangChain.js padroniza como um app trabalha com modelos de embedding e repositórios vetoriais. O pacote de integração da Oracle fornece o OracleVS, uma implementação de vector store que persiste texto, metadados e embeddings vetoriais no Oracle AI Database. Seu app chama métodos do LangChain.js em vez de escrever SQL manualmente para cada consulta por similaridade.

O mesmo pacote também inclui OracleDocLoader, OracleTextSplitter, OracleEmbeddings e OracleSummary. São blocos opcionais úteis; o exemplo abaixo foca no OracleVS e mantém a geração de embeddings separada para deixar o fluxo fácil de entender.

Diagrama de arquitetura mostrando um fluxo RAG em TypeScript com LangChain.js: uma interface React envia uma pergunta para uma API em Node.js, o LangChain.js cria embeddings e recupera documentos via OracleVS de uma tabela vetorial no Oracle AI Database, e a API retorna uma resposta fundamentada.

Ingestão e recuperação de documentos com LangChain.js, OracleVS e Oracle AI Database

Principais recursos da integração

Armazene embeddings junto com metadados do documento

Um modelo de embedding transforma texto em vetores numéricos. O OracleVS armazena esses vetores com o texto de origem e metadados estruturados. Metadados como categoria do documento ou fonte ajudam o app a restringir as buscas sem perder contexto útil.

Recupere trechos relevantes usando similaridade vetorial

No momento da consulta, o mesmo modelo de embedding converte a pergunta em um vetor. O Oracle compara esse vetor com os vetores armazenados usando uma estratégia de distância configurada, como a distância cosseno, e retorna os documentos mais próximos. Os resultados permanecem como objetos Document do LangChain, prontos para o processamento a jusante.

Controle os resultados com filtros e MMR

A busca por similaridade responde: “quais itens estão mais próximos desta pergunta?”. Um filtro por metadados reduz os documentos elegíveis. O MMR adiciona outro objetivo: manter os trechos relevantes enquanto reduz resultados quase duplicados. Essas operações se complementam — não são intercambiáveis.

Primeiros passos com LangChain.js e Oracle AI Database

Pré-requisitos

Para este exemplo em TypeScript, você precisa do Node.js 24.13.0, npm 11.6.2, uma instância local do Oracle AI Database 26ai Free com suporte a vetores, e um schema com permissão para criar, inserir, consultar e dropar a tabela de demonstração e seu índice vetorial. Você também precisa de uma chave de API da OpenAI para o exemplo de embedding. OpenAIEmbeddings é uma opção compatível com LangChain, não uma exigência do OracleVS.

Instale o Node.js pela página oficial de downloads do Node.js.

Para o caminho local principal, siga o quick start do Oracle AI Database Free. Depois que o banco estiver em execução, use um serviço como localhost:1521/FREEPDB1 e um schema com as permissões acima.

Crie um projeto TypeScript

mkdir langchain-oracle-demo
cd langchain-oracle-demo
npm init -y
npm pkg set type=module
npm install @oracle/[email protected] @langchain/[email protected] @langchain/[email protected] [email protected] [email protected]
npm install --save-dev [email protected] [email protected] @types/[email protected]

Crie um arquivo chamado index.ts nesta pasta. Adicione os trechos executáveis de TypeScript abaixo nesse mesmo arquivo, na ordem mostrada. Não crie um arquivo separado para cada trecho. Copie apenas os trechos de TypeScript executáveis: os blocos de SQL e de saída representativa são exemplos explicativos e não devem ser colados no index.ts.

A configuração type=module no package.json permite o await no escopo global usado pelos exemplos. A configuração de pacotes do Node.js está documentada no guia oficial de pacotes do Node.js.

O pacote de integração da Oracle implementa o vector store, @langchain/core fornece Document, @langchain/openai fornece o modelo de embedding do exemplo, e oracledb gerencia a conexão com o banco. As versões acima correspondem ao app de referência; o tsx executa o exemplo em TypeScript diretamente, sem etapa de build separada.

Configure a conexão

ORACLE_USER=your_schema
ORACLE_PASSWORD=your_password
ORACLE_CONNECT_STRING=localhost:1521/FREEPDB1
OPENAI_API_KEY=your_api_key

Salve esses valores em um arquivo .env local e adicione .env ao .gitignore. Este artigo usa o Oracle AI Database Free local como configuração principal para que os passos sejam reproduzíveis. O Autonomous AI Database é uma alternativa válida de implantação, mas exige o descritor de serviço e a configuração de wallet ou TLS desse ambiente.

import "dotenv/config";
import oracledb from "oracledb";
import { Document } from "@langchain/core/documents";
import { OpenAIEmbeddings } from "@langchain/openai";
import { OracleVS, DistanceStrategy, VectorElementFormat }
  from "@oracle/langchain-oracledb";

const pool = await oracledb.createPool({
  user: process.env.ORACLE_USER,
  password: process.env.ORACLE_PASSWORD,
  connectString: process.env.ORACLE_CONNECT_STRING,
  poolMin: 1,
  poolMax: 4,
});

O pool permite que o OracleVS reutilize sessões do banco. Mantenha todas as instruções de ingestão, recuperação e verificação dentro do bloco try. O próximo bloco inicia esse bloco, e os trechos seguintes o continuam. O pool é fechado somente após a verificação, na seção de limpeza abaixo. Em um servidor, inicialize o pool uma vez e feche-o no encerramento gracioso, em vez de abrir uma nova conexão para cada requisição.

Como construir busca de documentos com LangChain.js

Vamos usar 10 notas curtas de uma base de conhecimento, incluindo trechos sobrepostos para recuperação. O corpus é pequeno de propósito, para permitir comparar a busca por similaridade com filtro por metadados e MMR.

Defina seus documentos de conhecimento

try {
  const documents = [
    ["database-guide", "database", "Oracle AI Database stores vector embeddings alongside application data."],
    ["connection-pooling", "operations", "A connection pool reuses Oracle database sessions across requests."],
    ["vector-indexes", "performance", "HNSW vector indexes can improve nearest-neighbor search as a table grows."],
    ["metadata-filtering", "retrieval", "Metadata filters restrict retrieval to matching categories or sources."],
    ["similarity-search", "retrieval", "Similarity search returns chunks closest to the query embedding."],
    ["mmr-retrieval", "retrieval", "MMR reduces repeated content while keeping results relevant."],
    ["retrieval-overlap-1", "retrieval", "Similarity search may return several near-duplicate passages when multiple notes explain the same retrieval strategy."],
    ["retrieval-overlap-2", "retrieval", "Several notes about the same retrieval strategy can produce repetitive top matches; MMR selects a more diverse set while preserving relevance."],
    ["troubleshooting", "troubleshooting", "For empty results, check ingestion, embeddings, and filters."],
    ["embedding-compatibility", "retrieval", "Ingestion and query retrieval must use compatible dimensions."],
  ].map(([source, category, pageContent]) =>
    new Document({ pageContent, metadata: { source, category } }));

Cada Document tem pageContent e metadata. Os campos source e category acompanham o documento na ingestão e na recuperação, para que o app explique de onde veio o resultado e restrinja buscas a um subconjunto relevante.

Configure embeddings e crie o OracleVS

  const embeddings = new OpenAIEmbeddings({
    model: "text-embedding-3-small",
  });

  const vectorStore = await OracleVS.fromDocuments(documents, embeddings, {
    client: pool,
    tableName: "LC_JS_RAG_DEMO",
    query: "Oracle AI Database document search",
    distanceStrategy: DistanceStrategy.COSINE,
    format: VectorElementFormat.FLOAT32,
  });

OracleVS.fromDocuments() é a chamada central da integração. Ela inicializa o vector store, gera embeddings para os documentos fornecidos e armazena conteúdo, vetores e metadados no Oracle AI Database.

O parâmetro query fornece um texto de amostra que é convertido em embedding durante a inicialização para determinar a dimensão vetorial necessária para a tabela. Ele não é usado para pesquisar os documentos armazenados. DistanceStrategy.COSINE define a métrica de distância vetorial, enquanto VectorElementFormat.FLOAT32 define o formato de elemento do vetor.

Antes de reexecutar a ingestão, use um novo nome de tabela de demonstração ou limpe os dados existentes para evitar inserir documentos duplicados.

O OracleVS aceita uma implementação de embedding compatível com LangChain, permitindo trocar o provedor sem alterar o fluxo do vector store. Porém, os embeddings usados para ingestão e recuperação devem ser compatíveis com a coluna vetorial do Oracle.

O OracleVS determina a dimensão vetorial na inicialização usando o modelo de embedding configurado. Para inspecionar as dimensões e o formato de armazenamento de um vetor já salvo no Oracle AI Database, execute a consulta SQL a seguir:

SELECT
    VECTOR_DIMENSION_COUNT(embedding) AS vector_dimensions,
    VECTOR_DIMENSION_FORMAT(embedding) AS vector_format
FROM LC_JS_RAG_DEMO
FETCH FIRST 1 ROW ONLY;

Se você trocar para um modelo de embedding com dimensão diferente, crie uma tabela vetorial compatível e regenere os embeddings dos documentos. Mesmo que dois modelos gerem vetores com a mesma dimensão, seus espaços de embedding podem diferir; por isso, re-embed documentos existentes antes de usar o novo modelo na recuperação.

Para as assinaturas dos métodos do vector store e opções de recuperação, veja a referência oficial do VectorStore no LangChain.js.

Recupere documentos com busca por similaridade

Por exemplo, a chamada abaixo pede ao vector store OracleVS os 3 documentos mais próximos e imprime a fonte nos metadados junto com o texto de cada trecho:

  const retrievalQuestion =
    "How can vector retrieval reduce repetitive results?";
  const results = await vectorStore.similaritySearch(
    retrievalQuestion,
    3
  );
  console.log(results.map((doc) => ({
    source: doc.metadata.source,
    text: doc.pageContent,
  })));

O código mapeia cada Document do LangChain para um objeto simples contendo source e pageContent para exibição. Uma saída representativa aparece abaixo; a ordem exata pode variar com o modelo de embedding e a consulta:

[
  { source: "retrieval-overlap-2", text: "Several notes about the same retrieval strategy can produce repetitive top matches; MMR selects a more diverse set while preserving relevance." },
  { source: "retrieval-overlap-1", text: "Similarity search may return several near-duplicate passages when multiple notes explain the same retrieval strategy." },
  { source: "mmr-retrieval", text: "MMR reduces repeated content while keeping results relevant." }
]

O primeiro argumento é a pergunta do usuário e o segundo é k, o número máximo de documentos a recuperar. O LangChain.js usa o modelo de embedding configurado para converter a pergunta em vetor, e o Oracle AI Database executa a busca por similaridade para achar os documentos mais próximos.

Se menos de k documentos ficarem disponíveis após as condições de busca e filtros por metadados, o método retorna apenas os resultados disponíveis. Os Document recuperados contêm texto e metadados, que podem ser exibidos com atribuição de fonte ou repassados para uma etapa posterior de geração de resposta.

Inspecione as pontuações de recuperação

Por exemplo, use similaritySearchWithScore quando quiser inspecionar a distância associada a cada documento recuperado:

  const scored = await vectorStore.similaritySearchWithScore(
    "Where are document embeddings stored?",
    3
  );

  for (const [doc, score] of scored) {
    console.log({
      text: doc.pageContent,
      source: doc.metadata.source,
      score,
    });
  }

similaritySearchWithScore retorna uma distância com cada correspondência. Seu valor numérico e direção dependem da estratégia de distância escolhida, então não é uma “porcentagem de confiança” universal. Compare pontuações apenas usando o mesmo modelo de embedding e a mesma estratégia de distância, e inspecione o trecho recuperado antes de definir um limite.

Limite resultados com filtros por metadados

  const databaseOnly = await vectorStore.similaritySearch(
    "Where are vector embeddings stored?",
    3,
    { category: { $eq: "database" } }
  );

  console.log(databaseOnly.map((doc) => doc.metadata.source));

Exemplo de saída:

["database-guide"]

O terceiro argumento restringe a busca a itens com category = database. Neste corpus, o resultado filtrado previsível é ["database-guide"]. Um filtro altera quais documentos são elegíveis; a similaridade vetorial continua ranqueando os documentos elegíveis.

Use MMR para reduzir resultados repetitivos

  const diverse = await vectorStore.maxMarginalRelevanceSearch(
    retrievalQuestion,
    {
      k: 3,
      fetchK: 6,
      lambda: 0.5,
    }
  );
  console.log(diverse.map((doc) => doc.metadata.source));

Saída representativa para um corpus com sobreposição (a ordem pode variar entre modelos e execuções):

["retrieval-overlap-2", "mmr-retrieval", "metadata-filtering"]

O MMR primeiro considera um conjunto de candidatos (fetchK) e então seleciona k documentos equilibrando relevância com diversidade. Um lambda menor enfatiza mais a diversidade; um valor maior enfatiza mais a relevância. Com o corpus sobreposto acima, as fontes selecionadas podem diferir da busca por similaridade comum, tornando o trade-off de recuperação visível.

Passe o contexto recuperado para um app de IA

  const question = "How does LangChain.js retrieve Oracle documents?";
  const contextDocs = await vectorStore.similaritySearch(question, 3);

  const context = contextDocs
    .map((doc, i) => `[${i + 1}] ${doc.pageContent}`)
    .join("\n\n");

  console.log({ question, context });

Este é o ponto de passagem entre a recuperação do LangChain.js e a chamada ao modelo de linguagem grande (LLM): o app tem uma pergunta mais evidências inspecionáveis, prontas para um prompt que peça ao modelo para responder a partir desse contexto.

Recuperação e geração são responsabilidades separadas. Aqui, context é uma string de texto simples que um modelo de chat pode consumir. Você pode fornecê-la ao modelo com a instrução de responder apenas com base no material recuperado e citar os identificadores de fonte. A integração com o banco funciona mesmo sem um modelo de chat.

Como verificar a integração

Uma validação útil checa a ingestão e cada estratégia de recuperação separadamente. Primeiro, confirme que o vector store foi criado sem erro no banco. Depois, inspecione os metadados de fonte retornados pela busca por similaridade, o resultado filtrado e o resultado com MMR.

  const check = await vectorStore.similaritySearch(
    "How does OracleVS connect to LangChain.js?",
    3
  );

  if (check.length === 0) {
    throw new Error("No documents retrieved; inspect ingestion and filters.");
  }

  console.log({
    similarity: check.map((doc) => doc.metadata.source),
    filtered: databaseOnly.map((doc) => doc.metadata.source),
    mmr: diverse.map((doc) => doc.metadata.source),
  });

Feche o pool de conexões após a verificação

} finally {
  await pool.close(10);
}

A limpeza roda apenas após finalizar ingestão, recuperação e verificação. O tempo de drenagem dá uma pequena janela para conexões em uso concluírem. Em um servidor de longa execução, mantenha o pool aberto até o encerramento gracioso. Veja a documentação do pool.close() do node-oracledb para detalhes do ciclo de vida.

Neste ponto, o arquivo index.ts completo pode ser executado com:

npx tsx index.ts

Uma saída de validação representativa é:

{
  similarity: ["retrieval-overlap-1", "retrieval-overlap-2", "mmr-retrieval"],
  filtered: ["database-guide"],
  mmr: ["retrieval-overlap-2", "mmr-retrieval", "metadata-filtering"]
}

A ordem de similaridade exata e os valores de distância podem variar conforme o modelo e o provedor de embedding. O resultado filtrado deve conter database-guide, enquanto o resultado com MMR deve mostrar um conjunto variado de fontes de recuperação do corpus sobreposto.

Dicas e solução de problemas

A conexão com o banco falha

Verifique a string de conexão, as credenciais, o serviço acessível e os privilégios do schema. Se você usar o Autonomous AI Database, confirme a configuração exigida de wallet ou TLS. Teste a conexão com o banco de forma independente antes de depurar a recuperação.

Ocorre incompatibilidade na dimensão do embedding

Os vetores criados na ingestão e os vetores da consulta devem ter dimensões compatíveis. Usar modelos de embedding diferentes para inserções e consultas pode quebrar a busca ou degradar resultados. Mantenha a escolha do modelo consistente para uma tabela.

Uma busca não retorna documentos

Confirme que a ingestão inseriu linhas e tente novamente sem filtros de metadados restritivos. Para corpora pequenos, experimente consultas mais amplas e inspecione o conteúdo armazenado.

Os resultados são relevantes, mas repetitivos

Compare a busca por similaridade com o MMR usando um corpus com trechos sobrepostos. Ajuste k, fetchK e lambda enquanto verifica se a diversidade não está custando a perda de trechos importantes.

Vale a pena criar um índice vetorial?

Para um dataset pequeno, comece validando a corretude sem ajustar indexação. À medida que os dados crescem, avalie índices vetoriais do Oracle como HNSW (Hierarchical Navigable Small World) ou IVF (Inverted File), conforme seus requisitos de performance e acurácia. A criação do índice é uma otimização, não pré-requisito para entender a integração básica.

Para mais detalhes sobre índices vetoriais no Oracle, veja a documentação de índices vetoriais da Oracle.

Explore uma implementação completa de referência em TypeScript

Para ver como esses conceitos se juntam em um app funcional, explore a implementação de referência com LangChain.js e Oracle AI Database.

Construído em TypeScript, o app reúne ingestão de documentos, armazenamento vetorial, busca por similaridade, filtro por metadados e MMR usando LangChain.js e Oracle AI Database. Ele também oferece uma interface interativa para experimentar configurações de recuperação, inspecionar documentos recuperados e entender como diferentes estratégias afetam o contexto retornado para o app.

O repositório inclui o código-fonte e as instruções de setup, permitindo explorar a integração completa e adaptar a implementação aos seus projetos.

Conclusão e próximos passos

Você conectou o LangChain.js ao Oracle AI Database via OracleVS, representou conhecimento como objetos Document, criou embeddings vetoriais persistentes e comparou busca por similaridade, filtro por metadados e MMR. Como próximo passo, leia a documentação oficial do LangChain.js e o guia oficial de integração Oracle LangChain JavaScript.

Se você trabalha em outras linguagens, nosso tutorial de Oracle AI Vector Search cobre os mesmos passos de armazenamento e consulta em Python, e nosso tutorial de LangChain4j cria um agente Java com Oracle AI Database.

Nosso curso Retrieval Augmented Generation (RAG) com LangChain é um complemento opcional focado em recuperação; os exemplos estão em Python, mas os conceitos de fluxo se aplicam a esta implementação em TypeScript.

FAQs

O que acontece se eu trocar o modelo de embedding depois de armazenar os documentos?

Os embeddings armazenados na tabela vetorial do Oracle devem ser compatíveis com os embeddings usados na busca. Trocar de modelo pode alterar tanto as dimensões quanto o significado das coordenadas do vetor; portanto, re-embed e reindexe os documentos ao mudar de modelo. Use a mesma configuração de embedding para ingestão e recuperação nas consultas.

Eu preciso de um modelo de chat para usar o OracleVS?

Não. Um fluxo com vector store exige um modelo de embedding para ingestão e consulta. Um modelo de chat é opcional e geralmente é adicionado quando os trechos recuperados devem ser transformados em uma resposta em linguagem natural.

Posso usar um provedor de embedding diferente da OpenAI?

Sim. O OracleVS aceita uma implementação de embedding compatível com LangChain. Escolha um provedor que atenda aos seus requisitos e use a mesma configuração compatível de embedding para documentos e consultas.

Por que usar filtro por metadados junto com similaridade vetorial?

A similaridade vetorial encontra conteúdo semanticamente próximo; o filtro por metadados restringe qual conteúdo pode ser retornado, como documentos de uma categoria ou fonte específica.

Quando devo escolher MMR em vez da busca por similaridade comum?

O MMR ajuda quando os primeiros resultados contêm trechos repetitivos e o app se beneficia de evidências mais variadas. A busca por similaridade simples é mais direta quando os vizinhos mais próximos são o objetivo principal.

Daniela Pavlenco

Autor

Daniela Pavlenco

Sou Developer Advocate na Oracle, com foco em ajudar desenvolvedores a explorar tecnologias de IA e a criar aplicações práticas com ferramentas e frameworks modernos. Meu trabalho envolve criar conteúdo técnico, exemplos práticos e recursos para desenvolvedores que tornam conceitos complexos mais fáceis de entender e aplicar em projetos do mundo real.

Temas

Relacionado

blog

Os 7 melhores bancos de dados vetoriais em 2026