설정 가이드

설정 가이드 (레거시 hybrid)

LangChain 관리형 제어 플레인과 자체 관리 데이터 플레인으로 구성된 레거시 하이브리드 배포 모델이에요.

경고: 이 페이지는 LangChain 관리형 제어 플레인이 클라우드의 에이전트 서버를 오케스트레이션하는 레거시 하이브리드 배포 모델을 설명해요. 현재 하이브리드 모델은 하이브리드를 참조해요.

참고: 하이브리드 옵션은 Enterprise 플랜이 필요해요. 자세한 내용은 데모 신청을 통해 알아보세요.

hybrid 모델은 LangSmith 인프라를 LangChain의 클라우드와 자체 클라우드로 나눠요:

  • 제어 플레인 (Control plane) (LangSmith UI, API, 오케스트레이션)은 LangChain의 클라우드에서 실행되며 LangChain이 관리해요.
  • 데이터 플레인 (Data plane) (에이전트 서버 및 에이전트 워크로드)은 자체 클라우드에서 실행되며 사용자가 관리해요.

이것은 관리형 인터페이스의 편의성과 자체 환경에서 워크로드를 실행하는 유연성을 결합해요.

참고: 제어 플레인, 데이터 플레인, 에이전트 서버 아키텍처 개념에 대해 자세히 알아보세요.

컴포넌트 책임 실행 위치 관리 주체
<제어 플레인(Control plane)>
  • 배포 및 리비전 생성을 위한 UI
  • 배포 관리를 위한 API
  • 관측 가능성 데이터 저장
 LangChain의 클라우드 LangChain
<데이터 플레인(Data plane)>
  • 배포를 조정하는 Operator/listener
  • 에이전트 서버 (에이전트/그래프)
  • 백킹 서비스 (Postgres, Redis 등)
 자체 클라우드 사용자

하이브리드 모델로 LangSmith를 실행할 때는 LangSmith API 키로 인증해요.

워크플로

  1. langgraph-cli 또는 Studio를 사용해 그래프를 로컬에서 테스트해요.
  2. langgraph build 명령으로 Docker 이미지를 빌드해요.
  3. 제어 플레인 UI에서 에이전트 서버를 배포해요.

참고: 지원되는 컴퓨트 플랫폼: Kubernetes. 아래 Kubernetes 설정을 참조해요.

아키텍처

Hybrid deployment: LangChain-hosted control plane (LangSmith UI/APIs) manages deployments. Your cloud runs a listener, Agent Server instances, and backing stores (Postgres/Redis) on Kubernetes. Hybrid deployment: LangChain-hosted control plane (LangSmith UI/APIs) manages deployments. Your cloud runs a listener, Agent Server instances, and backing stores (Postgres/Redis) on Kubernetes.

컴퓨트 플랫폼

  • Kubernetes: Hybrid는 모든 Kubernetes 클러스터에서 데이터 플레인 실행을 지원해요.

팁: Kubernetes 설정은 아래 Kubernetes 설정을 참조해요.

LangSmith 및 제어 플레인으로의 이그레스

하이브리드 배포 모델에서 자체 호스팅 데이터 플레인은 제어 플레인에 네트워크 요청을 보내 데이터 플레인에 구현해야 할 변경 사항을 폴링해요. 데이터 플레인 배포의 트레이스도 제어 플레인과 통합된 LangSmith 인스턴스로 전송돼요. 제어 플레인으로의 이 트래픽은 HTTPS를 통해 암호화돼요. 데이터 플레인은 LangSmith API 키로 제어 플레인에 인증해요.

이 이그레스를 활성화하려면 내부 방화벽 규칙이나 클라우드 리소스(예: Security Groups)를 업데이트해 특정 IP 주소를 허용해야 할 수 있어요.

경고: AWS/Azure PrivateLink 또는 GCP Private Service Connect는 현재 지원되지 않아요. 이 트래픽은 인터넷을 통해 이동해요.

출처: 문서

본문

Kubernetes 설정

다음 단계는 자체 호스팅 데이터 플레인을 관리형 LangSmith 제어 플레인에 연결하는 방법을 설명해요.

사전 요구사항

  1. 클러스터에 KEDA가 설치되어 있어야 해요.

      helm repo add kedacore https://kedacore.github.io/charts
  helm install keda kedacore/keda --namespace keda --create-namespace

    참고: KEDA는 큐 크기에 따라 배포 시스템을 자동 확장하는 데 사용돼요.

  2. 유효한 Ingress 컨트롤러가 클러스터에 설치되어 있어야 해요. 배포용 인그레스 구성에 대한 자세한 내용은 설치를 위한 인그레스 생성을 참조해요. 프로덕션 설정에서는 현대적인 Gateway API를 사용하는 것을 적극 권장해요.

  3. 리스너가 여러 네임스페이스를 관찰하도록 계획하고 있다면, 표준 인그레스 대신 Gateway API 또는 Istio Gateway를 사용해야 해요. 표준 인그레스 리소스는 같은 네임스페이스의 서비스로만 트래픽을 라우팅할 수 있는 반면, Gateway나 Istio Gateway는 여러 네임스페이스의 서비스로 트래픽을 라우팅할 수 있어요.

  4. 클러스터에 여러 배포를 위한 여유 공간이 있어야 해요. 새 노드를 자동으로 프로비저닝하려면 Cluster-Autoscaler를 권장해요.

  5. 두 개의 제어 플레인 URL로 이그레스를 활성화해야 해요. 리스너는 이러한 엔드포인트를 폴링해 배포를 확인해요. LangSmith 리전과 일치하는 쌍을 사용해요.

LangSmith Deployment 제어 플레인:

Region URL
GCP US https://api.smith.langchain.com
GCP EU https://eu.api.smith.langchain.com
GCP APAC https://apac.api.smith.langchain.com
AWS US https://aws.api.smith.langchain.com

LangSmith API:

Region URL
GCP US https://api.smith.langchain.com
GCP EU https://eu.api.smith.langchain.com
GCP APAC https://apac.api.smith.langchain.com
AWS US https://aws.api.smith.langchain.com

설정

  1. LangSmith 조직 ID를 제공해요. LangSmith 조직은 자체 클라우드에 데이터 플레인을 배포하도록 구성돼요.

  2. LangSmith UI에서 리스너를 생성해요. Listener 데이터 모델은 실제 "listener" 애플리케이션에 대해 구성돼요.

    1. 왼쪽 내비게이션에서 Deployments > Listeners를 선택해요.
    2. 페이지 오른쪽 상단에서 + Create Listener를 선택해요.
    3. 리스너에 대한 고유 Compute ID를 입력해요. Compute ID는 현재 LangSmith 워크스페이스의 모든 리스너에 걸쳐 고유해야 하는 사용자 정의 식별자예요. Compute ID는 사용자가 새 배포를 만들 때 최종 사용자에게 표시돼요. Compute ID가 에이전트 서버 배포가 배포될 위치에 대한 컨텍스트를 최종 사용자에게 제공하는지 확인해요. 예를 들어 Compute ID를 k8s-cluster-name-dev-01로 설정할 수 있어요. 이 예시에서 Kubernetes 클러스터 이름은 k8s-cluster-name, dev는 "development" 워크로드용으로 예약된 클러스터임을 나타내며, 01은 이름 충돌을 줄이는 숫자 접미사예요.
    4. 하나 이상의 Kubernetes 네임스페이스를 입력해요. 나중에 "listener" 애플리케이션이 각 네임스페이스에 배포하도록 구성돼요.
    5. 페이지 오른쪽 상단에서 Submit을 선택해요.
    6. 리스너 생성 후 리스너 ID를 복사해요. 나중에 Kubernetes 클러스터에 실제 "listener" 애플리케이션을 설치할 때 사용해요(5단계).

    참고: 중요 — LangSmith UI에서 리스너를 생성해도 Kubernetes 클러스터에 "listener" 애플리케이션이 설치되지는 않아요.

  3. Kubernetes 클러스터에 필요한 컴포넌트를 설치하기 위해 Helm 차트가 제공돼요.

    • langgraph-dataplane-listener: 배포 변경을 위해 LangChain의 제어 플레인을 수신하고 다운스트림 CRD를 생성/업데이트하는 서비스예요. 이는 "listener" 애플리케이션이에요.
    • LangGraphPlatform CRD: LangSmith Deployment를 위한 CRD. LangSmith Deployment 인스턴스 관리를 위한 스펙을 담아요.
    • langgraph-dataplane-operator: LangSmith CRD의 변경을 처리하는 연산자.
    • langgraph-dataplane-redis: langgraph-dataplane-listener가 다양한 작업(주로 배포 생성 및 삭제)을 관리하는 데 사용하는 Redis 인스턴스.

  4. langgraph-dataplane-values.yaml 파일을 구성해요.

      config:
    langsmithApiKey: *** # API Key of your Workspace
    langsmithWorkspaceId: "" # Workspace ID
    hostBackendUrl: "https://api.host.langchain.com" # Use the matching regional LangSmith Deployment control plane URL from the table above
    smithBackendUrl: "https://api.smith.langchain.com" # Use the matching regional LangSmith API URL from the table above
    langgraphListenerId: "" # Listener ID from Step 2f
    watchNamespaces: "" # comma-separated list of Kubernetes namespaces that the listener and operator will deploy to
    enableLGPDeploymentHealthCheck: true # enable/disable health check step for deployments

  ingress:
    hostname: "" # specify a hostname that will be configured for all deployments

  operator:
    enabled: true
    createCRDs: true # set this to `false` if the CRD has been previously installed in the current Kubernetes cluster
    • config.langsmithApiKey: langgraph-listener 배포는 langsmithApiKey로 LangChain의 LangGraph 제어 플레인 API에 인증해요.
    • config.langsmithWorkspaceId: langgraph-listener 배포는 LangSmith 워크스페이스의 에이전트 서버 배포에 결합돼요. 즉 langgraph-listener 배포는 지정된 LangSmith 워크스페이스 ID의 에이전트 서버 배포만 관리할 수 있어요.
    • config.langgraphListenerId: LangSmith 워크스페이스와 결합되는 것 외에도 langgraph-listener 배포는 리스너에도 결합돼요. 새 에이전트 서버 배포가 생성되면 자동으로 langgraphListenerId에 결합돼요. langgraphListenerId를 지정하면 langgraph-listener 배포가 langgraphListenerId에 결합된 에이전트 서버 배포만 관리할 수 있게 보장돼요.
    • config.watchNamespaces: langgraph-listener 배포가 배포할 Kubernetes 네임스페이스의 쉼표 구분 목록. 이 목록은 2d단계에서 지정한 네임스페이스 목록과 일치해야 해요.
    • config.enableLGPDeploymentHealthCheck: 에이전트 서버 헬스 체크를 비활성화하려면 false로 설정해요.
    • ingress.hostname: 배포 워크플로의 일부로 langgraph-listener 배포는 에이전트 서버 헬스 체크 엔드포인트(GET /ok)를 호출해 애플리케이션이 올바르게 시작됐는지 확인해요. 일반적인 설정은 에이전트 서버 배포용 공유 DNS 레코드 또는 도메인을 만드는 것이에요. 이는 LangSmith가 관리하지 않아요. 생성 후 ingress.hostname을 도메인으로 설정하면 헬스 체크를 완료하는 데 사용돼요.
    • operator.createCRDs: Kubernetes 클러스터에 이미 LangGraphPlatform CRD가 설치되어 있으면 이 값을 false로 설정해요. 설치 중에 CRD가 이미 설치되어 있으면 오류가 발생해요. 동일한 Kubernetes 클러스터에 여러 리스너가 배포된 경우 이 상황이 발생할 수 있어요.

  5. langgraph-dataplane Helm 차트를 배포해요.

      helm repo add langchain https://langchain-ai.github.io/helm/
  helm repo update
  helm upgrade -i langgraph-dataplane langchain/langgraph-dataplane --values langgraph-dataplane-values.yaml --wait --debug

  6. 성공하면 네임스페이스에서 세 개의 서비스가 시작되는 것을 볼 수 있어요.

      NAME                                            READY   STATUS              RESTARTS   AGE
  langgraph-dataplane-listener-6dd4749445-zjmr4   0/1     ContainerCreating   0          26s
  langgraph-dataplane-operator-6b88879f9b-t76gk   1/1     Running             0          26s
  langgraph-dataplane-redis-0                     1/1     Running             0          25s

    이제 하이브리드 인프라가 배포를 생성할 준비가 됐어요.

같은 클러스터에 추가 데이터 플레인 구성

같은 클러스터의 다른 네임스페이스에 데이터 플레인을 만들려면 위 단계를 반복하고 helm upgrade에 -n 옵션을 전달해 다른 네임스페이스를 지정해요.

같은 클러스터에 여러 데이터 플레인을 설치할 때 다음 규칙을 따르는 것이 매우 중요해요:

  1. config.watchNamespaces 목록은 다른 설치의 config.watchNamespaces와 절대 겹쳐서는 안 돼요. 예를 들어 설치 A가 foo,bar 네임스페이스를 관찰한다면 설치 B는 foo나 bar를 관찰할 수 없어요. 같은 네임스페이스를 관찰하는 여러 연산자나 리스너는 예기치 않은 동작을 유발해요. 즉 여러 LangSmith 워크스페이스가 같은 네임스페이스에 배포할 수 없어요! 이를 더 잘 이해하려면 클러스터 조직 섹션을 검토해요.
  2. Gateway API 또는 Istio Gateway를 사용해야 해요. 표준 인그레스 리소스에 의존하면 같은 클러스터의 다른 데이터 플레인이 만든 Ingress 객체와 충돌할 수 있어요. 이러한 경우의 동작은 특정 인그레스 컨트롤러에 따라 다르므로, 예측 불가능하거나 바람직하지 않은 결과가 초래될 수 있어요.

리스너

hybrid 옵션에서 LangSmith 워크스페이스와 Kubernetes 클러스터가 어떻게 구성되는지에 따라 하나 이상의 "listener" 애플리케이션이 실행될 수 있어요.

Kubernetes 클러스터 조직

  • 하나 이상의 리스너가 Kubernetes 클러스터에서 실행될 수 있어요.
  • 리스너는 해당 클러스터의 하나 이상의 네임스페이스에 배포할 수 있어요.
  • 여러 리스너가 같은 네임스페이스에 배포할 수 없어요.
  • 클러스터 소유자는 리스너 레이아웃과 에이전트 서버 배포를 계획할 책임이 있어요.

LangSmith 워크스페이스 조직

  • 워크스페이스는 하나 이상의 리스너와 연결될 수 있어요.
  • 리스너는 하나의 워크스페이스와만 연결될 수 있어요. LangSmith 워크스페이스 대 리스너는 일대다 관계예요.
  • 워크스페이스는 모든 리스너가 배포된 Kubernetes 클러스터에만 배포할 수 있어요.

사용 사례

일반적인 리스너 구성의 몇 가지 예시는 다음과 같아요(엄격한 요구사항은 아님):

각 LangSmith 워크스페이스 → 별도 Kubernetes 클러스터

  • 클러스터 alpha는 워크스페이스 A를 실행
  • 클러스터 beta는 워크스페이스 B를 실행

하나의 클러스터, 워크스페이스당 하나의 네임스페이스

  • 클러스터 alpha, 네임스페이스 1은 워크스페이스 A를 실행
  • 클러스터 alpha, 네임스페이스 2는 워크스페이스 B를 실행

별도 클러스터, 공유 "dev" 클러스터

  • 클러스터 alpha는 워크스페이스 A를 실행
  • 클러스터 beta는 워크스페이스 B를 실행
  • 클러스터 dev는 워크스페이스 A와 B를 실행
  • 두 워크스페이스 모두 두 개의 리스너가 있고, 클러스터 dev에는 두 개의 리스너 배포가 있음

더 알아보기 (Learn more)