Common Pitfalls: 현장에서 겪는 실수들

Pitfall 1: 청크 크기와 토큰 수 혼동

# ❌ 실수: "chunk_size=500이면 500토큰이겠지"
splitter = RecursiveCharacterTextSplitter(chunk_size=500)
# 실제로는 500'자'(characters)!

# 한글은 1글자 = 약 2~3 토큰
# 500자 한글 = 약 1000~1500 토큰
# 임베딩 모델 최대 토큰이 512이면 -> 잘릴 수 있다!

# ✅ 해결: 토큰 기준으로 설정
from langchain_text_splitters import TokenTextSplitter

splitter = TokenTextSplitter(
    chunk_size=256,      # 토큰 단위
    chunk_overlap=50,
    model_name="gpt-4o"  # 토크나이저 지정
)

Pitfall 2: 메타데이터 누락

# ❌ 실수: 메타데이터 없이 청킹
chunks = splitter.split_text(full_text)
# chunk가 어느 문서, 어느 페이지에서 왔는지 모른다!

# ✅ 해결: split_documents 사용
from langchain_core.documents import Document

doc = Document(
    page_content=full_text,
    metadata={
        "source": "SOP-CNC-E001_v2.1.pdf",
        "equipment": "CNC-3000",
        "version": "2.1",
        "approved_date": "2024-03-15",
    }
)
chunks = splitter.split_documents([doc])
# 각 chunk에 metadata가 자동 상속됨!

Pitfall 3: overlap 없이 청킹

❌ overlap=0:
"...파라미터 #2012의 정상 범위는"  |  "80-120이며 이를 초과하면..."
      Chunk A                    |       Chunk B
                                 ← 정보 단절!

✅ overlap=100:
"...#2012의 정상 범위는 80-120이며"  | "정상 범위는 80-120이며 초과하면..."
      Chunk A                       |       Chunk B
                              ← 겹침 구간 →

Pitfall 4: 인덱싱/검색 임베딩 모델 불일치

# ❌ 치명적 실수
# 인덱싱 시
embeddings = OpenAIEmbeddings(model="text-embedding-3-large")
vectorstore = Chroma.from_documents(docs, embeddings)

# 검색 시 (다른 모델!)
embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
results = vectorstore.similarity_search(query)
# → 차원 불일치 → 오류 또는 엉뚱한 결과!

# ✅ 해결: 상수로 관리
EMBEDDING_MODEL = "text-embedding-3-small"
embeddings = OpenAIEmbeddings(model=EMBEDDING_MODEL)
# 인덱싱과 검색 모두 같은 embeddings 객체 사용

Pitfall 5: 제조 용어 미처리

❌ 실수: 제조 약어/기호를 그대로 임베딩
"CN1 CN2 절연저항 >= 1MΩ #2012"
→ 임베딩 모델이 "#2012"를 숫자로 인식

✅ 해결: 전처리에서 용어 정규화
"CN1 CN2 커넥터 절연저항 1메가옴 이상
 파라미터 번호 2012"
→ 의미가 더 명확하게 임베딩됨

Pitfall 6: 표 데이터 텍스트 변환 실패

❌ 표를 그냥 텍스트로 변환:
"최대가압력500ton4903kN스트로크350mm..."
→ 값과 항목 구분 불가

✅ 표를 구조적 텍스트로 변환:
"최대 가압력: 500 ton (4,903 kN)
 스트로크: 350 mm
 슬라이드 속도 급속하강: 300 mm/s"
→ 항목별 검색 가능