API de RAG

Configure a API de Retrieval-Augmented Generation (RAG) para indexação e recuperação de documentos usando Langchain e FastAPI. Esta API integra-se ao LibreChat para fornecer respostas com reconhecimento de contexto baseadas em arquivos enviados pelo usuário.

A API de RAG indexa arquivos enviados pelo usuário e recupera passagens relevantes para aumentar seus prompts, fornecendo ao LibreChat respostas conscientes do contexto baseadas em seus documentos. Ela é executada como um serviço FastAPI separado, suportado por um banco de dados PostgreSQL + pgvector.

Novo no RAG?

A Apresentação da API de RAG explica o conceito com mais detalhes e contém um link para um vídeo útil. Esta página aborda a configuração e os ajustes.

Disponibilidade

O RAG funciona com Agents, bem como com Custom Endpoints, OpenAI, Azure OpenAI, Anthropic e Google.

Os Assistants da OpenAI possuem sua própria implementação de RAG por meio da funcionalidade "Retrieval" (detalhes aqui). Usar a API de RAG com a Assistants API ainda vale a pena, uma vez que a OpenAI cobra tanto pelo armazenamento de arquivos quanto pelo Retrieval. Esta integração está planejada para uma atualização futura.

Início Rápido com Docker

Para Docker, a RAG API já está configurada tanto no docker-compose.yml padrão quanto no deploy-compose.yml, incluindo o valor de RAG_API_URL. Você só precisa garantir que está executando a imagem e os arquivos compose mais recentes. Consulte o guia de atualização do LibreChat para Docker se não tiver certeza de como atualizar.

Arquivo .env compartilhado

Com a configuração padrão do Docker, o arquivo .env é compartilhado entre o LibreChat e a RAG API. Defina as variáveis de RAG nesse mesmo arquivo. A lista completa encontra-se no RAG API README.

Escolha o provedor de embeddings que você deseja usar.

Use RAG com embeddings da OpenAI. Esta é a configuração padrão.

Defina a URL da API de RAG. Adicione o seguinte ao seu arquivo .env:

RAG_API_URL=http://host.docker.internal:8000

Forneça uma chave de API da OpenAI (se necessário). Se sua chave de API da OpenAI estiver definida como user_provided, adicione uma chave para embeddings. Pule esta etapa se você já fornecer a chave da OpenAI em seu arquivo .env.

RAG_OPENAI_API_KEY=sk-your-openai-api-key-example

Inicie os containers.

docker compose up -d

Use RAG com embeddings do Hugging Face.

Configure o provedor. Adicione o seguinte ao seu arquivo .env:

RAG_API_URL=http://host.docker.internal:8000
EMBEDDINGS_PROVIDER=huggingface
HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxx

Mude para a imagem completa da API RAG. Atualize seu arquivo docker-compose.override.yml:

version: '3.4'

services:
  rag_api:
    image: registry.librechat.ai/danny-avila/librechat-rag-api-dev:latest

Inicie os containers.

docker compose up -d

Use RAG com embeddings locais do Ollama.

Pré-requisito

Você precisa do Ollama e do modelo de embedding nomic-embed-text. Faça o pull dele com ollama pull nomic-embed-text.

Configure o provedor. Adicione o seguinte ao seu arquivo .env:

RAG_API_URL=http://host.docker.internal:8000
EMBEDDINGS_PROVIDER=ollama
OLLAMA_BASE_URL=http://host.docker.internal:11434
EMBEDDINGS_MODEL=nomic-embed-text

Mude para a imagem completa da API RAG. Atualize seu arquivo docker-compose.override.yml:

version: '3.4'

services:
  rag_api:
    image: registry.librechat.ai/danny-avila/librechat-rag-api-dev:latest
    # If running on Linux
    # extra_hosts:
    #   - "host.docker.internal:host-gateway"

Inicie os containers.

docker compose up -d

Lite vs. full image

O Docker usa a imagem "lite" da RAG API por padrão (registry.librechat.ai/danny-avila/librechat-rag-api-dev-lite:latest), que suporta apenas embeddings remotos da OpenAI ou de um serviço remoto HuggingFace/Ollama que você tenha configurado.

Para embeddings locais, altere a imagem no arquivo compose para a build completa, registry.librechat.ai/danny-avila/librechat-rag-api-dev:latest. Faça essa alteração no seu Docker Compose Override File. Veja o docker-compose.override.yml.example na raiz do projeto para um exemplo.

Se você deseja um arquivo compose que inclua apenas o banco de dados PostgreSQL + pgvector e a API Python, veja rag.yml na raiz do projeto.

Armazenamento de banco de dados

Os arquivos compose padrão armazenam os dados do pgvector/PostgreSQL no volume pgdata2 gerenciado pelo Docker. Isso é intencional: os arquivos do banco de dados não precisam ser editados diretamente a partir do host, e um volume gerenciado evita problemas comuns de propriedade e permissão. Arquivos editáveis voltados ao usuário (uploads, logs, imagens, dados do MongoDB e configuração do NGINX) são montados via bind-mount em pastas do projeto onde o acesso direto pelo host é útil.

Configuração Local

Uma configuração sem contêiner é mais prática. Siga as instruções no repositório da RAG API.

Defina RAG_API_URL no seu arquivo .env do LibreChat para onde quer que a API esteja acessível a partir da sua configuração. Isso difere do Docker, onde o valor já está definido no arquivo docker-compose.yml padrão.

Configuração

Defina as opções da API de RAG por meio de variáveis de ambiente em um arquivo .env acessível à API. A maioria é opcional, exceto pelas credenciais e caminhos exigidos pelo provedor escolhido. Na configuração padrão, apenas RAG_OPENAI_API_KEY é obrigatória.

Variáveis de Ambiente

Key	Type	Description	Example
RAG_API_URL	string	URL do serviço de API de RAG.	RAG_API_URL=http://host.docker.internal:8000
RAG_OPENAI_API_KEY	string	Chave de API da OpenAI para embeddings. Substitui a OPENAI_API_KEY para RAG.	# RAG_OPENAI_API_KEY=sk-your-key
RAG_OPENAI_BASEURL	string	URL base personalizada da OpenAI para embeddings de RAG.	# RAG_OPENAI_BASEURL=
RAG_USE_FULL_CONTEXT	boolean	Buscar o contexto completo do arquivo em vez dos 4 principais resultados. Padrão: false.	# RAG_USE_FULL_CONTEXT=true
EMBEDDINGS_PROVIDER	string	Provedor de Embeddings: openai, azure, huggingface, huggingfacetei ou ollama. Padrão: openai.	# EMBEDDINGS_PROVIDER=openai
EMBEDDINGS_MODEL	string	Modelo de embeddings a ser usado. O padrão depende do provedor.	# EMBEDDINGS_MODEL=text-embedding-3-small
RAG_PORT	number	Porta onde a RAG API é executada. Padrão: 8000.	# RAG_PORT=8000
RAG_HOST	string	Hostname para a API de RAG. Padrão: 0.0.0.0.	# RAG_HOST=0.0.0.0
COLLECTION_NAME	string	Nome da coleção do vector store. Padrão: testcollection.	# COLLECTION_NAME=testcollection
CHUNK_SIZE	number	Tamanho dos blocos de texto. Padrão: 1500.	# CHUNK_SIZE=1500
CHUNK_OVERLAP	number	Sobreposição entre chunks. Padrão: 100.	# CHUNK_OVERLAP=100
OLLAMA_BASE_URL	string	URL base do Ollama ao usar embeddings do Ollama.	# OLLAMA_BASE_URL=http://host.docker.internal:11434

Precedência de credenciais

OPENAI_API_KEY funciona para embeddings de RAG, mas RAG_OPENAI_API_KEY a substitui para evitar conflitos de credenciais.

Para a lista completa de variáveis e suas descrições, veja o RAG API repo.

Uso

Assim que a RAG API estiver em execução, ela se integra ao LibreChat automaticamente. Quando um usuário faz upload de arquivos para uma conversa, a API os indexa e os utiliza para respostas sensíveis ao contexto.

Faça upload de arquivos para a conversa. Se RAG_API_URL não estiver configurado ou não puder ser acessado, o upload falhará.

Chat as usual. À medida que o usuário interage com o modelo, a RAG API recupera passagens relevantes dos arquivos indexados com base na entrada e as utiliza para aumentar o prompt.

Controle quando os arquivos são consultados. Por padrão, o armazenamento vetorial é consultado a cada nova mensagem em uma conversa que possua um arquivo anexado. Elabore seus prompts de acordo.

Desative Resend Files nas configurações da conversa para consultar arquivos apenas quando eles forem explicitamente anexados a uma mensagem.

Alternância de Reenvio de Arquivos nas configurações de conversa

Reutilize arquivos indexados. Faça o upload de um arquivo uma vez e, em seguida, anexe-o a qualquer nova mensagem ou conversa a partir do Painel Lateral.

Anexando arquivos indexados a partir do Painel Lateral

Os arquivos devem estar no armazenamento "Host". Os arquivos da "OpenAI" são tratados de forma diferente e são exclusivos para Assistants, portanto, não devem ter sido enviados enquanto o endpoint Assistants estava selecionado e ativo. Visualize e gerencie seus arquivos no Painel Lateral.

Visualizando e gerenciando arquivos a partir do Painel Lateral

Solução de problemas

Se você encontrar problemas ao configurar ou usar a RAG API:

Confirme se todas as variáveis de ambiente necessárias estão definidas corretamente no seu arquivo .env.
Certifique-se de que o banco de dados vetorial esteja configurado e acessível.
Verifique se a chave de API da OpenAI ou outras credenciais de provedor são válidas.
Verifique os logs do LibreChat e da API de RAG em busca de erros ou avisos.

Se o problema persistir, consulte a documentação da RAG API ou pergunte à comunidade do LibreChat no GitHub Discussions ou no Discord.

API de RAG

Nesta página