대량 내보내기 모니터링 및 문제 해결

대량 내보내기 상태를 모니터링하고, 실행 중인 내보내기를 관리하며, 실패를 해결해요.

내보내기 작업을 만들었다면 이 페이지의 API를 사용해 진행 상황을 추적하고, 개별 런을 검사하며, 필요하면 중지할 수 있어요. 이 페이지는 또한 LangSmith가 실패를 자동으로 처리하는 방법과 재시도를 모두 소진한 후 내보내기가 실패할 때 해야 할 일도 다뤄요.

이 페이지에서는 다음을 다뤄요:

특정 내보내기의 내보내기 상태 모니터링 및 런 나열.
워크스페이스의 모든 내보내기 나열.
내보내기 중지.
자동 재시도 동작, 실패 시나리오, 상태 수명 주기, 동시성 제한 및 진행 상황 추적을 포함한 실패 모드 및 재시도 정책.
실패한 내보내기 문제 해결.

셀프 호스팅, GCP EU, GCP APAC 및 AWS US SaaS의 경우

셀프 호스팅 설치, GCP EU(eu.api.smith.langchain.com), GCP APAC(apac.api.smith.langchain.com) 또는 AWS US(aws.api.smith.langchain.com)의 경우 아래 요청의 LangSmith URL을 업데이트하세요.

출처: 문서

본문

내보내기 상태 모니터링

내보내기 작업의 상태를 모니터링하려면 다음 cURL 명령을 사용하세요:

curl --request GET \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/{export_id}' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: ***' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID'

{export_id}를 모니터링하려는 내보내기의 ID로 바꾸세요. 이 명령은 지정된 내보내기 작업의 현재 상태를 검색해요.

내보내기의 런 나열

내보내기는 일반적으로 내보낼 특정 날짜 파티션에 해당하는 여러 런으로 나뉘어요. 특정 내보내기와 연관된 모든 런을 나열하려면 다음 cURL 명령을 사용하세요:

curl --request GET \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/{export_id}/runs' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: ***' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID'

이 명령은 지정된 내보내기와 관련된 모든 런을 가져오며, 런 ID, 상태, 생성 시간, 내보낸 행 수 등의 세부 정보를 제공해요.

모든 내보내기 나열

모든 내보내기 작업의 목록을 검색하려면 다음 cURL 명령을 사용하세요:

curl --request GET \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: ***' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID'

이 명령은 현재 상태와 생성 타임스탬프와 함께 모든 내보내기 작업 목록을 반환해요.

내보내기 중지

기존 내보내기를 중지하려면 다음 cURL 명령을 사용하세요:

curl --request PATCH \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/{export_id}' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: ***' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
  --data '{
    "status": "Cancelled"
}'

{export_id}를 취소하려는 내보내기의 ID로 바꾸세요. 작업은 한 번 취소되면 다시 시작할 수 없으며 새 내보내기 작업을 만들어야 한다는 점에 유의하세요.

실패 모드 및 재시도 정책

LangSmith 대량 내보내기는 복원력을 보장하기 위해 일시적인 실패와 인프라 문제를 자동으로 처리해요.

각 대량 내보내기는 여러 런으로 나뉘며, 각 런은 특정 날짜 파티션(보통 일 단위로 구성)의 데이터를 처리해요. 런은 독립적으로 처리되므로 다음이 가능해요:

서로 다른 기간의 병렬 처리.
각 런에 대한 독립적인 재시도 로직.
중단된 경우 특정 체크포인트에서 재개.

내보내기의 각 런(날짜 범위)은 자체 실패 처리와 재시도 예산을 가져요. 런이 모든 재시도를 소진한 후 실패하면 전체 내보내기가 FAILED로 표시돼요.

자동 재시도 동작

내보내기 작업은 다음 동작으로 일시적인 실패를 자동으로 재시도해요:

최대 재시도 횟수: 런당 20회 (변경될 수 있음).
재시도 지연: 시도 사이 30초 (고정, 지수 백오프 없음).
런 타임아웃: 런당 최대 4시간.
전체 워크플로 타임아웃: 전체 내보내기 72시간.

실패 시나리오

실패 유형	원인	자동 재시도?	필요한 조치
인프라 중단	배포, 서버 재시작, 워커 충돌	예, 남은 재시도와 함께 자동 재큐.	없음, 작업이 자동으로 재개돼요.
런 타임아웃	단일 런이 4시간 제한 초과	예, 최대 20회 재시도 (변경될 수 있음).	지속되면 날짜 범위를 좁히거나, 필터를 추가하거나, 내보낼 필드를 제한하세요.
워크플로 타임아웃	전체 내보내기가 72시간 초과	아니요	내보내기 범위(날짜 범위, 필터)를 줄이거나 더 작은 내보내기로 나누세요.
스토리지/대상 오류	잘못된 자격 증명, 버킷 누락, 권한 문제	아니요	대상 구성을 수정하고 새 내보내기를 만드세요.
대상 삭제됨	내보내기 중 버킷이 제거됨	아니요	대상을 다시 만들고 내보내기를 다시 시작하세요.
종료 처리 오류	데이터 직렬화 문제, 리소스 고갈	예, 최대 20회 재시도 (변경될 수 있음).	런 오류 세부 정보를 확인하세요. 조사가 필요할 수 있어요.

단일 런 실패(모든 재시도 소진 후)는 전체 내보내기를 실패시켜요.

내보내기 상태 수명 주기

내보내기는 다음 상태를 가질 수 있어요:

상태	설명
`CREATED`	내보내기가 생성되었지만 아직 처리를 시작하지 않았어요.
`RUNNING`	내보내기가 런을 활발히 처리 중이에요.
`COMPLETED`	모든 런이 성공적으로 내보내졌어요.
`FAILED`	하나 이상의 런이 재시도를 소진한 후 실패했어요.
`CANCELLED`	내보내기가 사용자에 의해 수동 취소됐어요.
`TIMEDOUT`	내보내기가 48시간 워크플로 타임아웃을 초과했어요.

개별 런도 동일한 상태를 가질 수 있어요: CREATED, RUNNING, COMPLETED, FAILED, CANCELLED 또는 TIMEDOUT.

동시성 및 속도 제한

시스템 안정성을 보장하기 위해 내보내기는 다음 제한의 적용을 받아요:

내보내기당 최대 동시 런 수: 45
워크스페이스당 최대 동시 내보내기 수: 15

여러 내보내기가 실행 중이라면 용량을 사용할 수 있을 때까지 새 런 작업이 대기열에 들어가요.

셀프 호스팅: 대량 내보내기 동시성 및 페이로드 크기 튜닝

LangSmith Self-hosted에서 동시성 제한은 기본값이에요. 대량 내보내기 중 pod 메모리 사용량을 튜닝하려면 langsmith-backend 서비스에서 다음 환경 변수를 구성하세요:

환경 변수	기본값	설명
`BULK_EXPORT_MAX_CONCURRENT_RUNS`	`5`	단일 내보내기 내에서 스케줄링 패스당 병렬로 대기열에 넣는 파티션 런의 최대 수. 큰 날짜 파티션을 처리할 때 최대 메모리를 제한하려면 줄이세요.
`DATA_EXPORT_RUN_LIMIT`	`500`	내보내기 창을 페이징할 때 쿼리당 런 스토어에서 가져오는 페이지 크기(최대 행 수).
`DATA_EXPORT_MAX_BATCH_PAYLOAD_SIZE_KB`	`100000` (100 MB)	내보내기 런 동안 배치가 플러시되기 전에 누적되는 최대 페이로드 크기(KB). 각 배치의 메모리 사용량을 낮추려면 줄이세요.

예시: 메모리 제약이 있는 배포를 위한 보수적 설정

# In your Helm values
BULK_EXPORT_MAX_CONCURRENT_RUNS: "10"
DATA_EXPORT_RUN_LIMIT: "5"
DATA_EXPORT_MAX_BATCH_PAYLOAD_SIZE_KB: "512"

이 값을 낮추면 병렬 처리가 줄어들고 총 내보내기 시간이 늘어날 수 있지만, pod당 최대 메모리 사용량은 낮아져요. 메모리 제약이 있는 노드에서 OOM(메모리 부족) 오류가 발생한다면 이 설정이 도움이 될 수 있어요.

진행 상황 추적 및 재개 가능성

내보내기 시스템은 각 런에 대한 상세한 진행 메타데이터를 유지해요:

데이터 스트림의 최신 커서 위치.
내보낸 행 수.
작성된 Parquet 파일 목록.

이 진행 추적은 다음을 가능하게 해요:

정상적인 재개: 런이 중단되면(예: 배포로 인해) 처음부터가 아니라 마지막 체크포인트에서 재개해요.
진행 상황 모니터링: API를 통해 얼마나 많은 데이터가 내보내졌는지 추적.
효율적인 재시도: 실패한 런은 이미 성공적으로 작성된 데이터를 다시 내보내지 않아요.

실패한 내보내기 문제 해결

내보내기가 실패하면 다음 단계를 따르세요:

내보내기 상태 확인: GET /api/v1/bulk-exports/{export_id} 엔드포인트를 사용해 내보내기 세부 정보와 상태를 검색하세요.
런 오류 검토: 런 나열 API로 런을 모니터링할 수 있어요. 각 런에는 재시도 시도별로 키가 지정된 상세 오류 메시지가 있는 errors 필드가 포함돼요 (예: retry_0, retry_1).
대상 접근 확인: 대상 버킷이 여전히 존재하고 자격 증명이 유효한지 확인하세요.
런 크기 확인: 타임아웃 오류가 보이면 날짜 파티션에 데이터가 너무 많을 수 있어요. 내보낼 필드 제한이 도움이 될 수 있어요.
시스템 제한 검토: 동시성 제한(내보내기당 런 5개, 워크스페이스당 내보내기 3개)에 걸리지 않았는지 확인하세요.

스토리지 관련 오류의 경우 내보내기를 다시 시도하기 전에 AWS CLI 또는 gsutil로 대상 구성을 테스트할 수 있어요.

대량 내보내기 모니터링 및 문제 해결