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 초기화 후 필수 절차:

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

name

django-rag

description

Django RAG 스킬 (Gemini + LangChain + 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 초기화 후 필수 절차:

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

django-rag

Django RAG 스킬 (Gemini + LangChain + ChromaDB)

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

임베딩 모델

LLM 모델 (답변 생성)

중요 임포트 경로

3. ChromaDB 설정 규칙

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

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

핵심 파일 위치

5. API 에러 진단 가이드

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

에러: ResourceExhausted - quota_id: GenerateRequestsPerDayPerProjectPerModel-FreeTier

에러: chromadb.errors.InvalidDimensionException

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

6. API 동작 확인 스크립트

7. 문서 재인덱싱 절차

이 저장소의 다른 Skills

이 저장소의 다른 Skills

Django RAG 스킬 (Gemini + LangChain + ChromaDB)

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

임베딩 모델

LLM 모델 (답변 생성)

중요 임포트 경로

3. ChromaDB 설정 규칙

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

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

핵심 파일 위치

5. API 에러 진단 가이드

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

에러: ResourceExhausted - quota_id: GenerateRequestsPerDayPerProjectPerModel-FreeTier

에러: chromadb.errors.InvalidDimensionException

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

6. API 동작 확인 스크립트

7. 문서 재인덱싱 절차

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

에러: `ResourceExhausted - quota_id: GenerateRequestsPerDayPerProjectPerModel-FreeTier`

에러: `chromadb.errors.InvalidDimensionException`

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

에러: `ResourceExhausted - quota_id: GenerateRequestsPerDayPerProjectPerModel-FreeTier`

에러: `chromadb.errors.InvalidDimensionException`