이 가이드를 진행하기 전에 LangSmith 아키텍처 개요와 외부 ClickHouse 연결 가이드를 먼저 읽어주세요.
아키텍처 개요
셀프 호스팅 LangSmith 인스턴스와 함께 LangSmith 관리형 ClickHouse를 사용하는 아키텍처는 완전히 셀프 호스팅된 ClickHouse 인스턴스를 사용하는 것과 유사하지만, 몇 가지 주요 차이점이 있습니다:- LangSmith 인스턴스와 LangSmith 관리형 ClickHouse 인스턴스 간에 프라이빗 네트워크 연결을 설정해야 합니다. 이는 데이터를 안전하게 보호하고 셀프 호스팅 LangSmith 인스턴스에서 ClickHouse 인스턴스에 연결할 수 있도록 하기 위함입니다.
- 이 옵션을 사용하면 트레이스의 민감한 정보(입력 및 출력)가 민감한 정보가 VPC를 벗어나지 않도록 하기 위해 ClickHouse 대신 클라우드 내의 클라우드 객체 스토리지(S3 또는 GCS)에 저장됩니다. 특정 데이터 필드가 저장되는 위치에 대한 자세한 내용은 데이터 스토리지를 참조하세요.
- LangSmith 팀은 ClickHouse 인스턴스를 모니터링하고 원활하게 실행되도록 보장합니다. 이를 통해 실행 수집 지연 및 쿼리 성능과 같은 메트릭을 추적할 수 있습니다.
요구 사항
- 지원되는 Blob 스토리지 옵션을 사용해야 합니다. 자세한 내용은 Blob 스토리지 가이드를 참조하세요.
- 프라이빗 엔드포인트를 사용하려면 VPC가 ClickHouse Cloud에서 지원하는 리전에 있어야 합니다. 그렇지 않으면 방화벽 규칙으로 보호할 퍼블릭 엔드포인트를 사용해야 합니다. VPC에는 트래픽을 허용 목록에 추가할 수 있도록 NAT 게이트웨이가 필요합니다.
- LangSmith 관리형 ClickHouse 서비스에 연결할 수 있는 VPC가 있어야 합니다. 필요한 네트워킹을 설정하려면 당사 팀과 협력해야 합니다.
- LangSmith 셀프 호스팅 인스턴스가 실행 중이어야 합니다. Kubernetes 및 Docker 설치 모두에서 관리형 ClickHouse 서비스를 사용할 수 있습니다.
데이터 스토리지
ClickHouse는 실행 및 피드백 데이터, 구체적으로 다음을 저장합니다:- 모든 피드백 데이터 필드.
- 일부 실행 데이터 필드.
inputs, outputs, errors, manifests, extras, events로 정의합니다. 이러한 필드에는 LLM 프롬프트 및 완료가 포함될 수 있기 때문입니다. LangSmith 관리형 ClickHouse를 사용하면 이러한 민감한 필드는 클라우드 내의 클라우드 객체 스토리지(S3 또는 GCS)에 저장되고 나머지 실행 데이터는 ClickHouse에 저장되어 민감한 정보가 VPC를 벗어나지 않도록 보장합니다.
저장된 피드백 데이터 필드
모든 피드백 데이터가 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 |
| run_id | UUID | Unique identifier for a specific run within a session |
| key | string | A key describing the criteria of the feedback, eg “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, eg “api”, “app”, “evaluator” |
| feedback_source.metadata | object | Reserved for additional metadata, currently |
| feedback_source.user_id | UUID | Unique identifier for the user providing feedback |
저장된 실행 데이터 필드
실행 데이터 필드는 관리형 ClickHouse 데이터베이스와 클라우드 객체 스토리지(예: S3 또는 GCS) 간에 분할됩니다.객체 스토리지에 저장된 실행 필드의 경우 ClickHouse에는 참조 또는 포인터만 유지됩니다. 예를 들어
inputs 및 outputs 콘텐츠는 S3/GCS로 오프로드되며, ClickHouse 레코드는 inputs_s3_urls 및 outputs_s3_urls 필드에 해당 S3 URL을 저장합니다.| 필드 | 저장 위치 |
|---|---|
id | ClickHouse |
name | ClickHouse |
inputs | 객체 스토리지 |
run_type | ClickHouse |
start_time | ClickHouse |
end_time | ClickHouse |
extra | 객체 스토리지 |
error | 객체 스토리지 |
outputs | 객체 스토리지 |
events | 객체 스토리지 |
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 (더 이상 사용되지 않음) | ClickHouse |
serialized | ClickHouse |
manifest_id (더 이상 사용되지 않음) | 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.