Chroma 오픈소스 문서에 기여했습니다 — 변경 내용과 배운 점

출처: Dev.to

Chroma는 AI 생태계에서 가장 널리 사용되는 오픈소스 벡터 데이터베이스 중 하나입니다. 수많은 RAG 파이프라인, 의미 검색 시스템, AI 에이전트 메모리 레이어의 핵심 역할을 하며 — 제가 직접 만든 프로젝트에도 포함됩니다. 그래서 GitHub에서 이슈 #3111, 즉 Haystack 통합 문서 업데이트 요청을 발견했을 때, 직접 해결하기로 했습니다.

이 이슈는 단순했습니다. 기존 문서는 오래됐고, 설치 단계가 명확하지 않으며, ChromaDocumentStore에 대한 실용적인 예제가 거의 없었습니다. 하지만 자세히 살펴보니 이미 열려 있는 PR이 두 개 있었습니다. 여기서 상황이 흥미로워졌습니다.

아무것도 쓰기 전에, 다른 사람들이 이미 무엇을 했는지 확인했습니다. 이 정확한 이슈에 대해 두 개의 열린 PR이 있었습니다:

• PR #3112: 전체 문서 파일을 삭제했습니다. 기여자는 문서를 “업데이트”하는 가장 좋은 방법이 파일을 완전히 없애는 것이라고 판단했죠. 이는 사용자에게 도움이 되지 않으며, 단지 죽은 링크를 만들 뿐입니다.

• PR #7229 (manikanta7cheruku): 코드 예제의 Path 버그를 수정하고 LLM을 HuggingFace(Mixtral)에서 OpenAI(GPT‑3.5‑turbo)로 교체했습니다. Path 수정은 좋았지만, LLM 교체는 논란이 있습니다. 무료이며 자체 호스팅 가능한 모델을 유료 API 키가 필요한 모델로 바꾼 것은 오픈소스 문서에 더 나쁜 기본값을 제공하는 셈이죠.

두 PR 모두 핵심 요청인 ChromaDocumentStore에 대한 포괄적이고 명확한 예제를 다루지 못했습니다. 그래서 저는 직접 문서를 작성했습니다.

docs/mintlify/integrations/frameworks/haystack.mdx 파일을 80줄에서 187줄로 재작성했습니다. 추가된 내용은 다음과 같습니다:

• 원본 문서에는 pip install chroma-haystack만 있었는데, 통합 패키지가 항상 올바르게 의존성을 끌어오지 못하는 경우가 있어 haystack-ai를 명시적인 의존성으로 추가했습니다.
• 10줄 정도의 최소 예제를 추가해 Document 생성, 쓰기, 카운트를 한 번에 보여줍니다. 이는 설정이 정상 동작하는지 가장 빠르게 확인할 수 있는 방법입니다:

  from haystack import Document
  from haystack_integrations.document_stores.chroma import ChromaDocumentStore
  
  document_store = ChromaDocumentStore()
  
  docs = [
      Document(content="Chroma stores documents as vectors."),
      Document(content="Haystack provides the orchestration layer."),
  ]
  document_store.write_documents(docs)
  print(document_store.count_documents())  # Output: 2

• 원본 문서에서는 인‑메모리 모드만 다루었지만, 세 가지 모드(인‑메모리(개발용), 디스크 기반 영구 저장소, Docker 혹은 chroma run을 이용한 원격 클라이언트‑서버(프로덕션))를 모두 문서화했습니다.
• 기존 코드에 "data" / Path(name)와 같이 문자열을 Path 객체와 나누는 부분이 있었는데, 이는 TypeError를 일으킵니다. 이를 Path("data") / name으로 수정했습니다.
• 세 가지 검색 패턴을 추가했습니다: 텍스트 쿼리(Chroma가 자동 임베딩), 임베딩 쿼리(미리 계산된 벡터), 그리고 Haystack의 필터 문법을 이용한 메타데이터 필터링