Chroma 실전 예제 — 내 문서 검색 챗봇 30분 만들기

ChatGPT를 쓰다 보면 답답한 순간이 있습니다. "내 회의록을 읽고 요약해줘" 같은 요청은 매번 본문을 통째로 붙여넣어야 하니까요. 문서가 100개쯤 쌓이면 이 방식은 한계에 부딪힙니다.

오늘은 그 문제를 해결하는 도구인 Chroma를 직접 써봅니다. 벡터 데이터베이스라는, 이름은 거창해도 실제로는 "AI가 알아듣는 검색엔진" 정도의 물건입니다. 코드를 한 번도 안 짜본 분도 따라올 수 있게 개념부터 풀어 쓰겠습니다.

저도 처음엔 RAG니 임베딩이니 하는 단어에 질려 멀리했습니다. 막상 써보니 30분이면 동작하는 챗봇이 손에 잡히더군요. 그 경험을 그대로 옮깁니다.

Chroma가 뭐길래 — 핵심 정리

Chroma는 문장의 의미를 숫자로 저장하고, 비슷한 의미의 문장을 빠르게 찾아주는 데이터베이스입니다. 일반 데이터베이스(엑셀 표 같은 구조)가 "단어가 똑같이 일치하는지"를 본다면, Chroma는 "뜻이 비슷한지"를 봅니다.

예를 들어 "환불 정책"으로 검색하면, 일반 검색은 그 단어가 들어간 문서만 찾습니다. Chroma는 "반품 규정", "돈 돌려받기" 같은 표현도 같이 찾아줍니다. 단어가 아니라 의미를 비교하니까요.

이게 가능한 이유는 임베딩(embedding) 덕분입니다. 임베딩은 문장을 1,500개 정도의 숫자 묶음으로 바꾸는 작업입니다. 비슷한 뜻의 문장은 비슷한 숫자가 나오도록 AI가 변환해줍니다.

도구	성격	비용	비전공자 적합도
Chroma	가벼움, 로컬 실행	무료	★★★★★
Pinecone	클라우드, 대규모	유료(무료 티어 有)	★★★
Weaviate	기능 풍부	유료/오픈소스	★★
FAISS	고성능, 저수준	무료	★

처음 입문하기에는 Chroma가 가장 부담이 적습니다. 설치 한 줄, 노트북 안에서 그대로 돌아갑니다.

30분 안에 만들 챗봇의 전체 흐름

전체 그림을 먼저 보면 헤매지 않습니다. 우리가 만들 챗봇은 이렇게 동작합니다.

[내 문서들]
    ↓ (잘게 자르기)
[문장 조각들]
    ↓ (OpenAI로 임베딩)
[숫자 벡터]
    ↓ (저장)
[Chroma DB]
    ↑
사용자 질문 → 임베딩 → 비슷한 조각 찾기 → GPT가 답변 생성

핵심은 두 가지입니다. 미리 문서를 잘게 잘라 Chroma에 넣어두는 것, 그리고 질문이 들어오면 비슷한 조각만 골라 GPT에게 같이 넘기는 것.

이 구조를 RAG(Retrieval-Augmented Generation, 검색 보강 생성)라고 부릅니다. AI가 답하기 전에 관련 자료를 먼저 검색해 와서 참고하게 만드는 방식이죠. 환각(없는 사실을 지어내는 현상)을 줄이는 가장 실용적인 방법으로 알려져 있습니다.

설치 전 준비물 체크리스트

본격적으로 시작하기 전에 환경을 확인합니다. 아래 네 가지가 모두 ✅면 다음 챕터로 넘어가면 됩니다.

• ☐Python 3.9 이상 설치 (터미널에서 python --version 으로 확인)
• ☐터미널 사용법 — 명령어 복붙해서 실행할 줄 알면 충분
• ☐OpenAI API 키 발급 (platform.openai.com 가입 후 발급)
• ☐검색하고 싶은 텍스트 파일 1~2개 (PDF·docx도 가능하지만 일단 .txt로 시작 권장)

여기서 막히기 쉬운 부분이 두 가지입니다.

터미널은 검은 화면에 명령어를 한 줄씩 쳐서 컴퓨터에게 직접 시키는 프로그램입니다. 맥은 "터미널" 앱, 윈도우는 "PowerShell"이나 "명령 프롬프트"를 열면 됩니다. 처음엔 낯설지만, 우리가 쓸 명령은 5~6줄뿐입니다.

API 키는 일종의 출입증입니다. OpenAI 서버에 "내가 누구인지" 알리고 비용을 내 계정에 청구하기 위한 비밀번호 같은 것이죠. 한 번 발급받으면 다시 볼 수 없으니 메모장에 잘 보관해야 합니다.

💡 OpenAI 신규 가입 시 일정 무료 크레딧이 제공된 시기가 있었지만, 글 작성 시점 기준으로는 정책이 자주 바뀝니다. 카드 등록이 필요할 수 있으니 공식 가격 페이지를 한 번 확인하세요.

5분 만에 끝나는 설치

터미널을 열고 아래 명령을 그대로 입력합니다. 한 줄씩 복사해 붙여넣고 Enter를 누르세요.

pip install chromadb openai

pip는 파이썬용 앱스토어 같은 도구입니다. 위 명령은 "Chroma와 OpenAI 라이브러리를 설치해줘"라는 뜻입니다. 1~2분 정도 글자가 쭉 흘러간 뒤 멈추면 끝입니다.

그다음 API 키를 환경변수로 등록합니다. 코드에 직접 적으면 실수로 인터넷에 노출될 위험이 있어서, 운영체제에 비밀스럽게 저장하는 방식이 안전합니다.

# 맥/리눅스
export OPENAI_API_KEY="sk-여기에_본인_키_붙여넣기"

# 윈도우 PowerShell
$env:OPENAI_API_KEY="sk-여기에_본인_키_붙여넣기"

이 설정은 터미널을 닫으면 사라집니다. 영구히 저장하려면 .zshrc(맥)나 시스템 환경변수(윈도우)에 추가해야 하지만, 처음 실습이라면 그냥 매번 입력해도 충분합니다.

핵심 코드 — 문서 넣고 검색하기

이제 실제 코드입니다. 텍스트 에디터(메모장보다는 VS Code 같은 무료 에디터 추천)에 chatbot.py라는 파일로 저장합니다.

import chromadb
from chromadb.utils import embedding_functions

# 1. OpenAI 임베딩 함수 준비
openai_ef = embedding_functions.OpenAIEmbeddingFunction(
    model_name="text-embedding-3-small"
)

# 2. Chroma 클라이언트 만들기 (디스크에 저장)
client = chromadb.PersistentClient(path="./my_db")

# 3. 컬렉션 생성 (문서를 담을 폴더 같은 개념)
collection = client.get_or_create_collection(
    name="my_docs",
    embedding_function=openai_ef
)

# 4. 문서 넣기
collection.add(
    documents=[
        "Chroma는 오픈소스 벡터 데이터베이스입니다.",
        "환불은 구매 후 7일 이내에 가능합니다.",
        "고객센터 운영시간은 평일 9시부터 6시까지입니다."
    ],
    ids=["doc1", "doc2", "doc3"]
)

# 5. 검색하기
results = collection.query(
    query_texts=["언제까지 돈을 돌려받을 수 있나요?"],
    n_results=2
)

print(results)

위 코드는 "환불 가능 기간"이라는 단어가 한 글자도 들어있지 않은 질문("돈을 돌려받을 수 있나요?")에도 doc2를 1순위로 찾아옵니다. 의미 기반 검색의 위력이죠.

터미널에서 python chatbot.py를 실행하면 결과가 출력됩니다. 처음 실행하면 OpenAI에 임베딩을 요청하느라 2~3초 걸리고, 그다음부터는 빨라집니다.

진짜 챗봇으로 만들기 — GPT 연결

검색만 되면 챗봇이 아니라 검색엔진입니다. 찾아온 조각을 GPT에게 넘겨 자연스러운 답변으로 만드는 단계가 필요합니다.

from openai import OpenAI

llm = OpenAI()

def ask(question):
    # 관련 문서 3개 찾기
    results = collection.query(
        query_texts=[question],
        n_results=3
    )
    context = "\n".join(results["documents"][0])
    
    # GPT에게 문서와 함께 질문
    response = llm.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "system", "content": f"다음 자료를 참고해 답하세요:\n{context}"},
            {"role": "user", "content": question}
        ]
    )
    return response.choices[0].message.content

print(ask("환불은 며칠 안에 신청해야 하나요?"))

이게 끝입니다. 30줄이 안 됩니다.

이 코드의 핵심은 system 메시지에 검색된 자료를 함께 넣는다는 점입니다. GPT는 일반 지식이 아니라 내가 넣은 문서만 보고 답합니다. 사내 매뉴얼·개인 메모·전공 책 무엇이든 같은 패턴으로 동작합니다.

자주 막히는 부분과 해결법

저도 그랬고 주변에서도 똑같이 걸리는 지점들입니다.

증상	원인	해결
openai.AuthenticationError	API 키 미설정/오타	echo $OPENAI_API_KEY로 키 확인
검색 결과가 영 엉뚱함	문서 조각이 너무 김	200~500자 단위로 자르기
같은 문서가 매번 1순위	컬렉션에 중복 저장됨	client.delete_collection("my_docs") 후 재실행
한국어 검색이 어색함	임베딩 모델 한계	text-embedding-3-large로 교체
OpenAI 비용이 걱정됨	매번 임베딩 재계산	PersistentClient 사용 (위 예제대로면 OK)

특히 세 번째 증상이 흔합니다. 코드를 여러 번 실행하면 add()가 누적돼 같은 문서가 3~4번 들어갑니다. 실습 중에는 컬렉션을 지우고 다시 만드는 게 깔끔합니다.

비용은 생각보다 저렴합니다. text-embedding-3-small 기준으로 책 한 권(약 30만 자)을 통째로 임베딩해도 0.01달러 수준입니다(OpenAI 공식 가격 기준). 한 번 임베딩한 결과는 Chroma에 저장되니 재실행할 때는 추가 비용이 들지 않습니다.

PDF·웹페이지로 확장하기

실전에서는 .txt 파일만 다루지 않습니다. 회사 매뉴얼은 PDF, 회의록은 워드, 위키 페이지는 웹에 있습니다.

langchain 또는 llama-index 같은 보조 라이브러리를 쓰면 한두 줄로 처리됩니다.

from langchain_community.document_loaders import PyPDFLoader

loader = PyPDFLoader("manual.pdf")
pages = loader.load_and_split()

collection.add(
    documents=[p.page_content for p in pages],
    ids=[f"page_{i}" for i in range(len(pages))]
)

PDF가 100페이지짜리여도 위 코드로 끝납니다. 페이지 단위로 알아서 잘라 넣어주거든요.

다만 한국어 PDF는 깨지는 경우가 종종 있습니다(특히 스캔본). 이럴 땐 OCR 도구를 한 번 거쳐야 하는데, 이건 별도 글로 다뤄볼 만한 주제입니다.

마무리

Chroma 실전 예제로 30분 만에 동작하는 문서 검색 챗봇까지 만들어봤습니다. 핵심은 의외로 단순합니다. 문서를 잘라 임베딩으로 바꾸고, 질문이 오면 비슷한 조각을 찾아 GPT에게 함께 넘긴다. 이게 RAG의 전부입니다.

처음엔 임베딩이라는 단어부터 막막했지만, 직접 collection.add()와 collection.query()를 실행해보면 감이 옵니다. 결국 도구일 뿐이고, 한 번 손에 익으면 사내 위키 검색이든 개인 노트 정리든 같은 패턴으로 풀 수 있습니다.

다음 단계로는 자기 PDF 한두 개를 넣어 직접 질문해보길 권합니다. 검색이 어색한 부분을 발견하면 그게 다음 학습 주제가 됩니다 — 청크 크기 조정, 한국어 임베딩 모델 비교, 메타데이터 필터링 같은 것들이요. 그 단계까지 가면 RAG 입문은 졸업입니다.