Kubernetes에서 LangSmith 셀프 호스팅

Kubernetes에서 LangSmith 셀프 호스팅

Kubernetes 클러스터에서 LangSmith(관측성, 트레이싱, 평가)를 설정하는 방법을 알려드릴게요. Helm을 사용해 LangSmith와 그 의존성을 설치합니다.

정보: LangSmith 셀프 호스팅은 가장 크고 보안에 민감한 고객을 위해 설계된 Enterprise Plan의 애드온입니다. 자세한 내용은 가격 페이지를 참고하고, 사용자 환경에서 LangSmith를 시험해 볼 라이선스 키를 원한다면 영업팀에 문의하세요.

이 페이지를 완료하면 다음을 갖게 됩니다:

  • LangSmith UI 및 API: 관측성, 트레이싱, 평가용.
  • 백엔드 서비스: (queue, playground, ACE).
  • 데이터 저장소: (PostgreSQL, Redis, ClickHouse, 선택적 blob storage).

에이전트 배포의 경우: 배포 기능을 추가하려면 먼저 이 가이드를 완료한 뒤 LangSmith Deployment 활성화를 따르세요.

LangChain은 다음 Kubernetes 배포판에서 LangSmith를 성공적으로 테스트했습니다:

  • Google Kubernetes Engine (GKE)
  • Amazon Elastic Kubernetes Service (EKS): 아키텍처 패턴과 모범 사례는 AWS 셀프 호스팅을 참고하세요.
  • Azure Kubernetes Service (AKS): 아키텍처 패턴과 모범 사례는 AKS 셀프 호스팅을 참고하세요.
  • OpenShift (4.14+)
  • Minikube와 Kind (개발 목적)

팁: IaC(Infrastructure as Code)를 선호하시나요? Terraform으로 배포하면 AWS, Azure, GCP용 클러스터 프로비저닝, 시크릿 연결, Helm 릴리스를 하나의 워크플로로 묶습니다. 아래 페이지는 이미 관리하는 모든 인증 클러스터에 대한 Helm 전용 경로를 다룹니다.

출처: 문서

본문

사전 요구사항

다음 도구/항목을 준비하세요. 일부는 선택 사항으로 표시됩니다:

  1. LangSmith 라이선스 키
    1. LangChain 담당자에게 받을 수 있습니다. 자세한 내용은 영업팀에 문의하세요.
  2. Api Key Salt
    1. 직접 생성할 수 있는 시크릿 키입니다. 무작위 문자열이어야 합니다.
    2. 다음 명령으로 생성할 수 있습니다:
    openssl rand -base64 32
  3. JWT Secret (선택 사항이지만 기본 인증에 사용)
    1. 직접 생성할 수 있는 시크릿 키입니다. 무작위 문자열이어야 합니다.
    2. 다음 명령으로 생성할 수 있습니다:
    openssl rand -base64 32

데이터베이스

LangSmith는 트레이스를 저장하기 위해 PostgreSQL 데이터베이스, Redis 캐시, ClickHouse 데이터베이스를 사용합니다. 기본적으로 이 서비스들은 Kubernetes 클러스터 내부에 설치됩니다. 하지만 외부 데이터베이스를 사용하는 것을 적극 권장합니다. PostgreSQL과 Redis의 최선의 선택은 클라우드 프로바이더의 관리 서비스입니다.

자세한 내용은 외부 서비스 설정 가이드를 참고하세요:

각 데이터 저장소의 최소 지원 버전은 셀프 호스팅 의존성 최소 버전을 참고하세요.

Kubernetes 클러스터 요구사항

  1. kubectl로 접근할 수 있는 동작하는 Kubernetes 클러스터가 필요합니다. 클러스터는 다음 최소 요구사항을 충족해야 합니다:
    1. 권장: 최소 16 vCPU, 64GB 메모리 사용 가능
      • 조직 규모/사용량에 따라 모든 서비스에 대한 리소스 requests/limits를 조정해야 할 수 있습니다. 권장사항은 셀프 호스트 스케일 가이드에서 찾을 수 있습니다.
      • 리소스 사용량에 따라 노드 스케일 업/다운을 처리하려면 클러스터 오토스케일러 사용을 권장합니다.
      • 오토스케일링을 켤 수 있도록 메트릭스 서버를 설정하는 것을 권장합니다.
      • ClickHouse를 클러스터 내부에서 실행한다면 최소 4 vCPU와 16GB 메모리가 할당 가능한(allocatable) 노드가 있어야 합니다. ClickHouse는 기본적으로 이 양의 리소스를 요청하기 때문입니다.
    2. 클러스터에서 유효한 동적 PV provisioner 또는 사용 가능한 PV (클러스터 내부에서 데이터베이스를 실행하는 경우에만 필요)
      • 영속성을 활성화하기 위해 클러스터 내부에서 실행되는 모든 데이터베이스에 볼륨을 프로비저닝하려고 시도합니다.
      • 클러스터에서 PV를 사용하는 경우 프로덕션 환경에서 백업을 설정하는 것을 적극 권장합니다.
      • 더 나은 성능을 위해 SSD로 지원되는 스토리지 클래스 사용을 강력히 권장합니다. 7000 IOPS와 1000 MiB/s 처리량을 권장합니다.
      • EKS에서는 동적 프로비저닝을 위해 ebs-csi-driver가 설치·구성되어 있는지 확인해야 할 수 있습니다. 자세한 내용은 EBS CSI Driver 문서를 참고하세요. 다음으로 확인할 수 있습니다:
      kubectl get storageclass
      출력에는 동적 프로비저닝을 지원하는 provisioner가 있는 스토리지 클래스가 최소 하나 이상 있어야 합니다. 예: 
      NAME            PROVISIONER                 RECLAIMPOLICY   VOLUMEBINDINGMODE      ALLOWVOLUMEEXPANSION   AGE
gp2 (default)   ebs.csi.eks.amazonaws.com   Delete          WaitForFirstConsumer   true                   161d

      참고: 볼륨 확장을 지원하는 스토리지 클래스 사용을 적극 권장합니다. 트레이스는 많은 디스크 공간을 요구할 수 있고 볼륨을 시간이 지나며 크기를 조정해야 할 수 있기 때문입니다. 스토리지 클래스에 대한 자세한 내용은 Kubernetes 문서를 참고하세요.

  2. Helm
    1. helm을 설치하려면 Helm 문서를 참고하세요.
  3. https://beacon.langchain.com으로의 Egress (오프라인 모드가 아닌 경우)
    1. LangSmith는 라이선스 검증과 사용량 보고를 위해 https://beacon.langchain.com으로의 egress가 필요합니다. LangSmith가 제대로 동작하려면 필수입니다. egress 요구사항에 대한 자세한 내용은 Egress 섹션을 참고하세요.

참고: LangSmith 서비스는 0.14.0부터 기본적으로 IPv4와 IPv6 모두에서 수신 대기합니다. IPv4 전용, IPv6 전용, 이중 스택 클러스터 모두 추가 구성이 필요 없습니다.

Helm 차트 구성하기

  1. 이전 단계의 구성 옵션으로 langsmith_config.yaml이라는 새 파일을 만듭니다.
    1. langsmith_config.yaml 파일에 설정할 수 있는 여러 구성 옵션이 있습니다. 특정 구성 옵션에 대한 자세한 내용은 Configuration 섹션을 참고하세요.
    2. Kubernetes나 Helm이 처음이라면 Helm Chart 저장소의 examples 디렉터리에 있는 예제 구성 중 하나로 시작하는 것을 권장합니다: LangSmith helm chart examples.
    3. Helm Chart 저장소의 values.yaml 파일에서 전체 구성 옵션 목록을 볼 수 있습니다: LangSmith Helm Chart

경고: langsmith_config.yaml에 필요한 설정만 재정의하세요. 전체 values.yaml을 복사하지 마세요. 구성을 최소로 유지해야 Helm 차트의 새 기본값과 업그레이드를 계속 상속받을 수 있습니다.

팁: 클러스터가 non-root 또는 읽기 전용 컨테이너 정책을 강제한다면 read-only Helm 구성 예제로 시작하세요. LangSmith 컨테이너는 루트 권한이 필요하지 않습니다. 예제는 runAsNonRoot, 서비스 UID/GID, fsGroup, RuntimeDefault seccomp 프로필, 드롭된 capabilities, 비활성화된 권한 승격, 임시 저장소가 필요한 서비스용 쓰기 가능 emptyDir 마운트를 설정하는 방법을 보여줍니다.

  1. 최소한 다음 구성 옵션을 설정해야 합니다 (기본 인증 사용):

    경고: apiKeySalt를 한 번 설정하고 변경하지 마세요. 이 값은 모든 API 키를 저장 시 해시하는 데 사용됩니다. 이를 회전시키면 조직의 모든 기존 API 키가 영구적으로 무효화되어 모든 사용자가 키를 다시 생성해야 합니다.

    config:
  langsmithLicenseKey: "<your license key>"
  apiKeySalt: "<your api key salt>"
  authType: mixed
  basicAuth:
    enabled: true
    initialOrgAdminEmail: "[email protected]" # Change this to your admin email address
    initialOrgAdminPassword: "secure-password" # Must be at least 12 characters long and have at least one lowercase, uppercase, and symbol
    jwtSecret: <your jwt salt> # A random string of characters used to sign JWT tokens for basic auth.

insights:
  enabled: true
  encryptionKey: "<insights-encryption-key>"

polly:
  enabled: true
  encryptionKey: "<chat-encryption-key>"
    Insights(AI 기반 트레이스 분석)와 Polly(워크스페이스 내 채팅)는 최근 차트 버전에서 기본으로 활성화되며 설치 시점에 암호화 키가 필요합니다. openssl rand -hex 32 같은 명령으로 각 키를 생성하세요.

사용하는 외부 데이터베이스의 연결 세부정보도 지정해야 합니다.

Kubernetes에 배포하기

  1. Kubernetes 클러스터에 연결할 수 있는지 확인합니다 (빈 네임스페이스에 설치하는 것을 강력히 권장합니다).
    1. kubectl get pods 실행 출력은 다음과 비슷해야 합니다: 
        langsmith-eks-2vauP7wf 21:07:46 No resources found in default namespace.

    참고: 기본 네임스페이스 외의 네임스페이스를 사용한다면 -n <namespace> 플래그로 helm과 kubectl 명령에서 네임스페이스를 지정해야 합니다.

  2. LangChain Helm 저장소가 추가되었는지 확인합니다 (로컬 차트를 사용한다면 이 단계 건너뛰기). 
    helm repo add langchain https://langchain-ai.github.io/helm
  3. 차트의 최신 버전을 찾습니다. 사용 가능한 버전은 Helm Chart 저장소에서 찾을 수 있습니다.
    • 일반적으로 최신 버전 사용을 권장합니다.
    • helm search repo langchain/langsmith --versions로 사용 가능한 버전을 볼 수도 있습니다. 출력은 다음과 비슷합니다:
     langchain/langsmith             	0.13.0     	0.13.1   	Helm chart to deploy the langsmith application ...
 langchain/langsmith             	0.12.34     	0.12.73   	Helm chart to deploy the langsmith application ...
 langchain/langsmith             	0.12.33     	0.12.72   	Helm chart to deploy the langsmith application ...
 langchain/langsmith             	0.12.32     	0.12.70   	Helm chart to deploy the langsmith application ...
 langchain/langsmith             	0.12.31     	0.12.69   	Helm chart to deploy the langsmith application ...
  4. helm upgrade -i langsmith langchain/langsmith --values langsmith_config.yaml --version <version> -n <namespace> --wait --debug 실행
    • <namespace>를 LangSmith를 배포할 네임스페이스로 바꿉니다.
    • <version>을 이전 단계에서 설치할 LangSmith 버전으로 바꿉니다. 대부분의 사용자는 사용 가능한 최신 버전을 설치해야 합니다.

    참고: -n <namespace>로 지정한 네임스페이스는 이 명령을 실행하기 전에 이미 존재해야 합니다. 존재하지 않으면 kubectl create namespace <namespace>로 먼저 만들거나 위 helm 명령에 --create-namespace 플래그를 추가하세요. helm install 명령이 성공적으로 실행되고 끝나면 다음과 비슷한 출력이 표시됩니다:

    NAME: langsmith
LAST DEPLOYED: Fri Sep 17 21:08:47 2021
NAMESPACE: langsmith
STATUS: deployed
REVISION: 1
TEST SUITE: None
    여러 Kubernetes 리소스를 만들고 데이터베이스와 다른 서비스를 초기화하기 위한 여러 작업을 실행하므로 몇 분이 걸릴 수 있습니다.
  5. kubectl get pods 실행. 출력은 이제 다음과 비슷해야 합니다 (정확한 pod 이름은 버전과 구성에 따라 다를 수 있습니다): 
     langsmith-ace-backend-98fbd468c-x9gjl         1/1     Running   0
 langsmith-backend-84999bbcb7-dfhml            1/1     Running   0
 langsmith-clickhouse-0                        1/1     Running   0
 langsmith-frontend-79bdcbccc6-r7pt7           1/1     Running   0
 langsmith-ingest-queue-cbb67748-8rl8x         1/1     Running   0
 langsmith-platform-backend-586bd9d97c-2g5mv   1/1     Running   0
 langsmith-playground-859d44b46c-fjqjh         1/1     Running   0
 langsmith-postgres-0                          1/1     Running   0
 langsmith-queue-7bd6cb8b9b-bmvxm              1/1     Running   0
 langsmith-redis-0                             1/1     Running   0

배포 검증하기

  1. kubectl get services 실행 출력은 다음과 비슷해야 합니다: 
     NAME                         TYPE           CLUSTER-IP       EXTERNAL-IP                                                                   PORT(S)                      AGE
 langsmith-ace-backend        ClusterIP      172.20.92.210    <none>                                                                        1987/TCP                     1m
 langsmith-backend            ClusterIP      172.20.156.146   <none>                                                                        1984/TCP                     1m
 langsmith-clickhouse         ClusterIP      172.20.250.160   <none>                                                                        8123/TCP,9000/TCP,9363/TCP   1m
 langsmith-frontend           LoadBalancer   172.20.18.173    <external-ip>                                                                 80:30879/TCP,443:31364/TCP   1m
 langsmith-platform-backend   ClusterIP      172.20.95.187    <none>                                                                        1986/TCP                     1m
 langsmith-playground         ClusterIP      172.20.142.121   <none>                                                                        1988/TCP                     1m
 langsmith-postgres           ClusterIP      172.20.226.128   <none>                                                                        5432/TCP                     1m
 langsmith-redis              ClusterIP      172.20.57.248    <none>                                                                        6379/TCP                     1m
  2. langsmith-frontend 서비스의 외부 IP를 curl로 확인합니다: 
    curl <external ip>/api/tenants
    예상 출력: 
    [{"id":"00000000-0000-0000-0000-000000000000","has_waitlist_access":true,"created_at":"2023-09-13T18:25:10.488407","display_name":"Personal","config":{"is_personal":true,"max_identities":1},"tenant_handle":"default"}]
  3. 브라우저에서 langsmith-frontend 서비스의 외부 IP를 방문합니다. LangSmith UI가 표시되고 동작해야 합니다.

LangSmith 사용하기

이제 LangSmith가 실행 중이므로 코드를 트레이싱하는 데 사용하기 시작할 수 있습니다. 셀프 호스팅 LangSmith 사용 방법에 대한 자세한 내용은 셀프 호스팅 사용 가이드를 참고하세요.

LangSmith 인스턴스는 이제 실행 중이지만 완전히 설정되지는 않았을 수 있습니다.

기본 구성 중 하나를 사용했다면 기본 관리자 사용자 계정이 생성되어 langsmith_config.yaml 파일에 지정한 이메일 주소와 비밀번호로 로그인할 수 있습니다.

다음 단계로 인프라 관리자와 함께 다음을 진행하는 것을 강력히 권장합니다:

  • 더 쉬운 접근을 위해 LangSmith 인스턴스에 대한 DNS 설정
  • LangSmith에 제출된 트레이스의 전송 중 암호화를 보장하기 위한 SSL 구성
  • LangSmith 인스턴스 보안을 위한 Single Sign-On 구성
  • LangSmith를 외부 Postgres 및 Redis 인스턴스에 연결
  • 대용량 파일 저장을 위한 Blob Storage 설정

이 옵션들을 구성하는 방법에 대한 자세한 내용은 구성 섹션을 검토하세요.

LangSmith Deployment, Fleet, Insights, Chat, Sandboxes 활성화하기

관측성, 트레이싱, 평가를 넘어 셀프 호스팅 인스턴스에서 다음 기능을 활성화할 수 있습니다:

  • LangSmith Deployment: LangSmith UI를 통해 에이전트를 배포·스케일·관리.
  • Fleet: 코드를 작성하지 않고 AI 에이전트 생성·관리.
  • Insights: 트레이스와 애플리케이션 데이터에 대한 AI 기반 분석.
  • Chat: 트레이스, 스레드, 프롬프트, 실험 결과를 분석하는 데 도움을 주는 LangSmith 전반의 워크스페이스 내 채팅 경험.
  • Sandboxes: LangSmith에서 코드 실행, 임시 서비스 노출, 메모리 스냅샷 생성.

이 구성요소들을 설정하려면 추가 기능 활성화 가이드를 따르세요.

더 알아보기