체크포인터 백엔드 구성하기

체크포인트 저장을 위해 Agent Server가 PostgreSQL, MongoDB 또는 커스텀 구현을 사용하도록 구성해요.

Agent Server는 체크포인터 백엔드를 사용해서 그래프 상태를 영구 저장해요. 기본적으로 LangSmith는 체크포인트를 다른 서버 데이터와 함께 PostgreSQL에 저장해요. MongoDB로 전환하거나 커스텀 구현을 제공할 수도 있어요.

체크포인터 백엔드와 관계없이 LangSmith는 스레드, 런, 어시스턴트, 크론, 그리고 메모리 스토어에 항상 PostgreSQL이 필요해요. 체크포인터 백엔드는 체크포인트 데이터를 어디에 저장할지만 제어해요.

출처: 문서

본문

사용 가능한 백엔드

백엔드	스토리지	구성	사용 사례
`default`	PostgreSQL	없음 (내장)	표준 배포
`mongo`	MongoDB	`langgraph.json` 또는 `LS_DEFAULT_CHECKPOINTER_BACKEND` 환경 변수	기존 MongoDB 인프라를 가진 팀
`custom`	사용자 제공	`langgraph.json`	커스텀 스토리지 백엔드 (커스텀 체크포인터 참고)

기본값 (PostgreSQL)

PostgreSQL은 기본 체크포인터 백엔드예요. 별도 구성이 필요 없어요. 커스텀 PostgreSQL 인스턴스를 사용하려면 POSTGRES_URI_CUSTOM 환경 변수를 설정하세요.

MongoDB 체크포인팅 설정하기

Agent Server v0.7.64 이상이 필요해요.

사전 요구 사항

MongoDB 복제본 세트 (독립 실행형 mongod는 지원되지 않아요). 셀프 매니지드 복제본 세트, mongos 라우터 또는 MongoDB Atlas 같은 매니지드 서비스가 될 수 있어요.
경로에 데이터베이스 이름을 포함한 연결 URI (예: /langgraph).

백엔드 선택하기

다음 방법 중 하나로 백엔드를 "mongo"로 설정해요:

langgraph.json에서 (앱 레벨—애플리케이션 코드와 함께 번들됨):

{
  "dependencies": ["."],
  "graphs": {
    "agent": "./agent.py:graph"
  },
  "checkpointer": {
    "backend": "mongo",
    "ttl": {
      "strategy": "delete",
      "default_ttl": 43200,
      "sweep_interval_minutes": 10
    }
  }
}

환경 변수로 (플랫폼 레벨—독립 실행형 배포를 관리하는 운영자를 위한):

LS_DEFAULT_CHECKPOINTER_BACKEND=mongo

환경 변수는 langgraph.json에 지정하지 않은 에이전트 서버의 기본 백엔드를 설정해요. langgraph.json에 backend 값이 포함되어 있으면 그 값이 우선해요.

MongoDB URI 제공하기

배포 시 LS_MONGODB_URI 환경 변수를 설정하세요:

LS_MONGODB_URI="mongodb://user:***@host:27017/langgraph?replicaSet=rs0"

연결 URI 요구 사항

URI는 다음을 만족해야 해요:

복제본 세트 멤버 또는 mongos 라우터를 가리켜야 함
경로에 대상 데이터베이스 이름을 포함해야 함

유효한 예시:

mongodb://user:***@host:27017/langgraph?replicaSet=rs0
mongodb://host1:27017,host2:27017,host3:27017/mydb?replicaSet=prod-rs
mongodb+srv://user:***@cluster.example.net/langgraph

환경별 배포

독립 실행형 (Kubernetes):

langgraph-cloud Helm 차트 (v0.2.6+)에는 MongoDB 지원이 내장되어 있어요. values 파일에서 활성화하세요:

번들 MongoDB (개발 및 테스트):

mongo:
  enabled: true
  resources:
    requests:
      cpu: 500m
      memory: 1Gi
  persistence:
    size: 8Gi

차트는 단일 노드 MongoDB 복제본 세트를 배포하고 서버가 자동으로 이를 사용하도록 구성해요.

외부 MongoDB (프로덕션):

mongo:
  enabled: true
  external:
    enabled: true
    connectionUrl: "mongodb://user:***@mongo.example.net:27017/langgraph?replicaSet=rs0"

또는 기존 Kubernetes 시크릿을 참조하세요:

mongo:
  enabled: true
  external:
    enabled: true
    existingSecretName: "my-mongo-secret"

시크릿에는 mongodb_connection_url 키가 포함되어야 해요.

독립 실행형 (Docker):

langgraph.json이 이미 backend를 "mongo"로 설정했다면 URI만 제공하면 돼요. 그렇지 않으면 두 환경 변수를 모두 설정하세요:

docker run \
    --env-file .env \
    -p 8123:8000 \
    -e REDIS_URI="redis://redis:6379" \
    -e DATABASE_URI="postgres://postgres:***@postgres:5432/postgres" \
    -e LS_DEFAULT_CHECKPOINTER_BACKEND=mongo \
    -e LS_MONGODB_URI="mongodb://mongo:27017/langgraph?replicaSet=rs0" \
    -e LANGSMITH_API_KEY="..." \
    my-image

MongoDB를 포함한 전체 Docker Compose 예시는 독립 실행형 서버 가이드를 참고하세요.

클라우드:

langgraph.json에서 backend를 "mongo"로 설정한 다음, LangSmith UI의 배포 설정에 환경 변수로 LS_MONGODB_URI를 추가하세요.

MongoDB 인스턴스는 Cloud 데이터 플레인에서 접근 가능해야 해요. MongoDB Atlas 같은 매니지드 서비스가 이에 적합해요.

비체크포인트 데이터에는 여전히 PostgreSQL이 자동 프로비저닝돼요.

커스텀 체크포인터

PostgreSQL이나 MongoDB 외의 스토리지 백엔드를 사용하려면 커스텀 BaseCheckpointSaver를 구현하세요. 자세한 내용은 커스텀 체크포인터 추가하기를 참고하세요.

체크포인터 백엔드 구성하기