셀프 호스팅의 LangSmith Engine

셀프 호스팅 LangSmith 인스턴스에 LangSmith Engine을 설치하고, 그것이 환경 밖에서 의존하는 것과 데이터를 처리하는 방법을 이해해요.

셀프 호스팅 Engine에는 LangSmith Helm 차트 0.16.0 이상과 Engine 엔타이틀먼트를 포함하는 라이선스가 필요해요. 이전 차트 버전에서는 사용할 수 없어요. 주문에 엔타이틀먼트를 추가하려면 영업 팀에 문의하세요.

LangSmith Engine은 LangSmith 내의 에이전트로, 프로덕션 트레이스를 모니터링하고 이를 이슈로 클러스터링하며, 각 이슈를 소스 코드에 대해 진단하고, 수정 사항을 PR로 제안하며, 데이터셋에 추가할 ground truth 평가를 식별해요. 제품 개요는 Engine을 참고하세요.

셀프 호스팅 LangSmith에서 Engine의 오케스트레이션(detect, fix, verify 루프 포함)은 LangSmith의 일부로 VPC 안에서 실행돼요. 모델 작업은 VPC 안에서 완전히 실행될 수 없어요. Engine은 필요한 콘텐츠를 Langchain 관리형 ZDR(기록 보존 없음) 서비스인 LangSmith Intelligence(LSI)로 보내요.

이 페이지는 두 부분을 다뤄요: Engine이 환경 밖에서 의존하는 것과, 인스턴스에 Engine 설치하는 방법. Engine을 소스 코드에 연결하려면 Engine을 GitHub에 연결에 설명된 대로 자체 GitHub App을 만들고 구성하세요.

Engine은 세 종류의 데이터로 작동해요:

코드 (선택): 이슈 진단과 수정 제안을 위해 Engine이 읽는 에이전트의 소스.
트레이스: 사용자 메시지, 도구 출력, PII를 포함할 수 있는 에이전트의 런타임 데이터.
모델: Engine이 진단 실행, 수정 생성, 평가 작성에 사용하는 LLM 호출.

출처: 문서

본문

클라우드 및 지역별 가용성

Engine은 LSI가 사용 가능한 곳에서 사용할 수 있어요:

클라우드	지역	상태
AWS	US	사용 가능
GCP	US	사용 가능

다른 지역의 가용성은 영업 팀에 문의하세요.

작동 방식

LSI는 Engine을 구동하는 LangChain 관리형 서비스예요.

흐름:

셀프 호스팅 Engine은 이 페이지의 클라우드별 섹션에 나열된, 해당 클라우드의 LSI 게이트웨이로 HTTPS 요청을 보내요.
Engine은 LangSmith 라이선스 검증 중 얻은 단기 라이선스 JWT로 인증해요. 별도의 모델 프로바이더 자격 증명을 제공하지 않아요.
LSI는 JWT를 검증하고 LangChain 환경 내부의 프라이빗 네트워킹을 통해 모델 프로바이더로 요청을 라우팅해요.
LSI는 응답을 셀프 호스팅 Engine에 반환해요.

각 요청은 Engine이 작업을 수행하는 데 필요한 트레이스 콘텐츠, 코드, 중간 출력을 포함해요. LSI와 모델 프로바이더는 요청을 처리하기 위해 그 콘텐츠를 처리해요.

클러스터는 그 게이트웨이로의 아웃바운드 HTTPS를 허용해야 해요. 연결은 공용 egress 또는 프라이빗 연결을 사용할 수 있어요. AWS에서는 AWS PrivateLink로 연결을 따라 Engine 트래픽을 프라이빗 네트워킹으로 유지하세요.

LSI에 대한 연결을 사용할 수 없으면 Engine은 더 낮은 품질의 출력으로 저하되는 대신 중지하고 오류를 반환해요. 클러스터 내 모델이나 대체 프로바이더가 없어 폴백할 수 없어요. LangSmith 배포의 나머지는 영향을 받지 않으며, Engine은 다음 예약 스캔에서 다시 시도해요.

LangSmith Intelligence가 보존하는 것

LSI는 프롬프트나 모델 응답의 콘텐츠를 영구화하지 않아요. 다음 메타데이터를 사용량 귀속 및 청구용으로 유지해요:

사용량 귀속에 사용되는 계정, 워크스페이스, 프로젝트 식별자.
청구에 사용되는 모델 및 토큰 사용 메타데이터.

모델 프로바이더 보존 및 학습 약속은 Engine 보안을 참고하세요.

클라우드별 연결

AWS (US에서 사용 가능)

게이트웨이 호스트는 beacon.aws.langchain.com이에요. LSI는 LangChain AWS 환경의 AWS Bedrock으로 요청을 라우팅해요.

AWS PrivateLink로 연결

PrivateLink를 구성하기 전에 Helm 및 egress 구성을 포함한 Engine 설치를 완료하세요.

AWS PrivateLink는 Engine 트래픽을 공용 인터넷에 노출하지 않고 VPC에서 LSI로 라우팅해요. LSI 엔드포인트 서비스는 us-east-2에서 호스팅되며, AWS는 다른 지역의 VPC에서 접근을 지원해요.

시작하기 전에 AWS 계정 ID, VPC ID, 프라이빗 서브넷 ID, 인터페이스 엔드포인트용 보안 그룹을 수집하세요. 그 엔드포인트 보안 그룹을 구성해 Engine을 실행하는 노드나 워크로드에 연결된 보안 그룹에서만, 또는 그것들을 포함하는 가장 작은 프라이빗 CIDR에서만 포트 443의 인바운드 TCP 트래픽을 허용하세요. 0.0.0.0/0은 허용하지 마세요.

VPC를 LSI에 연결하려면:

접근 요청: AWS 계정 ID를 계정 담당자 또는 [email protected]에 문의하세요. LangChain이 계정을 엔드포인트 서비스의 허용 principal 목록에 추가해요.

인터페이스 VPC 엔드포인트 생성: VPC가 있는 지역에 대해 AWS 프로바이더를 구성하세요. VPC가 다른 지역에 있더라도 service_region을 us-east-2로 유지하세요. 가용 영역마다 프라이빗 서브넷 하나를 선택하세요.

service_region 인수에는 HashiCorp AWS 프로바이더 5.82.0 이상이 필요해요.

resource "aws_vpc_endpoint" "langsmith_intelligence" {
  vpc_id              = var.vpc_id
  service_name        = "com.amazonaws.vpce.us-east-2.vpce-svc-054f37092752bff6b"
  service_region      = "us-east-2"
  vpc_endpoint_type   = "Interface"
  subnet_ids          = var.private_subnet_ids
  security_group_ids  = [var.security_group_id]
  private_dns_enabled = false
}

LangChain이 연결을 수락할 때까지 대기: LangChain이 연결을 수락한 후 엔드포인트 상태가 pendingAcceptance에서 available로 바뀌어요. 연결성을 테스트하기 전에 변경 사항이 전파되도록 몇 분 기다리세요.
LSI 호스트 이름을 엔드포인트로 라우팅: VPC에서 DNS 확인과 DNS 호스트 이름을 활성화하세요. 그런 다음 Route 53 프라이빗 호스팅 영역과 별칭 레코드를 만들어 beacon.aws.langchain.com이 VPC 내부의 VPC 엔드포인트로 확인되게 하세요. TLS 인증서 검증이 성공하도록 이 호스트 이름을 변경하지 마세요. 프라이빗 호스팅 영역은 엔드포인트를 사용할 수 없을 때 공용 DNS로의 폴백도 방지해요.
```
resource "aws_route53_zone" "langsmith_intelligence" {
  name = "beacon.aws.langchain.com"

  vpc {
    vpc_id = var.vpc_id
  }
}

resource "aws_route53_record" "langsmith_intelligence" {
  zone_id = aws_route53_zone.langsmith_intelligence.zone_id
  name    = "beacon.aws.langchain.com"
  type    = "A"

  alias {
    name                   = aws_vpc_endpoint.langsmith_intelligence.dns_entry[0].dns_name
    zone_id                = aws_vpc_endpoint.langsmith_intelligence.dns_entry[0].hosted_zone_id
    evaluate_target_health = true
  }
}
```
워크로드가 Amazon 제공 리졸버 대신 기업 DNS 리졸버를 사용한다면, Route 53 Resolver로 조건부 전달을 구성하거나 엔드포인트 DNS 이름을 가리키는 beacon.aws.langchain.com에 대한 동등한 프라이빗 DNS 재정의를 만드세요.
프라이빗 연결성 검증: Engine을 실행하는 노드나 컨테이너에서 게이트웨이 호스트 이름을 확인하세요:
```
getent ahostsv4 beacon.aws.langchain.com
```
결과에 엔드포인트 네트워크 인터페이스에 할당된 프라이빗 IP 주소가 포함되는지 확인하세요. 그런 다음 분석을 시작하고 성공적으로 완료되는지 확인하세요. 분석이 완료되지 않으면 Engine 설치 및 egress 구성을 검토하세요.

GCP (US에서 사용 가능)

게이트웨이 호스트는 beacon.langchain.com이에요. LSI는 LangChain GCP 환경의 Vertex로 요청을 라우팅해요.

이 호스트는 셀프 호스팅 LangSmith가 라이선스 검증과 청구 텔레메트리에 사용하는 것과 같아서, GCP 배포는 새 egress 대상을 추가하는 대신 경로를 추가해요. egress 구성을 참고하세요.

모델 선택 및 품질

Engine은 LSI를 통해 클라우드의 모델 프로바이더를 사용해요: AWS에서는 Amazon Bedrock, GCP에서는 Vertex AI.

Engine은 이슈 클러스터링, 코드에 대한 근본 원인 진단, 수정 생성, 검증할 평가 작성에 각각 그 역할에 맞게 조정된 서로 다른 모델을 사용해요. LangChain은 품질과 토큰 효율을 위해 이 모델들을 튜닝하고, 더 나은 모델을 사용할 수 있게 되면 업데이트해요.

Engine은 BYOK(자체 키 가져오기) 설정이 아닌 관리형 추론을 사용해요. 이렇게 하면 Engine 동작이 일관되게 유지되고 LangChain이 모델을 업데이트함에 따라 개선돼요. BYOK 설정에서는 모델 선택, 튜닝, 토큰 효율이 요청 간에 달라질 수 있어요.

Engine이 데이터를 처리하는 곳

셀프 호스팅 배포에서 Engine은 환경과 LangChain 사이에서 데이터 처리를 분리해요:

환경: Engine 오케스트레이션과 LangSmith에 저장된 트레이스는 셀프 호스팅 환경에 남아요.
LangChain 환경: LSI와 모델 프로바이더가 Engine이 보내는 콘텐츠를 처리해요. LSI는 위에서 설명한 청구 메타데이터를 유지해요.

배포와 무관한 Engine의 데이터 처리(모든 모델 프로바이더와의 기록 보존 없음, 모델 학습/파인튜닝에 고객 데이터 미사용 포함)는 Engine 보안에 설명돼 있어요.

Engine 설치

Engine은 기본적으로 비활성화돼 있어요. Sandboxes, LangSmith Intelligence 연결, 외부에서 도달 가능한 config.hostname, Engine 암호화 키가 필요해요. Engine을 활성화하기 전에 사전 요구 사항을 완료하세요.

Engine과 Insights는 같은 이미지에서 실행되고 하나의 배포를 공유해요. Engine에는 Insights가 필요하지 않아요. 설치가 이미 Insights를 실행 중이라면, Engine 활성화는 새 팟 대신 구성을 추가해요.

구성 요소

Engine을 활성화하면 다음을 프로비저닝하거나 재사용해요:

standalone-insights-api-server: engine 및 insights 그래프를 모두 서빙.
standalone-insights-queue: Engine 및 Insights용 백그라운드 런 처리.
공유 배포용 전용 PostgreSQL 및 Redis 인스턴스. 각각 외부 인스턴스로 교체 가능.
Sandboxes 활성화에 설명된 샌드박스 구성 요소.

Engine은 또한 런을 디스패치하고 스케줄링하는 platform-backend와 ingest-queue에 구성을 추가해요.

사전 요구 사항

Sandboxes 활성화: 먼저 Sandboxes 활성화를 완료하세요. KVM 지원 노드 풀과 JuiceFS 스토리지를 포함해요.

Engine의 샌드박스는 하나의 워크스페이스와 연결돼요. Engine이 있는 설치는 공유 조직이 있어야 해요. 공유 조직에 워크스페이스가 정확히 하나 있으면 LangSmith가 그 워크스페이스를 사용해요. 공유 조직에 워크스페이스가 둘 이상 있으면 LangSmith는 자동으로 선택하지 않아요. engine.sandboxTenantId를 워크스페이스 ID로 설정해야 해요.
Engine 전용으로 예약된 워크스페이스를 사용하세요:
- Engine은 자체 사용량을 LCU로 계량하므로 Engine의 샌드박스는 Sandboxes 제품으로 청구되지 않아요.
- Engine의 샌드박스는 워크스페이스의 다른 샌드박스와 동일한 동시 샌드박스, CPU, 메모리 할당량을 사용해요. 워크스페이스가 한도에 가까우면 Engine 런이 실패하거나 인터랙티브 샌드박스에 더 적은 용량을 남길 수 있어요.
- Engine의 샌드박스는 그 워크스페이스에 나열되며 접근 권한이 있는 사람이 중지할 수 있어요.
- 각 샌드박스는 에이전트가 생성한 코드를 실행해요.
- 저장소 자격 증명은 샌드박스 인증 프록시에 유지되며 샌드박스 내부에서 실행되는 코드에는 사용할 수 없어요.
라이선스 엔타이틀먼트 확인: Engine은 Sandboxes와 같은 방식으로 별도로 라이선스가 부여돼요. 라이선스에 Engine 엔타이틀먼트가 있어야 해요. LangSmith는 시작 시와 이후 주기적으로 https://beacon.langchain.com에 대해 라이선스 키를 검증하므로, 엔타이틀먼트가 주문에 추가되면 구성을 변경하지 않아도 적용돼요.
LangSmith Intelligence로 egress 허용: 클러스터에서 클라우드의 LangSmith Intelligence 게이트웨이 URL로의 아웃바운드 HTTPS를 허용하세요. 이 URL을 engine.intelligenceBaseUrl의 값으로 사용하세요.

클라우드 engine.intelligenceBaseUrl

AWS https://beacon.aws.langchain.com/intelligence

GCP https://beacon.langchain.com/intelligence

GCP에서 이것은 LangSmith가 라이선스 검증 및 청구 텔레메트리에 이미 사용하는 것과 같은 호스트를 사용하므로, Engine은 새 egress 대상을 추가하는 대신 경로를 추가해요.

Engine은 AWS US 및 GCP US의 셀프 호스팅 배포에서 사용할 수 있어요. 클라우드 및 지역별 가용성을 확인하고 롤아웃을 계획하기 전에 영업 팀과 커버리지를 확인하세요.

일반 egress를 여는 대신 게이트웨이를 특정 허용 목록 항목으로 추가하세요. AWS 트래픽을 프라이빗 네트워킹으로 유지하려면 AWS PrivateLink로 LangSmith Intelligence 연결을 참고하세요. 요청은 LangSmith 라이선스 검증 중 얻은 단기 라이선스 JWT를 사용해요. Engine의 트래픽은 호스트를 공유하는 경우에도 egress 구성에 설명된 청구 및 운영 텔레메트리와 분리돼 있어요.

오프라인(에어 갭) 설치는 Engine을 실행할 수 없어요. 폴백할 수 있는 클러스터 내 모델이 없어요.
호스트 이름이 외부에서 도달 가능한지 확인: Engine의 샌드박스는 langsmith CLI를 사용해 LangSmith 설치를 호출하므로, config.hostname이 샌드박스 네트워크에서 도달 가능해야 해요. Helm 검증은 localhost와 클러스터 내 *.svc 주소를 거부해요.

ingress 설정에 설명된 대로 TLS로 인그레스를 통해 그 호스트 이름을 서빙하세요. Engine은 자체 사용자가 이미 도달하는 주소 이상을 노출하도록 요구하지 않아요. 샌드박스 egress는 LangSmith 호스트 이름, github.com, api.github.com, Python 패키지 레지스트리로 허용 목록이 지정돼요. 런별 자격 증명은 샌드박스 내부에서 읽을 수 있는 대신 샌드박스 외부의 프록시가 주입해요.
Engine 암호화 키 생성: Engine은 단기 자격 증명을 담을 수 있는, LangSmith가 전달하는 런 페이로드를 암호화하기 위해 자체 Fernet 키를 사용해요. 하나 생성하세요:
```
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
```
구성 파일이 아닌 미리 정의된 Kubernetes Secret에 engine_encryption_key로 저장하세요. 기존 시크릿 사용을 참고하세요.

나중에 키를 교체하려면 현재 값을 engine_encryption_key_previous에 복사하고 새 키를 engine_encryption_key로 설정하세요. 이전 키는 복호화에만 허용되므로, 교체 직전에 암호화된 런도 완료돼요.

클라우드	`engine.intelligenceBaseUrl`
AWS	`https://beacon.aws.langchain.com/intelligence`
GCP	`https://beacon.langchain.com/intelligence`

Helm으로 활성화

Sandboxes 활성화의 전체 Sandboxes 값과 함께 langsmith_config.yaml에 다음을 추가하세요. 이 예시들은 Engine 전용 값과 sandboxes.enabled 플래그만 보여줘요.

Kubernetes 시크릿 사용 (권장)

이름으로 기존 Secret을 참조하세요. 차트는 그로부터 engine_encryption_key를 자동으로 읽어요.

config:
  existingSecretName: "<your-secret-name>"
  # Must be reachable from the sandbox network.
  hostname: "https://langsmith.example.com"

engine:
  enabled: true
  intelligenceBaseUrl: "https://beacon.aws.langchain.com/intelligence"

sandboxes:
  enabled: true

인라인 값 사용

구성 파일에 암호화 키를 직접 설정하세요.

이렇게 하면 라이브 자격 증명이 구성 파일에 들어가요. 버전 관리에 커밋하지 마세요. Kubernetes Secret을 선호하세요.

config:
  hostname: "https://langsmith.example.com"

engine:
  enabled: true
  intelligenceBaseUrl: "https://beacon.aws.langchain.com/intelligence"
  encryptionKey: "<engine-encryption-key>"

sandboxes:
  enabled: true

설치에 워크스페이스가 둘 이상인 공유 조직이 있으면 Engine의 샌드박스를 소유한 워크스페이스를 설정하세요:

engine:
  sandboxTenantId: "<workspace-id>"

이전 Insights 이미지 핀에서 업그레이드하려면 추가 확인이 하나 필요해요: 값이 images.engineInsightsAgentImage.repository를 폐지된 langsmith-clio 이미지로 고정했다면 해당 핀을 제거하거나 업데이트하세요. Engine과 Insights는 이제 langsmith-insights-engine에서 실행되며, 차트는 langsmith-clio를 거부해요. 자세한 내용은 LangSmith 설치용 이미지 미러링을 참고하세요.

적용하기 전에 업데이트된 차트를 검증하세요:

helm template langsmith langchain/langsmith \
  --values langsmith_config.yaml \
  --version <version> \
  --namespace <namespace>

차트는 렌더링 시점에 Engine 구성을 검증하고 누락된 값을 명명하는 메시지와 함께 실패하므로, 이 명령은 오설정이 클러스터에 도달하기 전에 잡아줘요.

업데이트된 차트를 적용하세요:

helm upgrade -i langsmith langchain/langsmith \
  --values langsmith_config.yaml \
  --version <version> \
  --namespace <namespace> \
  --wait

설치 검증

공유 Engine 및 Insights 배포가 실행 중인지 확인하세요:

kubectl get pods -n <namespace> | grep standalone-insights

API 서버와 큐 팟 모두 Running 상태여야 해요. 그런 다음 Engine 런을 디스패치하므로 platform-backend가 정상인지 확인하세요:

kubectl rollout status deployment/langsmith-platform-backend -n <namespace>

이후 LangSmith UI에 Engine이 나타나지 않으면 가장 흔한 원인은 Engine 엔타이틀먼트가 없는 라이선스와 LangSmith에서 Engine 켜기에 설명된 조직 수준 토글입니다.

LangSmith UI에서 Engine을 활성화하고 구성한 후 Engine 분석을 시작하고 추적 프로젝트에 결과가 나타나는지 확인하세요. 이렇게 하면 Engine, Sandboxes, LangSmith Intelligence를 통한 전체 경로가 검증돼요. 팟이 실행되고 있는 것만으로는 그 경로를 검증하지 못해요.

분석이 완료되지 않으면 Engine 팟이 실행 중인지, 샌드박스 워크스페이스에 사용 가능한 할당량이 있는지, 클러스터가 engine.intelligenceBaseUrl에 구성된 LangSmith Intelligence 게이트웨이 URL에 도달할 수 있는지 확인하세요.

LangSmith에서 Engine 켜기

Helm에서 Engine을 활성화하면 기능을 사용 가능하게 만들 뿐 스캔을 시작하지 않아요. 차트 값을 활성화한 후 LangSmith에서 설정을 완료하세요:

조직 관리자가 Settings > Engine enablement 아래에서 조직에 Engine을 켜요. 자세한 내용은 이슈 찾기 및 수정을 참고하세요.
모든 사용자가 프로젝트의 Engine 탭에서 추적 프로젝트에 Engine을 설정해요. 자세한 내용은 추적 프로젝트에 Engine 설정을 참고하세요.

GitHub 저장소 연결은 선택 사항이며 Engine의 진단과 수정을 개선해요. 연결이 없으면 Engine은 소스 코드를 읽거나 풀 리퀘스트를 열 수 없어요. GitHub App을 만들고 host-backend를 구성하려면 Engine을 GitHub에 연결을 참고하세요.

Engine 비활성화

engine.enabled를 false로 설정하고 다시 적용하세요:

engine:
  enabled: false

Engine이 런 디스패치를 중지해요. Insights는 같은 배포를 공유하므로, insights.enabled가 true이면 standalone-insights 팟은 계속 실행돼요.

셀프 호스팅의 LangSmith Engine