이 가이드를 진행하기 전에 LangSmith 아키텍처 개요와 외부 ClickHouse 연결 가이드를 먼저 읽어주세요.
아키텍처 개요
자체 호스팅 LangSmith 인스턴스와 함께 LangSmith 관리형 ClickHouse를 사용하는 아키텍처는 완전 자체 호스팅 ClickHouse 인스턴스를 사용하는 것과 유사하지만 몇 가지 주요 차이점이 있습니다:- LangSmith 인스턴스와 LangSmith 관리형 ClickHouse 인스턴스 간에 프라이빗 네트워크 연결을 설정해야 합니다. 이는 데이터의 보안을 보장하고 자체 호스팅 LangSmith 인스턴스에서 ClickHouse 인스턴스에 연결할 수 있도록 하기 위함입니다.
- 이 옵션을 사용하면 trace의 민감한 정보(input과 output)가 ClickHouse 대신 클라우드 내의 클라우드 객체 스토리지(S3 또는 GCS)에 저장되어 민감한 정보가 VPC를 벗어나지 않도록 보장합니다. 특정 데이터 필드가 저장되는 위치에 대한 자세한 내용은 데이터 저장을 참조하세요.
- LangSmith 팀이 ClickHouse 인스턴스를 모니터링하고 원활하게 실행되도록 보장합니다. 이를 통해 run-ingestion 지연 및 쿼리 성능과 같은 메트릭을 추적할 수 있습니다.
요구사항
- 지원되는 blob storage 옵션을 사용해야 합니다. 자세한 내용은 blob storage 가이드를 참조하세요.
- private endpoint를 사용하려면 VPC가 ClickHouse Cloud에서 지원하는 region에 있어야 합니다. 그렇지 않으면 방화벽 규칙으로 보안을 유지할 public endpoint를 사용해야 합니다. VPC에는 트래픽을 허용 목록에 추가할 수 있도록 NAT gateway가 필요합니다.
- LangSmith 관리형 ClickHouse 서비스에 연결할 수 있는 VPC가 있어야 합니다. 필요한 네트워킹을 설정하려면 저희 팀과 협력해야 합니다.
- LangSmith 자체 호스팅 인스턴스가 실행 중이어야 합니다. Kubernetes 및 Docker 설치 모두에서 관리형 ClickHouse 서비스를 사용할 수 있습니다.
데이터 저장
ClickHouse는 run과 feedback 데이터를 저장하며, 구체적으로는:- 모든 feedback 데이터 필드.
- 일부 run 데이터 필드.
inputs, outputs, errors, manifests, extras, events로 정의합니다. 이러한 필드에는 LLM 프롬프트와 완성이 포함될 수 있기 때문입니다. LangSmith 관리형 ClickHouse를 사용하면 이러한 민감한 필드는 클라우드 내의 클라우드 객체 스토리지(S3 또는 GCS)에 저장되고 나머지 run 데이터는 ClickHouse에 저장되어 민감한 정보가 VPC를 벗어나지 않도록 보장합니다.
저장된 feedback 데이터 필드
모든 feedback 데이터가 ClickHouse에 저장되므로 feedback(점수 및 주석/코멘트) 또는 저장된 run 데이터 필드에 언급된 다른 run 필드에 민감한 정보를 전송하지 마세요.
| Field Name | Type | Description |
|---|---|---|
| id | UUID | 레코드 자체의 고유 식별자 |
| created_at | datetime | 레코드가 생성된 시간 |
| modified_at | datetime | 레코드가 마지막으로 수정된 시간 |
| session_id | UUID | 실행이 속한 실험 또는 추적 프로젝트의 고유 식별자 |
| run_id | UUID | 세션 내 특정 실행의 고유 식별자 |
| key | string | 피드백의 기준을 설명하는 키, 예: “correctness” |
| score | number | 피드백 키와 연관된 숫자 점수 |
| value | string | 점수와 연관된 값을 저장하기 위해 예약됨. 범주형 피드백에 유용함. |
| comment | string | 레코드와 연관된 코멘트 또는 주석. 주어진 점수에 대한 정당화가 될 수 있음. |
| correction | object | 수정 세부 정보를 저장하기 위해 예약됨 (있는 경우) |
| feedback_source | object | 피드백 소스에 대한 정보를 포함하는 객체 |
| feedback_source.type | string | 피드백이 발생한 소스의 유형, 예: “api”, “app”, “evaluator” |
| feedback_source.metadata | object | 추가 메타데이터를 위해 예약됨, 현재 |
| feedback_source.user_id | UUID | 피드백을 제공하는 사용자의 고유 식별자 |
저장된 run 데이터 필드
Run 데이터 필드는 관리형 ClickHouse 데이터베이스와 클라우드 객체 스토리지(예: S3 또는 GCS) 간에 분할됩니다.객체 스토리지에 저장된 run 필드의 경우 ClickHouse에는 참조 또는 포인터만 유지됩니다. 예를 들어,
inputs와 outputs 콘텐츠는 S3/GCS로 오프로드되며, ClickHouse 레코드는 inputs_s3_urls 및 outputs_s3_urls 필드에 해당 S3 URL을 저장합니다.| 필드 | 저장 위치 |
|---|---|
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 |
Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.