LangSmith 관리형 ClickHouse

LangSmith 관리형 ClickHouse

LangSmith가 ClickHouse를 트레이스와 피드백의 기본 저장 엔진으로 사용하는 방법과, LangSmith 관리형 ClickHouse를 연결하는 방법을 알려드릴게요.

확인: 이 가이드를 진행하기 전에 LangSmith 아키텍처 개요와 외부 ClickHouse 연결 가이드를 읽어주세요.

LangSmith는 트레이스와 피드백의 기본 저장 엔진으로 ClickHouse를 사용합니다. 더 쉬운 관리와 스케일링을 위해 셀프 호스팅 LangSmith 인스턴스를 외부 ClickHouse 인스턴스에 연결하는 것을 권장합니다. LangSmith 관리형 ClickHouse는 LangSmith 팀이 모니터링·유지 관리하는 완전 관리형 ClickHouse 인스턴스를 사용할 수 있게 하는 옵션입니다.

출처: 문서

본문

아키텍처 개요

셀프 호스팅 LangSmith 인스턴스에서 LangSmith 관리형 ClickHouse를 사용하는 아키텍처는 완전 셀프 호스팅 ClickHouse 인스턴스를 사용하는 것과 비슷하며, 몇 가지 핵심 차이가 있습니다:

  • LangSmith 인스턴스와 LangSmith 관리형 ClickHouse 인스턴스 사이에 사설 네트워크 연결을 설정해야 합니다. 이는 데이터를 안전하게 유지하고 셀프 호스팅 LangSmith 인스턴스에서 ClickHouse 인스턴스에 연결할 수 있게 하기 위함입니다.
  • 이 옵션을 사용하면 트레이스의 민감한 정보(입력과 출력)는 ClickHouse 대신 클라우드 내의 클라우드 객체 스토리지(S3 또는 GCS)에 저장되어, 민감한 정보가 VPC 밖으로 나가지 않도록 합니다. 특정 데이터 필드가 어디에 저장되는지에 대한 자세한 내용은 데이터 저장을 참고하세요.
  • LangSmith 팀이 ClickHouse 인스턴스를 모니터링하고 원활하게 실행되도록 보장합니다. 이를 통해 실행 수집 지연과 쿼리 성능 같은 메트릭을 추적할 수 있습니다.

요구사항

  • 지원되는 blob storage 옵션을 사용해야 합니다. 자세한 내용은 blob storage 가이드를 읽어주세요.
  • 프라이빗 엔드포인트를 사용하려면 VPC가 ClickHouse Cloud 지원 리전에 있는지 확인하세요. 그렇지 않으면 방화벽 규칙으로 보호할 공용 엔드포인트를 사용해야 합니다. VPC에는 트래픽을 허용 목록에 추가할 수 있도록 NAT 게이트웨이가 있어야 합니다.
  • LangSmith 관리형 ClickHouse 서비스에 연결할 수 있는 VPC가 있어야 합니다. 필요한 네트워킹을 설정하려면 당사 팀과 협력해야 합니다.
  • 실행 중인 LangSmith 셀프 호스팅 인스턴스가 있어야 합니다. 관리형 ClickHouse 서비스를 Kubernetes 설치와 함께 사용할 수 있습니다.

데이터 저장

ClickHouse는 실행(runs) 및 피드백(feedback) 데이터를 저장하며, 구체적으로:

  • 모든 피드백 데이터 필드.
  • 일부 실행 데이터 필드.

필드 목록은 저장된 실행 데이터 필드와 저장된 피드백 데이터 필드를 참고하세요.

LangChain은 실행의 inputs, outputs, errors, manifests, extras, events를 민감한 애플리케이션 데이터로 정의합니다. 이 필드는 LLM 프롬프트와 완성을 포함할 수 있기 때문입니다. LangSmith 관리형 ClickHouse에서는 이러한 민감한 필드를 클라우드 내의 클라우드 객체 스토리지(S3 또는 GCS)에 저장하고, 나머지 실행 데이터는 ClickHouse에 저장하여 민감한 정보가 VPC 밖으로 나가지 않게 합니다.

저장된 피드백 데이터 필드

참고: 모든 피드백 데이터는 ClickHouse에 저장되므로, 피드백(점수와 주석/코멘트)이나 저장된 실행 데이터 필드에 언급된 다른 실행 필드에 민감한 정보를 보내지 마세요.

LangSmith 관리형 ClickHouse 구성을 사용하면 모든 피드백 데이터 필드가 ClickHouse에 저장됩니다:

Field Name Type Description
id UUID Unique identifier for the record itself
created_at datetime Timestamp when the record was created
modified_at datetime Timestamp when the record was last modified
session_id UUID Unique identifier for the experiment or tracing project the run was a part of. Required when creating feedback for a run.
run_id UUID Unique identifier for a specific run within a session
start_time datetime Start time of the run the feedback is for. Optional, but providing it lets LangSmith process the feedback quicker.
key string A key describing the criteria of the feedback, e.g. 'correctness'
score number Numerical score associated with the feedback key
value string Reserved for storing a value associated with the score. Useful for categorical feedback.
comment string Any comment or annotation associated with the record. This can be a justification for the score given.
correction object Reserved for storing correction details, if any
feedback_source object Object containing information about the feedback source
feedback_source.type string The type of source where the feedback originated, e.g. 'api', 'app', 'evaluator'
feedback_source.metadata object Reserved for additional metadata, currently
feedback_source.user_id UUID Unique identifier for the user providing feedback

이 참조 문서는 실행에 대한 평가 점수와 주석을 나타내는 LangSmith의 방식인 저장된 피드백 형식을 설명합니다.

저장된 실행 데이터 필드

실행 데이터 필드는 관리형 ClickHouse 데이터베이스와 클라우드 객체 스토리지(예: S3 또는 GCS) 사이에 나뉩니다.

참고: 객체 스토리지에 저장된 실행 필드는 참조 또는 포인터만 ClickHouse에 유지됩니다. 예를 들어 inputs와 outputs 내용은 S3/GCS로 오프로드되고, ClickHouse 레코드는 inputs_s3_urls와 outputs_s3_urls 필드에 해당 S3 URL을 저장합니다.

표는 각 실행 필드와 저장 위치를 설명합니다:

Field Storage Location
id ClickHouse
name ClickHouse
inputs Object Storage
run_type ClickHouse
start_time ClickHouse
end_time ClickHouse
extra Object Storage
error Object Storage
outputs Object Storage
events Object Storage
tags ClickHouse
trace_id ClickHouse
dotted_order ClickHouse
status ClickHouse
child_run_ids ClickHouse
direct_child_run_ids ClickHouse
parent_run_ids ClickHouse
feedback_stats ClickHouse
reference_example_id ClickHouse
total_tokens ClickHouse
prompt_tokens ClickHouse
completion_tokens ClickHouse
total_cost ClickHouse
prompt_cost ClickHouse
completion_cost ClickHouse
first_token_time ClickHouse
session_id ClickHouse
in_dataset ClickHouse
parent_run_id ClickHouse
execution_order (deprecated) ClickHouse
serialized ClickHouse
manifest_id (deprecated) ClickHouse
manifest_s3_id ClickHouse
inputs_s3_urls ClickHouse
outputs_s3_urls ClickHouse
price_model_id ClickHouse
app_path ClickHouse
last_queued_at ClickHouse
share_token ClickHouse

이 참조 문서는 트레이스의 구성 요소인 저장된 실행(span)의 형식을 설명합니다.

더 알아보기