API RAG

Configura l'API di Retrieval-Augmented Generation (RAG) per l'indicizzazione e il recupero dei documenti utilizzando Langchain e FastAPI. Questa API si integra con LibreChat per fornire risposte basate sul contesto a partire dai file caricati dall'utente.

L'API RAG indicizza i file caricati dagli utenti e recupera i passaggi pertinenti per arricchire i tuoi prompt, fornendo a LibreChat risposte consapevoli del contesto e basate sui tuoi documenti. Viene eseguita come un servizio FastAPI separato supportato da un database PostgreSQL + pgvector.

Nuovo di RAG?

La RAG API Presentation spiega il concetto in modo più dettagliato e rimanda a un video utile. Questa pagina copre l'installazione e la configurazione.

Disponibilità

RAG funziona con gli Agents, così come con Custom Endpoints, OpenAI, Azure OpenAI, Anthropic e Google.

Gli OpenAI Assistants hanno la loro implementazione RAG tramite la funzionalità "Retrieval" (dettagli qui). L'utilizzo dell'API RAG con l'API Assistants è comunque utile, poiché OpenAI addebita costi sia per l'archiviazione dei file che per il Retrieval. Questa integrazione è prevista per un futuro aggiornamento.

Avvio rapido con Docker

Per Docker, l'API RAG è già configurata sia nel file docker-compose.yml predefinito che nel file deploy-compose.yml, incluso il valore RAG_API_URL. Devi solo assicurarti di utilizzare l'immagine e i file compose più recenti. Consulta la guida all'aggiornamento di LibreChat per Docker se non sai come procedere con l'aggiornamento.

File .env condiviso

Con la configurazione Docker predefinita, il file .env è condiviso tra LibreChat e la RAG API. Definisci le variabili RAG nello stesso file. L'elenco completo si trova nel RAG API README.

Scegli il provider di embeddings che desideri utilizzare.

Usa RAG con gli embedding di OpenAI. Questa è la configurazione predefinita.

Imposta l'URL dell'API RAG. Aggiungi quanto segue al tuo file .env:

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

Fornisci una chiave API OpenAI (se necessario). Se la tua chiave API OpenAI è impostata su user_provided, aggiungi una chiave per gli embeddings. Salta questo passaggio se fornisci già la chiave OpenAI nel tuo file .env.

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

Avvia i container.

docker compose up -d

Usa RAG con gli embedding di Hugging Face.

Configura il provider. Aggiungi quanto segue al tuo file .env:

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

Passa all'immagine completa dell'API RAG. Aggiorna il tuo file docker-compose.override.yml:

version: '3.4'

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

Avvia i container.

docker compose up -d

Usa RAG con embedding locali di Ollama.

Prerequisito

Hai bisogno di Ollama e del modello di embedding nomic-embed-text. Scaricalo con ollama pull nomic-embed-text.

Configura il provider. Aggiungi quanto segue al tuo file .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

Passa all'immagine completa dell'API RAG. Aggiorna il tuo file 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"

Avvia i container.

docker compose up -d

Lite vs. full image

Docker utilizza per impostazione predefinita l'immagine "lite" della RAG API (registry.librechat.ai/danny-avila/librechat-rag-api-dev-lite:latest), che supporta solo embedding remoti da OpenAI o da un servizio remoto HuggingFace/Ollama che hai configurato.

Per gli embedding locali, sostituisci l'immagine nel file compose con la build completa, registry.librechat.ai/danny-avila/librechat-rag-api-dev:latest. Apporta questa modifica nel tuo Docker Compose Override File. Consulta docker-compose.override.yml.example nella root del progetto per un esempio.

Se desideri un file compose che includa solo il database PostgreSQL + pgvector e l'API Python, consulta rag.yml nella root del progetto.

Archiviazione database

I file compose predefiniti memorizzano i dati di pgvector/PostgreSQL nel volume pgdata2 gestito da Docker. Questa è una scelta intenzionale: i file del database non devono essere modificati direttamente dall'host e un volume gestito evita comuni problemi di proprietà e permessi. I file modificabili dall'utente (upload, log, immagini, dati MongoDB e configurazione NGINX) sono montati tramite bind-mount nelle cartelle del progetto, dove l'accesso diretto dall'host è utile.

Configurazione Locale

Una configurazione non containerizzata richiede un approccio più manuale. Segui le istruzioni nel repository RAG API.

Imposta RAG_API_URL nel tuo file .env di LibreChat ovunque l'API sia raggiungibile dalla tua configurazione. Questo differisce da Docker, dove il valore è già impostato nel file docker-compose.yml predefinito.

Configurazione

Imposta le opzioni dell'API RAG tramite variabili d'ambiente in un file .env accessibile all'API. La maggior parte sono facoltative, a parte le credenziali e i percorsi richiesti dal provider scelto. Nella configurazione predefinita, è richiesto solo RAG_OPENAI_API_KEY.

Variabili d'ambiente

Key	Type	Description	Example
RAG_API_URL	string	URL del servizio API RAG.	RAG_API_URL=http://host.docker.internal:8000
RAG_OPENAI_API_KEY	string	Chiave API OpenAI per gli embedding. Sovrascrive OPENAI_API_KEY per RAG.	# RAG_OPENAI_API_KEY=sk-your-key
RAG_OPENAI_BASEURL	string	URL di base OpenAI personalizzato per gli embedding RAG.	# RAG_OPENAI_BASEURL=
RAG_USE_FULL_CONTEXT	boolean	Recupera l'intero contesto del file invece dei primi 4 risultati. Predefinito: false.	# RAG_USE_FULL_CONTEXT=true
EMBEDDINGS_PROVIDER	string	Provider di Embeddings: openai, azure, huggingface, huggingfacetei, o ollama. Predefinito: openai.	# EMBEDDINGS_PROVIDER=openai
EMBEDDINGS_MODEL	string	Modello di embeddings da utilizzare. Il valore predefinito dipende dal provider.	# EMBEDDINGS_MODEL=text-embedding-3-small
RAG_PORT	number	Porta su cui viene eseguita la RAG API. Predefinito: 8000.	# RAG_PORT=8000
RAG_HOST	string	Hostname per l'API RAG. Predefinito: 0.0.0.0.	# RAG_HOST=0.0.0.0
COLLECTION_NAME	string	Nome della collezione del vector store. Predefinito: testcollection.	# COLLECTION_NAME=testcollection
CHUNK_SIZE	number	Dimensione dei chunk di testo. Predefinito: 1500.	# CHUNK_SIZE=1500
CHUNK_OVERLAP	number	Sovrapposizione tra i chunk. Predefinito: 100.	# CHUNK_OVERLAP=100
OLLAMA_BASE_URL	string	URL di base di Ollama quando si utilizzano gli embedding di Ollama.	# OLLAMA_BASE_URL=http://host.docker.internal:11434

Precedenza delle credenziali

OPENAI_API_KEY funziona per gli embedding RAG, ma RAG_OPENAI_API_KEY lo sovrascrive per evitare conflitti di credenziali.

Per l'elenco completo delle variabili e le relative descrizioni, consultare il repository RAG API.

Utilizzo

Una volta che la RAG API è in esecuzione, si integra automaticamente con LibreChat. Quando un utente carica dei file in una conversazione, l'API li indicizza e li utilizza per risposte basate sul contesto.

Carica file nella conversazione. Se RAG_API_URL non è configurato o non è raggiungibile, il caricamento fallisce.

Chatta come al solito. Mentre l'utente interagisce con il modello, l'API RAG recupera i passaggi pertinenti dai file indicizzati in base all'input e li utilizza per arricchire il prompt.

Controlla quando vengono interrogati i file. Per impostazione predefinita, il vector store viene interrogato a ogni nuovo messaggio in una conversazione a cui è allegato un file. Elabora i tuoi prompt di conseguenza.

Disattiva Resend Files nelle impostazioni della conversazione per interrogare i file solo quando sono esplicitamente allegati a un messaggio.

Interruttore Resend Files nelle impostazioni della conversazione

Riutilizza i file indicizzati. Carica un file una volta, quindi allegalo a qualsiasi nuovo messaggio o conversazione dal Pannello Laterale.

Allegare file indicizzati dal pannello laterale

I file devono essere nell'archiviazione "Host". I file "OpenAI" vengono gestiti in modo diverso ed esclusivo per gli Assistants, quindi non devono essere stati caricati mentre l'endpoint Assistants era selezionato e attivo. Visualizza e gestisci i tuoi file dal Pannello Laterale.

Visualizzazione e gestione dei file dal pannello laterale

Risoluzione dei problemi

Se riscontri problemi durante la configurazione o l'utilizzo della RAG API:

Assicurati che tutte le variabili d'ambiente richieste siano impostate correttamente nel tuo file .env.
Assicurati che il database vettoriale sia configurato e accessibile.
Verifica che la chiave API di OpenAI o le credenziali di altri provider siano valide.
Controlla sia i log di LibreChat che quelli dell'API RAG per eventuali errori o avvisi.

Se il problema persiste, consulta la documentazione della RAG API o chiedi alla community di LibreChat su GitHub Discussions o Discord.

API RAG

In questa pagina