Chroma와 agentic ai

Chroma 기반 Agentic AI 구축 가이드 (HTML)

요약: 이 문서는 Chroma(ChromaDB)를 벡터 저장소로 사용하고 LangChain 스타일의 agent(Planner + Tools + Executor) 패턴을 적용해 실무에서 바로 쓸 수 있는 형태로 정리한 단계별 가이드입니다.

1. 무엇을 만들 것인가 — 개요

Agentic AI는 LLM을 중심으로 계획(Plan) → 도구 호출(Call Tool) → 관찰(Observe) → 재계획 루프를 돌리는 시스템입니다. Chroma는 임베딩 기반 검색(벡터 DB) 역할을 담당하여 에이전트가 신뢰할 수 있는 외부 지식을 찾게 해줍니다.

2. 전체 아키텍처(권장)

1. 데이터 수집 (문서, FAQ, 로그 등)
2. 전처리 & 문서 분절(chunking) — 문맥 단위로 분리
3. 임베딩 생성 (OpenAI/로컬 임베더 등)
4. 벡터 저장소 — Chroma 컬렉션
5. Retriever 레이어 (LangChain의 retriever 등)
6. 에이전트(Planner + Tool Registry + Executor)
7. 모니터링·로깅·안전 필터

3. 데이터 준비 (Ingestion)

핵심 포인트:

• 문서를 300–800 토큰 단위로 분절하세요 (토큰 한도를 고려).
• 각 chunk에 metadata를 붙이세요 (source, created_at, doc_id 등).
• 대량 문서는 배치 임베딩으로 처리해 속도와 비용 최적화.

4. 임베딩 선택

도메인·언어 특성에 따라 임베딩 모델을 선택하세요. (OpenAI, Cohere, sentence-transformers, 또는 로컬 임베더)

5. Chroma 세팅 — 기본 예시

파이썬: Chroma 설치 및 간단한 add/query

# 설치 (예시)
# pip install chromadb

import chromadb
from chromadb.config import Settings

# 영구 저장(disk-based) 예시: duckdb + parquet backend 사용
client = chromadb.Client(Settings(
    chroma_db_impl="duckdb+parquet",
    persist_directory="./chroma_db"
))

# 컬렉션 생성
collection = client.create_collection(name="my_docs")

# 문서 추가 예시 (ids, embeddings, metadatas, documents는 미리 준비)
collection.add(
    ids=["doc1", "doc2"],
    embeddings=[[0.1, 0.2, ...], [0.2, 0.0, ...]],
    metadatas=[{"source":"manual.pdf","created_at":"2025-10-01"}, {"source":"faq.md","created_at":"2025-09-20"}],
    documents=["내용 1 ...", "내용 2 ..."]
)

# 쿼리 (검색)
results = collection.query(query_embeddings=[query_emb], n_results=5)
print(results)

Tip: 실제 임베딩 생성은 OpenAI나 로컬 임베딩 모델을 통해 별도로 수행하고, 그 결과(벡터)를 Chroma에 저장합니다.

6. LangChain(또는 유사 프레임워크)과 통합

LangChain의 벡터스토어 래퍼(예: Chroma)를 사용하면 retriever를 LLM/agent에 바로 연결할 수 있습니다.

from langchain.vectorstores import Chroma
from langchain.embeddings import OpenAIEmbeddings

emb = OpenAIEmbeddings()  # 예시
vect = Chroma(client=client, collection_name="my_docs", embeddings=emb)
retriever = vect.as_retriever(search_kwargs={"k":4})

# retriever.get_relevant_documents("질문") 로 관련 문서 추출 가능

7. 에이전트 디자인 — Planner, Tools, Executor

기본 구성:

• Planner: 질문을 작업 단위로 분해
• Tool Registry: 검색, 계산, 외부 API 등 호출 가능한 도구 집합
• Executor: Planner의 지시대로 도구 호출 → 관찰 반환 → 반복
• Stopping Criteria: 최대 루프 수, 시간 제한, 안전 규칙

툴 래퍼 간단 예시 (LangChain 스타일)

from langchain.tools import BaseTool

class SearchDocsTool(BaseTool):
    name = "search_docs"
    description = "문서 검색 후 요약(출처 포함)을 반환합니다"

    def _run(self, query: str):
        docs = retriever.get_relevant_documents(query)
        return "\n".join([f"{d.page_content} (source={d.metadata.get('source')})" for d in docs])

8. RAG + Agent 결합 패턴 (권장)

에이전트의 질문 흐름 예시:

1. 에이전트가 질문 수신
2. Retriever로 관련 문서(top-k) 획득
3. Planner가 문서 내용을 요약/검토 → 필요한 툴 선정
4. 툴 호출(예: 외부 API, 계산기)
5. 관찰 결과를 바탕으로 최종 응답 생성 (근거 출처 포함)

9. 예제: 최소 동작하는 로컬 에이전트 (개념 코드)

# 초기설정(임베딩, Chroma, retriever는 앞에서 준비되었다고 가정)
from langchain.agents import initialize_agent, AgentType
from langchain.llms import OpenAI
from langchain.tools import Tool

# LLM 설정 (예시)
llm = OpenAI(temperature=0)

# 툴 정의(함수 -> Tool)
def search_docs(query: str) -> str:
    docs = retriever.get_relevant_documents(query)
    return "\n".join([f\"{d.page_content} (source={d.metadata.get('source')})\" for d in docs])

def simple_calc(expr: str) -> str:
    # 매우 간단한 계산기 (주의: 실제 시스템에서는 안전성 검증 필요)
    return str(eval(expr))

tools = [
    Tool.from_function(search_docs, name="search_docs", description="Search company docs"),
    Tool.from_function(simple_calc, name="calc", description="Simple calculator")
]

agent = initialize_agent(tools, llm, agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION, verbose=True)

# 실행
resp = agent.run("제품 X의 배포일정을 찾아 요약하고, Q4 매출을 계산하려면 '1000*1.2' 값을 계산해줘")
print(resp)

주의: 실제 환경에서는 eval 사용 금지, 입력 검증·샌드박스화 필요합니다.

10. 안전성·품질 확보

• 모든 retriever 결과의 근거 메타데이터를 응답에 포함하세요 (source, date).
• 도구 호출 시 화이트리스트/입력 검증을 적용하세요.
• 실행 루프에 최대 반복 수와 시간 제한을 설정하세요.
• 사용자에게 '모름'이라고 정직하게 답할 수 있도록 설계하세요(추측 금지).

11. 모니터링·평가

수집할 메트릭 예시:

• 정확도(정답률), 회수된 근거의 정합성 비율
• 환각(hallucination) 사례 수집·분류
• 응답 시간, 토큰/비용
• 도구 호출 실패율

12. 운영(운영성 고려사항)

• 대규모 문서: Chroma의 persistence(duckdb+parquet 등) 사용, 인덱스/샤딩 고려
• 동시성: Chroma client의 동시 접근 정책 확인
• 비용: 임베딩 API 배치 처리로 절감
• 보안: 민감 정보는 암호화·접근제어, 내부 호스팅 고려

13. 모범 사례 & 팁

• 메타데이터에 source_type, created_at, confidence를 추가
• Retriever로 가져온 문서가 토큰 한도를 초과하면 요약(압축) 후 제공
• 테스트셋(질문/정답/필수근거)을 만들어 자동검증 파이프라인 구성
• 에이전트의 행동 로그(Plan → Tool → Observation)를 모두 보관해 문제 재현에 사용

14. 체크리스트 (배포 전)

1. 데이터 분절 및 메타데이터 완비
2. 임베딩 품질 검증 (샘플 쿼리로 유사도 확인)
3. Chroma 컬렉션 persist 확인
4. 툴의 입력 검증과 샌드박스 적용
5. 루프 한계·타임아웃 설정
6. 감사·로깅·모니터링 파이프라인 연결
7. 사용자 피드백 루프(라벨링) 준비

15. 추가 고려사항 (현업 사례 별)

• 고객지원용: 민감정보 마스킹, 답변 근거(링크) 의무화
• 내부문서 Q&A: 버전관리(문서 업데이트 시 재임베딩 전략)
• 제품추천/상담: 실시간 데이터 연동(재고·가격), 트랜잭션 전용 도구 분리

16. 마무리

위 가이드는 Chroma를 중심으로 한 벡터 저장·검색 계층과, LangChain 스타일의 에이전트 패턴을 결합해 안정적으로 동작하는 agentic AI를 만드는 과정을 단계별로 설명했습니다. 실제 적용 시에는 LLM/임베딩 제공자, LangChain 등 프레임워크 버전에 따라 API가 달라질 수 있으므로 배포 전 작은 프로토타입으로 검증하시길 권장합니다.

도움 필요하시면 다음 작업 중 하나를 골라주세요:

• 실제 도메인(예: 고객지원, 제품문서)에 맞춘 완전한 코드 템플릿 생성
• LangChain 및 Chroma 버전(예: LangChain v0.1x / v1.x)을 지정한 구체 코드
• 배포 체크리스트(쿠버네티스, Docker, CI/CD) 생성

선택하시면 그에 맞춰 바로 HTML/코드/배포 스크립트를 만들어 드립니다.