django-rag

name	django-rag
description	Django 프로젝트에서 Google Gemini API + LangChain + ChromaDB를 사용하는 RAG(Retrieval-Augmented Generation) 파이프라인을 구현, 디버깅, 유지보수할 때 사용하는 스킬. RAG 관련 에러(모델명 오류, API quota 초과, ChromaDB 불일치 등)를 수정하거나, 임베딩/LLM 코드를 새로 작성하거나, 기존 코드를 점검할 때 반드시 이 스킬을 참조하라.

Django RAG 스킬 (Gemini + LangChain + ChromaDB)

이 프로젝트는 Google Gemini API, LangChain, ChromaDB를 조합한 RAG 파이프라인을 사용한다.
잘못된 모델명, API 할당량 초과, ChromaDB 벡터 불일치 등이 반복적으로 발생했으므로, 아래 내용을 반드시 준수하라.

---

1. 확정된 모델 목록 (절대 임의 변경 금지)

임베딩 모델

# ✅ 올바른 모델명 (documents/services.py, chat/services.py 모두 동일하게 사용)
model = "models/gemini-embedding-001"

⚠️ 주의: 아래 모델명들은 사용하지 말 것

• ❌ models/embedding-001 → API 404 NOT_FOUND 에러 발생
• ❌ models/text-embedding-004 → 2026년 1월 14일 서비스 종료

LLM 모델 (답변 생성)

# ✅ 현재 사용 중인 모델
model = "gemini-2.5-flash-lite"
---

## 2. 의존성 패키지

`pyproject.toml` 기준 RAG 관련 핵심 패키지:
```toml
"chromadb>=1.5.5",
"langchain>=1.2.15",
"langchain-community>=0.4.1",
"langchain-google-genai>=4.2.1",

중요 임포트 경로

# 임베딩
from langchain_google_genai import GoogleGenerativeAIEmbeddings, ChatGoogleGenerativeAI

# 벡터스토어
from langchain_community.vectorstores import Chroma

# 체인 구성
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough
from langchain_core.output_parsers import StrOutputParser

# 문서 로딩/분할
from langchain_community.document_loaders import PyPDFLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter

❌ google.generativeai 패키지는 deprecated 경고가 뜬다.
직접 테스트 용도로는 쓸 수 있지만, 프로덕션 코드에선 langchain-google-genai를 사용하라.

---

3. ChromaDB 설정 규칙

# settings.py
CHROMA_DB_PATH = os.path.join(BASE_DIR, 'chroma_db')

# 벡터스토어 초기화 시 반드시 동일한 collection_name 사용
collection_name = "hr_documents"

ChromaDB 불일치 문제 (핵심 주의사항)

임베딩 모델을 변경하면 반드시 ChromaDB를 초기화해야 한다.
모델이 달라지면 벡터 차원(dimension)이 달라져서 chromadb가 에러를 낸다.

# ChromaDB 초기화 (모델 변경 시 필수 실행)
Remove-Item -Path "chroma_db" -Recurse -Force

# 이후 모든 문서의 is_embedded를 False로 리셋
uv run python manage.py shell -c "from documents.models import Document; Document.objects.all().update(is_embedded=False)"

임베딩 모델을 절대 함부로 바꾸지 말 것. 바꾸면 기존 DB와 충돌한다.

---

4. RAG 파이프라인 구조 개요

[사용자 질문]
    ↓
[ChromaDB 검색 (gemini-embedding-001로 쿼리 임베딩)]
    ↓
[관련 문서 청크 추출 (k=5)]
    ↓
[ChatPromptTemplate에 context + question 주입]
    ↓
[ChatGoogleGenerativeAI (gemini-2.5-flash-lite) 답변 생성]
    ↓
[ChatMessage DB 저장 (role, content, sources)]
    ↓
[HTMX로 message_pair.html partial 반환]

핵심 파일 위치

파일	역할
chat/services.py	RAG 체인 구성 + 답변 생성 + DB 저장
documents/services.py	PDF 파싱 + 임베딩 + ChromaDB 저장
chat/views.py	HTMX POST 처리 → services 호출
templates/chat/partials/message_pair.html	HTMX 응답용 메시지 파셜

---

5. API 에러 진단 가이드

에러: 404 NOT_FOUND - models/embedding-001 is not found

원인: 모델명에 gemini 접두사가 빠졌거나 deprecated된 이름 사용
해결: model="models/gemini-embedding-001" 로 수정

에러: ResourceExhausted - quota_id: GenerateRequestsPerDayPerProjectPerModel-FreeTier

원인: 무료 티어 일일 할당량 초과
해결 순서:
  1. 다른 모델 시도 (예: gemini-2.5-flash-lite)
  2. 하루 지나면 자동 리셋
  3. 유료 플랜 업그레이드

에러: chromadb.errors.InvalidDimensionException

원인: ChromaDB에 저장된 벡터와 현재 임베딩 모델의 차원이 다름
해결: chroma_db 폴더 삭제 후 전체 문서 재인덱싱

채팅 전송 시 500 에러 (응답 없고 화면 변화 없음)

진단 순서:
  1. 브라우저 개발자 도구 Network 탭에서 /chat/<id>/send/ 응답 확인
  2. Django runserver 터미널 로그 확인
  3. 위 에러 목록과 대조

---

6. API 동작 확인 스크립트

모델 변경 후 또는 에러 발생 시, 아래 명령으로 빠르게 API 상태를 확인하라:

# 사용 가능한 모델 목록 조회
uv run python -c "
import google.generativeai as genai
import environ, os
from pathlib import Path

env = environ.Env()
environ.Env.read_env(os.path.join(Path('.'), '.env'))
genai.configure(api_key=env('GOOGLE_API_KEY'))

for m in genai.list_models():
    if 'generateContent' in m.supported_generation_methods:
        print(m.name)
"

# 채팅 응답 확인
uv run python -c "
import google.generativeai as genai
import environ, os
from pathlib import Path

env = environ.Env()
environ.Env.read_env(os.path.join(Path('.'), '.env'))
genai.configure(api_key=env('GOOGLE_API_KEY'))

model = genai.GenerativeModel('gemini-2.5-flash-lite')
response = model.generate_content('안녕?')
print('[+] 응답:', response.text)
"

---

7. 문서 재인덱싱 절차

임베딩 모델 변경 또는 ChromaDB 초기화 후 필수 절차:

1. chroma_db 폴더 삭제
2. 모든 Document의 is_embedded=False로 리셋
3. /documents/ 페이지에서 PDF 재업로드 또는 기존 파일 재인덱싱 트리거
4. 서버 로그에서 [+] Successfully embedded Document ID X 확인