LibreChatRAG API
Langchain과 FastAPI를 사용하여 문서 인덱싱 및 검색을 위한 Retrieval-Augmented Generation (RAG) API를 구성합니다. 이 API는 LibreChat과 통합되어 사용자가 업로드한 파일을 기반으로 문맥을 인식하는 응답을 제공합니다.
RAG API는 사용자가 업로드한 파일을 인덱싱하고 관련 구절을 검색하여 프롬프트를 보강함으로써, LibreChat이 문서에 기반한 문맥 인식 응답을 제공할 수 있도록 합니다. 이 서비스는 PostgreSQL + pgvector 데이터베이스를 기반으로 하는 별도의 FastAPI 서비스로 실행됩니다.
RAG가 처음이신가요?
RAG API Presentation에서 해당 개념을 더 자세히 설명하며 유용한 영상으로 연결되는 링크를 제공합니다. 이 페이지에서는 설정 및 구성을 다룹니다.
가용성
RAG는 Agents뿐만 아니라 Custom Endpoints, OpenAI, Azure OpenAI, Anthropic, Google과 함께 작동합니다.
OpenAI Assistants는 "Retrieval" 기능(상세 내용 여기)을 통해 자체적인 RAG 구현을 제공합니다. OpenAI는 파일 저장과 Retrieval 모두에 대해 비용을 청구하므로, Assistants API와 함께 RAG API를 사용하는 것은 여전히 가치가 있습니다. 이 통합은 향후 업데이트에서 지원될 예정입니다.
Docker Quick Start
Docker의 경우, RAG API는 기본 docker-compose.yml 및 deploy-compose.yml 파일 모두에 RAG_API_URL 값을 포함하여 이미 연결되어 있습니다. 최신 이미지와 compose 파일을 실행하고 있는지 확인하기만 하면 됩니다. 업데이트 방법을 잘 모르겠다면 Docker용 LibreChat 업데이트 가이드를 참조하세요.
공유 .env 파일
기본 Docker 설정에서는 .env 파일이 LibreChat과 RAG API 간에 공유됩니다. RAG 변수를 동일한 파일에 정의하십시오. 전체 목록은 RAG API README에서 확인할 수 있습니다.
사용할 임베딩 제공업체를 선택하세요.
OpenAI 임베딩을 사용하여 RAG를 사용합니다. 이는 기본 구성입니다.
RAG API URL을 설정합니다. 다음 내용을 .env 파일에 추가하세요:
RAG_API_URL=http://host.docker.internal:8000OpenAI API 키를 제공하세요(필요한 경우). OpenAI API 키가 user_provided로 설정된 경우, 임베딩을 위한 키를 추가하세요. .env 파일에 이미 OpenAI 키를 제공하고 있다면 이 단계를 건너뛰세요.
RAG_OPENAI_API_KEY=sk-your-openai-api-key-example컨테이너를 시작합니다.
docker compose up -dHugging Face 임베딩을 사용하여 RAG를 사용하세요.
공급자(provider)를 구성합니다. .env 파일에 다음을 추가하세요:
RAG_API_URL=http://host.docker.internal:8000
EMBEDDINGS_PROVIDER=huggingface
HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxx전체 RAG API 이미지로 전환하세요. docker-compose.override.yml 파일을 업데이트합니다:
version: '3.4'
services:
rag_api:
image: registry.librechat.ai/danny-avila/librechat-rag-api-dev:latest컨테이너를 시작합니다.
docker compose up -dOllama 로컬 임베딩을 사용하여 RAG를 활용하세요.
전제 조건
Ollama와 nomic-embed-text 임베딩 모델이 필요합니다. ollama pull nomic-embed-text 명령어로 해당 모델을 가져오세요.
공급자(provider)를 구성합니다. .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전체 RAG API 이미지로 전환하세요. 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"컨테이너를 시작합니다.
docker compose up -dLite vs. full image
Docker는 기본적으로 RAG API의 "lite" 이미지(registry.librechat.ai/danny-avila/librechat-rag-api-dev-lite:latest)를 사용하며, 이는 OpenAI의 원격 임베딩이나 사용자가 구성한 원격 HuggingFace/Ollama 서비스만 지원합니다.
로컬 임베딩을 사용하려면, compose 파일의 이미지를 전체 빌드 버전인 registry.librechat.ai/danny-avila/librechat-rag-api-dev:latest로 변경하세요. 이 변경 사항은 Docker Compose Override File에서 적용해야 합니다. 예시는 프로젝트 루트에 있는 docker-compose.override.yml.example를 참조하세요.
PostgreSQL + pgvector 데이터베이스와 Python API만 포함하는 compose 파일을 원하신다면, 프로젝트 루트에 있는 rag.yml을 확인하세요.
데이터베이스 저장소
기본 compose 파일은 pgvector/PostgreSQL 데이터를 Docker가 관리하는 pgdata2 볼륨에 저장합니다. 이는 의도된 설계입니다. 데이터베이스 파일은 호스트에서 직접 편집할 필요가 없으며, 관리형 볼륨을 사용하면 일반적인 소유권 및 권한 문제를 방지할 수 있기 때문입니다. 사용자가 직접 편집해야 하는 파일(업로드, 로그, 이미지, MongoDB 데이터, NGINX 설정)은 호스트에서 직접 접근하는 것이 유용하므로 프로젝트 폴더에 바인드 마운트(bind-mounted)됩니다.
로컬 설정
컨테이너를 사용하지 않는 설정은 더 많은 수동 작업이 필요합니다. RAG API repo의 지침을 따르세요.
LibreChat .env 파일에서 RAG_API_URL을 설정하여 설정 환경에서 API에 접근할 수 있도록 하십시오. 이는 기본 docker-compose.yml 파일에 값이 이미 설정되어 있는 Docker와는 다릅니다.
구성
API가 액세스할 수 있는 .env 파일의 환경 변수를 통해 RAG API 옵션을 설정합니다. 선택한 공급자가 요구하는 자격 증명 및 경로를 제외한 대부분의 옵션은 선택 사항입니다. 기본 설정에서는 RAG_OPENAI_API_KEY만 필수입니다.
환경 변수
| Key | Type | Description | Example |
|---|---|---|---|
| RAG_API_URL | string | RAG API 서비스의 URL입니다. | RAG_API_URL=http://host.docker.internal:8000 |
| RAG_OPENAI_API_KEY | string | 임베딩을 위한 OpenAI API 키입니다. RAG를 위해 OPENAI_API_KEY를 재정의합니다. | # RAG_OPENAI_API_KEY=sk-your-key |
| RAG_OPENAI_BASEURL | string | RAG 임베딩을 위한 사용자 지정 OpenAI 기본 URL입니다. | # RAG_OPENAI_BASEURL= |
| RAG_USE_FULL_CONTEXT | boolean | 상위 4개 결과 대신 전체 파일 컨텍스트를 가져옵니다. 기본값: false. | # RAG_USE_FULL_CONTEXT=true |
| EMBEDDINGS_PROVIDER | string | Embeddings provider: openai, azure, huggingface, huggingfacetei 또는 ollama. 기본값: openai. | # EMBEDDINGS_PROVIDER=openai |
| EMBEDDINGS_MODEL | string | 사용할 임베딩 모델입니다. 기본값은 제공업체에 따라 다릅니다. | # EMBEDDINGS_MODEL=text-embedding-3-small |
| RAG_PORT | number | RAG API가 실행되는 포트입니다. 기본값: 8000. | # RAG_PORT=8000 |
| RAG_HOST | string | RAG API의 호스트 이름입니다. 기본값: 0.0.0.0. | # RAG_HOST=0.0.0.0 |
| COLLECTION_NAME | string | 벡터 저장소 컬렉션 이름. 기본값: testcollection. | # COLLECTION_NAME=testcollection |
| CHUNK_SIZE | number | 텍스트 청크의 크기입니다. 기본값: 1500. | # CHUNK_SIZE=1500 |
| CHUNK_OVERLAP | number | 청크 간의 중첩. 기본값: 100. | # CHUNK_OVERLAP=100 |
| OLLAMA_BASE_URL | string | Ollama 임베딩 사용 시 Ollama base URL. | # OLLAMA_BASE_URL=http://host.docker.internal:11434 |
자격 증명 우선순위
OPENAI_API_KEY는 RAG 임베딩에 작동하지만, 자격 증명 충돌을 방지하기 위해 RAG_OPENAI_API_KEY가 이를 재정의합니다.
변수 및 해당 설명의 전체 목록은 RAG API repo를 참조하세요.
사용법
RAG API가 실행되면 LibreChat과 자동으로 통합됩니다. 사용자가 대화에 파일을 업로드하면, API는 해당 파일을 인덱싱하고 문맥을 인식하는 응답을 생성하는 데 사용합니다.
대화에 파일을 업로드합니다. RAG_API_URL이 구성되지 않았거나 연결할 수 없는 경우, 업로드가 실패합니다.
평소처럼 채팅하세요. 사용자가 모델과 상호작용하면, RAG API가 입력 내용을 바탕으로 인덱싱된 파일에서 관련 구절을 검색하여 프롬프트를 보강하는 데 사용합니다.
파일이 쿼리되는 시점을 제어하세요. 기본적으로 벡터 저장소는 파일이 첨부된 대화에서 새로운 메시지가 전송될 때마다 쿼리됩니다. 이에 맞춰 프롬프트를 작성하세요.
대화 설정에서 Resend Files를 끄면 파일이 메시지에 명시적으로 첨부된 경우에만 파일을 쿼리합니다.
색인된 파일 재사용. 파일을 한 번 업로드하면 사이드 패널에서 새 메시지나 대화에 언제든지 첨부할 수 있습니다.
파일은 "Host" 스토리지에 있어야 합니다. "OpenAI" 파일은 다르게 처리되며 Assistants 전용이므로, Assistants endpoint가 선택되어 활성화된 상태에서 업로드되어서는 안 됩니다. 사이드 패널에서 파일을 확인하고 관리하세요.
문제 해결
RAG API를 설정하거나 사용하는 중에 문제가 발생하면:
.env파일에 모든 필수 환경 변수가 올바르게 설정되었는지 확인하세요.- 벡터 데이터베이스가 구성되어 있고 접근 가능한지 확인하세요.
- OpenAI API 키 또는 기타 공급자 자격 증명이 유효한지 확인하세요.
- LibreChat 및 RAG API 로그에서 오류나 경고가 있는지 확인하세요.
문제가 지속되면 RAG API 문서를 참조하거나 GitHub Discussions 또는 Discord의 LibreChat 커뮤니티에 문의하세요.
이 가이드는 어떤가요?