ChromaDB 영속성

ChromaDB 영속성 (Persistent Client)

프로세스를 종료했다가 다시 시작해도 데이터가 그대로 남아 있어야 할 때가 있어요. 그럴 때 ChromaDB는 데이터를 로컬 디스크에 저장하고 시작할 때 다시 불러오는 영속 클라이언트(PersistentClient) 를 제공해요.

출처: 공식문서 - Persistent Client

PersistentClient 사용하기

PersistentClient를 만들면 데이터가 자동으로 디스크에 저장되고, 이미 데이터가 있으면 시작할 때 자동으로 불러와져요. path는 ChromaDB가 데이터베이스 파일을 저장할 디렉토리예요.

import chromadb

client = chromadb.PersistentClient(path="/path/to/save/to")

path를 지정하지 않으면 기본값은 .chroma 디렉토리가 돼요.

클라이언트 종류

ChromaDB는 쓰임새에 따라 여러 클라이언트를 제공해요.

  • Cloud Client — Chroma Cloud에 연결하는 클라이언트예요. tenant, database, api key를 지정해요.
  • 인메모리/Ephemeral Client — chromadb.Client()를 호출하면 인메모리 서버가 시작되고 그에 연결되는 클라이언트가 반환돼요. 파이썬 노트북에서 다른 임베딩 함수나 검색 기법을 실험해보기에 좋아요. 데이터를 디스크에 보존하지 않아요.
  • Persistent Client — 데이터를 디스크에 저장하는 클라이언트예요. 로컬 개발·테스트용이며, 프로덕션에서는 서버 기반 Chroma 인스턴스를 권장해요.

유용한 편의 메서드

클라이언트 객체는 몇 가지 편의 메서드를 제공해요.

  • heartbeat() — 나노초 단위의 하트비트를 반환해요. 클라이언트가 서버에 계속 연결되어 있는지 확인하는 데 유용해요.
  • reset() — 데이터베이스를 완전히 비우고 초기 상태로 되돌려요. ⚠️ 이 작업은 파괴적이고 되돌릴 수 없어요.
client.heartbeat()
client.reset()

서버 모드 (Client-Server Mode)

JavaScript/TypeScript 클라이언트나 프로덕션 배포에서는 로컬 Chroma 서버에 연결하는 방식을 써요. npm으로 Chroma 서버를 설치하고 직접 실행하면 데이터를 유지하면서 서버 모드로 쓸 수 있어요.

npm install chromadb
npx chroma run --path ./getting-started

공식 Docker 이미지로도 서버를 띄울 수 있어요.

docker pull chromadb/chroma
docker run -p 8000:8000 chromadb/chroma

서버가 로컬에서 실행되면 ChromaClient로 연결해요. 기본적으로 http://localhost:8000의 default_tenant·default_database에 연결되며, 필요하면 ssl, host, port, database, headers 같은 값을 생성자에 넘겨 바꿀 수 있어요.

const client = new ChromaClient({
  ssl: false,
  host: "localhost",
  port: 9000, // 서버 설정에 따른 비표준 포트
  database: "my-db",
  headers: {},
});

더 알아보기 (Learn more)